/**
 * @file  XTPCalendarCustomProperties.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
 *
 */

#if !defined(_XTP_CALENDAR_CUSTOM_PROPERTIES_H__)
#	define _XTP_CALENDAR_CUSTOM_PROPERTIES_H__

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

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

//////////////////////
class CXTPPropExchange;

/**
 * @brief
 *  This class is used to store properties collection.
 *
 * @details
 *  It contains methods to Get, Set, Remove and Iterate on properties.
 *
 * @see CXTPCalendarEvent::GetCustomProperties()
 */
class _XTP_EXT_CLASS CXTPCalendarCustomProperties : public CXTPCmdTarget
{
	/** @cond */
	DECLARE_DYNAMIC(CXTPCalendarCustomProperties)
	/** @endcond */
public:
	/**
	 * @brief
	 * Default object constructor.
	 *
	 * @param bNameIgnoreCase [in] if TRUE - properties names are not
	 *						 case sensitive.
	 */
	CXTPCalendarCustomProperties(BOOL bNameIgnoreCase = TRUE);

	/**
	 * @brief
	 * Default object destructor.
	 */
	virtual ~CXTPCalendarCustomProperties();

	/**
	 * @brief
	 *  This member function is used to get property value using the specified
	 *  name.
	 *
	 * @param pcszName [in] A pointer to property name string.
	 * @param rVarValue [out] A reference to COleVariant object to receive
	 *                  property value.
	 *
	 * @details
	 * The corresponding method for ActiveX returns a VT_EMPTY variant value
	 * instead of FALSE.
	 * @return TRUE if successful, FALSE if specified property is not present
	 *		  in the collection.
	 *
	 * @see SetProperty
	 * @see RemoveProperty
	 */
	virtual BOOL GetProperty(LPCTSTR pcszName, COleVariant& rVarValue) const;

	/**
	 * @brief
	 *  This member function is used to set property value with the specified
	 *  name.
	 *
	 * @param pcszName [in] A pointer to property name string.
	 * @param varValue [in] A const reference to COleVariant object with a
	 *                 property value.
	 *
	 * @return TRUE if successful, FALSE otherwise.
	 *
	 * @see GetProperty
	 * @see RemoveProperty
	 */
	virtual BOOL SetProperty(LPCTSTR pcszName, const COleVariant& varValue);

	/**
	 * @brief
	 *  This member function is used to remove property with the specified
	 *  name.
	 *
	 * @param pcszName [in] A pointer to property name string.
	 *
	 * @return TRUE if successful, FALSE otherwise.
	 *
	 * @see GetProperty
	 * @see SetProperty
	 */
	virtual BOOL RemoveProperty(LPCTSTR pcszName);

	/**
	 * @brief
	 *  This member function is used to remove all properties.
	 *
	 * @see RemoveProperty
	 * @see GetProperty
	 * @see SetProperty
	 */
	virtual void RemoveAll();

	/**
	 * @brief
	 *  This member function is to get properties count in the collection.
	 *
	 * @return Properties amount in the collection.
	 *
	 * @see GetProperty
	 * @see SetProperty
	 * @see RemoveProperty
	 * @see RemoveAll
	 */
	virtual int GetCount();

	/**
	 * @brief
	 *  Starts a properties collection iteration by returning a POSITION
	 *  value that can be passed to a GetNextProperty call.
	 *
	 * @return A POSITION value with start position.
	 *
	 * @see GetNextProperty
	 * @see CMap
	 */
	POSITION GetStartPosition() const;

	/**
	 * @brief
	 *  Retrieves the properties collection element at rPos, then updates
	 *  rPos to refer to the next element in the collection.
	 *
	 * @param rPos [in out] Specifies a reference to a POSITION value
	 *             returned by a previous GetNextProperty or
	 *             GetStartPosition call.
	 * @param rStrName [out] A reference to CString object to receive
	 *                 property name value.
	 * @param rVarValue [out] A reference to COleVariant object to receive
	 *                  property value.
	 *
	 * @see GetStartPosition
	 * @see CMap
	 */
	void GetNextProperty(POSITION& rPos, CString& rStrName, COleVariant& rVarValue) const;

	/**
	 * @brief
	 * Call this member function to Store/Load a properties collection
	 * using the specified data object.
	 *
	 * @param pPX Source or destination CXTPPropExchange data object reference.
	 *
	 * @details
	 * This member function is used to store or load properties collection
	 * data to or form an storage.
	 */
	virtual void DoPropExchange(CXTPPropExchange* pPX);

public:
	/**
	 * @brief
	 *  This helper function is used to load a properties collection from a XML
	 *  string source.
	 *
	 * @param pcszXMLData [in] A pointer to a XML string data source.
	 *
	 * @details RemoveAll method is called for collection before loading.
	 *
	 * @return TRUE if successful, FALSE otherwise.
	 *
	 * @see SaveToXML
	 */
	BOOL LoadFromXML(LPCTSTR pcszXMLData);

	/**
	 * @brief
	 *  This helper function is used to store a properties collection to a XML
	 *  string.
	 *
	 * @param rstrXMLData - [out] A XML string object reference.
	 *
	 * @return TRUE if successful, FALSE otherwise.
	 *
	 * @see LoadFromXML
	 */
	BOOL SaveToXML(CString& rstrXMLData);

	/**
	 * @brief
	 *  This helper function is used to copy properties from a source collection
	 *  object to a destination collection.
	 *
	 * @param pDest [out] A pointer to destination properties collection object.
	 *
	 * @details
	 *  RemoveAll method is called for destination collection before copying.
	 *
	 * @see LoadFromXML
	 * @see SaveToXML
	 */
	void CopyTo(CXTPCalendarCustomProperties* pDest);

protected:
	/**
	 * @brief
	 * Call this member function to Load a properties collection
	 * using the specified data object.
	 *
	 * @param pPX Source CXTPPropExchange data object reference.
	 */
	void _Load(CXTPPropExchange* pPX);

	/**
	 * @brief
	 * Call this member function to Store a properties collection
	 * using the specified data object.
	 *
	 * @param pPX Destination CXTPPropExchange data object reference.
	 */
	void _Save(CXTPPropExchange* pPX);

	/**
	 * @brief
	 *  Call this member function to prepare a property name before passing it
	 *  to the map access functions.
	 *
	 * @param pcszName [in] A pointer to a property name string.
	 *
	 * @details
	 *  If m_bNameIgnoreCase is TRUE, property names are converted to
	 *  lower case.
	 *
	 * @return Prepared property name string to pass to the map access functions.
	 */
	CString PrepareName(LPCTSTR pcszName) const;

	typedef CMap<CString, LPCTSTR, COleVariant, COleVariant&> CXTPOleVariantMap;

	CXTPOleVariantMap m_mapProperties; /**< Properties storage map.*/
	BOOL m_bNameIgnoreCase;			   /**< if TRUE - properties names are not case sensitive.*/

#	ifdef _XTP_ACTIVEX

	afx_msg VARIANT OleGetProperty(LPCTSTR strName);
	afx_msg void OleSetProperty(LPCTSTR strName, VARIANT& Value);

	afx_msg long OleGetCount();

	afx_msg void OleRemove(LPCTSTR strName);
	afx_msg void OleRemoveAll();

	afx_msg void OleLoadFromString(LPCTSTR strData);
	afx_msg BSTR OleSaveToString();

	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPCalendarCustomProperties);

	DECLARE_ENUM_VARIANTLIST(CXTPCalendarCustomProperties);

#	endif
};

#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif // !defined(_XTP_CALENDAR_CUSTOM_PROPERTIES_H__)