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

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

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

class CXTPShortcutListBoxTheme;
class CXTPImageManagerIcon;

/**
 * @brief
 * CCXTPShortcutListBox is a CListBox derived class. It is used to implement
 * an Outlook bar style control. It can only be used with the LBS_OWNERDRAWVARIABLE
 * style bit set. This is a simpler version of CXTOutBarCtrl and does not
 * allow for shortcut folders.
 */
class _XTP_EXT_CLASS CXTPShortcutListBox : public CListBox
{
	/** @cond */
	DECLARE_DYNAMIC(CXTPShortcutListBox)
	/** @endcond */
public:
	/**
	 * @brief
	 * CONTENT_ITEM structure is used by the CXTPShortcutListBox
	 * class to maintain information about a particular menu item.
	 * @see
	 * CXTPShortcutListBox
	 */
	struct CONTENT_ITEM
	{
		/** @cond */
		CONTENT_ITEM();
		~CONTENT_ITEM();
		/** @endcond */

		int m_nIndex;				   /**< Zero-based index for the menu item. */
		BOOL m_bEnabled;			   /**< TRUE if the menu item is enabled. */
		CString m_strText;			   /**< Text label for the menu item. */
		CXTPImageManagerIcon* m_pIcon; /**< Icon handle for the menu item. */
	};

	/**
	 * @brief
	 * List for maintaining CONTENT_ITEM structures.
	 * @details
	 * CList definition used by the CXTPShortcutListBox class to maintain
	 * a list of CONTENT_ITEM structures representing each menu item
	 * defined for the menu list box control.
	 * @see
	 * CXTPShortcutListBox, CXTPShortcutListBox::InsertMenuItem, CONTENT_ITEM
	 */
	typedef CList<CONTENT_ITEM*, CONTENT_ITEM*> CContentItemList;

public:
	/**
	 * @brief
	 * Constructs a CXTPShortcutListBox object.
	 */
	CXTPShortcutListBox();

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

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.
	 * @details
	 * eTheme 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.
	 * @return TRUE if successful; otherwise FALSE.
	 */
	BOOL SetTheme(XTPControlTheme eTheme);

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

	/**
	 * @brief
	 * This member function creates an Outlook Bar control.
	 * @param dwStyle    Window style.
	 * @param rect       The size and position of the window, in client
	 * coordinates of 'pParentWnd'.
	 * @param pParentWnd The parent window.
	 * @param nID        The ID of the child window.
	 * @return
	 * Nonzero if successful, otherwise zero.
	 */
	virtual BOOL Create(DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, UINT nID);

	/**
	 * @brief
	 * Call this member function to set the text and background colors
	 * for the Outlook bar.
	 * @param clrText     An RGB value representing the text color.
	 * @param clrBack     An RGB value representing the background color.
	 * @param clrBackDark An RGB value representing the dark background color.
	 * If defined, then the background will be drawn
	 * with a gradient effect from crBack to crBackDark.
	 */
	void SetColors(COLORREF clrText, COLORREF clrBack, COLORREF clrBackDark = COLORREF_NULL);

	/**
	 * @brief
	 * This member function inserts a menu item into the Outlook bar. Unlike
	 * the AddMenuItem member function, InsertMenuItem does not cause an
	 * Outlook bar with the LBS_SORT style to be sorted.
	 * @param iIndex Specifies the zero-based index of the position to insert the
	 * menu item. If this parameter is -1, the menu item is added
	 * to the end of the list.
	 * @param nIconID Resource ID of the icon associated with this menu item.
	 * @param lpszText Pointer to the NULL-terminated string for the menu item.
	 * @param bEnabled TRUE if the menu item is enabled.
	 * @return
	 * The zero-based index of the position at which the menu item was inserted.
	 * The return value is LB_ERR if an error occurs. The return value is
	 * LB_ERRSPACE if insufficient space is available to store the new menu item.
	 */
	int InsertMenuItem(int iIndex, UINT nIconID, LPCTSTR lpszText, BOOL bEnabled = TRUE);

	/**
	 * @brief
	 * Call this member function to add a menu item to an Outlook bar. If
	 * the Outlook bar was not created with the LBS_SORT style, then the
	 * menu item is added to the end of the Outlook bar. Otherwise, the
	 * menu item is inserted into the Outlook bar, and the Outlook bar is
	 * sorted. If the Outlook bar was created with the LBS_SORT style but
	 * not the LBS_HASSTRINGS style, then the framework sorts the Outlook
	 * bar by one or more calls to the CompareItem member function. Use
	 * InsertMenuItem to insert a menu item into a specific location within
	 * the Outlook bar.
	 * @param nIconID Resource ID of the icon associated with this menu item.
	 * @param lpszText Pointer to the NULL-terminated string for the menu item.
	 * @param bEnabled TRUE if the menu item is enabled.
	 * @return
	 * The zero-based index to the menu item in the Outlook bar. The return
	 * value is LB_ERR if an error occurs. The return value is LB_ERRSPACE
	 * if insufficient space is available to store the new menu item.
	 */
	int AddMenuItem(UINT nIconID, LPCTSTR lpszText, BOOL bEnabled = TRUE);

