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

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

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

/**
 * @brief
 * CXTPPropertyGridItemFlags is a CXTPPropertyGridItem derived class.
 * It is used to create a Flags value item in a Property Grid control.
 * @details
 * A flag item is used to combine multiple boolean values into a
 * single item. When using a flag item, you must add constraints
 * to the flag item. Each constraint will have a value of TRUE or
 * FALSE. The flag item will have an expand button that when clicked
 * will display all boolean constraints for that item. The value of
 * the flag item will be the sum of all the boolean constraints with
 * a value of TRUE.
 *
 * NOTE: Constraint values must be in powers of 2 if you will have an
 * "All" constraint that indicates that the value of all boolean
 * constraints is TRUE or FALSE.
 *
 * In the example below, the flag item's initial value will be 9, this
 * value is stored in CXTPPropertyGridItemFlags::m_nValue and can be
 * set with SetFlags and retrieved with GetFlags. The string value will
 * be "[Windows 98; Windows 95]" and this value is stored in
 * CXTPPropertyGridItem::m_strValue, which can be retrieved
 * with CXTPPropertyGridItem::GetValue. You must use the SetFlags method
 * to change the flag items value by code. The string value is what is
 * displayed to the user.
 *
 *
 * <b>Example:</b>
 * This sample illustrates how to add an item of type Flags to your grid:
 * <pre>
 * //Adds a category to the grid called "Software"
 * CXTPPropertyGridItem* pStandard   = m_wndPropertyGrid.AddCategory(_T("Software"));
 *
 * //Adds a CXTPPropertyGridItemFlags item with a caption of "Supported OS" and an initial value of
 * 9 CXTPPropertyGridItemFlags* pItem = (CXTPPropertyGridItemFlags*)(pStandard->AddChildItem(new
 * CXTPPropertyGridItemFlags(_T("Supported OS"), 1 + 8)));
 *
 * //Adds a constraint that will set all items TRUE or FALSE, note the value of the constraint is
 * the sum
 * //of all the other constraints.  This item will also be updated when the values of the other
 * constraints
 * //have changed.
 * pItem->GetConstraints()->AddConstraint(_T("All Windows"), 1 + 2 + 4 + 8 + 16 + 32);
 *
 * //Adds a constraint that can have a value of TRUE or FALSE
 * pItem->GetConstraints()->AddConstraint(_T("Windows 98"), 1);
 * pItem->GetConstraints()->AddConstraint(_T("Windows 2000"), 2);
 * pItem->GetConstraints()->AddConstraint(_T("Windows XP"), 4);
 * pItem->GetConstraints()->AddConstraint(_T("Windows 95"), 8);
 * pItem->GetConstraints()->AddConstraint(_T("Windows NT"), 16);
 * pItem->GetConstraints()->AddConstraint(_T("Windows 2003"), 32);
 *
 * //This changes the value of the flag item to 21 and the string
 * //caption to [Windows 98; Windows XP; Windows NT]
 * pItem->SetFlags(21);
 *
 * //GetFlags will return the sum of all true constraints
 * TRACE(_T("Flags Item Value= %d\n"), pItem->GetFlags());
 *
 * //GetValue will return a string containing the text of all true constraints
 * TRACE(_T("Flags Item String= %s\n"), pItem->GetValue());
 * </pre>
 *
 * @see
 * CXTPPropertyGridItemFlags::SetFlags, CXTPPropertyGridItemFlags::GetFlags,
 * CXTPPropertyGridItem::GetValue
 */
class _XTP_EXT_CLASS CXTPPropertyGridItemFlags : public CXTPPropertyGridItem
{
public:
	/**
	 * @brief
	 * Constructs a CXTPPropertyGridItemFlag object.
	 * @param strCaption Caption of the item.
	 * @param nValue     Initial value of the item.
	 * See the description of CXTPPropertyGridItemFlags for
	 * a more detailed description of this value.
	 * @param pBindFlags If not NULL, then the value of the item
	 * is bound the value of this variable.
	 * @details
	 * Class CXTPPropertyGridItemFlags 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
	 * BindToFlags 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
	 * BindToFlags
	 */
	CXTPPropertyGridItemFlags(LPCTSTR strCaption, int nValue = 0, int* pBindFlags = NULL);

