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

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

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

class CXTPGridRecord;
class CXTPPropExchange;
class CXTPMarkupContext;
class CXTPGridRecordItem;
class CXTPGridRecordItemRange;

/**
 * @brief
 * Enumeration of text search parameters.
 * @details
 * Call CXTPGridRecords::FindRecordItem to search for a record item by text.
 *
 * <b>Example:</b>
 * <pre>m_wndGrid.GetRecords()->FindRecordItem(... , xtpGridTextSearchWholeWord |
 * xtpGridTextSearchBackward);</pre>
 * @see
 * CXTPGridRecords::FindRecordItem
 */
enum XTPGridTextSearchParms
{
	xtpGridTextSearchExactPhrase = 1, /**< Search exact phrase. */
	xtpGridTextSearchMatchCase   = 2, /**< Match case during search. */
	xtpGridTextSearchBackward	= 4, /**< Search backward. */
	xtpGridTextSearchExactStart  = 8, /**< Search phrase starting in the beginning of the item
										 caption. */
};

/**
 * @brief
 * This class represents a grid records collection.
 * It supports an array of CXTPGridRecord pointers.
 *
 * <b>Example:</b>
 * See example for the CXTPGridRecords::Add method.
 * @see
 * CXTPGridRecord
 */
class _XTP_EXT_CLASS CXTPGridRecords : public CXTPHeapObjectT<CXTPCmdTarget, CXTPGridDataAllocator>
{
	DECLARE_DYNAMIC(CXTPGridRecords)

	void _Init();
	void _swapIndexes(int& A, int& B);
	void _clampIndexes(int& nOrig, const int& nMin, const int& nMax);

public:
	/**
	 * @brief
	 * Constructs an empty CXTPGridRecord pointer array.
	 * @param bArray Flag for array-based case (if TRUE).
	 *
	 * <b>Example:</b>
	 * <pre>
	 * // Declare a local CXTPGridRecords object.
	 * CXTPGridRecords myList;
	 *
	 * // Declare a dynamic CXTPGridRecords object.
	 * CXTPGridRecords* pTree = new CXTPGridRecords();
	 * </pre>
	 */
	CXTPGridRecords(BOOL bArray = FALSE);

	/**
	 * @brief
	 * Constructs an empty CXTPGridRecord pointer array in case it is
	 * used as a member of a CXTPGridRecord object to store children.
	 * @param pOwnerRecord Pointer to the owner CXTPGridRecord object.
	 */
	CXTPGridRecords(CXTPGridRecord* pOwnerRecord);

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

	/**
	 * @brief
	 * Obtains an associated owner record pointer.
	 * @return
	 * An associated owner record pointer, or NULL if no owner record
	 * is associated with the records collection.
	 */
	CXTPGridRecord* GetOwnerRecord() const;

public:
	/**
	 * @brief
	 * Gets the number of record 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.
	 * @return
	 * The number of record elements in this collection.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRecords::Add method.
	 * @see
	 * CXTPGridRecords overview
	 */
	int GetCount() const;

	/**
	 * @brief
	 * Gets the record 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 record element at the specified numeric index.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRecords::Add method.
	 */
	CXTPGridRecord* GetAt(int nIndex) const;

	/**
	 * @brief
	 * Adds a new record element to the end of this collection.
	 * @param pRecord Pointer to the new record element to be added.
	 * @details
	 * Use this method to add a specified CXTPGridRecord pointer
	 * to the end of the CXTPGridRecords collection.
	 * @return
	 * A pointer to the newly added record element.
	 *
	 * <b>Example:</b>
	 * <pre>
	 * CXTPGridRecords* pList = new CXTPGridRecords();
	 * pList->Add(new CXTPGridRecord());
	 * pList->Add(new CXTPGridRecord());
	 * CXTPGridRecord* pRecord0 = pList->GetAt(0);
	 * CXTPGridRecord* pRecord1 = pList->GetAt(1);
	 * _ASSERTE(2 == pList->GetCount());
	 * pList->RemoveAll();
	 * _ASSERTE(0 == pList->GetCount());
	 * </pre>
	 * @see
	 * CXTPGridRecords overview, GetAt, RemoveAll, GetCount
	 */
	CXTPGridRecord* Add(CXTPGridRecord* pRecord);

	/**
	 * @brief
	 * Call this member function to store/load a grid records collection.
	 * @param pPX Source/destination CXTPPropExchange data object reference.
	 */
	virtual void DoPropExchange(CXTPPropExchange* pPX);