	/**
	 * @brief
	 * Call this member function to enable/disable the menu item
	 * specified by <i>iItem</i>.
	 * @param iItem Index of the menu item to enable or disable.
	 * @param bEnabled TRUE to enable the menu item, FALSE to disable.
	 * @return
	 * TRUE if the menu item's enabled state was successfully updated,
	 * otherwise FALSE.
	 */
	BOOL EnableMenuItem(int iItem, BOOL bEnabled);

	/**
	 * @brief
	 * Call this member function to retrieve a CONTENT_ITEM object that
	 * represents the menu item specified by 'iItem'.
	 * @param iItem Specifies the zero-based index of the menu item to retrieve.
	 * @return
	 * A CONTENT_ITEM pointer.
	 */
	CONTENT_ITEM* GetMenuItem(int iItem);

	/**
	 * @brief
	 * Call this member function to set the cursor, text, and border
	 * attributes for a highlighted item.
	 * @param nIDCursor    Resource ID of the highlight cursor.
	 * @param bNoBorder    True if not border is displayed when item is highlighted.
	 * @param bNoUnderline True if text is not underlined when item is highlighted.
	 */
	void SetHighlightCursor(UINT nIDCursor, bool bNoBorder = false, bool bNoUnderline = false);

	/** @cond */
	_XTP_DEPRECATED_IN_FAVOR(SetHighlightCursor)
	void SetHilightCursor(UINT nIDCursor, bool bNoBorder = false, bool bNoUnderline = false)
	{
		SetHighlightCursor(nIDCursor, bNoBorder, bNoUnderline);
	}
	/** @endcond */

	/**
	 * @brief
	 * This member function is called by the outlook bar to determine the
	 * string height for a multi-line text item.
	 * @param lspzItem A NULL-terminated string.
	 * @return
	 * The height, in pixels, of the specified string.
	 */
	int GetTextHeight(LPCTSTR lspzItem) const;

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

	/** @cond */
	DECLARE_MESSAGE_MAP()

	//{{AFX_VIRTUAL(CXTPShortcutListBox)
	virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);
	virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);
	virtual BOOL OnWndMsg(UINT message, WPARAM wParam, LPARAM lParam, LRESULT* pResult);
	//}}AFX_VIRTUAL

	//{{AFX_MSG(CXTPShortcutListBox)
	afx_msg void OnLButtonDown(UINT nFlags, CPoint point);
	afx_msg void OnLButtonUp(UINT nFlags, CPoint point);
	afx_msg void OnMouseMove(UINT nFlags, CPoint point);
	afx_msg void OnWindowPosChanged(WINDOWPOS FAR* lpwndpos);
	afx_msg BOOL OnEraseBkgnd(CDC* pDC);
	afx_msg void OnPaint();
	afx_msg BOOL OnSetCursor(CWnd* pWnd, UINT nHitTest, UINT message);
	afx_msg void OnMouseLeave();
	//}}AFX_MSG
	afx_msg LRESULT OnSetTheme(WPARAM wParam, LPARAM lParam);
	/** @endcond */

private:
	BOOL Create(LPCTSTR lpszClassName, LPCTSTR lpszWindowName, DWORD dwStyle, const RECT& rect,
				CWnd* pParentWnd, UINT nID, CCreateContext* pContext = NULL);
	void RedrawItem(int iIndex);
	void RedrawItem(CPoint point);

public:
	bool m_bNoBorder;	/**< true to disable a border drawn around highlighted items. */
	bool m_bNoUnderline; /**< true if the text is not drawn with a underline when no highlight
							border is displayed. */

protected:
	int m_nPrevIndex;	 /**< Previously selected menu index. */
	int m_bHilightItemID; /**< Index of the currently highlighted item, set to -1 if no selection.
						   */
	bool m_bHilight;	  /**< true when the menu item is selected. */
	bool m_bTimerActive;  /**< true if the redraw timer is active. */
	CPoint m_point;		  /**< Holds the cursor position. */
	CContentItemList m_arContentItems;  /**< Array of CONTENT_ITEM structs that represent each item
										   in the Outlook bar. */
	HCURSOR m_hCursor;					/**< Cursor display when item is hovered over. */
	CXTPShortcutListBoxTheme* m_pTheme; /**< Pointer to the current theme object. */
};

/** @cond */
#	define CXTOutlookBar CXTPShortcutListBox
/** @endcond */

//////////////////////////////////////////////////////////////////////
/** @cond */
AFX_INLINE BOOL CXTPShortcutListBox::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 CXTPShortcutListBoxTheme* CXTPShortcutListBox::GetTheme()
{
	return m_pTheme;
}
/** @endcond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // #if !defined(__XTPSHORTCUTLISTBOX_H__)
	   /** @endcond */