/**
 * @file XTPImageList.h
 *
 * @copyright
 * (c) 1998-2025 Codejock Software, All Rights Reserved.
 *
 * This source file is the property of Codejock Software and must not be
 * redistributed by any means without the explicit written permission of
 * Codejock Software.
 *
 * The use of this source code is governed by the terms and conditions specified
 * in the Toolkit Pro license agreement. Codejock Software grants you, as a
 * single software developer, the limited right to use this software on one
 * computer only.
 *
 * Contact Information:
 * support@codejock.com
 * http://www.codejock.com
 *
 */

/** @cond */
#if !defined(__XTPIMAGELIST_H__)
#	define __XTPIMAGELIST_H__
/** @endcond */

#	if _MSC_VER > 1000
#		pragma once
#	endif // _MSC_VER > 1000

#	include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h"

/**
 * @brief
 * CXTPImageList extends CImageList with add additional functionality for
 * images resizing that depends on DPI.
 */
class _XTP_EXT_CLASS CXTPImageList : public CObject
{
	DECLARE_DYNAMIC(CXTPImageList);

public:
	/** @cond */
	typedef CXTPGdiObjectPtrProxy<CImageList, CXTPImageList> XTPImageListPtrProxy;
	/** @endcond */

private:
	CImageList* m_imageList;
	int m_imageCx;

	/**
	 * @brief
	 * Initializes an image list and attaches it to a CXTPImageList object.
	 * @param bitmap Pointer to the bitmap containing the image or images.
	 * @param cx Dimensions of each image, in pixels.
	 * @param nGrow Number of images by which the image list can grow when the
	 * system needs to resize the list to make room for new images.
	 * This parameter represents the number of new images the resized
	 * image list can contain.
	 * @param crMask Color used to generate a mask. Each pixel of this color
	 * in the specified bitmap is changed to black, and the
	 * corresponding bit in the mask is set to one.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 * @details
	 * If image has size 16x16 px and DPI settings set 150%, then image will be
	 * resized to 24x24 px and added to imagelist.
	 */
	BOOL Create(CBitmap* bitmap, int cx, int nGrow, COLORREF crMask);

	/**
	 * @brief
	 * Resizes image specified by the source bitmap and stores it into
	 * the destination bitmap.
	 * @param src Pointer to the source bitmap.
	 * @param dst Pointer to the destination bitmap while will contain the the
	 * resized image upon successful completion.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 * @details
	 * If image has size 16x16 px and DPI settings set 150%, then image will be
	 * resized to 24x24 px.
	 */
	BOOL Resize(CBitmap* src, CBitmap* dst);

public:
	/**
	 * @brief
	 * Constructs a CXTPImageList object
	 */
	CXTPImageList();

	/**
	 * @brief
	 * Destroys a CXTPImageList object, handles cleanup and deallocation
	 */
	virtual ~CXTPImageList();

