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

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

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

class CXTPCommandBar;
class CXTPControl;
class CXTPCommandBars;
class CXTPCommandBarList;
class CXTPPropExchange;
struct XTP_COMMANDBARS_PROPEXCHANGE_PARAM;
class CXTPOriginalControls;

/**
 * @brief
 * CXTPControls is a CXTPCmdTarget derived class.
 * It represents a collection of controls.
 */
class _XTP_EXT_CLASS CXTPControls : public CXTPCmdTarget
{
	/** @cond */
	DECLARE_DYNCREATE(CXTPControls)
	/** @endcond */
private:
	struct XTPBUTTONINFO; /**< Internal helper structure. */

public:
	/**
	 * @brief
	 * Protected constructor used by dynamic creation.
	 */
	CXTPControls();

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

public:
	/**
	 * @brief
	 * Call this member to return the control at the specified index.
	 * @param nIndex An integer index.
	 * @return
	 * The CXTPControl pointer currently at this index.
	 */
	CXTPControl* GetAt(int nIndex) const;

	/**
	 * @brief
	 * This member function returns the index of the first control, starting
	 * at position 0, whose command ID matches nIDFind.
	 * @param nIDFind Command ID of the control to find.
	 * @return
	 * The index of the control, or -1 if no control has the given command ID.
	 */
	int CommandToIndex(int nIDFind) const;

	/**
	 * @brief
	 * Call this member to add a new control.
	 * @param nId          Identifier of the control to be added.
	 * @param lpszParameter Parameter of the control to be added.
	 * @param nBefore      Index of the control to be inserted.
	 * @param bTemporary   TRUE if this control is temporary.
	 * @param pControl     A pointer to the control
	 * @return
	 * A pointer to the added control.
	 */
	CXTPControl* Add(CXTPControl* pControl, int nId, LPCTSTR lpszParameter = NULL, int nBefore = -1,
					 BOOL bTemporary = FALSE);

	/**
	 * @brief
	 * Call this member to add a new control.
	 * @param controlType  The type of the control to be added.
	 * @param nId          Identifier of the control to be added.
	 * @param lpszParameter Parameter of the control to be added.
	 * @param nBefore      Index of the control to be inserted.
	 * @param bTemporary   TRUE if this control is temporary.
	 * @return
	 * A pointer to the added control.
	 */
	CXTPControl* Add(XTPControlType controlType, int nId, LPCTSTR lpszParameter = NULL,
					 int nBefore = -1, BOOL bTemporary = FALSE);

	/**
	 * @brief
	 * Call this member to add a new control.
	 * @param pControl     A pointer to the control to be added.
	 * @return
	 * A pointer to the added control.
	 */
	CXTPControl* Add(CXTPControl* pControl);

	/**
	 * @brief
	 * Call this member to insert a new control.
	 * @param pControl A pointer to the control to be added.
	 * @param nBefore Index of the control to be inserted.
	 * @return
	 * A pointer to the added control.
	 * @see
	 * Add
	 */
	CXTPControl* InsertAt(CXTPControl* pControl, int nBefore);

	/**
	 * @brief
	 * Call this member to add a new control.
	 * @param pMenu  Menu that contains the control.
	 * @param nIndex Index of the control to be added.
	 * @return
	 * Pointer to the added control.
	 */
	CXTPControl* AddMenuItem(CMenu* pMenu, int nIndex);

	/**
	 * @brief
	 * Call this member to remove a control.
	 * @param pControl Control to be removed.
	 */
	virtual void Remove(CXTPControl* pControl);

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

	/**
	 * @brief
	 * Call this member to remove all controls.
	 */
	void RemoveAll();

	/**
	 * @brief
	 * Call this member to get the count of the controls.
	 * @return
	 * The count of the controls.
	 */
	int GetCount() const;

	/**
	 * @brief
	 * Call this member to find the specified control.
	 * @param nId        The control's identifier.
	 * @return
	 * Pointer to the CXTPControl object if successful, otherwise NULL.
	 */
	CXTPControl* FindControl(int nId) const;

	/**
	 * @brief
	 * Call this member to find the specified control.
	 * @param type       The type of the control to find.
	 * @param nId        The control's identifier.
	 * @param bVisible   TRUE if the control is visible.
	 * @param bRecursive TRUE to find in the nested command bars.
	 * @return
	 * Pointer to the CXTPControl object if successful, otherwise NULL.
	 */
	CXTPControl* FindControl(XTPControlType type, int nId, BOOL bVisible, BOOL bRecursive) const;

