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

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

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

class CXTPRibbonGroups;
class CXTPRibbonBar;
class CXTPRibbonGroup;
class CXTPRibbonTab;
class CXTPCommandBar;
class CXTPPropExchange;

/**
 * @brief
 * Ribbon tab context color
 *
 * <b>Example:</b>
 * <pre>
 * pTab = pRibbonBar->AddTab(ID_TAB_CHARTFORMAT);
 * pTab->SetContextTab(xtpRibbonTabContextColorGreen, ID_TAB_CONTEXTCHART);
 * </pre>
 * @see
 * CXTPRibbonTab, CXTPRibbonTab::SetContextColor
 */
enum XTPRibbonTabContextColor
{
	xtpRibbonTabContextColorNone,   /**< Default color.		   */
	xtpRibbonTabContextColorBlue,   /**< Blue context color.   */
	xtpRibbonTabContextColorYellow, /**< Yellow context color. */
	xtpRibbonTabContextColorGreen,  /**< Green context color.  */
	xtpRibbonTabContextColorRed,	/**< Red context color.	   */
	xtpRibbonTabContextColorPurple, /**< Purple context color. */
	xtpRibbonTabContextColorCyan,   /**< Cyan context color.   */
	xtpRibbonTabContextColorOrange  /**< Orange context color. */
};

/** @cond */

// Context headers internal classes

class _XTP_EXT_CLASS CXTPRibbonTabContextHeader
{
public:
	CXTPRibbonTabContextHeader(CXTPRibbonTab* pFirstTab);

public:
	CXTPRibbonTab* m_pFirstTab;
	CXTPRibbonTab* m_pLastTab;
	CString m_strCaption;
	XTPRibbonTabContextColor m_color;
	CRect m_rcRect;
};

class _XTP_EXT_CLASS CXTPRibbonTabContextHeaders
{
public:
	CXTPRibbonTabContextHeaders();
	~CXTPRibbonTabContextHeaders();

public:
	void RemoveAll();
	int GetCount() const;
	void Add(CXTPRibbonTabContextHeader* pHeader);
	CXTPRibbonTabContextHeader* GetHeader(int nIndex) const;
	CXTPRibbonTabContextHeader* HitTest(CPoint pt) const;

protected:
	CArray<CXTPRibbonTabContextHeader*, CXTPRibbonTabContextHeader*> m_arrHeaders;
};
/** @endcond */

/**
 * @brief
 * Represents a tab in the Ribbon Bar.
 * @details
 * Tabs in the ribbon bar are used to display different groups of items.
 * The CXTPRibbonBar.InsertTab method adds a new CXTPRibbonTab object to
 * the tabs collection of the ribbon bar.
 *
 * Tabs in the ribbon bar contain one or more CXTPRibbonGroup objects.
 * Buttons, pop-ups, etc. can then be added to the groups.
 *
 * The CXTPRibbonBar::GetTabCount property can be used to determine the
 * total number of tabs that have been added.
 * @see
 * CXTPRibbonBar.InsertTab, CXTPRibbonBar::GetTabCount, CXTPRibbonBar::GetTab
 */
class _XTP_EXT_CLASS CXTPRibbonTab : public CXTPTabManagerItem
{
	/** @cond */
	DECLARE_SERIAL(CXTPRibbonTab)
	/** @endcond */
public:
	/**
	 * @brief
	 * Constructs a CXTPRibbonTab object.
	 */
	CXTPRibbonTab();

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

public:
	/**
	 * @brief
	 * Gets the collection of CXTPRibbonGroup objects that have been added
	 * to the CXTPRibbonTab.
	 * @details
	 * A CXTPRibbonGroup is used to hold buttons, pop-ups, edit controls,
	 * combo box controls, etc. The group organizes the different types of
	 * controls in a CXTPRibbonTab so it is easy to see what functionality
	 * the controls should perform. Groups are added to the group collection
	 * using the AddGroup and InsertGroup methods. 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 collection of CXTPRibbonGroup objects that have
	 * been added to the CXTPRibbonTab.
	 * @see
	 * CXTPRibbonGroups::GetAt, CXTPRibbonGroups::InsertAt, CXTPRibbonGroups::Add,
	 * CXTPRibbonGroups.GetCount
	 */
	CXTPRibbonGroups* GetGroups() const;

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

	/**
	 * @brief
	 * Gets the parent command bar.
	 * @return
	 * A pointer to the parent CXTPCommandBar object.
	 */
	CXTPCommandBar* GetParent() const;

	/**
	 * @brief
	 * Gets the text caption of the tab.
	 * @return
	 * The text caption of the tab. This is the text displayed in
	 * the tab button.
	 * @see
	 * SetCaption
	 */
	virtual CString GetCaption() const;

	/**
	 * @brief
	 * Copies the tab.
	 * @param pRibbonTab Pointer to a source CXTPRibbonTab object.
	 */
	virtual void Copy(CXTPRibbonTab* pRibbonTab);

