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

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

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

class CXTPGridColumn;
class CXTPGridHeader;
class CXTPGridControl;
class CXTPGridColumnOrder;
class CXTPPropExchange;

/**
 * @brief
 * This class is a collection of grid column objects. Each
 * grid column object can be referred to by its zero-based index.
 * @details
 * This class provides main operations to manipulate a list of columns:
 * Adding/removing columns
 * Showing columns header
 * Working with field chooser
 * Working with "group by" field
 * (Re)Storing column settings
 * To create a CXTPGridColumns object simply call its constructor with
 * one parameter - the pointer to the parent Grid control object.
 */
class _XTP_EXT_CLASS CXTPGridColumns : public CXTPCmdTarget
{
	friend class CXTPGridColumn;

public:
	/**
	 * @brief
	 * Constructs a CXTPGridColumns object.
	 * @param pControl Pointer to the parent Grid control object.
	 */
	CXTPGridColumns(CXTPGridControl* pControl);

	/**
	 * @brief
	 * Destroys a CXTPGridColumns object.
	 * @details
	 * Handles cleanup and deallocation, including all of the objects
	 * presented in the list by calling the Clear() member function.
	 */
	virtual ~CXTPGridColumns();

	/**
	 * @brief
	 * Retrieves the total number of column items in the collection.
	 * @return
	 * The total number of column items in the collection.
	 */
	int GetCount() const;

	/**
	 * @brief
	 * Clears all column collection items.
	 */
	void Clear();

	/**
	 * @brief
	 * Retrieves the number of visible columns in the collection.
	 * @details
	 * Unlike the GetCount() member function, this function only returns
	 * the count of columns whose visibility property is set to TRUE.
	 * @return
	 * The number of visible columns in the collection.
	 */
	int GetVisibleColumnsCount() const;

	/**
	 * @brief
	 * Retrieves all visible columns in the collection and places
	 * them within a referenced CXTPGridColumns array object.
	 * @param arrColumns Reference to a CXTPGridColumns array object.
	 * @details
	 * The referenced CXTPGridColumns array object will be filled
	 * with all visible columns in the collection.
	 */
	void GetVisibleColumns(CXTPGridColumns& arrColumns) const;

	/**
	 * @brief
	 * Retrieves the column item at a specified index in the collection.
	 * @param nIndex Index of the column to retrieve; must be greater than or equal
	 * to zero and less than the value returned by GetCount().
	 * @return
	 * A pointer to the column item at the specified index if successful, or
	 * a NULL value if the specified index is less than zero or greater
	 * than the value returned by GetCount().
	 */
	CXTPGridColumn* GetAt(int nIndex) const;

	/**
	 * @brief
	 * Retrieves the closest visible column to a specified index in the
	 * collection that appears at or before the specified index.
	 * @param nIndex Index of a column in the collection; must be greater than or equal
	 * to zero and less than the value returned by GetCount().
	 * @return
	 * A pointer to the closest visible column to the specified index in the
	 * collection that appears at or before the specified index, or a NULL value
	 * if either a visible column is not found or the specified index is less
	 * than zero or greater than the value returned by GetCount().
	 */
	CXTPGridColumn* GetVisibleAt(int nIndex) const;

	/**
	 * @brief
	 * Retrieves the index of the column at a specified left offset.
	 * @param nOffset Left offset, in pixels, of the column to retrieve the index of.
	 * @param bFrozen TRUE to count frozen columns, FALSE to not count frozen columns.
	 * @return
	 * The index of the column at the specified left offset.
	 */
	int GetAtOffset(int nOffset, BOOL bFrozen) const;

	/**
	 * @brief
	 * Retrieves the left offset, in pixels, of the column at a specified index.
	 * @param nIndex Index of the column to retrieve the left offset of
	 * (i.e. this value should include frozen and non-frozen columns).
	 * @return
	 * The left offset, in pixels, of the column at the specified index.
	 */
	int GetOffset(int nIndex) const;

