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

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

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

class CXTPGridRow;
class CXTPGridRecord;
class CXTPGridRecordItem;
class CXTPGridControl;
class CXTPGridColumns;

/**
 * @brief
 * This enumeration defines the selection change action.
 * @see
 * XTP_NM_GRID_SELCHANGING, XTP_NM_SELECTION_CHANGING
 */
enum XTPGridSelectionChangeType
{
	xtpGridSelectionAdd,	/**< Row will be added to the selected rows collection.     */
	xtpGridSelectionRemove, /**< Row will be removed from the selected rows collection. */
	xtpGridSelectionClear   /**< The selected rows collection will be cleared.          */
};

/**
 * @brief
 * This struct defines data for an XTP_NM_GRID_SELCHANGING notification.
 * @see
 * XTP_NM_GRID_SELCHANGING, XTP_NM_SELECTION_CHANGING
 */
struct XTP_NM_SELECTION_CHANGING
{
	NMHDR hdr; /**< Standard structure, containing information about a notification message. */
	CXTPGridRow* pRow; /**< Pointer to the row associated with the notification. It is NULL for an
						  xtpGridSelectionClear action. */
	XTPGridSelectionChangeType nType; /**< Selection change action. */
};

/**
 * @brief
 * This structure contains information for use in processing an
 * XTP_NM_GRID_STATECHANGED message.
 */
struct XTP_NM_GRIDSTATECHANGED
{
	NMHDR hdr;  /**< Standard structure, containing information. */
	int nBegin; /**< Zero-based index of the first item in the range of items. */
	int nEnd;   /**< Zero-based index of the last item in the range of items. */
};

class _XTP_EXT_CLASS CXTPGridScreenRows : public CArray<CXTPGridRow*, CXTPGridRow*>
{
public:
	CXTPGridScreenRows();
	~CXTPGridScreenRows();

public:
	CXTPGridRow* HitTest(CPoint pt) const;
	void Clear();
};

class _XTP_EXT_CLASS CXTPGridRowsArray : public CArray<CXTPGridRow*, CXTPGridRow*>
{
	friend class CXTPGridSection;

public:
	void ReserveSize(INT_PTR nNewSize, INT_PTR nGrowBy = -1);
};

/**
 * @brief
 * This class represents a rows collection class.
 * It supports an array of CXTPGridRow pointers.
 *
 * <b>Example:</b>
 * See CXTPGridRows::Add for an example of how to work with this class.
 * @see
 * CXTPGridRow, CXTPGridSelectedRows
 */
class _XTP_EXT_CLASS CXTPGridRows : public CXTPHeapObjectT<CXTPCmdTarget, CXTPGridDataAllocator>
{
	void _swapIndexes(int& A, int& B);
	void _clampIndexes(int& nOrig, const int& nMin, const int& nMax);

public:
	/**
	 * @brief
	 * Constructs an empty CXTPGridRow pointer array.
	 *
	 * <b>Example:</b>
	 * <pre>
	 * // Declare a local CXTPGridRows object.
	 * CXTPGridRows myList;
	 *
	 * // Declare a dynamic CXTPGridRows object.
	 * CXTPGridRows* pTree = new CXTPGridRows();
	 * </pre>
	 */
	CXTPGridRows();

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

	/**
	 * @brief
	 * Determines if this row collection contains a specified row.
	 * @param pRow Pointer to a CXTPGridRow.
	 * @return
	 * TRUE if this row collection contains the specified row.
	 */
	virtual BOOL Contains(const CXTPGridRow* pRow) const;

	/**
	 * @brief
	 * Removes all the elements from this collection.
	 * @param bResetRow TRUE to remove the visible flag of child rows.
	 * @details
	 * Removes all the pointers from this array and releases the instances
	 * of all stored CXTPGridRow objects.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRows::Add method.
	 * @see
	 * CXTPGridRows overview
	 */
	virtual void Clear(BOOL bResetRow = TRUE);

	/**
	 * @brief
	 * Gets the number of row elements in this collection.
	 * @details
	 * Call this method to retrieve the number of elements in the array.
	 * Since indexes are zero-based, the size is 1 greater than
	 * the largest index.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRows::Add method.
	 * @return
	 * The number of row elements in this collection.
	 * @see
	 * CXTPGridRows overview
	 */
	int GetCount() const;

	/**
	 * @brief
	 * Gets the row element at a specified numeric index in this collection.
	 * @param nIndex Integer index that is greater than or equal to 0
	 * and less than the value returned by GetCount.
	 * @return
	 * A pointer to the row element at the specified numeric index.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRows::Add method.
	 */
	virtual CXTPGridRow* GetAt(int nIndex) const;

