/**
 * @file XTPControlGalleryItems.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(__XTPCONTROLGALLERYITEMS_H__)
#	define __XTPCONTROLGALLERYITEMS_H__
/** @endcond */

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

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

/**
 * @brief
 * CXTPControlGalleryItems is a CXTPCmdTarget derived class. It represents
 * a collection of items for gallery control.
 */
class _XTP_EXT_CLASS CXTPControlGalleryItems : public CXTPCmdTarget
{
	/** @cond */
	DECLARE_DYNAMIC(CXTPControlGalleryItems)
	/** @endcond */
protected:
	/**
	 * @brief
	 * Constructs a CXTPControlGalleryItems object.
	 * @param pAction Action for gallery control to link with.
	 * @param pCommandBars Commandbars object.
	 * @details
	 * Protected constructor, use CreateItems to create items for gallery.
	 */
	CXTPControlGalleryItems(CXTPControlAction* pAction, CXTPCommandBars* pCommandBars);

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

public:
	/**
	 * @brief
	 * Creates new items collection for gallery control.
	 * @param pCommandBars Parent Commandbars.
	 * @param nId Identifier of the items
	 * @return A newly created gallery item collection object pointer.
	 */
	static CXTPControlGalleryItems* AFX_CDECL CreateItems(CXTPCommandBars* pCommandBars, int nId);

public:
	/**
	 * @brief
	 * Call this method to remove all items in the collection.
	 */
	void RemoveAll();

	/**
	 * @brief
	 * Call this member to remove an item.
	 * @param nIndex Index of the item to be removed.
	 */
	void Remove(int nIndex);

	/**
	 * @brief
	 * Call this member to add a new item.
	 * @param nId   Identifier of the item.
	 * @param nImage Image of the item.
	 * @return
	 * A pointer to the added item.
	 */
	CXTPControlGalleryItem* AddItem(int nId, int nImage);

	/**
	 * @brief
	 * Call this member to add a new item.
	 * @param nId   Identifier of the item.
	 * @param nImage Image of the item.
	 * @param lpszCaption Caption of the item to be added.
	 * @return
	 * A pointer to the added item.
	 */
	CXTPControlGalleryItem* AddItem(LPCTSTR lpszCaption, int nId, int nImage);

	/**
	 * @brief
	 * Call this member to add a new item.
	 * @param pItem Item to be added.
	 * @param nId   Identifier of the item.
	 * @param nImage Image of the item.
	 * @return
	 * A pointer to the added item.
	 */
	CXTPControlGalleryItem* AddItem(CXTPControlGalleryItem* pItem, int nId = -1, int nImage = -1);

	/**
	 * @brief
	 * Call this member to add a new item.
	 * @param nImage Image of the item.
	 * @param lpszCaption Caption of the item to be added.
	 * @return
	 * A pointer to the added item.
	 */
	CXTPControlGalleryItem* AddItem(LPCTSTR lpszCaption, int nImage = -1);

	/**
	 * @brief
	 * Call this member to insert a new item.
	 * @param nIndex Index to insert new item.
	 * @param pItem Item to be added.
	 * @param nId   Identifier of the item.
	 * @param nImage Image of the item.
	 * @return
	 * A pointer to the added item.
	 */
	CXTPControlGalleryItem* InsertItem(int nIndex, CXTPControlGalleryItem* pItem, int nId = -1,
									   int nImage = -1);

	/**
	 * @brief
	 * Call this member to add a new label item.
	 * @param nId   Identifier of the item.
	 *
	 * @return
	 * A pointer to the added item.
	 */
	CXTPControlGalleryItem* AddLabel(int nId);

	/**
	 * @brief
	 * Call this member to add a new label item.
	 *
	 * @param lpszCaption Caption of the item to be added.
	 * @return
	 * A pointer to the added item.
	 */
	CXTPControlGalleryItem* AddLabel(LPCTSTR lpszCaption);

	/**
	 * @brief
	 * Call this method to set the image manager for the items.
	 * @param pImageManager New image manager to be set.
	 */
	void SetImageManager(CXTPImageManager* pImageManager);

	/**
	 * @brief
	 * Retrieves the image manager for the items.
	 * @return
	 * The image manager for the items.
	 */
	CXTPImageManager* GetImageManager() const;

	/**
	 * @brief
	 * Determines the default size of the items.
	 * @return
	 * The default size of the items.
	 * @see
	 * SetItemSize
	 */
	CSize GetItemSize() const;

	/**
	 * @brief
	 * Call this method to set the size of the items.
	 * @param szItem New size to be set.
	 * @see
	 * GetItemSize
	 */
	void SetItemSize(CSize szItem);

	/**
	 * @brief
	 * Call this member to get the count of the items.
	 * @return
	 * The count of the items in the collection.
	 */
	int GetItemCount() const;