	/**
	 * @brief
	 * Gets the indentation column of this collection.
	 * @return
	 * A pointer to the indentation column of this collection.
	 * @details
	 * Indentation columns are used to represent the ends of column collections.
	 * An indentation column is usually the first column in the list.
	 */
	CXTPGridColumn* GetIndentColumn() const;

	/**
	 * @brief
	 * Finds a specified column by its item index/internal name.
	 * @param nItemIndex       Item index of the column to find.
	 * @details
	 * Searches the collection sequentially to find the first column
	 * matching the specified column's item index/internal name.
	 * @return
	 * A pointer to the found column if successful, otherwise NULL.
	 */
	CXTPGridColumn* Find(int nItemIndex) const;

	/**
	 * @brief
	 * Finds a specified column by its item index/internal name.
	 * @param strInternalName  Internal name of the column to find.
	 * @details
	 * Searches the collection sequentially to find the first column
	 * matching the specified column's item index/internal name.
	 * @return
	 * A pointer to the found column if successful, otherwise NULL.
	 */
	CXTPGridColumn* Find(const CString& strInternalName) const;

	/**
	 * @brief
	 * Adds a specified column to the end of the collection.
	 * @param pColumn Pointer to the column to be added.
	 * @details
	 * Adds a new column to the end of a collection, increasing the collection by 1.
	 */
	void Add(CXTPGridColumn* pColumn);

	/**
	 * @brief
	 * Removes a specified column from the collection.
	 * @param pColumn Pointer to the column to be removed.
	 */
	void Remove(CXTPGridColumn* pColumn);

	/**
	 * @brief
	 * Clears the sort order for all columns.
	 */
	void ResetSortOrder();

	/**
	 * @brief
	 * Gets the associated grid header object.
	 * @return
	 * A pointer to the associated grid header object.
	 */
	CXTPGridHeader* GetGridHeader() const;

	/** @cond */
	_XTP_DEPRECATED_IN_FAVOR(GetGridHeader)
	CXTPGridHeader* GetReportHeader() const;
	/** @endcond */

	/**
	 * @brief
	 * Repositions a specified column in the collection.
	 * @param nNewIndex New index of the column.
	 * @param nOldIndex Old index of the column.
	 * @return
	 * The new index of the column if successful, otherwise a value of -1.
	 */
	int ChangeColumnOrder(int nNewIndex, int nOldIndex);

	/**
	 * @brief
	 * Retrieves the index of a column.
	 * @param pColumn Pointer to the column whose index must be retrieved.
	 * @details
	 * Searches for the first occurrence of the specified column,
	 * beginning with the first index in the collection.
	 * @return
	 * The index of the first occurrence of the specified column if successful,
	 * otherwise a value of -1.
	 */
	int IndexOf(const CXTPGridColumn* pColumn) const;

	/**
	 * @brief
	 * Inserts a specified column to the sort columns array according to
	 * the columns order of the group columns array.
	 * @param pColumn Pointer to the column to be inserted.
	 */
	void InsertSortColumn(CXTPGridColumn* pColumn);

	/**
	 * @brief
	 * Sets a specified column as the sorted column and
	 * resets the previous sort order.
	 * @param pColumn     Pointer to the column to be set.
	 * @param bIncreasing TRUE if the column should be sorted in increasing order,
	 * FALSE if the column should be sorted in decreasing order.
	 */
	void SetSortColumn(CXTPGridColumn* pColumn, BOOL bIncreasing);

	/**
	 * @brief
	 * Gets the columns groups order array.
	 * @return
	 * A pointer to the columns groups order array.
	 */
	CXTPGridColumnOrder* GetGroupsOrder() const;

	/**
	 * @brief
	 * Gets the columns sort order array.
	 * @return
	 * A pointer to the columns sort order array.
	 */
	CXTPGridColumnOrder* GetSortOrder() const;

