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

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

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

class CXTPPropExchange;

/**
 * @brief
 * CXTPPropExchangeEnumerator is standalone class. It used by CXTPPropExchange to enumerate
 * child sections.
 *
 *
 * <b>Example:</b>
 * <pre>
 * extern CXTPPropExchange* pPX;
 *
 * CXTPPropExchangeEnumeratorPtr pEnumerator(pPX->GetEnumerator(_T("Icon")));
 * POSITION posEnum = pEnumerator->GetPosition();
 *
 * while (posEnum)
 * {
 *    CXTPPropExchangeSection secIcon(pEnumerator->GetNext(posEnum));
 * }
 * </pre>
 * @see CXTPPropExchange, CXTPPropExchange::GetEnumerator
 */
class _XTP_EXT_CLASS CXTPPropExchangeEnumerator
{
public:
	/**
	 * @brief
	 * Constructs a CXTPPropExchangeEnumerator object.
	 * @param pContainer Parent section of enumerator
	 * @param lpszSection Enumerator section name
	 */
	CXTPPropExchangeEnumerator(CXTPPropExchange* pContainer, LPCTSTR lpszSection);

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

public:
	/**
	 * @brief
	 * Call this method to init enumerable section
	 * @param dwCount Count of items to be stored.
	 * @param bCompactMode TRUE to use "compact mode" of XML nodes.
	 * @return
	 * A POSITION value that can be used for iteration; NULL if the section is empty.
	 */
	virtual POSITION GetPosition(DWORD dwCount = 0, BOOL bCompactMode = TRUE);

	/**
	 * @brief
	 * Call this method to get next enumerable section to load.
	 * @param pos A reference to a POSITION value returned by a previous GetNext, GetPosition, or
	 * other member function call.
	 * @return Returns next enumerable section to load
	 */
	virtual CXTPPropExchange* GetNext(POSITION& pos);

	CXTPPropExchange* GetContainer() const;
	virtual int GetCount() const;

protected:
	CXTPPropExchange* m_pContainer; /**< Parent section of enumerator */
	CString m_strSectionName;		/**< Enumerator section name */
	DWORD m_nCount;					/**< Count of items to load. */
};
/** @cond */
AFX_INLINE CXTPPropExchange* CXTPPropExchangeEnumerator::GetContainer() const
{
	return m_pContainer;
}
/** @endcond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // !defined(__XTPPROPEXCHANGEENUMERATOR_H__)
/** @endcond */