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

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

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

/**
 * @brief
 * Constants used by the CXTPListBox control to determine the current
 * theme style that has been set.
 */
enum XTPListBoxStyle
{
	xtpListBoxStandard,							 /**< Default theme. */
	xtpListBoxOfficeXP,							 /**< Office XP style theme. */
	xtpListBoxOffice2007,						 /**< Office 2007 style theme. */
	xtpListBoxOffice2013,						 /**< Office 2013 style theme. */
	xtpListBoxOffice2016 = xtpListBoxOffice2013, /**< Office 2016 style theme. */
	xtpListBoxVisualStudio2015,					 /**< Visual Studio 2015 style theme. */
	xtpListBoxVisualStudio2017,					 /**< Visual Studio 2017 style theme. */
	xtpListBoxVisualStudio2019,					 /**< Visual Studio 2019 style theme. */
	xtpListBoxVisualStudio2022,					 /**< Visual Studio 2022 style theme. */
	xtpListBoxNativeWindows10,					 /**< Native Windows 10 style theme. */
	xtpListBoxNativeWindows11,					 /**< Native Windows 11 style theme. */
};

class CXTPListBox;

/**
 * @brief
 * CXTPListBoxTheme is the base class used by CXTPListBox themes to draw
 * the list box control.
 */
class _XTP_EXT_CLASS CXTPListBoxTheme
{
public:
	/**
	 * @brief
	 * Handles theme destruction.
	 */
	virtual ~CXTPListBoxTheme()
	{
	}

	/**
	 * @brief
	 * This method is called to draw the CXTPListBox object.
	 * @param pDC      Pointer to a valid device context.
	 * @param pListBox Pointer to a valid CXTPListBox object.
	 * @param lpDIS    A long pointer to a DRAWITEMSTRUCT structure. The
	 * structure contains information about the item to be
	 * drawn and the type of drawing required.
	 */
	virtual void DrawItem(CDC* pDC, CXTPListBox* pListBox, LPDRAWITEMSTRUCT lpDIS) = 0;

	/**
	 * @brief
	 * This method is called to draw text for the CXTPListBox object.
	 * @param pDC      Pointer to a valid device context.
	 * @param rcText   Size of the area to draw the text to.
	 * @param pListBox Pointer to a valid CXTPListBox object.
	 * @param lpDIS    A long pointer to a DRAWITEMSTRUCT structure. The
	 * structure contains information about the item to be
	 * drawn and the type of drawing required.
	 */
	virtual void DrawItemText(CDC* pDC, CRect rcText, CXTPListBox* pListBox,
							  LPDRAWITEMSTRUCT lpDIS);

	/**
	 * @brief
	 * Called to update the colors and metrics used to draw the
	 * CXTPListBox object.
	 */
	virtual void RefreshMetrics() = 0;

	/**
	 * @brief
	 * Called to retrieve the background color for the list box.
	 * @return
	 * An RGB value representing the background color.
	 */
	virtual COLORREF GetBackColor();

	/**
	 * @brief
	 * Call this member function to draw the list control borders.
	 * @param pDC Pointer to a valid device context.
	 * @param rc  Size of the area to draw.
	 * @return
	 * TRUE if non-client border drawing is handled, otherwise FALSE.
	 */
	virtual BOOL DrawNcBorders(CDC* pDC, CRect rc);
};

/**
 * @brief
 * CXTPListBox is a CListBox derived class. CXTPListBox extends the
 * standard list box control to enable flicker free drawing.
 */
class _XTP_EXT_CLASS CXTPListBox : public CListBox
{
	/** @cond */
	DECLARE_DYNAMIC(CXTPListBox)
	/** @endcond */
public:
	/**
	 * @brief
	 * Constructs a CXTPListBox object.
	 */
	CXTPListBox();

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

public:
	/**
	 * @brief
	 * Call this member function to initialize the list box. This method
	 * should be called directly after creating or sub-classing the control.
	 * @param bAutoFont true to enable automatic font initialization.
	 */
	virtual void Initialize(bool bAutoFont = true);

	/**
	 * @brief
	 * Called to retrieve the background color for the list box.
	 * @return
	 * An RGB value representing the background color.
	 */
	virtual COLORREF GetBackColor();

	/**
	 * @brief
	 * Call this method to set the style of the list box.
	 * @param style An XTPListBoxStyle constant used to specify which theme to be
	 * used by the control. This method is here only for backward
	 * compatibilty with older versions and may be removed with a
	 * future release. Plese use the SetTheme() method instead.
	 * @see
	 * XTPListBoxStyle, GetListStyle, SetTheme
	 */
	void SetListStyle(XTPListBoxStyle style);

