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

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

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

class CXTPTaskPanel;
class CXTPTaskPanelPaintManager;
class CXTPTaskPanelItems;
class CXTPTaskPanelGroup;
class CXTPImageManagerIcon;
class CXTPPropExchange;
class CXTPMarkupUIElement;

/**
 * @brief
 * CXTPTaskPanelItem is used in a Task Panel control
 * to represent a single item.
 */
class _XTP_EXT_CLASS CXTPTaskPanelItem
	: public CXTPCmdTarget
	, public CXTPAccessible
{
	/** @cond */
	DECLARE_INTERFACE_MAP()
	DECLARE_DYNCREATE(CXTPTaskPanelItem)
	/** @endcond */
protected:
	/**
	 * @brief
	 * Constructs a CXTPTaskPanelItem object
	 */
	CXTPTaskPanelItem();

public:
	/**
	 * @brief
	 * Destroys a CXTPTaskPanelItem object, handles cleanup and deallocation.
	 */
	virtual ~CXTPTaskPanelItem();

	/**
	 * @brief
	 * Gets the parent Task Panel control.
	 * @return
	 * A pointer to the parent Task Panel control.
	 */
	CXTPTaskPanel* GetTaskPanel() const;

	/**
	 * @brief
	 * Sets the identifier for the item.
	 * @param nID Indentifier to be set.
	 */
	void SetID(UINT nID);

	/**
	 * @brief
	 * Sets the identifier for the item.
	 * @param nID       Identifier to be set.
	 * @param lpCaption Caption to be set.
	 * @param lpTooltip Tooltip to be set.
	 */
	void SetID(UINT nID, LPCTSTR lpCaption, LPCTSTR lpTooltip = NULL);

	/**
	 * @brief
	 * Gets the identifier of the item.
	 * @return
	 * The identifier of the item.
	 */
	UINT GetID() const;

	/**
	 * @brief
	 * Call this method to get the identifier of the item.
	 * @return
	 * Identifier of the item.
	 */
	BOOL IsDroppedOff() const;

	/**
	 * @brief
	 * Sets the caption for the item.
	 * @param lpszCaption Caption to be set.
	 */
	void SetCaption(LPCTSTR lpszCaption);

	/**
	 * @brief
	 * Sets the tooltip text for the item.
	 * @param lpszTooltip Tooltip text to be set.
	 * @details
	 * The tooltip text is displayed when the mouse cursor is over the item.
	 */
	void SetTooltip(LPCTSTR lpszTooltip);

	/**
	 * @brief
	 * Gets the type of the item.
	 * @return
	 * The type of the item; one of the values defined by
	 * the XTPTaskPanelItemType enumeration.
	 */
	XTPTaskPanelItemType GetType() const;

	/**
	 * @brief
	 * Sets the type for the item.
	 * @param typeItem Type to be set; must be one of the values defined by
	 * the the XTPTaskPanelItemType enumeration.
	 */
	void SetType(XTPTaskPanelItemType typeItem);

	/**
	 * @brief
	 * Gets the caption of the item.
	 * @return
	 * The caption of the item.
	 */
	CString GetCaption() const;

	/**
	 * @brief
	 * Gets the tooltip text of the item.
	 * @details
	 * The tooltip text is displayed when the mouse cursor is over the item.
	 * @return
	 * The tooltip text of the item.
	 */
	CString GetTooltip() const;

	/**
	 * @brief
	 * Determines if the item is enabled/disabled.
	 * @return
	 * TRUE if the item is enabled, FALSE if the item is disabled.
	 */
	BOOL GetEnabled() const;

	/**
	 * @brief
	 * Enables/disables the item.
	 * @param bEnabled TRUE to enable the item, FALSE to disable the item.
	 */
	void SetEnabled(BOOL bEnabled);

	/**
	 * @brief
	 * Gets the paint manager.
	 * @return
	 * A pointer to the paint manager.
	 */
	CXTPTaskPanelPaintManager* GetPaintManager() const;

	/**
	 * @brief
	 * Determines if the item is hot.
	 * @return
	 * TRUE if the item is hot, otherwise FALSE.
	 */
	BOOL IsItemHot() const;

	/**
	 * @brief
	 * Determines if the item is pressed.
	 * @return
	 * TRUE if the item is pressed, otherwise FALSE.
	 */
	BOOL IsItemPressed() const;

	/**
	 * @brief
	 * Determines if the item is focused.
	 * @return
	 * TRUE if the item is focused, otherwise FALSE.
	 */
	BOOL IsItemFocused() const;

	/**
	 * @brief
	 * Determines if the item is being dragged.
	 * @return
	 * TRUE if the item is being dragged, otherwise FALSE.
	 * @see
	 * IsItemDragOver
	 */
	BOOL IsItemDragging() const;

	/**
	 * @brief
	 * Determines if another item is being dragged over this item.
	 * @return
	 * TRUE if another item is being dragged over this item, otherwise FALSE.
	 * @see
	 * IsItemDragging
	 */
	BOOL IsItemDragOver() const;

	/**
	 * @brief
	 * Determines if the item is a group.
	 * @return
	 * TRUE if the item is a group, otherwise FALSE.
	 */
	BOOL IsGroup() const;

	/**
	 * @brief
	 * Redraws the parent Task Panel control.
	 * @param bAnimate TRUE to animate changes.
	 */
	void RedrawPanel(BOOL bAnimate = FALSE) const;

	/**
	 * @brief
	 * Sets the icon index for the item.
	 * @param nIndex Icon index to be set.
	 * @details
	 * The icon index refers to the index of the icon within
	 * the image list of the parent Task Panel control.
	 */
	void SetIconIndex(int nIndex);

	/**
	 * @brief
	 * Gets the icon index of the item.
	 * @details
	 * The icon index refers to the index of the icon within
	 * the image list of the parent Task Panel control.
	 * @return
	 * The icon index of the item.
	 */
	int GetIconIndex() const;

	/**
	 * @brief
	 * Determines if the item can be focused.
	 * @return
	 * TRUE if the item can be focused, otherwise FALSE.
	 */
	virtual BOOL IsAcceptFocus() const;

	/**
	 * @brief
	 * Retrieves the image of the item.
	 * @param nWidth Width of the icon to be retrieved
	 * (e.g. pass in a value of 16 to retrieve a 16x16 image).
	 * @details
	 * CXTPImageManagerIcon can have multiple image sizes for the same item.
	 * @return
	 * A pointer to the image of the item.
	 */
	CXTPImageManagerIcon* GetImage(int nWidth) const;

	/**
	 * @brief
	 * Restores a specified COleDataSource object.
	 * @param pDataObject Pointer to the COleDataSource object to restore.
	 * @return
	 * A pointer to the item that was stored within
	 * the COleDataSource object.
	 * @details
	 * This method will restore the item that was cached using
	 * the PrepareDrag method.
	 * @see
	 * PrepareDrag, CacheGlobalData, CopyToClipboard,
	 * PasteFromClipboard
	 */
	static CXTPTaskPanelItem* AFX_CDECL CreateFromOleData(COleDataObject* pDataObject);

	/**
	 * @brief
	 * Restores the COleDataSource object contained within a specified CFile object.
	 * @param pDataObject Pointer to the CFile object containing
	 * the COleDataSource object to restore.
	 * @return
	 * A pointer to the item that was stored within
	 * the COleDataSource object.
	 * @details
	 * This method will restore the item that was cached using
	 * the PrepareDrag method.
	 * @see
	 * PrepareDrag, CacheGlobalData, CopyToClipboard,
	 * PasteFromClipboard
	 */
	static CXTPTaskPanelItem* AFX_CDECL CreateFromOleFile(CFile* pDataObject);

	/**
	 * @brief
	 * Stores information to HGLOBAL about the group item being dragged.
	 * @return
	 * An HGLOBAL object containing information about the group item
	 * being dragged if successful, NULL if an OLE or Archive exception
	 * was thrown while caching the data.
	 * @see
	 * PrepareDrag, CreateFromOleData, CopyToClipboard, PasteFromClipboard
	 */
	HGLOBAL CacheGlobalData();

	/**
	 * @brief
	 * Removes this item from the array of items.
	 */
	void Remove();

	/**
	 * @brief
	 * Determines if the item is shown/hidden.
	 * @return
	 * TRUE if the item is shown, FALSE if the item is hidden.
	 */
	BOOL IsVisible() const;

	/**
	 * @brief
	 * Shows/hides the item.
	 * @param bVisible TRUE to show the item, FALSE to hide the item.
	 */
	void SetVisible(BOOL bVisible);

	/**
	 * @brief
	 * Repositions the groups in the Task Panel control.
	 */
	void RepositionPanel() const;

	/**
	 * @brief
	 * Gets the parent collection of items that this item belongs to.
	 * @return
	 * A pointer to the parent collection of items that this item belongs to.
	 * @details
	 * This method allows you to access sibling groups and/or items and
	 * determine the total number of siblings.
	 */
	CXTPTaskPanelItems* GetParentItems() const;

	/**
	 * @brief
	 * Gets the group that this item belongs to.
	 * @return
	 * A pointer to the group that this item belongs to.
	 */
	virtual CXTPTaskPanelGroup* GetItemGroup() const;

	/**
	 * @brief
	 * Gets the index of this item within the parent collection of items.
	 * @return
	 * The index of this item within the parent collection of items.
	 */
	int GetIndex() const;

	/**
	 * @brief
	 * Determines if dropping is enabled/disabled for this item.
	 * @return
	 * TRUE if dropping is enabled for this item,
	 * FALSE if dropping is disabled for this item.
	 */
	BOOL IsAllowDrop() const;

	/**
	 * @brief
	 * Enables/disables dropping for this item.
	 * @param bAllowDrop TRUE to enable dropping for this item,
	 * FALSE to disable dropping for this item.
	 */
	void AllowDrop(BOOL bAllowDrop);

	/**
	 * @brief
	 * Specifies the drag options for the item.
	 * @param nAllowDrag Drag options. See the Remarks section
	 * below for a list of available values.
	 * @details
	 * The nAllowDrag parameter can be one or more of the following values:
	 * <b>xtpTaskItemAllowDragCopyWithinGroup</b>: To only allow the copy operation
	 * within the group.
	 * <b>xtpTaskItemAllowDragCopyWithinControl</b>: To only allow the copy operation
	 * within the task panel.
	 * <b>xtpTaskItemAllowDragCopyOutsideControl</b>: To only allow the copy operation
	 * outside the task panel.
	 * <b>xtpTaskItemAllowDragCopy</b>: To allow the copy operation.
	 * <b>xtpTaskItemAllowDragMoveWithinGroup</b>: To only allow the move operation
	 * within the group.
	 * <b>xtpTaskItemAllowDragMoveWithinControl</b>: To only allow the move operation
	 * within the task panel.
	 * <b>xtpTaskItemAllowDragMoveOutsideControl</b>: To only allow the move operation
	 * outside the task panel.
	 * <b>xtpTaskItemAllowDragMove</b>: To allow the move operation.
	 * <b>xtpTaskItemAllowDragAll</b>: To allow all drag operations.
	 * @see
	 * IsAllowDrag, XTPTaskPanelItemAllowDrag
	 */
	void AllowDrag(long nAllowDrag = xtpTaskItemAllowDragDefault);

	/**
	 * @brief
	 * Determines if this item can be dragged.
	 * @return
	 * TRUE if this item can be dragged, otherwise FALSE.
	 * @see
	 * AllowDrag, XTPTaskPanelItemAllowDrag
	 */
	long IsAllowDrag() const;

	/**
	 * @brief
	 * Gets the item font
	 * (i.e. the font used to display task panel item text).
	 * @return
	 * A pointer to the item font.
	 */
	CFont* GetItemFont() const;

	/**
	 * @brief
	 * Sets the item font
	 * (i.e. the font used to display task panel item text).
	 * @param pLogFont Pointer to the item font to be set.
	 * @details
	 * The item font can be a custom font or the standard item font.
	 */
	void SetItemFont(LOGFONT* pLogFont);

	/**
	 * @brief
	 * Sets the bounding rectangle for the caption text of the item.
	 * @param pDC     Pointer to a valid device context.
	 * @param rc      Bounding rectangle to be set.
	 * @param nFormat Format of the caption text
	 * (i.e. DT_LEFT, DT_CENTER, DT_RIGHT, DT_VCENTER).
	 * @details
	 * This method is called by XTPTaskPanelPaintManager::DrawItemCaption
	 * to set the bounding rectangle for the caption text of the item.
	 * @see
	 * CXTPTaskPanelPaintManager::DrawItemCaption
	 */
	void SetTextRect(CDC* pDC, CRect rc, UINT nFormat);

	/**
	 * @brief
	 * Gets the bounding rectangle of the caption text of the item.
	 * @param pFormat Points to  the format object.
	 * (i.e. DT_LEFT, DT_CENTER, DT_RIGHT, DT_VCENTER).
	 * @return
	 * The bounding rectangle of the caption text of the item.
	 */
	CRect GetTextRect(UINT* pFormat = 0) const;

	/**
	 * @brief
	 * Gets the rectangle of the "tooltip zone".
	 * @return
	 * The base class implementation returns CRect(0, 0, 0, 0).
	 *
	 * The CXTPTaskPanelGroupItem implementation returns
	 * the rectangle of the "tooltip zone".
	 * @details
	 * The "tooltip zone" is the area where the tooltip will be displayed
	 * when the mouse is positioned over the group item.
	 *
	 * The member is overridden in CXTPTaskPanelGroupItem.
	 * @see
	 * CXTPTaskPanelGroupItem::GetHitTestRect
	 */
	virtual CRect GetHitTestRect() const;

	/**
	 * @brief
	 * Gets the rectangle of the "drawing zone".
	 * @return
	 * The rectangle of the "drawing zone".
	 * @see
	 * CXTPTaskPanelGroupItem::GetHitTestRect
	 */
	virtual CRect GetInvalidateRect() const;

	/**
	 * @brief
	 * Gets the application-supplied, 32-bit value associated with the item.
	 * @return
	 * The 32-bit value associated with the item.
	 */
	DWORD_PTR GetItemData() const;

	/**
	 * @brief
	 * Sets the 32-bit value associated with the item.
	 * @param dwData 32-bit value to associate with the item.
	 */
	void SetItemData(DWORD_PTR dwData);

public:
	/**
	 * @brief
	 * Retrieves the icon padding of the item.
	 * @return
	 * A reference to the icon padding of the item.
	 */
	CRect& GetIconPadding();

	/**
	 * @brief
	 * Gets the Markup element that renders the caption of the item.
	 * @return
	 * A pointer to the Markup element that renders the caption of the item.
	 */
	CXTPMarkupUIElement* GetMarkupUIElement() const;

	/**
	 * @brief
	 * This method is called to calculate boundary rectangle to fit caption
	 * @param pDC     Pointer to valid device context
	 * @param rc      Boundary rectangle
	 * @param nFormat Format flags to draw
	 * @return
	 * Size of caption
	 */
	virtual CSize GetCaptionTextSize(CDC* pDC, CRect rc, UINT nFormat);

	/**
	 * @brief
	 * This method is called to draw caption text
	 * @param pDC     Pointer to valid device context
	 * @param rc      Boundary rectangle to draw
	 * @param nFormat Format flags to draw
	 */
	virtual void DrawCaptionText(CDC* pDC, CRect rc, UINT nFormat);

public:
	/**
	 * @brief
	 * Reads/writes this object from/to an archive.
	 * @param pPX Pointer to a CXTPPropExchange object to serialize to/from.
	 */
	virtual void DoPropExchange(CXTPPropExchange* pPX);

	/**
	 * @brief
	 * Copies this item to the clipboard.
	 * @see
	 * PasteFromClipboard, CreateFromOleData, CacheGlobalData,
	 * PasteFromClipboard, PrepareDrag
	 */
	void CopyToClipboard();

	/**
	 * @brief
	 * Gets the last item placed in the clipboard.
	 * @return
	 * A pointer to the last item placed in the clipboard.
	 * @see
	 * CopyToClipboard, CreateFromOleData, CacheGlobalData,
	 * CopyToClipboard, PrepareDrag
	 */
	static CXTPTaskPanelItem* AFX_CDECL PasteFromClipboard();

	/**
	 * @brief
	 * Ensures that the item is visible in the Task Panel.
	 * @details
	 * This method will scroll the task panel and the group that
	 * the item is within until the item is visible.
	 */
	void EnsureVisible();

protected:
	/**
	 * @brief
	 * This method is called when an item is removed from
	 * the parent items collection.
	 */
	virtual void OnRemoved();

	/**
	 * @brief
	 * This method is called when an item is added to
	 * the parent items collection.
	 */
	virtual void OnInserted();

protected:
	/** @cond */
	// System accessibility Support
	virtual HRESULT GetAccessibleParent(IDispatch** ppdispParent);
	virtual HRESULT GetAccessibleDescription(VARIANT varChild, BSTR* pszDescription);
	virtual HRESULT GetAccessibleName(VARIANT varChild, BSTR* pszName);
	virtual HRESULT GetAccessibleRole(VARIANT varChild, VARIANT* pvarRole);
	virtual HRESULT AccessibleLocation(long* pxLeft, long* pyTop, long* pcxWidth, long* pcyHeight,
									   VARIANT varChild);
	virtual HRESULT AccessibleHitTest(long xLeft, long yTop, VARIANT* pvarChild);
	virtual HRESULT GetAccessibleState(VARIANT varChild, VARIANT* pvarState);
	virtual CCmdTarget* GetAccessible();
	virtual HRESULT AccessibleSelect(long flagsSelect, VARIANT varChild);
	/** @endcond */

protected:
	CXTPTaskPanel* m_pPanel; /**< Parent Task Panel. */
	CString m_strCaption;	/**< Caption of the item. */
	CString m_strTooltip;	/**< Tooltip of the item. */
	UINT m_nID;				 /**< Identifier of the item. */

	XTPTaskPanelItemType m_typeItem; /**< Type of the item. */

	CXTPTaskPanelItems* m_pItems; /**< Collection of child items. */

	int m_nIconIndex;  /**< Icon index. */
	BOOL m_bEnabled;   /**< TRUE if the item is enabled. */
	BOOL m_bAllowDrop; /**< TRUE if the item can be dragged. */
	long m_nAllowDrag; /**< TRUE if the item can be dropped. */

	CRect m_rcText;		   /**< Size and location of the caption text of the item. */
	UINT m_nTextFormat;	/**< Format of the caption text of the item. */
	BOOL m_bVisible;	   /**< TRUE if the item is visible. */
	CRect m_rcIconPadding; /**< Padding/spacing placed around the item icon. */

	DWORD_PTR m_dwData; /**< The 32-bit value associated with the item. */

	CXTPFont m_xtpFontItem; /**< Font of the item. */
	XTP_SUBSTITUTE_GDI_MEMBER_WITH_CACHED(CFont, m_fntItem, m_xtpFontItem, GetItemFontHandle);

	CXTPMarkupUIElement* m_pMarkupUIElement; /**< Markup element that renders caption. */

#	ifdef _XTP_ACTIVEX
	/** @cond */
	DECLARE_DISPATCH_MAP()
	DECLARE_OLETYPELIB_EX(CXTPTaskPanelItem)

	enum
	{
		dispidCaption   = 1L,
		dispidTooltip   = 2L,
		dispidEnabled   = 3L,
		dispidType		= 4L,
		dispidId		= 5L,
		dispidIconIndex = 6L,
	};
	afx_msg BSTR OleGetCaption();
	afx_msg BSTR OleGetTooltip();
	afx_msg LPDISPATCH OleGetGroup();
	afx_msg LPDISPATCH OleGetParentItems();
	int OleGetIndex();
	COleVariant m_oleTag;
	void OleSetIconPadding(long nLeft, long nTop, long nRight, long nBottom);
	LPFONTDISP OleGetFont();
	void OleSetFont(LPFONTDISP pFontDisp);
	void SetID_(UINT nID);

public:
	static CXTPTaskPanelItem* AFX_CDECL FromDispatch(LPDISPATCH pDisp);

/** @endcond */
#	endif /*_XTP_ACTIVEX*/

	friend class CXTPTaskPanelItems;
	friend class CXTPTaskPanelPaintManager;
};

