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

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

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

/**
 * @brief
 * Editor type for CXTPPropertyGridItemColor item.
 * @see
 * CXTPPropertyGridItemColor, CXTPPropertyGridItemColor::SetEditorStyle
 *
 * <b>Example:</b>
 * <pre>pItem->SetEditorStyle(xtpPropertyGridItemColorExtendedDialog);</pre>
 */
enum XTPPropertyGridItemColorEditor
{
	xtpPropertyGridItemColorPopup,			/**< Color pop-up editor. */
	xtpPropertyGridItemColorStandardDialog, /**< Standard color dialog editor. */
	xtpPropertyGridItemColorExtendedDialog  /**< Extended color Editor editor. */
};

/**
 * @brief
 * CXTPPropertyGridItemColor is a CXTPPropertyGridItem derived class.
 * It is used to create a COLORREF value item in a Property Grid control.
 */
class _XTP_EXT_CLASS CXTPPropertyGridItemColor : public CXTPPropertyGridItem
{
public:
	/**
	 * @brief
	 * Constructs a CXTPPropertyGridItemColor object.
	 * @param strCaption Caption of the item.
	 * @param clr        Initial COLORREF value of the item.
	 * @param pBindColor If not NULL, then the value of the item
	 * is bound the value of this variable.
	 * @details
	 * Class CXTPPropertyGridItemColor has no default constructor.
	 *
	 * When using the second constructor, the Identifier (nID) of the
	 * second constructor can be linked with a STRINGTABLE resource
	 * with the same ID in such form "Caption\\nDescription".
	 *
	 * BINDING:
	 * Variables can be bound to an item in two ways, the first is
	 * to pass in a variable at the time of creation, the second allows
	 * variables to be bound to an item after creation with the
	 * BindToColor member.
	 *
	 * Bound variables store the values of the property grid items
	 * and can be accessed without using the property grid methods
	 * and properties. Bound variables allow the property grid to
	 * store data in variables. When the value of a PropertyGridItem
	 * is changed, the value of the bound variable will be changed to
	 * the PropertyGridItem value. The advantage of binding is that
	 * the variable can be used and manipulated without using
	 * PropertyGridItem methods and properties.
	 *
	 * NOTE: If the value of the variable is changed without using
	 * the PropertyGrid, the PropertyGridItem value will not be
	 * updated until you call CXTPPropertyGrid::Refresh.
	 * @see
	 * BindToColor
	 */
	CXTPPropertyGridItemColor(LPCTSTR strCaption, COLORREF clr = 0, COLORREF* pBindColor = NULL);

	/**
	 * @brief
	 * Constructs a CXTPPropertyGridItemColor object.
	 * @param nID        Identifier of the item.
	 * @param clr        Initial COLORREF value of the item.
	 * @param pBindColor If not NULL, then the value of the item
	 * is bound the value of this variable.
	 * @details
	 * Class CXTPPropertyGridItemColor has no default constructor.
	 *
	 * When using the second constructor, the Identifier (nID) of the
	 * second constructor can be linked with a STRINGTABLE resource
	 * with the same ID in such form "Caption\\nDescription".
	 *
	 * BINDING:
	 * Variables can be bound to an item in two ways, the first is
	 * to pass in a variable at the time of creation, the second allows
	 * variables to be bound to an item after creation with the
	 * BindToColor member.
	 *
	 * Bound variables store the values of the property grid items
	 * and can be accessed without using the property grid methods
	 * and properties. Bound variables allow the property grid to
	 * store data in variables. When the value of a PropertyGridItem
	 * is changed, the value of the bound variable will be changed to
	 * the PropertyGridItem value. The advantage of binding is that
	 * the variable can be used and manipulated without using
	 * PropertyGridItem methods and properties.
	 *
	 * NOTE: If the value of the variable is changed without using
	 * the PropertyGrid, the PropertyGridItem value will not be
	 * updated until you call CXTPPropertyGrid::Refresh.
	 * @see
	 * BindToColor
	 */
	CXTPPropertyGridItemColor(UINT nID, COLORREF clr = 0, COLORREF* pBindColor = NULL);

	/**
	 * @brief
	 * Destroys a CXTPPropertyGridItemColor object.
	 */
	virtual ~CXTPPropertyGridItemColor();

public:
	/**
	 * @brief
	 * Sets the COLORREF value for the item.
	 * @param clr COLORREF value to be set.
	 */
	virtual void SetColor(COLORREF clr);

	/**
	 * @brief
	 * Gets the COLORREF value of the item.
	 * @return
	 * The COLORREF value of the item.
	 */
	virtual COLORREF GetColor() const;

	/**
	 * @brief
	 * Converts a specified string to a COLORREF.
	 * @param str String to be converted (in the format RRR;GGG;BBB).
	 * @return
	 * The converted COLORREF.
	 */
	static COLORREF AFX_CDECL StringToRGB(LPCTSTR str);