	/**
	 * @brief
	 * Reads/writes configuration to/from the provided archive stream.
	 * @param pPX Pointer to a CXTPPropExchange object to serialize to/from.
	 */
	virtual void DoPropExchange(CXTPPropExchange* pPX);

	/**
	 * @brief
	 * Gets the first visible column in the collection.
	 * @return
	 * A pointer to the first visible column in the collection.
	 * @see
	 * GetLastVisibleColumn
	 */
	CXTPGridColumn* GetFirstVisibleColumn() const;

	/**
	 * @brief
	 * Gets the last visible column in the collection.
	 * @return
	 * A pointer to the last visible column in the collection.
	 * @see
	 * GetFirstVisibleColumn
	 */
	CXTPGridColumn* GetLastVisibleColumn() const;

protected:
	CXTPGridColumnOrder* m_pGroupsOrder; /**< Container for the columns order in auto-grouping mode.
										  */
	CXTPGridColumnOrder* m_pSortOrder;   /**< Container for the columns sort order. */
	CArray<CXTPGridColumn*, CXTPGridColumn*> m_arrColumns; /**< Storage for column items. */
	CXTPGridControl* m_pControl;   /**< Pointer to the associated Grid control object. */
	CXTPGridColumn* m_pTreeColumn; /**< Column containing tree view images. */

#	ifdef _XTP_ACTIVEX
	/** @cond */
	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPGridColumns);

	afx_msg LPDISPATCH OleGetItem(long nIndex);
	afx_msg int OleGetItemCount();
	afx_msg LPDISPATCH OleAdd(long nId, LPCTSTR strCaption, int nWidth, BOOL bAutoSize);
	afx_msg LPDISPATCH OleAddEx(long nId, LPCTSTR strCaption, LPCTSTR strInternalName, int nWidth,
								BOOL bAutoSize);
	afx_msg LPDISPATCH OleFindColumn(long nId);

	DECLARE_ENUM_VARIANT(CXTPGridColumns)

	enum
	{
		dispidCount		 = 1L,
		dispidAdd		 = 2L,
		dispidAddEx		 = 3L,
		dispidFindColumn = 4L,
	};

/** @endcond */
#	endif
};

AFX_INLINE int CXTPGridColumns::GetCount() const
{
	return (int)m_arrColumns.GetSize();
}

AFX_INLINE CXTPGridColumn* CXTPGridColumns::GetAt(int nIndex) const
{
	return (nIndex >= 0 && nIndex < GetCount()) ? m_arrColumns.GetAt(nIndex) : NULL;
}

AFX_INLINE CXTPGridColumnOrder* CXTPGridColumns::GetGroupsOrder() const
{
	return m_pGroupsOrder;
}

AFX_INLINE CXTPGridColumnOrder* CXTPGridColumns::GetSortOrder() const
{
	return m_pSortOrder;
}

AFX_INLINE CXTPGridColumn* CXTPGridColumns::GetIndentColumn() const
{
	return (GetCount() > 0) ? m_arrColumns.GetAt(0) : NULL;
}

/**
 * @brief
 * Represents the column order, used for sorting and grouping.
 * @details
 * This class is a collection of sorted columns objects, each of which
 * can be referred to by its zero-based index.
 * It provides the following main operations to manipulate a list of columns:
 * adding/removing columns, get at a given position, clear collection,
 * get the index of an object by it pointer.
 * You create a CXTPGridColumnOrder object simply by calling its constructor
 * with one parameter pointer to the columns collection.
 */
class _XTP_EXT_CLASS CXTPGridColumnOrder : public CXTPCmdTarget
{
public:
	/**
	 * @brief
	 * Constructs a CXTPGridColumnOrder object.
	 * @param pColumns Parent columns collection.
	 */
	CXTPGridColumnOrder(CXTPGridColumns* pColumns);

