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

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

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

class CXTPTaskPanelGroup;
class CXTPTaskPanelItem;
class CXTPTaskPanel;
class CXTPPropExchange;

/**
 * @brief
 * CXTPTaskPanelItems is used in a Task Panel control
 * to represent a collection of items.
 */
class _XTP_EXT_CLASS CXTPTaskPanelItems : public CXTPCmdTarget
{
	/** @cond */
	DECLARE_DYNCREATE(CXTPTaskPanelItems)
	/** @endcond */
public:
	/**
	 * @brief
	 * Constructs a CXTPTaskPanelItems object.
	 * @param pPanel Pointer to the parent Task Panel.
	 */
	CXTPTaskPanelItems(CXTPTaskPanel* pPanel = NULL);

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

public:
	/**
	 * @brief
	 * Adds an item to this collection.
	 * @param pItem Pointer to the item to add.
	 * @param nID   Identifier of the item.
	 * @return
	 * A pointer to the newly added item.
	 */
	CXTPTaskPanelItem* Add(CXTPTaskPanelItem* pItem, UINT nID);

	/**
	 * @brief
	 * Adds an item to this collection.
	 * @param pItem     Pointer to the item to add.
	 * @param nID       Identifier of the item.
	 * @param lpCaption Caption of the item.
	 * @param lpTooltip Tooltip of the item.
	 * @return
	 * A pointer to the newly added item.
	 */
	CXTPTaskPanelItem* Add(CXTPTaskPanelItem* pItem, UINT nID, LPCTSTR lpCaption,
						   LPCTSTR lpTooltip = NULL);

	/**
	 * @brief
	 * Inserts an item at a specified index in this collection.
	 * @param nIndex Index to insert the item at.
	 * @param pItem  Pointer to the item to insert.
	 * @details
	 * To move an item, use the Move method.
	 * @return
	 * A pointer to the newly inserted item.
	 */
	CXTPTaskPanelItem* InsertAt(int nIndex, CXTPTaskPanelItem* pItem);

	/**
	 * @brief
	 * Retrieves the item at a specified index in this collection.
	 * @param nIndex Zero-based index of the item to retrieve.
	 * @return
	 * A pointer to the item at the specified index in this collection.
	 */
	CXTPTaskPanelItem* GetAt(int nIndex) const;

	/**
	 * @brief
	 * Removes all items from this collection.
	 * @param bReposition TRUE to reposition items after the removal
	 * is complete, FALSE otherwise.
	 * @see
	 * CXTPTaskPanel::Reposition
	 */
	void Clear(BOOL bReposition = TRUE);

	/**
	 * @brief
	 * Retrieves the item with a specified identifier.
	 * @param nID Identifier of the item to be retrieved.
	 * @return
	 * A pointer to the item with the specified identifier if successful,
	 * otherwise FALSE.
	 */
	CXTPTaskPanelItem* Find(UINT nID) const;

	/**
	 * @brief
	 * Removes a specified item from this collection.
	 * @param pItem Pointer to the item to be removed.
	 */
	void Remove(CXTPTaskPanelItem* pItem);

	/**
	 * @brief
	 * Removes the item at a specified index from this collection.
	 * @param nIndex Zero-based index of the item to be removed.
	 */
	void RemoveAt(int nIndex);

	/**
	 * @brief
	 * Retrieves the index of a specified item in this collection.
	 * @param pItem Pointer to the item with the index to be retrieved.
	 * @return
	 * The index of the specified item in this collection.
	 */
	int GetIndex(const CXTPTaskPanelItem* pItem) const;

	/**
	 * @brief
	 * Gets the number of items in this collection.
	 * @return
	 * The number of items in this collection.
	 */
	int GetCount() const;

	/**
	 * @brief
	 * Gets the owner.
	 * @return
	 * A pointer to the owner.
	 */
	CCmdTarget* GetOwner() const;

	/**
	 * @brief
	 * Moved a specified item to a specified index in this collection.
	 * @param pItem  Pointer to the item to be moved.
	 * @param nIndex Index to move the specified item to.
	 * @details
	 * Items are stored in a zero based array and are displayed in
	 * the order that they are added to the array. This method allows
	 * for the order of items in the array to be changed.
	 */
	void Move(CXTPTaskPanelItem* pItem, int nIndex);

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

	/**
	 * @brief
	 * Gets the default runtime class of items in this collection.
	 * @return
	 * A pointer to the default runtime class of items in this collection.
	 */
	virtual CRuntimeClass* GetDefaultItemClass() const;

