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

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

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

class CXTPCaption;
class CXTPCaptionPopupWnd;
class CXTPCaptionTheme;

#	define XTP_IDC_BTN_CLOSE 100

/**
 * @brief
 * CXTPCaptionButton is a CXTPButton derived class. It is used by the
 * CXTPCaption class to activate a CXTPCaptionPopupWnd window.
 */
class _XTP_EXT_CLASS CXTPCaptionButton : public CXTPButton
{
public:
	/**
	 * @brief
	 * Constructs a CXTPCaptionButton object.
	 */
	CXTPCaptionButton();

	/**
	 * @brief
	 * This member function is called to retrieve a pointer to the parent
	 * caption.
	 * @return
	 * A pointer to a CXTPCaption object.
	 */
	CXTPCaption* GetCaption()
	{
		return m_pCaption;
	}
	/**
	 * @brief
	 * This member function is called to set the pointer to the parent
	 * caption.
	 * @param pCaption A pointer to a CXTPCaption object.
	 */
	void SetCaption(CXTPCaption* pCaption)
	{
		m_pCaption = pCaption;
	}
	virtual BOOL SetTheme(XTPControlTheme eTheme);

	using CXTPButton::SetTheme;

protected:
	CXTPCaption* m_pCaption; /**< A pointer to the parent CXTPCaption. */
};

const DWORD CPWS_EX_GROOVE_EDGE = 0x0001; /**< @see CXTPCaption::Create */
const DWORD CPWS_EX_RAISED_EDGE = 0x0002; /**< @see CXTPCaption::Create */
const DWORD CPWS_EX_CLOSEBUTTON = 0x0004; /**< @see CXTPCaption::Create */

/**
 * @brief
 * CXTPCaption is a CStatic derived class. It is used to create captions
 * or info bars similar to those in Microsoft(r) Outlook.
 */
class _XTP_EXT_CLASS CXTPCaption : public CStatic
{
	/** @cond */
	DECLARE_DYNAMIC(CXTPCaption)
	/** @endcond */
public:
	/**
	 * @brief
	 * Destroys a CXTPCaption object, handles cleanup and deallocation.
	 */
	virtual ~CXTPCaption();

	/**
	 * @brief
	 * Constructs a CXTPCaption object.
	 */
	CXTPCaption();

public:
	/**
	 * @brief
	 * Call this member to switch the visual theme of the control.
	 * @param eTheme New visual theme. Can be any of the values listed in the
	 * Remarks section.
	 * @return TRUE if successful; otherwise FALSE.
	 * @details
	 * nStyle can be one of the following:
	 * <b>xtpControlThemeDefault</b>: Use default theme.
	 * <b>xtpControlThemeOfficeXP</b>: Use Office XP theme.
	 * <b>xtpControlThemeOffice2003</b>: Use Office 2003 theme.
	 */
	BOOL SetTheme(XTPControlTheme eTheme);

	/**
	 * @brief
	 * Call this member to switch the visual theme of the control.
	 * @param pTheme New visual theme.
	 * @return TRUE if successful; otherwise FALSE.
	 */
	BOOL SetTheme(CXTPCaptionTheme* pTheme);

	/**
	 * @brief
	 * Call this member function to get a pointer to the currently selected
	 * theme.
	 * @return
	 * A pointer to a CXTPCaptionTheme object representing the currently
	 * selected theme.
	 */
	CXTPCaptionTheme* GetTheme();

	/**
	 * @brief
	 * This member function is called to determine if the caption is
	 * configured to be used as the application's primary caption.
	 * @return
	 * true if the caption is configured to be used as the application's
	 * primary caption, otherwise false.
	 */
	bool IsAppCaption() const
	{
		return m_bAppCaption;
	}
	/**
	 * @brief
	 * This member function is called to set the flag that indicates
	 * if the caption is the application's primary caption.
	 * @param bAppCaption true to set the flag to indicate that the caption
	 * is the application's primary caption.
	 */
	void SetAppCaption(bool bAppCaption)
	{
		m_bAppCaption = bAppCaption;
	}