	/**
	 * @brief
	 * Removes all the elements from this collection.
	 * @details
	 * Removes all the pointers from this array and releases the
	 * instances of all stored CXTPGridRecord objects.
	 *
	 * <b>Example:</b>
	 * See example for the CXTPGridRecords::Add method.
	 * @see
	 * CXTPGridRecords overview
	 */
	void RemoveAll();

	/**
	 * @brief
	 * Removes a specified record from this collection by its index.
	 * @param nIndex Index of the record to remove.
	 */
	void RemoveAt(int nIndex);

	/**
	 * @brief
	 * Removes a specified record from this collection.
	 * @param pRecord Pointer to the record to be removed.
	 * @return
	 * The index of the removed record, or a value of -1 if the
	 * specified record does not exist within this collection.
	 */
	int RemoveRecord(CXTPGridRecord* pRecord);

	/**
	 * @brief
	 * Inserts a specified record at a specified index in this collection.
	 * @param nIndex  Index to insert the specified record at.
	 * @param pRecord Record 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 CXTPGridRecords::Add method.
	 */
	void InsertAt(int nIndex, CXTPGridRecord* pRecord);

	/**
	 * @brief
	 * Moves specified records to a specified index in this collection.
	 * @param nIndex   Index to move the specified records to.
	 * @param pRecords Records to be moved.
	 */
	void Move(int nIndex, CXTPGridRecords* pRecords);

	/**
	 * @brief
	 * Moves a specified record to a specified index in this collection.
	 * @param nIndex         Index to move the specified record to.
	 * @param pRecord        Record to be moved.
	 * @param bUpdateIndexes Flag to update indexes to 0-N set.
	 */
	void MoveRecord(int nIndex, CXTPGridRecord* pRecord, BOOL bUpdateIndexes = FALSE);

public:
	/**
	 * @brief
	 * Gets the markup context.
	 * @return
	 * A pointer to the markup context.
	 */
	CXTPMarkupContext* GetMarkupContext() const;

	/**
	 * @brief
	 * Sets the markup context.
	 * @param pMarkupContext Pointer to the markup context to be set.
	 */
	void SetMarkupContext(CXTPMarkupContext* pMarkupContext);

public:
	/**
	 * @brief
	 * Specifies if string comparisons should be case-sensitive.
	 * @param bCaseSensitive TRUE to set string comparisons to be case-sensitive,
	 * FALSE otherwise; the default value for this parameter is FALSE.
	 * @see
	 * IsCaseSensitive
	 */
	void SetCaseSensitive(BOOL bCaseSensitive);

	/**
	 * @brief
	 * Determines if string comparisons are case-sensitive.
	 * @return
	 * TRUE if string comparisons are case-sensitive, otherwise FALSE.
	 * @see
	 * SetCaseSensitive
	 */
	BOOL IsCaseSensitive() const;

	/**
	 * @brief
	 * Helper function to compare two strings.
	 * @param str1 First string to compare.
	 * @param str2 Second string to compare.
	 * @return
	 * Zero if str1 is identical to str2;
	 * Less than zero if str1 is less than str2;
	 * Greater than zero if str1 is greater than str2.
	 * @see
	 * SetCaseSensitive
	 */
	virtual int Compare(const CString& str1, const CString& str2) const;

	/**
	 * @brief
	 * Changes the size of this collection.
	 * @param nNewSize New size for this collection.
	 * @param nGrowBy  Minimum number of element slots to allocate in the
	 * event that a size increase is necessary.
	 */
	virtual void SetSize(INT_PTR nNewSize, INT_PTR nGrowBy = -1);

	/**
	 * @brief
	 * Sets a specified record element to a specified index in this collection.
	 * @param nIndex  Integer index to set the specified record element to;
	 * must be greater than or equal to zero and less than
	 * the value returned by GetCount.
	 * @param pRecord Pointer to the CXTPGridRecord object to add.
	 */
	virtual void SetAt(INT_PTR nIndex, CXTPGridRecord* pRecord);

	/**
	 * @brief
	 * Updates record element indices.
	 * @param nStart Integer index to begin the update from.
	 */
	virtual void UpdateIndexes(int nStart = 0);

	/**
	 * @brief
	 * Retrieves a record element by its bookmark.
	 * @param vtBookmark        Bookmark of the record element to retrieve.
	 * @param bSearchInChildren TRUE to search in children too, FALSE otherwise.
	 * @return
	 * A pointer to the record element if successful, otherwise NULL.
	 */
	virtual CXTPGridRecord* FindRecordByBookmark(VARIANT vtBookmark, BOOL bSearchInChildren);