	/**
	 * @brief
	 * Call this member to convert menu items to command bar controls.
	 * @param pMenu Menu to be converted.
	 * @return
	 * TRUE if the method was successful, otherwise FALSE.
	 */
	BOOL LoadMenu(CMenu* pMenu);

public:
	/**
	 * @brief
	 * Call this member to retrieve the first control.
	 * @return
	 * A pointer to a CXTPControl object.
	 */
	CXTPControl* GetFirst() const;

	/**
	 * @brief
	 * Finds the next control in the given direction.
	 * @param pControl Receives a pointer to the next control.
	 */
	void GetNext(CXTPControl*& pControl) const;

	/**
	 * @brief
	 * Finds the next control in the given direction.
	 * @param nIndex Current control index.
	 * @param nDirection Direction to find.
	 * @param bKeyboard TRUE to skip controls with xtpFlagSkipFocus flag.
	 * @param bSkipTemporary TRUE to skip all controls with Temporary flag
	 * @param bSkipCollapsed TRUE to skip all controls  with xtpHideExpand hide flag.
	 * @return
	 * Index of the next control.
	 */
	long GetNext(long nIndex, int nDirection = +1, BOOL bKeyboard = TRUE,
				 BOOL bSkipTemporary = FALSE, BOOL bSkipCollapsed = TRUE) const;

	/**
	 * @brief
	 * This member function determines which control, if any, is
	 * at a specified point.
	 * @param point Point to be tested.
	 * @return
	 * A pointer to the control at the position specified by 'point',
	 * otherwise NULL.
	 */
	CXTPControl* HitTest(CPoint point) const;

	/**
	 * @brief
	 * Call this member to change the type of the control.
	 * @param pControl Pointer to a CXTPControl object
	 * @param type Type to be changed to.
	 * @return
	 * A pointer to a CXTPControl object.
	 */
	CXTPControl* SetControlType(CXTPControl* pControl, XTPControlType type);

	/**
	 * @brief
	 * Call this member to change the type of the control.
	 * @param nIndex Index of the control.
	 * @param type Type to be changed to.
	 * @return
	 * A pointer to a CXTPControl object.
	 */
	CXTPControl* SetControlType(int nIndex, XTPControlType type);

	/**
	 * @brief
	 * Call this member to add a copy of a control.
	 * @param pClone Pointer to the CXTPControl object to copy.
	 * @param nBefore Index of the control to be inserted.
	 * @param bRecursive TRUE to copy recursively.
	 * @return
	 * A pointer to the added CXTPControl object.
	 */
	CXTPControl* AddClone(CXTPControl* pClone, int nBefore = -1, BOOL bRecursive = FALSE);

	/**
	 * @brief
	 * This method is called internally to reposition controls and
	 * determine their size.
	 * @param pDC      Pointer to a valid device context.
	 * @param nLength  Length of the parent bar.
	 * @param dwMode   Mode of the parent bar.
	 * @param rcBorder Borders of commandbar.
	 * @param nWidth   Width of the parent bar.
	 * @return
	 * Total size of the controls.
	 */
	CSize CalcDynamicSize(CDC* pDC, int nLength, DWORD dwMode, const CRect& rcBorder,
						  int nWidth = 0);

	/**
	 * @brief
	 * This method is called internally to reposition controls and
	 * determine their size for a pop-up bar.
	 * @param pDC      Pointer to a valid device context.
	 * @param nLength  Length of the parent bar.
	 * @param nWidth   Width of the parent bar.
	 * @param rcBorder Borders of pop-up bar.
	 * @return
	 * Total size of the controls.
	 * @see
	 * CalcDynamicSize
	 */
	CSize CalcPopupSize(CDC* pDC, int nLength, int nWidth, const CRect& rcBorder);

	/**
	 * @brief
	 * Call this member to get the number of visible controls.
	 * @param bIgnoreWrap TRUE to ignore controls that are wrapped.
	 * @return
	 * Number of visible controls.
	 */
	int GetVisibleCount(BOOL bIgnoreWrap = FALSE) const;

	/**
	 * @brief
	 * Finds a specified control by its ID.
	 * @param nIndex Control's identifier
	 * @param bIgnoreWraps TRUE to ignore controls that are wrapped
	 * @return
	 * Pointer to the CXTPControl object if successful, otherwise NULL.
	 */
	CXTPControl* GetVisibleAt(int nIndex, BOOL bIgnoreWraps = FALSE) const;

	/**
	 * @brief
	 * Call this member to attach the specified command bars object.
	 * @param pCommandBars Command bars object to attach.
	 * @details
	 * You can call this member if you create a plain toolbar and
	 * want to set CommandBars for it.
	 */
	void SetCommandBars(CXTPCommandBars* pCommandBars);

