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

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

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

class CXTPRibbonGroup;
class CXTPRibbonTab;

/**
 * @brief
 * Represents a collection of CXTPRibbonGroup objects.
 * @details
 * A CXTPRibbonTab uses the CXTPRibbonGroups object for its groups
 * collection to store all of the RibbonGroup objects that have been
 * added to the RibbonTab. A CXTPRibbonGroup is used to hold items
 * such as buttons, pop-ups, edit controls, etc.
 *
 * Groups are added to the groups collection using the Add
 * and InsertAt methods.
 * @see
 * Add, InsertAt
 */
class _XTP_EXT_CLASS CXTPRibbonGroups : public CXTPCmdTarget
{
public:
	/**
	 * @brief
	 * Constructs a CXTPRibbonGroups object.
	 */
	CXTPRibbonGroups();

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

public:
	/**
	 * @brief
	 * Copies all groups from a CXTPRibbonGroups object.
	 * @param pGroups Pointer to a CXTPRibbonGroups object to copy from.
	 */
	void Copy(CXTPRibbonGroups* pGroups);

	/**
	 * @brief
	 * Removes all groups.
	 * @see
	 * InsertAt, Remove, GetCount, GetAt, Add
	 */
	void RemoveAll();

	/**
	 * @brief
	 * Removes a specified group.
	 * @param nIndex Index of the group to be removed.
	 * @see
	 * InsertAt, Add, GetCount, GetAt, RemoveAll
	 */
	void Remove(int nIndex);

	/**
	 * @brief
	 * Removes a specified group.
	 * @param pGroup Pointer to the group to be removed.
	 * @see
	 * InsertAt, Add, GetCount, GetAt, RemoveAll
	 */
	void Remove(CXTPRibbonGroup* pGroup);

	/**
	 * @brief
	 * Adds a CXTPRibbonGroup to a CXTPRibbonTab at a specific location.
	 * @param nIndex      Position within the tab's groups collection to
	 * insert the new CXTPRibbonGroup.
	 * @param lpszCaption Text to display in the group title bar.
	 * This is the group's caption.
	 * @param nId         Identifier of the new group.
	 * @details
	 * InsertAt adds a group at a specific location within the tab's
	 * groups collection. Groups will be displayed in the order they
	 * are added. This means the group with an index of zero (0) will
	 * be displayed first to the far left, then to the immediate right
	 * will be the group with an index of one (1), and so on.
	 * @return
	 * A pointer to the CXTPRibbonGroup object added to the CXTPRibbonTab
	 * groups collection.
	 * @see
	 * Add, Remove, GetCount, GetAt, RemoveAll
	 */
	CXTPRibbonGroup* InsertAt(int nIndex, LPCTSTR lpszCaption, int nId = -1);

	/**
	 * @brief
	 * Adds a CXTPRibbonGroup to a CXTPRibbonTab at a specific location.
	 * @param nIndex      Position within the tab's groups collection to
	 * insert the new CXTPRibbonGroup.
	 * @param pGroup      New group to insert.
	 * @details
	 * InsertAt adds a group at a specific location within the tab's
	 * groups collection. Groups will be displayed in the order they
	 * are added. This means the group with an index of zero (0) will
	 * be displayed first to the far left, then to the immediate right
	 * will be the group with an index of one (1), and so on.
	 * @return
	 * A pointer to the CXTPRibbonGroup object added to the CXTPRibbonTab
	 * groups collection.
	 * @see
	 * Add, Remove, GetCount, GetAt, RemoveAll
	 */
	CXTPRibbonGroup* InsertAt(int nIndex, CXTPRibbonGroup* pGroup);

	/**
	 * @brief
	 * Adds a CXTPRibbonGroup to a CXTPRibbonTab.
	 * @param lpszCaption Text to display in the group title bar.
	 * This is the group's caption.
	 * @param nId         Identifier of new group.
	 * @details
	 * Tabs in the ribbon bar contain one or more CXTPRibbonGroup objects.
	 * Buttons, pop-ups, etc. can then be added to the groups.
	 * @return
	 * A pointer to the CXTPRibbonGroup object added to the CXTPRibbonTab
	 * groups collection.
	 * @see
	 * InsertAt, Remove, GetCount, GetAt, RemoveAll
	 */
	CXTPRibbonGroup* Add(LPCTSTR lpszCaption, int nId = -1);

	/**
	 * @brief
	 * Retrieves the total number of CXTPRibbonGroup objects that have
	 * been added to the CXTPRibbonTab.
	 * @return
	 * The total number of CXTPRibbonGroup objects that have been added
	 * to the CXTPRibbonTab.
	 * @see
	 * InsertAt, Remove, Add, GetAt, RemoveAll
	 */
	int GetCount() const;