	/**
	 * @brief
	 * Call this member function to get a reference to the caption's
	 * close/pop-up button.
	 * @return
	 * A reference to a CXTPCaptionButton object.
	 */
	CXTPCaptionButton& GetCaptionButton();

	/**
	 * @brief
	 * This member function will set the caption bar border, background,
	 * and font colors.
	 * @param clrBorder An RGB value that represents the new border color.
	 * @param clrFace An RGB value that represents the new background color.
	 * @param clrText An RGB value that represents the new font color.
	 */
	virtual void SetCaptionColors(COLORREF clrBorder, COLORREF clrFace, COLORREF clrText);

	/**
	 * @brief
	 * Call this member function to enable Office 2003 visualizations.
	 * @param b2003Colors true to enable Office 2003 visualizations,
	 * false to disable.
	 */
	void SetOffice2003Colors(bool b2003Colors = true);

	/**
	 * @brief
	 * Call this member function to retrieve the current style settings
	 * for the caption.
	 * @return
	 * A DWORD value that represents the current style set for the caption.
	 */
	DWORD GetCaptionStyle() const;

	/**
	 * @brief
	 * Modifies the caption title and appearance.
	 * @param nBorderSize   Specifies size in pixels of the banner border.
	 * @param pFont         Specifies the new caption font.
	 * @param lpszWindText  A NULL-terminated string specifying the new caption
	 * text.
	 * @param hIcon         Handle of the icon to be drawn in the caption.
	 * @details
	 * You can use this member function to set the border size that is
	 * drawn around the caption banner, the font that the caption will
	 * use, the caption text, and the icon to be displayed.
	 */
	virtual void ModifyCaptionStyle(int nBorderSize, CFont* pFont = NULL,
									LPCTSTR lpszWindText = NULL, HICON hIcon = NULL);

	/**
	 * @brief
	 * Call this member function to set the child and notification windows
	 * for the caption bar.
	 * @param pChild     A CWnd pointer that represents the child window to be
	 * displayed in the pop-up window.
	 * @param pNotifyWnd A CWnd pointer that represents the window to receive
	 * notification messages.
	 */
	virtual void SetChildWindow(CWnd* pChild, CWnd* pNotifyWnd);

	/**
	 * @brief
	 * This member function is called to destroy the pop-up window and
	 * associated children.
	 */
	virtual void KillChildWindow();

	/**
	 * @brief
	 * This member function is called to display the pop-up window and
	 * associated children.
	 * @return
	 * TRUE if the pop-up window is successfully displayed, otherwise FALSE.
	 */
	virtual BOOL ShowPopupWindow();

	/**
	 * @brief
	 * This member function is called to update the text and icon for the
	 * caption bar.
	 * @param lpszWindowText A NULL-terminated string to display in the caption bar.
	 * @param hIcon          Handle of the icon to display in the caption bar.
	 * It can be NULL.
	 */
	virtual void UpdateCaption(LPCTSTR lpszWindowText, HICON hIcon);

	/**
	 * @brief
	 * Creates and initializes the child window associated with the
	 * CXTPCaption object.
	 * @param pParentWnd      Specifies the parent window.
	 * @param lpszWindowName  Pointer to a NULL-terminated character string that contains
	 * the window name. This will be displayed in the caption area.
	 * @param dwExStyle       Specifies caption bar style. See the Remarks section below
	 * for a complete list of available styles.
	 * @param dwStyle         Specifies the control window style. Apply any combination
	 * of caption bar styles to the control.
	 * @param rect            Specifies the position and size of the caption bar. It can
	 * be either a <i>RECT</i> structure or a <i>CRect</i> object.
	 * @param nID             Specifies the caption bar control ID.
	 * @details
	 * This method creates a caption bar window and attaches it to the
	 * CXTPCaption object. You construct a caption bar in two steps.
	 * First, call the constructor, which constructs the CXTPCaption
	 * object. Then call Create, which creates the Window's child window
	 * and attaches it to CXTPCaption. Create initializes the window class
	 * name and window name and registers values for its style, parent,
	 * and ID.<p/>
	 *
	 * Styles to be added or removed can be combined by using the bitwise
	 * OR (|) operator. It can be one or more of the following:
	 * <b>CPWS_EX_GROOVE_EDGE</b>: Show the caption with a sunken border.
	 * <b>CPWS_EX_RAISED_EDGE</b>: Show the caption with a raised 3D border.
	 * <b>CPWS_EX_CLOSEBUTTON</b>: Caption has a close button.
	 * @return
	 * TRUE if successful, otherwise FALSE.
	 */
	virtual BOOL Create(CWnd* pParentWnd, LPCTSTR lpszWindowName,
						DWORD dwExStyle   = CPWS_EX_RAISED_EDGE,
						DWORD dwStyle	 = WS_VISIBLE | SS_CENTER | SS_CENTERIMAGE,
						const CRect& rect = CRect(0, 0, 0, 0), UINT nID = 0xffff);