	/**
	 * @brief
	 * Call this method to retrieve the style of the list box.
	 * @return
	 * An XTPListBoxStyle value that contains the style of the list box.
	 * @see
	 * XTPListBoxStyle, SetListStyle
	 */
	XTPListBoxStyle GetListStyle() const;

	/**
	 * @brief
	 * This member function sets the drawing theme for the control.
	 * @param nTheme A XTPControlTheme constant used to specify which theme
	 * is to be used for the control.
	 * @see
	 * XTPControlTheme
	 */
	void SetTheme(XTPControlTheme nTheme);

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

	/**
	 * @brief
	 * Call this member function to determine if the list box control
	 * has input focus.
	 * @return
	 * TRUE if the list box has focus, otherwise FALSE.
	 */
	BOOL HasFocus() const;

protected:
	/**
	 * @brief
	 * This method determines the list box item nearest to the point
	 * specified in pt when there is at least one item in the list box.
	 * @param pt Specifies the point for which to find the nearest item,
	 * specified relative to the upper-left corner of the client
	 * area of the list box.
	 * @param bOutside Specifies the reference to a BOOL variable which will
	 * be set to TRUE if pt is outside the client area of
	 * the list box, FALSE if pt is inside the client area
	 * of the list box.
	 * @param nIndex Receives the index of the item that was nearest to the
	 * point specified in pt if successful, otherwise -1.
	 * @return
	 * TRUE if an item is detected at the specified point, otherwise FALSE.
	 */
	BOOL TryItemFromPoint(CPoint pt, BOOL& bOutside, int& nIndex) const;

	/** @cond */
	DECLARE_MESSAGE_MAP()

	BOOL m_bPreSubclassInit;

	//{{AFX_VIRTUAL(CXTPListBox)
	virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);
	virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);
	virtual BOOL PreCreateWindow(CREATESTRUCT& cs);
	virtual void PreSubclassWindow();
	virtual void Init();
	//}}AFX_VIRTUAL

	//{{AFX_MSG(CXTPListBox)
	afx_msg BOOL OnEraseBkgnd(CDC* pDC);
	afx_msg void OnPaint();
	afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct);
	afx_msg LRESULT OnPrintClient(WPARAM wParam, LPARAM lParam);
	afx_msg void OnMouseLeave();
	afx_msg void OnMouseMove(UINT nFlags, CPoint point);
	afx_msg void OnSetFocus(CWnd* pOldWnd);
	afx_msg void OnKillFocus(CWnd* pNewWnd);
	afx_msg LRESULT OnSetTheme(WPARAM wParam, LPARAM lParam);
	afx_msg void OnNcPaint();
	//}}AFX_MSG
	/** @endcond */

public:
	CXTPListBoxTheme* m_pTheme; /**< Pointer to the currently active theme. */
	XTPControlTheme m_theme;	/**< List box theme. */
	int m_nItemHeight;			/**< Height of the items. */
	int m_nTextPadding;			/**< Text padding. */
	int m_nHotItem;				/**< Hot item index. */
};

/////////////////////////////////////////////////////////////////////////////
// CXTPScrollableListBoxT

/**
 * @brief
 * An adaptor for any CListBox derived control that overrides standard
 * scrollbars with custom scrollbars.
 * @param ListBoxBase Base CListBox derived class name.
 * @see
 * CXTPScrollable
 */
template<class ListBoxBase>
class CXTPScrollableListBoxT : public CXTPScrollable<ListBoxBase>
{
public:
	/**
	 * @brief
	 * Initializes scrollable control instance.
	 */
	CXTPScrollableListBoxT();

	using CXTPScrollable<ListBoxBase>::GetRuntimeClass;

protected:
	/** @cond */
	virtual DWORD FilterStyle(DWORD dwStyle) const;
	virtual BOOL RequiresMouseWheelOverriding() const;
	/** @endcond */
};

/**
 * @brief
 * Type alias for a CXTPListBox derived scrollable control.
 */
typedef CXTPScrollableListBoxT<CXTPListBox> CXTPScrollableListBox;
/** @cond */
template<class ListBoxBase>
AFX_INLINE CXTPScrollableListBoxT<ListBoxBase>::CXTPScrollableListBoxT()
{
	_ASSERTE(GetRuntimeClass()->IsDerivedFrom(RUNTIME_CLASS(CListBox)));
}

template<class ListBoxBase>
AFX_INLINE DWORD CXTPScrollableListBoxT<ListBoxBase>::FilterStyle(DWORD dwStyle) const
{
	return dwStyle & ~(WS_VSCROLL | WS_HSCROLL);
}

template<class ListBoxBase>
AFX_INLINE BOOL CXTPScrollableListBoxT<ListBoxBase>::RequiresMouseWheelOverriding() const
{
	return TRUE;
}
/** @endcond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // #if !defined(__XTPLISTBOX_H__)
	   /** @endcond */