	/**
	 * @brief
	 * Retrieves a record item by its text.
	 * @param nStartRecord Starting record index.
	 * @param nEndRecord   Ending record index.
	 * @param nStartColumn Starting column index.
	 * @param nEndColumn   Ending column index.
	 * @param nRecord      Record index to start the search from.
	 * @param nItem        Record item index to start the search from.
	 * @param pcszText     Search text.
	 * @param nFlags       Search parameters.
	 * @return
	 * A pointer to the record item if successful, otherwise NULL.
	 */
	virtual CXTPGridRecordItem* FindRecordItem(int nStartRecord, int nEndRecord, int nStartColumn,
											   int nEndColumn, int nRecord, int nItem,
											   LPCTSTR pcszText, int nFlags);

	void MergeItems(const CXTPGridRecordItemRange& range);

	/**
	 * @brief
	 * This method is called before record dropping is processed.
	 * @param pTargetRecord  Pointer to the record which is the target for dropping. Set
	 * to NULL to skip recursion checking. Also can be NULL when
	 * records are dropped on the top level of the Grid control.
	 * @param pTargetRecords Pointer to the records which are the target for dropping.
	 * @param bChangeParent  TRUE to change the parent of the current CXTPGridRecords.
	 */
	virtual void PrepareToDropping(CXTPGridRecord* pTargetRecord, CXTPGridRecords* pTargetRecords,
								   BOOL bChangeParent);

	/**
	 * @brief
	 * Removes redundant records.
	 */
	virtual void CleanOfRedundant();

protected:
	/** @cond */
	void SetVirtualMode(CXTPGridRecord* pVirtualRecord, int nCount);
	BOOL IsVirtualMode() const;
	virtual void _DoPropExchange(CXTPPropExchange* pPX);
	/** @endcond */

protected:
	CArray<CXTPGridRecord*, CXTPGridRecord*> m_arrRecords; /**< Internal storage array for record
															  items. */
	CXTPGridRecord* m_pVirtualRecord;					   // Virtual record.
	int m_nVirtualRecordsCount;							   /**< Virtual records count. */
	CXTPGridControl* m_pControl; /**< Pointer to the parent Grid control. */
	/** @cond */
	BOOL m_bArray;
	/** @endcond */

	BOOL m_bCaseSensitive; /**< Indicates whether string comparisons are case-sensitive. */

	CXTPGridRecord* m_pOwnerRecord; /**< Pointer to the owner record object (or NULL). */

	CXTPMarkupContext* m_pMarkupContext; /**< Markup context; */

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

	DECLARE_OLETYPELIB_EX(CXTPGridRecords);

	afx_msg int OleGetItemCount();
	afx_msg LPDISPATCH OleGetItem(long nIndex);
	afx_msg LPDISPATCH OleAdd();

	afx_msg LPDISPATCH OleInsert(int nIndex);
	afx_msg void OleInsertAt(int nIndex, LPDISPATCH pdispRecord);

	afx_msg LPDISPATCH OleFindRecordItem(int nStartRecord, int nEndRecord, int nStartColumn,
										 int nEndColumn, int nRecord, int nItem, LPCTSTR pcszText,
										 int nFlags);

	afx_msg void OleMergeItems(int nRecordFrom, int nRecordTo, int nColumnFrom, int nColumnTo);

	afx_msg void OleDoPropExchange(LPDISPATCH lpPropExchage);

	DECLARE_ENUM_VARIANT(CXTPGridRecords)

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

/** @endcond */
#	endif

	friend class CXTPGridControl;
	friend class CXTPGridRecord;
	friend class CXTPGridSection;
};
/** @cond */
AFX_INLINE BOOL CXTPGridRecords::IsVirtualMode() const
{
	return m_pVirtualRecord != NULL;
}
/** @endcond */
AFX_INLINE void CXTPGridRecords::SetCaseSensitive(BOOL bCaseSensitive)
{
	m_bCaseSensitive = bCaseSensitive;
}

AFX_INLINE BOOL CXTPGridRecords::IsCaseSensitive() const
{
	return m_bCaseSensitive;
}

AFX_INLINE CXTPGridRecord* CXTPGridRecords::GetOwnerRecord() const
{
	return m_pOwnerRecord;
}

AFX_INLINE CXTPMarkupContext* CXTPGridRecords::GetMarkupContext() const
{
	return m_pMarkupContext;
}

AFX_INLINE void CXTPGridRecords::SetMarkupContext(CXTPMarkupContext* pMarkupContext)
{
	m_pMarkupContext = pMarkupContext;
}
/** @cond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif //#if !defined(__XTPGRIDRECORDS_H__)
	   /** @endcond */