	/**
	 * @brief
	 * Retrieves the index of the next/previous visible item in this collection
	 * from a specified index.
	 * @param nIndex     Index to begin search.
	 * @param nDirection Direction to search in (+1 for next, -1 for previous).
	 * @return
	 * The index of the next/previous visible item in this collection
	 * from the specified index if successful, otherwise a value of -1.
	 * @see
	 * GetFirstVisibleItem, GetLastVisibleItem
	 */
	int GetNextVisibleIndex(int nIndex, int nDirection) const;

	/**
	 * @brief
	 * Gets the first visible item in this collection.
	 * @return
	 * A pointer to the first visible item in this collection.
	 * @see
	 * GetLastVisibleItem, GetNextVisibleIndex
	 */
	CXTPTaskPanelItem* GetFirstVisibleItem() const;

	/**
	 * @brief
	 * Gets the last visible item in this collection.
	 * @return
	 * A pointer to the last visible item in this collection.
	 * @see
	 * GetFirstVisibleItem, GetNextVisibleIndex
	 */
	CXTPTaskPanelItem* GetLastVisibleItem() const;

protected:
	CXTPTaskPanel* m_pPanel;								   /**< Parent Task Panel control. */
	CArray<CXTPTaskPanelItem*, CXTPTaskPanelItem*> m_arrItems; /**< Array of items. */
	CCmdTarget* m_pOwner; /**< Owner of items. Can be Task Panel or Group. */

#	ifdef _XTP_ACTIVEX
	/** @cond */

	afx_msg long OleGetItemCount();
	afx_msg LPDISPATCH OleItem(long nIndex);

	afx_msg void OleClear();
	afx_msg void OleRemove(long nIndex);
	afx_msg LPDISPATCH OleFind(long nID);
	afx_msg void OleMove(LPDISPATCH lpItem, long nIndex);
	afx_msg LPDISPATCH OleGetItem(long nIndex);

	DECLARE_ENUM_VARIANT(CXTPTaskPanelItems)

	DECLARE_OLETYPELIB_EX(CXTPTaskPanelItems)

	enum
	{
		dispidCount  = 1L,
		dispidRemove = 2L,
		dispidClear  = 3L,
		dispidAdd	= 4L,
		dispidFind   = 5L,
	};

	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

/** @endcond */
#	endif
	friend class CXTPTaskPanel;
	friend class CXTPTaskPanelGroup;
};

/**
 * @brief
 * CXTPTaskPanelGroupItems represents a collection of items in a group.
 */
class _XTP_EXT_CLASS CXTPTaskPanelGroupItems : public CXTPTaskPanelItems
{
public:
	/**
	 * @brief
	 * Constructs CXTPTaskPanelGroupItems object.
	 * @param pPanel Pointer to the parent Task Panel.
	 */
	CXTPTaskPanelGroupItems(CXTPTaskPanel* pPanel);

	/**
	 * @brief
	 * Gets the default runtime class of items in this collection.
	 * @return
	 * A pointer to the default runtime class of items in this collection.
	 */
	virtual CRuntimeClass* GetDefaultItemClass() const;

#	ifdef _XTP_ACTIVEX
	/** @cond */

	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPTaskPanelGroupItems)

	afx_msg LPDISPATCH OleAdd(long nID, LPCTSTR lpCaption, long nType,
							  const VARIANT& varImageIndex);
	afx_msg LPDISPATCH OleInsert(long nIndex, long nID, LPCTSTR lpCaption, long nType,
								 const VARIANT& varImageIndex);

/** @endcond */
#	endif
};

/**
 * @brief
 * CXTPTaskPanelGroups represents a collection of groups in a Task Panel control.
 */
class _XTP_EXT_CLASS CXTPTaskPanelGroups : public CXTPTaskPanelItems
{
public:
	/**
	 * @brief
	 * Constructs a CXTPTaskPanelGroups object.
	 * @param pPanel Pointer to the parent Task Panel.
	 */
	CXTPTaskPanelGroups(CXTPTaskPanel* pPanel);

	/**
	 * @brief
	 * Gets the default runtime class of items in this collection.
	 * @return
	 * A pointer to the default runtime class of items in this collection.
	 */
	virtual CRuntimeClass* GetDefaultItemClass() const;

#	ifdef _XTP_ACTIVEX
	/** @cond */

	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPTaskPanelGroups)

	afx_msg LPDISPATCH OleAdd(long nID, LPCTSTR lpCaption);
/** @endcond */
#	endif
};

AFX_INLINE int CXTPTaskPanelItems::GetCount() const
{
	return (int)m_arrItems.GetSize();
}
AFX_INLINE CXTPTaskPanelItem* CXTPTaskPanelItems::GetAt(int nIndex) const
{
	return nIndex >= 0 && nIndex < m_arrItems.GetSize() ? m_arrItems.GetAt(nIndex) : NULL;
}
AFX_INLINE CCmdTarget* CXTPTaskPanelItems::GetOwner() const
{
	return m_pOwner;
}

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