	/**
	 * @brief
	 * Adds a CXTPRibbonGroup to a CXTPRibbonTab.
	 * @param lpszCaption Text to display in the group's title bar.
	 * This is the group's caption.
	 * @return
	 * A pointer to the CXTPRibbonGroup object added to the CXTPRibbonTab's
	 * groups collection (CXTPRibbonTab::GetGroups).
	 * @see
	 * CXTPRibbonGroup::SetCaption, CXTPRibbonGroup::SetCaption, CXTPRibbonTab,
	 * CXTPRibbonTab::GetGroups
	 */
	CXTPRibbonGroup* AddGroup(LPCTSTR lpszCaption);

	/**
	 * @brief
	 * Adds a CXTPRibbonGroup to a CXTPRibbonTab.
	 * @param nID         Identifier of the group.
	 * @return
	 * A pointer to the CXTPRibbonGroup object added to the CXTPRibbonTab's
	 * groups collection (CXTPRibbonTab::GetGroups).
	 * @see
	 * CXTPRibbonGroup::SetCaption, CXTPRibbonGroup::SetCaption, CXTPRibbonTab,
	 * CXTPRibbonTab::GetGroups
	 */
	CXTPRibbonGroup* AddGroup(int nID);

	/**
	 * @brief
	 * Retrieves a group by its identifier.
	 * @param nId Identifier of the group to be retrieved.
	 * @return
	 * A pointer to the CXTPRibbonGroup object with the specified identifier.
	 * @see
	 * FindTab
	 */
	CXTPRibbonGroup* FindGroup(int nId) const;

	/**
	 * @brief
	 * Gets the tab color.
	 * @return
	 * The tab color; one of the values defined by the
	 * XTPRibbonTabContextColor enumeration.
	 * @see
	 * XTPRibbonTabContextColor
	 */
	XTPRibbonTabContextColor GetContextColor() const;

	/**
	 * @brief
	 * Sets the tab color.
	 * @param color New tab color; must be one of the values defined by the
	 * XTPRibbonTabContextColor enumeration.
	 * @see
	 * XTPRibbonTabContextColor
	 */
	void SetContextColor(XTPRibbonTabContextColor color);

	/**
	 * @brief
	 * Gets the context tab header text.
	 * @return
	 * The context tab header text.
	 * @see
	 * SetContextCaption, SetContextColor
	 */
	CString GetContextCaption() const;

	/**
	 * @brief
	 * Sets the context tab header text.
	 * @param lpszContextCaption New text to be set.
	 * @see
	 * GetContextCaption
	 */
	void SetContextCaption(LPCTSTR lpszContextCaption);

	/**
	 * @brief
	 * Gets the customize dialog specific tab text.
	 * @return
	 * The customize dialog specific tab text.
	 * @see
	 * GetCaption, SetCaption
	 */
	CString GetCustomizeCaption() const;

	/**
	 * @brief
	 * Sets the customize dialog specific tab text.
	 * @param lpszCustomizeCaption New text to be set.
	 * @see
	 * GetCaption, SetCaption
	 */
	void SetCustomizeCaption(LPCTSTR lpszCustomizeCaption);

	/**
	 * @brief
	 * Sets the customize dialog specific tab text.
	 * @param nCustomizeCaption Resource ID of the new text to be set.
	 * @see
	 * GetCaption, SetCaption
	 */
	void SetCustomizeCaption(UINT nCustomizeCaption);

	/**
	 * @brief
	 * Sets the context tab color and text.
	 * @param color New color to be set.
	 * @param nContextID Resource ID of the new text to be set.
	 * @see
	 * GetContextCaption, GetContextColor
	 */
	void SetContextTab(XTPRibbonTabContextColor color, int nContextID);

	/**
	 * @brief
	 * Sets the context tab color and text.
	 * @param color New color to be set.
	 * @param lpszContextCaption New text to be set.
	 * @see
	 * GetContextCaption, GetContextColor
	 */
	void SetContextTab(XTPRibbonTabContextColor color, LPCTSTR lpszContextCaption = NULL);

	/**
	 * @brief
	 * Gets the tab's ID.
	 * @details
	 * The ID is used to identify the tab.
	 * @return
	 * The tab's ID.
	 * @see
	 * SetID
	 */
	int GetID() const;

	/**
	 * @brief
	 * Sets the tab's ID.
	 * @param nId New ID to be set.
	 * @see
	 * GetID
	 */
	void SetID(int nId);

	/**
	 * @brief
	 * Gets the CXTPRibbonTabContextHeader associated with the tab.
	 * @return
	 * A pointer to the CXTPRibbonTabContextHeader associated with the tab.
	 */
	CXTPRibbonTabContextHeader* GetContextHeader() const;

	/**
	 * @brief
	 * Call this member to show/hide the tab.
	 * @param bVisible TRUE to show the tab, FALSE to hide the tab.
	 * @see
	 * IsVisible
	 */
	virtual void SetVisible(BOOL bVisible);