	/**
	 * @brief
	 * Gets the currently displayed rows of this collection.
	 * @return
	 * A pointer to a CXTPGridScreenRows object containing the
	 * currently displayed rows of this collection.
	 */
	virtual CXTPGridScreenRows* GetScreenRows();

	/**
	 * @brief
	 * Gets the index of the currently focused row.
	 * @return
	 * The index of the currently focused row.
	 */
	virtual int GetFocusedRowIndex() const;

	/**
	 * @brief
	 * Determines if a row in this collection currently has focus.
	 * @return
	 * TRUE if a row in this collection currently has focus.
	 */
	virtual BOOL HasFocus() const;

	/**
	 * @brief
	 * Sets the index of the currently focused row.
	 * @param nRow Row ID.
	 */
	virtual void SetFocusedRowIndex(int nRow);

	/**
	 * @brief
	 * Gets the currently focused row in the Grid control's view.
	 * @return
	 * A pointer to the currently focused row if successful, otherwise NULL.
	 */
	virtual CXTPGridRow* GetFocusedRow();

	/**
	 * @brief
	 * Adds a new row element to the end of this collection.
	 * @param pRow Pointer to the new row element to be added.
	 * @details
	 * Use this method to add the specified CXTPGridRow pointer
	 * to the end of the CXTPGridRows collection.
	 * @return
	 * The index of the newly added row element.
	 *
	 * <b>Example:</b>
	 * <pre>
	 * CXTPGridRows* pTree = new CXTPGridRows();
	 * pTree->Add(new CXTPGridRow(pControl, pRecord1));
	 * pTree->Add(new CXTPGridRow(pControl, pRecord2));
	 * CXTPGridRow* pRow0 = pTree->GetAt(0);
	 * CXTPGridRow* pRow1 = pTree->GetAt(1);
	 * _ASSERTE(pRow0 == pTree->GetPrev(pRow1));
	 * _ASSERTE(pRow1 == pTree->GetNext(pRow0));
	 * pTree->RemoveAt(0);
	 * _ASSERTE(1 == pTree->GetCount());
	 * pTree->InsertAt(0, pRow0);
	 * _ASSERTE(2 == pTree->GetCount());
	 * pTree->Clear();
	 * _ASSERTE(0 == pTree->GetCount());
	 * </pre>
	 * @see
	 * CXTPGridRows overview, GetAt, InsertAt, Clear, GetNext, GetPrev, GetCount
	 */
	virtual int Add(CXTPGridRow* pRow);

	/**
	 * @brief
	 * Removes a specified row from this collection by its index.
	 * @param nIndex Integer index that is greater than or equal to 0
	 * and less than the value returned by GetCount.
	 * @details
	 * In the process, this method shifts down all elements above the
	 * removed element. This method also decrements the upper bound
	 * of the array, but does not free memory. This class also releases
	 * the instance of the removed element.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRows::Add method.
	 */
	virtual void RemoveAt(int nIndex);

	/**
	 * @brief
	 * Removes a specified row from this collection by its index.
	 * @param nStartIndex Integer index that is greater than or equal to 0
	 * and less than the value returned by GetCount.
	 * @param nCount Specifies the number of rows to be removed starting at the specified start
	 * index.
	 * @details
	 * In the process, this method shifts down all elements above the
	 * removed elements. This method also decrements the upper bound
	 * of the array, but does not free memory. This class also releases
	 * the instance of the removed element.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRows::Add method.
	 */
	virtual void RemoveAt(int nStartIndex, int nCount);

	/**
	 * @brief
	 * Removes a specified row from this collection.
	 * @param pRow Pointer to the row to be removed.
	 * @return
	 * The index of the removed row, or a value of -1 if the
	 * specified row does not exist within this collection.
	 */
	virtual int RemoveRow(CXTPGridRow* pRow);

	/**
	 * @brief
	 * Inserts a specified row at a specified index in this collection.
	 * @param nIndex Integer index that is greater than or equal to 0
	 * and less than the value returned by GetCount.
	 * @param pRow   Row to be inserted.
	 * @details
	 * InsertAt inserts an element at a specified index in this array.
	 * In the process, it shifts up (by incrementing the index) the
	 * existing element at this index, and it shifts up all the elements
	 * above it.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRows::Add method.
	 */
	virtual void InsertAt(int nIndex, CXTPGridRow* pRow);

	/**
	 * @brief
	 * Gets the next row in the list.
	 * @param pRow            Pointer to the current row in the list.
	 * @param bSkipGroupFocus TRUE to skip all groups.
	 * @return
	 * A pointer to the next row in the list.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRows::Add method.
	 * @see
	 * GetPrev, CXTPGridControl::SkipGroupsFocus
	 */
	virtual CXTPGridRow* GetNext(CXTPGridRow* pRow, BOOL bSkipGroupFocus);