	/**
	 * @brief
	 * Initializes an image list and attaches it to a CXTPImageList object.
	 * @param cx Dimensions of each image, in pixels.
	 * @param cy Dimensions of each image, in pixels.
	 * @param nFlags Specifies the type of image list to create. This parameter
	 * can be a combination of the following values, but it can
	 * include only one of the ILC_COLOR values.
	 * @param nInitial Number of images that the image list initially contains.
	 * @param nGrow Number of images by which the image list can grow when the
	 * system needs to resize the list to make room for new images.
	 * This parameter represents the number of new images the resized
	 * image list can contain.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Create(int cx, int cy, UINT nFlags, int nInitial, int nGrow);

	/**
	 * @brief
	 * Initializes an image list and attaches it to a CXTPImageList object.
	 * @param nBitmapID Resource IDs of the bitmap to be associated with the image list.
	 * @param cx Dimensions of each image, in pixels.
	 * @param nGrow Number of images by which the image list can grow when the
	 * system needs to resize the list to make room for new images.
	 * This parameter represents the number of new images the resized
	 * image list can contain.
	 * @param crMask Color used to generate a mask. Each pixel of this color
	 * in the specified bitmap is changed to black, and the
	 * corresponding bit in the mask is set to one.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Create(UINT nBitmapID, int cx, int nGrow, COLORREF crMask);

	/**
	 * @brief
	 * Initializes an image list and attaches it to a CXTPImageList object.
	 * @param lpszBitmapID A string containing the resource IDs of the images.
	 * @param cx Dimensions of each image, in pixels.
	 * @param nGrow Number of images by which the image list can grow when the
	 * system needs to resize the list to make room for new images.
	 * This parameter represents the number of new images the resized
	 * image list can contain.
	 * @param crMask Color used to generate a mask. Each pixel of this color
	 * in the specified bitmap is changed to black, and the
	 * corresponding bit in the mask is set to one.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Create(LPCTSTR lpszBitmapID, int cx, int nGrow, COLORREF crMask);

	/**
	 * @brief
	 * Initializes an image list and attaches it to a CXTPImageList object.
	 * @param imagelist1 A reference to a CXTPImageList object.
	 * @param nImage1    Index of the first existing image.
	 * @param imagelist2 A reference to a CXTPImageList object.
	 * @param nImage2    Index of the second existing image.
	 * @param dx         Offset of the x-axis of the second image in relationship
	 *                   to the first image, in pixels.
	 * @param dy         Offset of the y-axis of the second image in relationship
	 *                   to the first image, in pixels.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Create(CXTPImageList& imagelist1, int nImage1, CXTPImageList& imagelist2, int nImage2,
				int dx, int dy);

	/**
	 * @brief
	 * Initializes an image list and attaches it to a CXTPImageList object.
	 * @param pImageList A pointer to a CXTPImageList object.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Create(CXTPImageList* pImageList);

	/**
	 * @brief
	 * Use this operator to get the attached handle of the CXTPImageList object.
	 * @return
	 * If successful, a handle to the image list represented by the CXTPImageList object;
	 * otherwise NULL.
	 */
	operator HIMAGELIST() const;

	/**
	 * @brief
	 * Call this function to retrieve the m_hImageList data member.
	 * @return
	 * A handle to the attached image list; otherwise NULL if no object is attached.
	 */
	HIMAGELIST GetSafeHandle() const;

	/**
	 * @brief
	 * Attaches an image list to a CXTPImageList object.
	 * @param hImageList A handle to an image list object.
	 * @return
	 * Nonzero if the attachment was successful; otherwise 0.
	 */
	BOOL Attach(HIMAGELIST hImageList);

	/**
	 * @brief
	 * Call this function to detach an image list object from a CXTPImageList object.
	 * @return
	 * A handle to an image list object.
	 */
	HIMAGELIST Detach();

	/**
	 * @brief
	 * Call this function to retrieve the number of images in an image list.
	 * @return
	 * The number of images.
	 */
	int GetImageCount() const;

	/**
	 * @brief
	 * Call this function to set the background color for an image list.
	 * @param cr Background color to set. It can be CLR_NONE. In that case,
	 * images are drawn transparently using the mask.
	 * @return
	 * The previous background color if successful; otherwise CLR_NONE.
	 */
	COLORREF SetBkColor(COLORREF cr);

	/**
	 * @brief
	 * Call this function to retrieve the current background color for an image list.
	 * @return
	 * The RGB color value of the CXTPImageList object background color.
	 */
	COLORREF GetBkColor() const;

	/**
	 * @brief
	 * Call this function to retrieve information about an image.
	 * @param nImage Zero-based index of the image.
	 * @param pImageInfo Pointer to an IMAGEINFO structure that receives information
	 * about the image. The information in this structure can be
	 * used to directly manipulate the bitmaps for the image.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL GetImageInfo(int nImage, IMAGEINFO* pImageInfo) const;

	/**
	 * @brief
	 * Call this function to delete an image list.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL DeleteImageList();

	/**
	 * @brief
	 * Call this member function to reset the number of images in a CXTPImageList object.
	 * @param uNewCount The value specifying the new total number of images in the image list.
	 * @return
	 * Nonzero if successful; otherwise zero.
	 */
	BOOL SetImageCount(UINT uNewCount);