	/**
	 * @brief
	 * Makes a copy of all controls.
	 * @param bRecursive TRUE to copy recursively.
	 * @return
	 * A pointer to a CXTPControls object.
	 */
	CXTPControls* Duplicate(BOOL bRecursive = FALSE);

	/**
	 * @brief
	 * This method is called to copy the control.
	 * @param pControls Controls to be copied.
	 * @param bRecursive TRUE to copy recursively.
	 */
	virtual void Copy(CXTPControls* pControls, BOOL bRecursive = FALSE);

	/**
	 * @brief
	 * Retrieves the parent command bars object.
	 * @return
	 * A pointer to a CXTPCommandBars object.
	 */
	CXTPCommandBars* GetCommandBars() const;

	/**
	 * @brief
	 * Moves the control to a specified position.
	 * @param pControl Pointer to a CXTPControl object.
	 * @param nBefore  Index to be moved.
	 */
	void MoveBefore(CXTPControl* pControl, int nBefore);

	/**
	 * @brief
	 * Attaches the parent command bar.
	 * @param pParent Pointer to a CXTPCommandBar object.
	 */
	void SetParent(CXTPCommandBar* pParent);

	/**
	 * @brief
	 * Creates the original controls set.
	 */
	void CreateOriginalControls();

	/**
	 * @brief
	 * Removes the original controls set.
	 */
	void ClearOriginalControls();

	/**
	 * @brief
	 * Retrieves the original controls set.
	 * @return
	 * A pointer to a CXTPControls object.
	 */
	CXTPOriginalControls* GetOriginalControls() const;

	/**
	 * @brief
	 * Call this method to assign original controls.
	 * @param pControls A pointer to a CXTPControls object to assign.
	 */
	void SetOriginalControls(CXTPOriginalControls* pControls);

	/**
	 * @brief
	 * Call this member to compare the controls.
	 * @param pControls Pointer to a CXTPControls object.
	 * @return
	 * TRUE if the controls are identical, otherwise FALSE.
	 */
	BOOL Compare(const CXTPControls* pControls);

	/**
	 * @brief
	 * Returns the changed status flag of the control.
	 * @return
	 * TRUE if the internal control state was changed since the last drawing,
	 * otherwise FALSE.
	 */
	BOOL IsChanged() const;

	/**
	 * @brief
	 * Either reads this object from or writes this object to an archive.
	 * @param pPX A CXTPPropExchange object to serialize to or from.
	 */
	virtual void DoPropExchange(CXTPPropExchange* pPX);

	/**
	 * @brief
	 * Call this method to check if the control has been changed and must be saved.
	 * @param pControl Control to be checked if it has been changed and must be saved.
	 * @return
	 * TRUE if the control must be saved, otherwise FALSE.
	 */
	virtual BOOL ShouldSerializeControl(CXTPControl* pControl);

	/**
	 * @brief
	 * Call this member to get the parent command bar.
	 * @return
	 * The parent command bar object.
	 */
	CXTPCommandBar* GetParent() const;

	/**
	 * @brief
	 * Determines if all controls in the collection are original
	 * (i.e. not added or modified by the user).
	 * @return
	 * TRUE if all controls in the collection were added at the time of
	 * creation or from the last time CreateOriginalControls was called.
	 */
	BOOL IsOriginalControls() const;

	/**
	 * @brief
	 * Sorts the commands list.
	 */
	void Sort();

protected:
	/**
	 * @brief
	 * This method is called when a control is added to the collection.
	 * @param pControl Control that was added to the collection.
	 */
	virtual void OnControlAdded(CXTPControl* pControl);

	/**
	 * @brief
	 * This method is called when a control is removed from the collection.
	 * @param pControl Control that was removed from the collection.
	 */
	virtual void OnControlRemoved(CXTPControl* pControl);

	/**
	 * @brief
	 * This method is called when a control is about to be removed from the collection.
	 * @param pControl Control to be removed from the collection.
	 * @return
	 * TRUE to cancel removing the control.
	 */
	virtual BOOL OnControlRemoving(CXTPControl* pControl);