	/**
	 * @brief
	 * Gets the previous row in the list.
	 * @param pRow            Pointer to the current row in the list.
	 * @param bSkipGroupFocus TRUE to skip all groups.
	 * @return
	 * A pointer to the previous row in the list.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRows::Add method.
	 * @see
	 * GetNext, CXTPGridControl::SkipGroupsFocus
	 */
	virtual CXTPGridRow* GetPrev(CXTPGridRow* pRow, BOOL bSkipGroupFocus);

	/**
	 * @brief
	 * Call this method to set virtual mode with nCount rows.
	 * @param pRow   Virtual row
	 * @param nCount Count of virtual rows
	 */
	virtual void SetVirtualMode(CXTPGridRow* pRow, int nCount);

	/**
	 * @brief
	 * Retrieves the row associated with a specified record.
	 * @param pRecord Pointer to the CXTPGridRecord object to find.
	 * @details
	 * This function will not search through row children.
	 * @return
	 * A pointer to the row associated with the specified record if successful,
	 * otherwise NULL.
	 */
	virtual CXTPGridRow* Find(CXTPGridRecord* pRecord);

	/**
	 * @brief
	 * Retrieves the row associated with a specified record.
	 * @param pRecord Pointer to the CXTPGridRecord object to find.
	 * @param bRecursive TRUE to copy recursively.
	 * @details
	 * This function will not search through row children.
	 * @return
	 * A pointer to the row associated with the specified record if successful,
	 * otherwise NULL.
	 */
	virtual CXTPGridRow* Find(CXTPGridRecord* pRecord, BOOL bRecursive);

	/**
	 * @brief
	 * Retrieves the row associated with a specified record.
	 * @param pRecord Pointer to the CXTPGridRecord object to find.
	 * @details
	 * This function will search through row children.
	 * @return
	 * A pointer to the row associated with the specified record if successful,
	 * otherwise NULL.
	 */
	virtual CXTPGridRow* FindInTree(CXTPGridRecord* pRecord);

	/**
	 * @brief
	 * Searches for a position to insert a specified row at.
	 * @param pRow          Pointer to the CXTPGridRow object to be inserted.
	 * @param bInsertAfter  Reference to a BOOL value to be set to TRUE by this method
	 * if the specified row must be inserted after the found row.
	 * @details
	 * This method will search through child rows.
	 * @return
	 * A pointer to the found CXTPGridRow object if successful, otherwise NULL.
	 */
	virtual CXTPGridRow* FindInsertionPos(CXTPGridRow* pRow, BOOL& bInsertAfter);

	/**
	 * @brief
	 * Recalculates the child indices of all rows in the collection.
	 * @param bRunInChildren TRUE to recalculate the child indices of row children.
	 */
	virtual void RefreshChildIndices(BOOL bRunInChildren = TRUE);

	/**
	 * @brief
	 * Resets the merge height for all rows
	 * (i.e. resets CXTPGridRow::m_nMergeHeight to -1 for all rows).
	 */
	void ClearMergeHeight();

	/**
	 * @brief
	 * Sorts rows in the collection.
	 * @param pCompareFunc Pointer to a T_CompareFunc function
	 * to be used to compare rows.
	 * @details
	 * This method uses the Visual C++ run-time library (MSVCRT) implementation
	 * of the quick-sort function, qsort, for sorting stored CXTPGridRow objects.
	 * Sort() internally uses the CompareRows method for comparing two rows.
	 * @see
	 * CompareRows
	 */
	virtual void SortEx(XTPGridRowsCompareFunc pCompareFunc);

	/**
	 * @brief
	 * Sorts rows in the collection.
	 * @details
	 * This method uses the Visual C++ run-time library (MSVCRT) implementation
	 * of the quick-sort function, qsort, for sorting stored CXTPGridRow objects.
	 * Sort() internally uses the CompareRows method for comparing two rows.
	 * @see
	 * CompareRows
	 */
	virtual void Sort();