	/**
	 * @brief
	 * This member function is called to refresh the caption button style.
	 */
	void RefreshButton();

	/**
	 * @brief
	 * This member function retrieves the current caption title.
	 * @return
	 * A reference to a CString object that contains the caption title.
	 */
	const CString& GetCaptionText();

	/**
	 * @brief
	 * Call this member function to see if the caption contains a close button.
	 * @return
	 * TRUE if the caption contains a close button, otherwise FALSE.
	 */
	BOOL HasCloseButton() const;

	/**
	 * @brief
	 * This member function is called to determine the size and location
	 * of the text associated with the caption.
	 * @return
	 * The size and location of the caption text, or an empty rect if
	 * no text is defined.
	 */
	virtual CRect GetTextRect() const;

protected:
	/**
	 * @brief
	 * This member function is called to draw the caption background.
	 * @param pDC    A CDC pointer that represents the current device context.
	 * @param rcItem A CRect reference that represents the size of the area to paint.
	 */
	virtual void DrawCaptionBack(CDC* pDC, CRect& rcItem);

	/**
	 * @brief
	 * This member function is called to paint the caption text.
	 * @param pDC A CDC pointer that represents the current device context.
	 */
	virtual void DrawCaptionText(CDC* pDC);

	/**
	 * @brief
	 * This member function is called to paint the caption icon.
	 * @param pDC    A CDC pointer that represents the current device context.
	 * @param rcItem A CRect reference that represents the size of the area to paint.
	 */
	virtual void DrawCaptionIcon(CDC* pDC, CRect& rcItem);

	/**
	 * @brief
	 * This member function is called to update the caption text.
	 * @param pDC A CDC pointer that represents the current device context.
	 */
	virtual void UpdateCaptionText(CDC* pDC);

	/**
	 * @brief
	 * This member function is called to determine the size and location
	 * of the button associated with the caption.
	 * @return
	 * The size and location of the caption button, or an empty rect
	 * if no button is defined.
	 */
	virtual CRect GetButtonRect() const;

	/**
	 * @brief
	 * Call this member function to refresh theme colors and redraw the control.
	 */
	virtual void RefreshMetrics();

	/** @cond */

	//{{AFX_VIRTUAL(CXTPCaption)
	virtual BOOL OnWndMsg(UINT message, WPARAM wParam, LPARAM lParam, LRESULT* pResult);
	//}}AFX_VIRTUAL

	//{{AFX_MSG(CXTPCaption)
	afx_msg void OnPaint();
	afx_msg LRESULT OnPrintClient(WPARAM wParam, LPARAM /*lParam*/);
	afx_msg BOOL OnEraseBkgnd(CDC* pDC);
	afx_msg void OnWindowPosChanged(WINDOWPOS FAR* lpwndpos);
	afx_msg void OnSysColorChange();
	afx_msg void OnSize(UINT nType, int cx, int cy);
	afx_msg void OnCaptButton();
	afx_msg void OnPushPinButton();
	afx_msg void OnPushPinCancel();
	//}}AFX_MSG
	afx_msg LRESULT OnSetTheme(WPARAM wParam, LPARAM lParam);