AFX_INLINE CXTPTaskPanel* CXTPTaskPanelItem::GetTaskPanel() const
{
	_ASSERTE(m_pPanel != NULL);
	return m_pPanel;
}
AFX_INLINE CString CXTPTaskPanelItem::GetCaption() const
{
	return m_strCaption;
}
AFX_INLINE CString CXTPTaskPanelItem::GetTooltip() const
{
	return m_strTooltip;
}
AFX_INLINE CXTPTaskPanelItems* CXTPTaskPanelItem::GetParentItems() const
{
	return m_pItems;
}
AFX_INLINE CRect& CXTPTaskPanelItem::GetIconPadding()
{
	return m_rcIconPadding;
}
AFX_INLINE void CXTPTaskPanelItem::OnRemoved()
{
}
AFX_INLINE DWORD_PTR CXTPTaskPanelItem::GetItemData() const
{
	return m_dwData;
}
AFX_INLINE void CXTPTaskPanelItem::SetItemData(DWORD_PTR dwData)
{
	m_dwData = dwData;
}
AFX_INLINE CXTPMarkupUIElement* CXTPTaskPanelItem::GetMarkupUIElement() const
{
	return m_pMarkupUIElement;
}
AFX_INLINE BOOL CXTPTaskPanelItem::IsDroppedOff() const
{
	return m_pPanel == NULL ? TRUE : FALSE;
}

#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // !defined(__XTPTASKPANELITEM_H__)
/** @endcond */