	/**
	 * @brief
	 * Compares two rows using groups and sort orders of the Grid control.
	 * @param pRow1 First row for comparison.
	 * @param pRow2 Second row for comparison.
	 * @details
	 * This function is called directly by the Sort method.
	 *
	 * The default implementation returns the result of the comparison
	 * of *pRow1 and *pRow2.
	 *
	 * This implementation uses CXTPGridRecordItem::Compare to compare
	 * two corresponding items from row records. First it compares the
	 * record items by group order, then by sort order. It returns the
	 * first comparison result that differs by equality. If no differences
	 * are found, then it returns 0.
	 *
	 * @return
	 * Zero if pRow1 is equal to pRow2;
	 * Less than zero if pRow1 is less than pRow2;
	 * Greater than zero if pRow1 is greater than pRow2.
	 * @see
	 * Sort, CXTPGridRecordItem::Compare
	 */
	static int AFX_CDECL CompareRows(const CXTPGridRow** pRow1, const CXTPGridRow** pRow2);

	/**
	 * @brief
	 * Compares two rows using groups and sort orders of the Grid control.
	 * @param pRow1 First row for comparison.
	 * @param pRow2 Second row for comparison.
	 * @details
	 * This function is called directly by the Sort method.
	 *
	 * The default implementation returns the result of the comparison
	 * of *pRow1 and *pRow2.
	 *
	 * This implementation uses CXTPGridRecordItem::Compare to compare
	 * two corresponding items from row records. First it compares the
	 * record items by group order, then by sort order. It returns the
	 * first comparison result that differs by equality. If no differences
	 * are found, then it returns 0.
	 *
	 * @return
	 * Zero if pRow1 is equal to pRow2;
	 * Less than zero if pRow1 is less than pRow2;
	 * Greater than zero if pRow1 is greater than pRow2.
	 * @see
	 * Sort, CXTPGridRecordItem::Compare
	 */
	static int AFX_CDECL CompareRows2(const CXTPGridRow** pRow1, const CXTPGridRow** pRow2);

	/**
	 * @brief
	 * Finds a record item by rows.
	 * @param nStartIndex  Starting index.
	 * @param nEndIndex    Ending index.
	 * @param nStartColumn Starting column.
	 * @param nEndColumn   Ending column.
	 * @param nItem        Record item index to start the search from.
	 * @param nRecordIndex Record index to start the search from.
	 * @param pcszText     Search text.
	 * @param nFlags       Search flags.
	 * @details
	 * The various values for nFlags are:
	 *
	 * xtpGridTextSearchExactPhrase Search exact phrase.
	 *
	 * xtpGridTextSearchMatchCase   Match case during search.
	 *
	 * xtpGridTextSearchBackward    Search backwards.
	 *
	 * xtpGridTextSearchExactStart  Search phrase where the start of the phrase
	 *
	 * matches exactly. For those familiar with grep,
	 * this is just like using the "^" to state that
	 * the text must start with the specified search.
	 * @return
	 * A pointer to the found record item if successful, otherwise NULL.
	 */
	virtual CXTPGridRecordItem* FindRecordItemByRows(int nStartIndex, int nEndIndex,
													 int nStartColumn, int nEndColumn,
													 int nRecordIndex, int nItem, LPCTSTR pcszText,
													 int nFlags);

	/** @cond */
	virtual void ReserveSize(INT_PTR nNewSize, INT_PTR nGrowBy = -1);
	virtual void SetSize(INT_PTR nNewSize, INT_PTR nGrowBy = -1);
	virtual void SetAt(INT_PTR nIndex, CXTPGridRow* pRow);
	/** @endcond */
protected:
	/** @cond */

	CXTPGridRowsArray m_arrRows; /**< Internal storage for CXTPGridRow objects. */
	/** @endcond */

	CXTPGridRow* m_pVirtualRow;		   /**< Virtual row. */
	CXTPGridScreenRows* m_pScreenRows; /**< Rows currently presented on screen. */
	int m_nVirtualRowsCount;		   /**< Count of virtual rows. */

	int m_nFocusedRow; /**< Current focused row index. */

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

	DECLARE_OLETYPELIB_EX(CXTPGridRows);

	afx_msg LPDISPATCH OleGetItem(long nIndex);
	int OleGetItemCount();
	DECLARE_ENUM_VARIANT(CXTPGridRows)

	afx_msg LPDISPATCH OleFindRow(LPDISPATCH pRecordDisp);
	afx_msg LPDISPATCH OleFindRowInTree(LPDISPATCH pRecordDisp);
	afx_msg LPDISPATCH OleFindRecordItemByRows(int nStartIndex, int nEndIndex, int nStartColumn,
											   int nEndColumn, int nRecord, int nItem,
											   LPCTSTR pcszText, int nFlags);
	enum
	{
		dispidCount = 1L,
	};

/** @endcond */
#	endif

	friend class CXTPGridControl;
	friend class CXTPTrackControl;
	friend class CXTPGridNavigator;
	friend class CXTPGridSection;
};
/** @cond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif //#if !defined(__XTPGRIDROWS_H__)
	   /** @endcond */