	/**
	 * @brief
	 * Call this function to add one or more images or an icon to an image list.
	 * @param pbmImage Pointer to the bitmap containing the image or images. The number
	 * of images is inferred from the width of the bitmap.
	 * @param pbmMask Pointer to the bitmap containing the mask. If no mask is used
	 * with the image list, this parameter is ignored.
	 * @return
	 * Zero-based index of the first new image if successful; otherwise -1.
	 */
	int Add(CBitmap* pbmImage, CBitmap* pbmMask);

	/**
	 * @brief
	 * Call this function to add one or more images or an icon to an image list.
	 * @param pbmImage Pointer to the bitmap containing the image or images. The number
	 * of images is inferred from the width of the bitmap.
	 * @param crMask Color used to generate the mask. Each pixel of this color in the
	 * given bitmap is changed to black and the corresponding bit in the
	 * mask is set to one.
	 * @return
	 * Zero-based index of the first new image if successful; otherwise -1.
	 */
	int Add(CBitmap* pbmImage, COLORREF crMask);

	/**
	 * @brief
	 * Call this function to add one or more images or an icon to an image list.
	 * @param hIcon Handle of the icon that contains the bitmap and mask for the new image.
	 * @return
	 * Zero-based index of the first new image if successful; otherwise -1.
	 */
	int Add(HICON hIcon);

	/**
	 * @brief
	 * Call this function to remove an image from an image list object.
	 * @param nImage Zero-based index of the image to remove.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Remove(int nImage);

	/**
	 * @brief
	 * Call this function to replace an image in an image list with a new image.
	 * @param nImage Zero-based index of the image to replace.
	 * @param pbmImage A pointer to the bitmap containing the image.
	 * @param pbmMask A pointer to the bitmap containing the mask. If no mask is used
	 * with the image list, this parameter is ignored.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Replace(int nImage, CBitmap* pbmImage, CBitmap* pbmMask);

	/**
	 * @brief
	 * Call this function to replace an image in an image list with a new image.
	 * @param nImage Zero-based index of the image to replace.
	 * @param hIcon A handle to the icon that contains the bitmap and mask for the new image.
	 * @return
	 * Zero-based index of the image if successful; otherwise -1.
	 */
	int Replace(int nImage, HICON hIcon);

	/**
	 * @brief
	 * Call this function to create an icon based on an image and its related mask in an image
	 * list.
	 * @param nImage Zero-based index of the image.
	 * @return
	 * Handle of the icon if successful; otherwise NULL.
	 */
	HICON ExtractIcon(int nImage);

	/**
	 * @brief
	 * Call this function to draw the image that is being dragged during a drag-and-drop
	 * operation.
	 * @param pDC Pointer to the destination device context.
	 * @param nImage Zero-based index of the image to draw.
	 * @param pt Location at which to draw within the specified device context.
	 * @param nStyle Flag specifying the drawing style. Refer to the platform SDK's documentation
	 * on ImageList_Draw function for ILD_* flags summary.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Draw(CDC* pDC, int nImage, POINT pt, UINT nStyle);

	/**
	 * @brief
	 * Call this function to add the zero-based index of an image to the list of images to be
	 * used as overlay masks.
	 * @param nImage Zero-based index of the image to use as an overlay mask.
	 * @param nOverlay One-based index of the overlay mask.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL SetOverlayImage(int nImage, int nOverlay);

	/**
	 * @brief
	 * This member function implements the behavior of the Win32 function ImageList_Copy, as
	 * described in the Windows SDK.
	 * @param iDst The zero-based index of the image to be used as the destination of the copy
	 * operation.
	 * @param iSrc The zero-based index of the image to be used as the source of the copy
	 * operation.
	 * @param uFlags The bit flag value that specifies the type of copy operation to be
	 * made.
	 * @return
	 * Nonzero if successful; otherwise zero.
	 */
	BOOL Copy(int iDst, int iSrc, UINT uFlags = ILCF_MOVE);

	/**
	 * @brief
	 * This member function implements the behavior of the Win32 function ImageList_Copy, as
	 * described in the Windows SDK.
	 * @param iDst The zero-based index of the image to be used as the destination of the copy
	 * operation.
	 * @param pSrc A pointer to a CXTPImageList object that is the target of the copy
	 * operation.
	 * @param iSrc The zero-based index of the image to be used as the source of the copy
	 * operation.
	 * @param uFlags The bit flag value that specifies the type of copy operation to be
	 * made.
	 * @return
	 * Nonzero if successful; otherwise zero.
	 */
	BOOL Copy(int iDst, CXTPImageList* pSrc, int iSrc, UINT uFlags = ILCF_MOVE);