	/**
	 * @brief
	 * Retrieves the column item at a specified index in the collection.
	 * @param nIndex Index of the column to retrieve; must be greater than or equal
	 * to zero and less than the value returned by GetCount().
	 * @return
	 * A pointer to the column item at the specified index if successful, or
	 * a NULL value if the specified index is less than zero or greater
	 * than the value returned by GetCount().
	 */
	CXTPGridColumn* GetAt(int nIndex);

	/**
	 * @brief
	 * Inserts a specified column at a specified index.
	 * @param nIndex  Index to insert the column at.
	 * @param pColumn Pointer to the column to be inserted.
	 * @return
	 * The index of the inserted column if successful, otherwise a value of -1.
	 */
	int InsertAt(int nIndex, CXTPGridColumn* pColumn);

	/**
	 * @brief
	 * Removes the column at a specified index from the collection.
	 * @param nIndex Index of the column to be removed.
	 */
	void RemoveAt(int nIndex);

	/**
	 * @brief
	 * Removes a specified column from the collection.
	 * @param pColumn Pointer to the column to be removed.
	 */
	void Remove(CXTPGridColumn* pColumn);

	/**
	 * @brief
	 * Adds a specified column to the end of the collection.
	 * @param pColumn         Pointer to the column to be added.
	 * @details
	 * Adds a new column to the end of a collection, increasing the collection by 1.
	 * @return
	 * The index of the newly added column.
	 */
	int Add(CXTPGridColumn* pColumn);

	/**
	 * @brief
	 * Adds a specified column to the end of the collection.
	 * @param pColumn         Pointer to the column to be added.
	 * @param bSortIncreasing TRUE if the column should be sorted in increasing order,
	 * FALSE if the column should be sorted in decreasing order.
	 * @details
	 * Adds a new column to the end of a collection, increasing the collection by 1.
	 * @return
	 * The index of the newly added column.
	 */
	int Add(CXTPGridColumn* pColumn, BOOL bSortIncreasing);

	/**
	 * @brief
	 * Retrieves the index of a column.
	 * @param pColumn Pointer to the column whose index must be retrieved.
	 * @details
	 * Searches for the first occurrence of the specified column,
	 * beginning with the first index in the collection.
	 * @return
	 * The index of the first occurrence of the specified column if successful,
	 * otherwise a value of -1.
	 */
	int IndexOf(const CXTPGridColumn* pColumn);

	/**
	 * @brief
	 * Clears all stored order information.
	 */
	void Clear();

	/**
	 * @brief
	 * Gets the number of columns in the collection.
	 * @return
	 * The number of columns in the collection.
	 */
	int GetCount() const;

	/**
	 * @brief
	 * Reads/writes column order settings to/from the provided archive stream.
	 * @param pPX Pointer to a CXTPPropExchange object to serialize to/from.
	 */
	virtual void DoPropExchange(CXTPPropExchange* pPX);

protected:
	CXTPGridColumns* m_pColumns; /**< Parent columns array. */

	CArray<CXTPGridColumn*, CXTPGridColumn*> m_arrColumns; /**< Storage for column items with the
															  corresponding order. */

#	ifdef _XTP_ACTIVEX
	/** @cond */
	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPGridColumnOrder);

	afx_msg int OleGetItemCount();
	afx_msg LPDISPATCH OleGetItem(long nIndex);
	afx_msg void OleAdd(LPDISPATCH lpColumn);
	afx_msg int OleIndexOf(LPDISPATCH lpColumn);

	DECLARE_ENUM_VARIANT(CXTPGridColumnOrder)

	enum
	{
		dispidCount = 1L,
	};

/** @endcond */
#	endif
};
/** @cond */
AFX_INLINE CXTPGridHeader* CXTPGridColumns::GetReportHeader() const
{
	return GetGridHeader();
}

#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif // #if !defined(__XTPGRIDCOLUMNS_H__)
	   /** @endcond */