	/**
	 * @brief
	 * Converts a specified COLORREF to a string.
	 * @param clr COLORREF to be coverted.
	 * @return
	 * The converted string (in the format RRR;GGG;BBB).
	 */
	static CString AFX_CDECL RGBToString(COLORREF clr);

	/**
	 * @brief
	 * Binds the item to a specified COLORREF value.
	 * @param pBindColor Pointer to a COLORREF value.
	 * @details
	 * Variables can be bound to an item in two ways, the first is
	 * to pass in a variable at the time of creation, the second allows
	 * variables to be bound to an item after creation with the
	 * BindToColor member.
	 *
	 * Bound variables store the values of the property grid items
	 * and can be accessed without using the property grid methods
	 * and properties. Bound variables allow the property grid to
	 * store data in variables. When the value of a PropertyGridItem
	 * is changed, the value of the bound variable will be changed to
	 * the PropertyGridItem value. The advantage of binding is that
	 * the variable can be used and manipulated without using
	 * PropertyGridItem methods and properties.
	 *
	 * NOTE: If the value of the variable is changed without using
	 * the PropertyGrid, the PropertyGridItem value will not be
	 * updated until you call CXTPPropertyGrid::Refresh.
	 */
	virtual void BindToColor(COLORREF* pBindColor);

public:
	/**
	 * @brief
	 * Sets the editor type for the item.
	 * @param editor Editor type to be set; can be one of the following:
	 *
	 * xtpPropertyGridItemColorPopup          Color pop-up editor.
	 *
	 * xtpPropertyGridItemColorStandardDialog Standard color dialog editor.
	 *
	 * xtpPropertyGridItemColorExtendedDialog Extended color Editor editor.
	 *
	 * @see
	 * GetEditorStyle, XTPPropertyGridItemColorEditor
	 */
	void SetEditorStyle(XTPPropertyGridItemColorEditor editor);

	/**
	 * @brief
	 * Gets the editor type of the item.
	 * @return
	 * The editor type of the item; one of the values defined
	 * by the XTPPropertyGridItemColorEditor enumeration.
	 * @see
	 * SetEditorStyle, XTPPropertyGridItemColorEditor
	 */
	XTPPropertyGridItemColorEditor GetEditorStyle();

protected:
	/**
	 * @brief
	 * This method is called when an item is drawn.
	 * Override this method if needed.
	 * @param dc      Reference to the device context to be used
	 * for rendering an image of the item.
	 * @param rcValue Bounding rectangle of the item.
	 * @return
	 * TRUE if the item is self-drawn.
	 */
	virtual BOOL OnDrawItemValue(CDC& dc, CRect rcValue);

	/**
	 * @brief
	 * Gets the bounding rectangle of the item value's text.
	 * Override this method to change it.
	 * @return
	 * The bounding rectangle of the item value's text.
	 */
	virtual CRect GetValueRect();

	/**
	 * @brief
	 * Sets the value of the item.
	 * Override this method to add new functionality. You should call
	 * the base class version of this function from your override.
	 * @param strValue Value to be set.
	 */
	virtual void SetValue(CString strValue);

	/**
	 * @brief
	 * This method is called when the user presses the in-place button.
	 * Override this method to show an item-specific dialog.
	 * @param pButton Pointer to the button that was pressed.
	 * @details
	 * The in-place button is the button that the user presses to
	 * display the color picker dialog.
	 */
	virtual void OnInplaceButtonDown(CXTPPropertyGridInplaceButton* pButton);

	/**
	 * @brief
	 * This method is called before the item becomes visible in the
	 * property grid.
	 * @details
	 * Before the item is inserted, it is first checked to see if it
	 * is bound to a variable. If it is, then the value of the item
	 * is updated with the value stored in the bound variable.
	 *
	 * OnBeforeInsert is called when an item is inserted,
	 * when a category is inserted, when a category or item is expanded,
	 * and when the sort property has changed.
	 */
	virtual void OnBeforeInsert();

protected:
	COLORREF m_clrValue;	/**< Color value of the item. */
	COLORREF* m_pBindColor; /**< Pointer to the variable bound to this item. */

	XTPPropertyGridItemColorEditor m_colorEditor; /**< Editor type of the item. */

private:
	DECLARE_DYNAMIC(CXTPPropertyGridItemColor)

#	ifdef _XTP_ACTIVEX
	/** @cond */
	afx_msg void OleSetValue(const VARIANT* varValue);
	afx_msg const VARIANT OleGetValue();

	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPPropertyGridItemColor)

	void BindDispatch();
/** @endcond */
#	endif
};

//////////////////////////////////////////////////////////////////////

AFX_INLINE COLORREF CXTPPropertyGridItemColor::GetColor() const
{
	return m_clrValue;
}
/** @cond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif //#if !defined(__XTPPROPERTYGRIDITEMCOLOR_H__)
	   /** @endcond */