	/**
	 * @brief
	 * Call this member function to draw an image from an image list.
	 * @param pimldp A pointer to an IMAGELISTDRAWPARAMS structure that contains information about
	 * the draw operation.
	 * @return
	 * TRUE if the image is successfully drawn; otherwise FALSE.
	 */
	BOOL DrawIndirect(IMAGELISTDRAWPARAMS* pimldp);

	/**
	 * @brief
	 * Call this function to read an image list from an archive.
	 * @param pArchive A pointer to a CArchive object from which the image list is to be read.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Read(CArchive* pArchive);

	/**
	 * @brief
	 * Call this function to write an image list object to an archive.
	 * @param pArchive A pointer to a CArchive object in which the image list is to be stored.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL Write(CArchive* pArchive);

	/**
	 * @brief
	 * Call this function to begin dragging an image.
	 * @param nImage Zero-based index of the image to drag.
	 * @param ptHotSpot Coordinates of the starting drag position (typically, the cursor position).
	 * The coordinates are relative to the upper left corner of the image.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL BeginDrag(int nImage, CPoint ptHotSpot);

	/**
	 * @brief
	 * Creates a new drag image by combining the given image (typically a mouse cursor image)
	 * with the current drag image.
	 * @param nDrag Index of the new image to be combined with the drag image.
	 * @param ptHotSpot Position of the hot spot within the new image.
	 * @return
	 * Nonzero if successful; otherwise 0.
	 */
	BOOL SetDragCursorImage(int nDrag, CPoint ptHotSpot);

	/** @cond */
#	if defined(_DEBUG) || defined(_AFXDLL)
	virtual void Dump(CDumpContext& dc) const;
	virtual void AssertValid() const;
#	endif
	/** @endcond */

	/**
	 * @brief
	 * Obtains a pointer to the encapsulated CImageList object.
	 * @return
	 * A pointer to the encapsulated CImageList object.
	 */
	CImageList* GetNativeGdiObject();

	/**
	 * @brief
	 * Obtains a pointer to the encapsulated CImageList object.
	 * @return
	 * A pointer to the encapsulated CImageList object.
	 */
	const CImageList* GetNativeGdiObject() const;

	/**
	 * @brief
	 * Converts an object to CImageList reference making it possible
	 * to use CXTPImageList with MFC classes and methods that use CImageList
	 * reference as an argument.
	 * @return
	 * An encapsulated CImageList object reference.
	 */
	operator CImageList&();

	/**
	 * @brief
	 * Converts an object to CImageList constant reference making it possible
	 * to use CXTPImageList with MFC classes and methods that use CImageList or
	 * CGdiObject constant reference as an argument.
	 * @return
	 * An encapsulated CImageList constant object reference.
	 */
	operator const CImageList&() const;

	/** @cond */
	XTPImageListPtrProxy operator&();
	const XTPImageListPtrProxy operator&() const;
	/** @endcond */
};
/** @cond */
AFX_INLINE CImageList* CXTPImageList::GetNativeGdiObject()
{
	return m_imageList;
}

AFX_INLINE const CImageList* CXTPImageList::GetNativeGdiObject() const
{
	return const_cast<CXTPImageList*>(this)->GetNativeGdiObject();
}

AFX_INLINE CXTPImageList::operator CImageList&()
{
	return *GetNativeGdiObject();
}

AFX_INLINE CXTPImageList::operator const CImageList&() const
{
	return *GetNativeGdiObject();
}

AFX_INLINE CXTPImageList::XTPImageListPtrProxy CXTPImageList::operator&()
{
	return XTPImageListPtrProxy(this);
}

AFX_INLINE const CXTPImageList::XTPImageListPtrProxy CXTPImageList::operator&() const
{
	return XTPImageListPtrProxy(const_cast<CXTPImageList*>(this));
}
/** @endcond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // !defined(__XTPIMAGELIST_H__)
/** @endcond */