	/** @cond */
protected:
	virtual void RefreshIndexes();
	static int AFX_CDECL CompareByCaption(const CXTPControl** ppItem1, const CXTPControl** ppItem2);

protected:
	void GenerateCommandBarList(DWORD& nID, CXTPCommandBarList* pCommandBarList,
								XTP_COMMANDBARS_PROPEXCHANGE_PARAM* pParam);
	void RestoreCommandBarList(CXTPCommandBarList* pCommandBarList);
	CSize _CalcSize(XTPBUTTONINFO* pData, BOOL bVert);
	int _WrapToolBar(XTPBUTTONINFO* pData, int nWidth, DWORD& dwMode);
	void _SizeFloatableBar(XTPBUTTONINFO* pData, int nLength, DWORD dwMode);
	void _AdjustBorders(XTPBUTTONINFO* pData, CSize& sizeResult, DWORD dwMode, CRect rcBorder);
	void _CenterControlsInRow(XTPBUTTONINFO* pData, int nFirst, int nLast, int, BOOL,
							  CSize sizeResult, CRect);
	void _MoveRightAlligned(XTPBUTTONINFO* pData, CSize sizeResult, CRect rcBorder, DWORD dwMode);
	void _SizePopupToolBar(XTPBUTTONINFO* pData, DWORD dwMode);

	CSize _CalcSmartLayoutToolBar(CDC* pDC, XTPBUTTONINFO* pData, DWORD& dwMode);
	CSize _WrapSmartLayoutToolBar(CDC* pDC, XTPBUTTONINFO* pData, int nWidth, DWORD& dwMode);
	CSize _ReduceSmartLayoutToolBar(CDC* pDC, XTPBUTTONINFO* pData, int nWidth, DWORD& dwMode);
	void _MakeSameWidth(int nStart, int nLast, int nWidth);
	/** @endcond */

protected:
	CXTPCommandBar* m_pParent;						  /**< Parent Command Bar. */
	CArray<CXTPControl*, CXTPControl*> m_arrControls; /**< Collection of controls. */
	CXTPCommandBars* m_pCommandBars;				  /**< Parent Command Bars. */
	CXTPOriginalControls* m_pOriginalControls;		  /**< Original controls collection. */
	BOOL m_bOriginalControls; /**< TRUE if all controls are original and unmodified. */
#	ifdef _XTP_COMMANDBARS_ACTIVEX
public:
	/** @cond */

	CArray<CXTPControl*, CXTPControl*>* CXTPControls::GetArray()
	{
		return &m_arrControls;
	}

	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPControls);

	afx_msg long OleGetItemCount();
	afx_msg LPDISPATCH OleItem(long nIndex);
	afx_msg LPDISPATCH OleGetItem(long nIndex);
	afx_msg LPDISPATCH OleAdd(long controlType, int nId, LPCTSTR strCaption, const VARIANT& pBefore,
							  const VARIANT& pTemporary);
	afx_msg void OleAddControl(LPDISPATCH Control, const VARIANT& pBefore);
	DECLARE_ENUM_VARIANT(CXTPControls)

	afx_msg LPDISPATCH OleParent();
	afx_msg LPDISPATCH OleGetOriginalControls();
	afx_msg LPDISPATCH OleFindControl(const VARIANT& varType, const VARIANT& varId,
									  const VARIANT& varVisible, const VARIANT& varRecursive);

	enum
	{
		dispidCount		  = 1L,
		dispidAdd		  = 2L,
		dispidParent	  = 3L,
		dispidFindControl = 4L,
	};

/** @endcond */
#	endif

	friend class CXTPCommandBar;
	friend class CXTPCommandBars;
	friend class CXTPToolBar;
	friend class CXTPMenuBar;
	friend class CXTPRibbonBar;
};

/**
 * @brief
 * CXTPOriginalControls object.
 */
class _XTP_EXT_CLASS CXTPOriginalControls : public CXTPControls
{
	/** @cond */
	DECLARE_DYNCREATE(CXTPOriginalControls)
	/** @endcond */
public:
	/**
	 * @brief
	 * Constructs a CXTPOriginalControls object.
	 */
	CXTPOriginalControls();

	friend class CXTPControls;
};

//////////////////////////////////////////////////////////////////////////

AFX_INLINE CXTPControl* CXTPControls::GetAt(int nIndex) const
{
	_ASSERTE(nIndex < m_arrControls.GetSize());
	return (nIndex >= 0 && nIndex < m_arrControls.GetSize()) ? m_arrControls.GetAt(nIndex) : NULL;
}
AFX_INLINE int CXTPControls::GetCount() const
{
	return (int)m_arrControls.GetSize();
}
AFX_INLINE CXTPOriginalControls* CXTPControls::GetOriginalControls() const
{
	return m_pOriginalControls;
}
AFX_INLINE CXTPCommandBar* CXTPControls::GetParent() const
{
	return m_pParent;
}
AFX_INLINE BOOL CXTPControls::IsOriginalControls() const
{
	return m_bOriginalControls;
}
/** @cond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif // #if !defined(__XTPCONTROLS_H__)
	   /** @endcond */