	/**
	 * @brief
	 * Gets the CXTPRibbonGroup object that has been added to the CXTPRibbonTab
	 * at a specified index.
	 * @param nIndex Index of the group to retrieve within the
	 * groups collection.
	 * @details
	 * GetAt retrieves the CXTPRibbonGroup from the m_arrGroups groups collection
	 * that contains all of the CXTPRibbonGroup objects that have been added
	 * to the CXTPRibbonTab.
	 * @return
	 * The CXTPRibbonGroup at the specified index.
	 * @see
	 * InsertAt, Remove, GetCount, Add, RemoveAll
	 */
	CXTPRibbonGroup* GetAt(int nIndex) const;

	/**
	 * @brief
	 * This member function determines which ribbon group, if any,
	 * is at a specified position.
	 * @param point Point to test.
	 * @return
	 * The CXTPRibbonGroup at the specified position, if any,
	 * otherwise NULL.
	 */
	CXTPRibbonGroup* HitTest(CPoint point) const;

	/**
	 * @brief
	 * Gets the CXTPRibbonBar object that the CXTPRibbonGroup belongs to.
	 * @return
	 * A pointer to the CXTPRibbonBar object that the CXTPRibbonGroup
	 * belongs to. This is the ribbon bar that the group is displayed in.
	 * @see
	 * CXTPRibbonBar
	 */
	CXTPRibbonBar* GetRibbonBar() const;

	/**
	 * @brief
	 * Gets the CXTPRibbonTab object that the CXTPRibbonGroup belongs to.
	 * @return
	 * A pointer to the CXTPRibbonTab object that the CXTPRibbonGroup
	 * belongs to. This is the tab that the group is displayed in.
	 * @see
	 * CXTPRibbonTab
	 */
	CXTPRibbonTab* GetParentTab() const;

	/**
	 * @brief
	 * This method is called internally to reposition groups and controls.
	 * @param pDC      Pointer to a valid device context.
	 * @param nLength  Length of the parent bar.
	 * @param dwMode   Mode of the parent bar.
	 * @param rcBorder Border to be set.
	 * @see
	 * CXTPRibbonBar::RepositionGroups
	 */
	void CalcDynamicSize(CDC* pDC, int nLength, DWORD dwMode, const CRect& rcBorder);

	/**
	 * @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);

public:
	/**
	 * @brief
	 * Gets the group scroll position.
	 * @return
	 * The group scroll position.
	 */
	int GetScrollPos() const;

protected:
	/** @cond */
	int _CalcSmartLayoutToolBar(int* pWidth);
	void _ReduceSmartLayoutToolBar(CDC* pDC, int* pWidth, int nWidth);
	/** @endcond */

private:
	void RefreshIndexes();

protected:
#	ifdef _XTP_COMMANDBARS_ACTIVEX
	/** @cond */

	afx_msg LPDISPATCH OleInsertGroup(int nIndex, LPCTSTR lpszTitle, int nId);
	afx_msg long OleGetItemCount();
	afx_msg LPDISPATCH OleGetItem(int nIndex);
	afx_msg LPDISPATCH OleAddGroup(LPCTSTR lpszTitle, int nId);
	afx_msg LPDISPATCH OleGetRibbonTab();
	afx_msg void OleRemoveAt(int nIndex);

	DECLARE_DISPATCH_MAP()
	DECLARE_OLETYPELIB_EX(CXTPRibbonGroups);
	DECLARE_INTERFACE_MAP()
	DECLARE_ENUM_VARIANT(CXTPRibbonGroups);

/** @endcond */
#	endif

protected:
	CArray<CXTPRibbonGroup*, CXTPRibbonGroup*> m_arrGroups; /**< Collection of groups. */
	CXTPRibbonTab* m_pParentTab; /**< A pointer to the CXTPRibbonTab object the CXTPRibbonGroup
									belongs to. This is the tab that the group is displayed in. */
	int m_nGroupsScrollPos;		 /**< Group scroll position. */
	friend class CXTPRibbonTab;
	friend class CXTPRibbonBar;
};

AFX_INLINE int CXTPRibbonGroups::GetCount() const
{
	return (int)m_arrGroups.GetSize();
}
AFX_INLINE CXTPRibbonGroup* CXTPRibbonGroups::GetAt(int nIndex) const
{
	_ASSERTE(nIndex < m_arrGroups.GetSize());
	return (nIndex >= 0 && nIndex < m_arrGroups.GetSize()) ? m_arrGroups.GetAt(nIndex) : NULL;
}
AFX_INLINE CXTPRibbonTab* CXTPRibbonGroups::GetParentTab() const
{
	return m_pParentTab;
}
AFX_INLINE int CXTPRibbonGroups::GetScrollPos() const
{
	return m_nGroupsScrollPos;
}

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