	DECLARE_MESSAGE_MAP()
	/** @endcond */

private:
	BOOL Create(LPCTSTR lpszClassName, LPCTSTR lpszWindowName, DWORD dwStyle, const RECT& rect,
				CWnd* pParentWnd, UINT nID, CCreateContext* pContext = NULL);
	BOOL Create(LPCTSTR lpszText, DWORD dwStyle, const RECT& rect, CWnd* pParentWnd,
				UINT nID = 0xffff);

public:
	int m_nBorder;		  /**< Size in pixels for the caption border. */
	COLORREF m_clrBorder; /**< An RGB value that represents the user-defined border color. */
	COLORREF m_clrFace;   /**< An RGB value that represents the user-defined background color. */
	COLORREF m_clrText;   /**< An RGB value that represents the user-defined font color. */

protected:
	int m_nOffset; /**< Size in pixels that the child window should leave for its caption area. */
	bool m_bUserColors; /**< true if the user has specified caption colors other than the default.
						 */
	bool m_bAppCaption; /**< true if the caption is used as the application's primary caption. */
	CWnd* m_pChildWnd;  /**< A CWnd pointer that represents the child window displayed in the pop-up
						   window. */
	CWnd* m_pParentView;  /**< A CWnd pointer that represents the child window's parent view. */
	CWnd* m_pSplitterWnd; /**< A CWnd pointer that represents the splitter window. It is used to
							 track size changes. */
	CSize m_sizeIcon;	 /**< Width and height of the caption icon area. */
	CRect m_rcChild;	  /**< Size of the child window displayed in the pop-up. */
	CRect m_rcParent;	 /**< Size of the child's parent view. */
	CRect m_rcSplitter;   /**< Size of the splitter window. */
	DWORD m_dwExStyle; /**< Border style bits, either CPWS_EX_GROOVE_EDGE | CPWS_EX_RAISED_EDGE. */
	HICON m_hIcon;	 /**< User-defined icon handle. The default value is NULL. */
	CString m_strCaption;			  /**< Text that will be displayed in the caption. */
	CXTPCaptionButton m_btnCaption;   /**< Button used to 'tack' the pop-up window back in place. */
	CXTPCaptionPopupWnd* m_pPopupWnd; /**< Pointer to the pop-up window. */
	CXTPCaptionTheme* m_pTheme;		  /**< Pointer to the current theme object. */
	BOOL m_bSubclassed;				  /**< TRUE if the window was sub-classed. */

	friend class CXTPCaptionButton;
	friend class CXTPCaptionButtonTheme;
	friend class CXTPCaptionTheme;
};

//////////////////////////////////////////////////////////////////////
/** @cond */
AFX_INLINE CXTPCaptionButton& CXTPCaption::GetCaptionButton()
{
	_ASSERTE(::IsWindow(m_btnCaption.m_hWnd));
	return m_btnCaption;
}
AFX_INLINE DWORD CXTPCaption::GetCaptionStyle() const
{
	return m_dwExStyle;
}
AFX_INLINE const CString& CXTPCaption::GetCaptionText()
{
	return m_strCaption;
}
AFX_INLINE BOOL CXTPCaption::HasCloseButton() const
{
	return ((m_dwExStyle & CPWS_EX_CLOSEBUTTON) == CPWS_EX_CLOSEBUTTON);
}
AFX_INLINE BOOL CXTPCaption::Create(LPCTSTR lpszClassName, LPCTSTR lpszWindowName, DWORD dwStyle,
									const RECT& rect, CWnd* pParentWnd, UINT nID,
									CCreateContext* pContext)
{
	return CWnd::Create(lpszClassName, lpszWindowName, dwStyle, rect, pParentWnd, nID, pContext);
}
AFX_INLINE BOOL CXTPCaption::Create(LPCTSTR lpszText, DWORD dwStyle, const RECT& rect,
									CWnd* pParentWnd, UINT nID)
{
	return CStatic::Create(lpszText, dwStyle, rect, pParentWnd, nID);
}
AFX_INLINE CXTPCaptionTheme* CXTPCaption::GetTheme()
{
	return m_pTheme;
}
/** @endcond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // #if !defined(__XTPCAPTION_H__)
	   /** @endcond */