	/**
	 * @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
	 * Sets the keyboard tip for the control.
	 * @param lpszKeyboardTip New keyboard tip to be set.
	 */
	void SetKeyboardTip(LPCTSTR lpszKeyboardTip);

	/**
	 * @brief
	 * Gets the keyboard tip of the control.
	 * @return
	 * The keyboard tip of the control.
	 */
	CString GetKeyboardTip() const;

protected:
	/**
	 * @brief
	 * This method is called before removing a tab from the ribbon tabs collection.
	 */
	void OnRemoved();

	/**
	 * @brief
	 * Called by the framework to route and dispatch command messages
	 * and to handle the update of command user-interface objects.
	 * @param nID          Command ID.
	 * @param nCode        Command notification code.
	 * @param pExtra       Used according to the value of nCode.
	 * @param pHandlerInfo If not NULL, then OnCmdMsg fills in the pTarget
	 * and pmf members of the pHandlerInfo structure
	 * instead of dispatching the command. Typically,
	 * this parameter should be NULL.
	 * @return
	 * Nonzero if the message is handled, otherwise 0.
	 */
	BOOL OnCmdMsg(UINT nID, int nCode, void* pExtra, AFX_CMDHANDLERINFO* pHandlerInfo);

#	ifdef _XTP_COMMANDBARS_ACTIVEX
	/** @cond */

	LPDISPATCH OleGetRibbonBar();
	LPDISPATCH OleGetGroups();

	DECLARE_DISPATCH_MAP()
	DECLARE_OLETYPELIB_EX(CXTPRibbonTab);
	DECLARE_INTERFACE_MAP()
	void OleGetRect(long* pLeft, long* pTop, long* pRight, long* pBottom);

/** @endcond */
#	endif

protected:
	CXTPRibbonGroups* m_pGroups; /**< Collection of CXTPRibbonGroup objects that have been added to
									the CXTPRibbonTab. */
	CXTPRibbonBar* m_pRibbonBar; /**< The CXTPRibbonBar object the CXTPRibbonTab belongs to. */

	CXTPCommandBar* m_pParent; /**< This is the ribbon bar that the tab is displayed in. */
	int m_nId;				   /**< Identifier of the tab. */
	XTPRibbonTabContextColor m_nContextColor; /**< Context color. */
	CString m_strContextCaption;			  /**< Context caption. */
	CString m_strCustomizeCaption; /**< Caption used by Customize dialog. If empty, a default
									  caption is displayed. */
	CXTPRibbonTabContextHeader* m_pContextHeader; /**< Context header. */
	CString m_strKeyboardTip;					  /**< Keyboard tip. */

	friend class CXTPRibbonBar;
	friend class CXTPRibbonTabContextHeader;
	friend class CXTPRibbonTabPopupToolBar;
	friend class CXTPRibbonControlTab;
};

AFX_INLINE void CXTPRibbonTab::SetKeyboardTip(LPCTSTR lpszKeyboardTip)
{
	m_strKeyboardTip = lpszKeyboardTip;
}
AFX_INLINE CString CXTPRibbonTab::GetKeyboardTip() const
{
	return m_strKeyboardTip;
}

AFX_INLINE CXTPRibbonGroups* CXTPRibbonTab::GetGroups() const
{
	return m_pGroups;
}
AFX_INLINE void CXTPRibbonTab::SetContextTab(XTPRibbonTabContextColor color,
											 LPCTSTR lpszContextCaption)
{
	m_nContextColor		= color;
	m_strContextCaption = lpszContextCaption;
}
AFX_INLINE int CXTPRibbonTab::GetID() const
{
	return m_nId;
}
AFX_INLINE void CXTPRibbonTab::SetID(int nID)
{
	m_nId = nID;
}
AFX_INLINE CString CXTPRibbonTab::GetContextCaption() const
{
	return m_strContextCaption;
}
AFX_INLINE CString CXTPRibbonTab::GetCustomizeCaption() const
{
	return m_strCustomizeCaption.IsEmpty() ? GetCaption() : m_strCustomizeCaption;
}
AFX_INLINE void CXTPRibbonTab::SetCustomizeCaption(LPCTSTR lpszCustomizeCaption)
{
	m_strCustomizeCaption = lpszCustomizeCaption;
}
AFX_INLINE XTPRibbonTabContextColor CXTPRibbonTab::GetContextColor() const
{
	return m_nContextColor;
}
AFX_INLINE void CXTPRibbonTab::SetContextColor(XTPRibbonTabContextColor color)
{
	m_nContextColor = color;
}
AFX_INLINE void CXTPRibbonTab::SetContextCaption(LPCTSTR lpszContextCaption)
{
	m_strContextCaption = lpszContextCaption;
}
AFX_INLINE CXTPRibbonTabContextHeader* CXTPRibbonTab::GetContextHeader() const
{
	return m_pContextHeader;
}
AFX_INLINE CXTPCommandBar* CXTPRibbonTab::GetParent() const
{
	return m_pParent;
}

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