	/**
	 * @brief
	 * Call this member to return the item at the specified index.
	 * @param nIndex An integer index.
	 * @return
	 * The CXTPControlGalleryItem pointer currently at this index.
	 */
	CXTPControlGalleryItem* GetItem(int nIndex) const;

	/**
	 * @brief
	 * Call this member to enable/disable clipping items if selection was changed
	 * @param bClipItems TRUE to enable clipping, FALSE to disable clipping.
	 * @details
	 * By default clipping is enabled.
	 */
	void ClipItems(BOOL bClipItems);

	/**
	 * @brief
	 * This method is called if items are added to or removed from the collection.
	 */
	virtual void OnItemsChanged();

	/**
	 * @brief
	 * This method is called to draw the item.
	 * @param pDC       Pointer to a valid device context.
	 * @param pGallery  Pointer to the parent gallery of the item.
	 * @param pItem     Pointer to the item to be drawn.
	 * @param rcItem    Bounding rectangle of the item.
	 * @param bEnabled  TRUE to draw the item enabled, FALSE to draw the item disabled.
	 * @param bSelected TRUE to draw the item selected.
	 * @param bPressed  TRUE to draw the item pressed.
	 * @param bChecked  TRUE to draw the item checked.
	 * @return Draws the item
	 */
	virtual BOOL PreDrawItem(CDC* pDC, CXTPControlGallery* pGallery, CXTPControlGalleryItem* pItem,
							 CRect rcItem, BOOL bEnabled, BOOL bSelected, BOOL bPressed,
							 BOOL bChecked);

	/**
	 * @brief
	 * Call this method to get the actions list for command bars.
	 * @return
	 * A pointer to the actions list for command bars.
	 */
	CXTPControlAction* GetAction() const;

	/**
	 * @brief
	 * Allows the use of a XAML snippet to be used for the text of items.
	 * @param bEnableMarkup TRUE to enable markup, FALSE to disable markup.
	 */
	void EnableMarkup(BOOL bEnableMarkup = TRUE);

	/**
	 * @brief
	 * Retrieves a pointer to the markup context.
	 * @return
	 * A pointer to a CXTPMarkupContext object.
	 */
	CXTPMarkupContext* GetMarkupContext() const;

private:
	void UpdateIndexes(int nStart /*= 0*/);

protected:
	CSize m_szItem;					   /**< Size of the items */
	CXTPImageManager* m_pImageManager; /**< Image manager of items */
	BOOL m_bClipItems;				   /**< TRUE to clip items */
	CXTPControlAction* m_pAction;	  /**< Action of the items */
	CArray<CXTPControlGalleryItem*, CXTPControlGalleryItem*> m_arrItems; /**< Array of items */
	CXTPMarkupContext* m_pMarkupContext;
	CXTPCommandBars* m_pCommandBars;

private:
	friend class CXTPControlGalleryItem;
	friend class CXTPControlGallery;
	friend class CXTPControlGalleryAction;

#	ifdef _XTP_COMMANDBARS_ACTIVEX
	/** @cond */

	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPControlGalleryItems);
	DECLARE_ENUM_VARIANT(CXTPControlGalleryItems);
	DECLARE_CONNECTION_EX(CXTPControlGalleryItems)

	afx_msg LPDISPATCH OleAddItem(int nId, LPCTSTR lpszCaption);
	afx_msg LPDISPATCH OleAddLabel(LPCTSTR lpszCaption);
	afx_msg LPDISPATCH OleAddSeparator();
	afx_msg long OleGetItemCount();
	afx_msg LPDISPATCH OleGetItem(int nIndex);
	afx_msg BOOL OleGetEnableMarkup();
	afx_msg void OleSetEnableMarkup(BOOL bEnableMarkup);
	afx_msg LPDISPATCH OleGetMarkupContext();

	DECLARE_PROPERTY(Icons, LPDISPATCH);
	DECLARE_PROPERTY(ItemWidth, int);
	DECLARE_PROPERTY(ItemHeight, int);

	/** @endcond */
#	endif
};

AFX_INLINE CXTPImageManager* CXTPControlGalleryItems::GetImageManager() const
{
	return m_pImageManager;
}
AFX_INLINE CSize CXTPControlGalleryItems::GetItemSize() const
{
	return m_szItem;
}
AFX_INLINE void CXTPControlGalleryItems::ClipItems(BOOL bClipItems)
{
	m_bClipItems = bClipItems;
}
AFX_INLINE CXTPControlAction* CXTPControlGalleryItems::GetAction() const
{
	return m_pAction;
}
AFX_INLINE CXTPMarkupContext* CXTPControlGalleryItems::GetMarkupContext() const
{
	return m_pMarkupContext;
}

#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // __XTPCONTROLGALLERYITEMS_H__
/** @endcond */