	/**
	 * @brief
	 * Constructs a CXTPPropertyGridItemFlag object.
	 * @param nID        Identifier of the item.
	 * @param nValue     Initial value of the item.
	 * See the description of CXTPPropertyGridItemFlags for
	 * a more detailed description of this value.
	 * @param pBindFlags If not NULL, then the value of the item
	 * is bound the value of this variable.
	 * @details
	 * Class CXTPPropertyGridItemFlags 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
	 * BindToFlags 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
	 * BindToFlags
	 */
	CXTPPropertyGridItemFlags(UINT nID, int nValue = 0, int* pBindFlags = NULL);

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

	/**
	 * @brief
	 * Sets the value of the item.
	 * @param nValue Value to be set; this should be the sum of the constraint values
	 * that have a value of TRUE (not the text).
	 * See the description of CXTPPropertyGridItemFlags for
	 * a more detailed description of this value.
	 * @details
	 * See CXTPPropertyGridItemFlags for more information.
	 * To set the text, use the SetValue method.
	 * @see
	 * CXTPPropertyGridItemFlags, GetFlags, SetValue
	 */
	virtual void SetFlags(int nValue);

	/**
	 * @brief
	 * Gets the value of the item.
	 * @return
	 * The value of the flag item; this should be the sum of the constraint values
	 * that have a value of TRUE (not the text).
	 * See the description of CXTPPropertyGridItemFlags for
	 * a more detailed description of this value.
	 * @details
	 * See CXTPPropertyGridItemFlags for more information.
	 * To get the text, use the CXTPPropertyGrid::GetValue method.
	 * @see
	 * CXTPPropertyGridItemFlags, SetFlags, CXTPPropertyGrid::GetValue.
	 */
	virtual int GetFlags() const;

	/**
	 * @brief
	 * Binds the item to a specified integer value.
	 * @param pBindFlags Pointer to an integer 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
	 * BindToFlags 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 BindToFlags(int* pBindFlags);

protected:
	/**
	 * @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 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();

	/**
	 * @brief
	 * This method is called when constraints are added to the item
	 * (i.e. when CXTPPropertyGridItemConstraints::AddConstraint is called).
	 * @see
	 * CXTPPropertyGridItemConstraints::AddConstraint
	 */
	virtual void OnConstraintsChanged();

	/**
	 * @brief
	 * Specifies if the item state should be set to read-only or to read/write.
	 * @param bReadOnly TRUE to set the item state to read-only,
	 * FALSE to set the item state to read/write.
	 */
	virtual void SetReadOnly(BOOL bReadOnly);

	/**
	 * @brief
	 * Gets the string notation of the selected flags.
	 * @return
	 * The string notation of the selected flags.
	 */
	virtual CString GetFlagsString();

	/**
	 * @brief
	 * Refreshes BOOL child items.
	 */
	virtual void UpdateChilds();

	class CXTPPropertyGridItemFlag;

private:
	void _Init(int nValue);
	BOOL HasFlag(const CString& strValue, CString strFlag) const;

protected:
	int m_nValue; /**< Value of the item. This is the sum of the constraint values that have a value
					 of TRUE. */
	int* m_pBindFlags; /**> Pointer to the variable bound to this item. */

private:
	DECLARE_DYNAMIC(CXTPPropertyGridItemFlags)

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

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

AFX_INLINE int CXTPPropertyGridItemFlags::GetFlags() const
{
	return m_nValue;
}

#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // __XTPPROPERTYGRIDITEMFLAGS_H__
/** @endcond */