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

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

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

class CXTPGridRecordItem;
class CXTPGridRecordItemPreview;
class CXTPGridColumn;
class CXTPGridRecords;
class CXTPPropExchange;
class CXTPMarkupContext;

struct XTP_GRIDRECORDITEM_DRAWARGS;
struct XTP_GRIDRECORDITEM_METRICS;

/**
 * @brief
 * CXTPGridRecord represents a collection of CXTPGridRecordItem objects
 * or objects of classes that are children of CXTPGridRecordItem.
 * A collection of such items is one record in a GridControl list.
 * You create an object of CXTPGridRecord by simply calling its constructor.
 * After calling its constructor, you can add items to the record.
 *
 * <b>Example:</b>
 * <pre>
 * // add new record to the record list
 * CXTPGridRecords* pList = new CXTPGridRecords();
 * pList->Add(new CXTPGridRecord());
 * </pre>
 */
class _XTP_EXT_CLASS CXTPGridRecord : public CXTPHeapObjectT<CXTPCmdTarget, CXTPGridDataAllocator>
{
	friend class CXTPGridRecords;
	friend class CXTPGridRow;
	friend class CXTPGridControl;
	friend class CXTPGridRecordItem;
	friend class CXTPGridPaintManager;
	/** @cond */
	DECLARE_SERIAL(CXTPGridRecord)
	/** @endcond */
public:
	/**
	 * @brief
	 * Constructs a CXTPGridRecord object.
	 */
	CXTPGridRecord();

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

	/**
	 * @brief
	 * Gets the number of items inside the record.
	 * @return
	 * The number of items inside the record.
	 * @see
	 * GetItem
	 */
	int GetItemCount() const;

	/**
	 * @brief
	 * Retrieves a record item by its index/column.
	 * @param nIndex  Zero-based index of the record item in the collection.
	 * @details
	 * You use this member function to get a record item from the collection by
	 * its index. If the provided index is less than 0 or greater than the
	 * value returned by GetItemCount, then GetItem will return NULL.
	 * @return
	 * A pointer to the record item if successful, otherwise NULL.
	 * @see
	 * GetItemCount
	 */
	CXTPGridRecordItem* GetItem(int nIndex) const;

	/**
	 * @brief
	 * Retrieves a record item by its index/column.
	 * @param pColumn Pointer to the column of the record item.
	 * @details
	 * You use this member function to get a record item from the collection by
	 * its index. If the provided index is less than 0 or greater than the
	 * value returned by GetItemCount, then GetItem will return NULL.
	 * @return
	 * A pointer to the record item if successful, otherwise NULL.
	 * @see
	 * GetItemCount
	 */
	CXTPGridRecordItem* GetItem(CXTPGridColumn* pColumn) const;

	/**
	 * @brief
	 * Gets the associated preview item of the record.
	 * @details
	 * Preview items are stored separately from all other items. A record
	 * can have only one preview item. If a GridRecord does not have
	 * a preview item, then GetItemPreview() will return NULL.
	 * @return
	 * The associated preview item if successful, otherwise NULL.
	 * @see
	 * SetPreviewItem
	 */
	CXTPGridRecordItemPreview* GetItemPreview() const;

	/**
	 * @brief
	 * Sets the associated preview item for the record.
	 * @param pItemPreview Pointer to the preview item to set.
	 * @details
	 * Preview items are stored separately from all other items. A record
	 * can have only one preview item.
	 * @see
	 * GetItemPreview
	 */
	void SetPreviewItem(CXTPGridRecordItemPreview* pItemPreview);

	/**
	 * @brief
	 * Gets the visible state of the record.
	 * @return
	 * TRUE if the record is visible, FALSE if the record is hidden.
	 * @see
	 * SetVisible
	 */
	BOOL IsVisible() const;

	/**
	 * @brief
	 * Sets the visible state for the record.
	 * @param bVisible TRUE to set the record to visible,
	 * FALSE to set the record to hidden.
	 * @see
	 * IsVisible
	 */
	void SetVisible(BOOL bVisible);

	/**
	 * @brief
	 * Gets the locked state of the record.
	 * @return
	 * TRUE if the record is locked, FALSE if the record is unlocked.
	 * @see
	 * SetLocked
	 */
	BOOL IsLocked() const;

	/**
	 * @brief
	 * Sets the locked state for the record.
	 * @param bLocked TRUE to set the record to locked,
	 * FALSE to set the record to unlocked.
	 * @details
	 * You should set the record to locked when the record
	 * should not be sorted on hide.
	 * @see
	 * IsLocked
	 */
	void SetLocked(BOOL bLocked);

	/**
	 * @brief
	 * Gets the editable state of the record.
	 * @return
	 * TRUE if the record is editable, otherwise FALSE.
	 * @see
	 * SetEditable
	 */
	BOOL IsEditable() const;

	/**
	 * @brief
	 * Sets the editable state for the record.
	 * @param bEditable TRUE to set the record to editable, FALSE otherwise.
	 */
	void SetEditable(BOOL bEditable = TRUE);

	/**
	 * @brief
	 * Gets the list of child items of the record.
	 * @details
	 * A grid record can have a list of child items.
	 * This method is used to get a pointer to that list.
	 * @return
	 * A pointer to the list of child items of the record.
	 */
	CXTPGridRecords* GetChilds();

	/**
	 * @brief
	 * Gets the list of parent items of the record.
	 * @return
	 * A pointer to the list of parent items of the record.
	 */
	CXTPGridRecords* GetRecords() const;

	/**
	 * @brief
	 * Determines if the record has child records.
	 * @return
	 * TRUE if the record has child records, otherwise FALSE.
	 * @see
	 * GetChilds
	 */
	BOOL HasChildren() const;

	/**
	 * @brief
	 * Removes all items from the record.
	 */
	void RemoveAll();

	/**
	 * @brief
	 * Gets the index of a specified record item object.
	 * @param pItem Pointer to the record item whose index must be retrieved.
	 * @return
	 * The zero-based index of the specified record item if successful,
	 * otherwise a value of -1.
	 */
	int IndexOf(const CXTPGridRecordItem* pItem) const;

	/**
	 * @brief
	 * Calculates item metrics based on specified draw arguments.
	 * Can be overridden by descendants.
	 * @param pDrawArgs    Pointer to an XTP_GRIDRECORDITEM_DRAWARGS
	 * structure used to calculate item metrics.
	 * @param pItemMetrics Pointer to an XTP_GRIDRECORDITEM_METRICS
	 * structure to fill with values.
	 */
	virtual void GetItemMetrics(XTP_GRIDRECORDITEM_DRAWARGS* pDrawArgs,
								XTP_GRIDRECORDITEM_METRICS* pItemMetrics);

	/**
	 * @brief
	 * Updates DataSet in VirtualMode without involving _RecordsetPtr.
	 * @details
	 * Can be overridden by descendants.
	 * @param row   Row.
	 * @param index Index.
	 * @param sText Value as a string.
	 * @return
	 * TRUE if successful.
	 */
	virtual BOOL UpdateRecordField(int row, int index, CString sText);

	/**
	 * @brief
	 * Gets the expanded state of the record.
	 * @details
	 * If the expanded state is set to TRUE, then the control will
	 * attempt to draw the record with all of its children.
	 * @return
	 * TRUE if the record is expanded, otherwise FALSE.
	 * @see
	 * SetExpanded
	 */
	BOOL IsExpanded() const;

	/**
	 * @brief
	 * Sets the expanded state for the record.
	 * @param bExpanded TRUE to set the record state to expanded.
	 * @details
	 * If the expanded state is set to TRUE, then the control will
	 * attempt to draw the record with all of its children.
	 * @see
	 * IsExpanded
	 */
	virtual void SetExpanded(BOOL bExpanded);

	BOOL IsSelected() const;

	void SetSelected(BOOL bSelected);

	/**
	 * @brief
	 * Determines if the record is filtered.
	 * @return
	 * TRUE if the record is filtered, otherwise FALSE.
	 */
	virtual BOOL IsFiltered() const;

	/**
	 * @brief
	 * Gets the record index in the array.
	 * @return
	 * The record index in the array.
	 */
	int GetIndex() const;

	/**
	 * @brief
	 * Adds a record item to the internal records item collection.
	 * @param pItem Pointer to the record item to add.
	 * @return
	 * A pointer to the newly added record item.
	 */
	CXTPGridRecordItem* AddItem(CXTPGridRecordItem* pItem);

	/**
	 * @brief
	 * Call this member function to store/load a grid record with record
	 * items using the specified data object.
	 * @param pPX Source/destination CXTPPropExchange data object reference.
	 */
	virtual void DoPropExchange(CXTPPropExchange* pPX);

	/**
	 * @brief
	 * Removes the record.
	 */
	void Delete();

	/**
	 * @brief
	 * Increments the reference counter of a record and all of its children.
	 */
	void TreeAddRef();

	/**
	 * @brief
	 * Decrements the reference counter of a record and all of its children.
	 */
	void TreeRelease();

	/**
	 * @brief
	 * Sets the bookmark for the data source record.
	 * @param vtBookmark Bookmark to be set.
	 */
	void SetBookmark(VARIANT vtBookmark);

	/**
	 * @brief
	 * Gets the bookmark to the data source record.
	 * @return
	 * The bookmark to the data source record.
	 */
	VARIANT GetBookmark() const;

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

	/**
	 * @brief
	 * Gets the parent record.
	 * @return
	 * A pointer to the parent record.
	 */
	CXTPGridRecord* GetParentRecord() const;

	/**
	 * @brief
	 * Gets the height of rows in FreeHeight RC mode.
	 * @return
	 * The height of rows in FreeHeight RC mode.
	 */
	int GetFreeHeight();

	/**
	 * @brief
	 * Sets the height for rows in FreeHeight RC mode.
	 * @param nFreeHeight Height to be set.
	 */
	void SetFreeHeight(int nFreeHeight);

protected:
	void SetGridControl(CXTPGridControl* pGridControl);

	/** @cond */
	_XTP_DEPRECATED_IN_FAVOR(SetGridControl)
	void SetReportControl(CXTPGridControl* pGridControl);
	/** @endcond */

protected:
	CArray<CXTPGridRecordItem*, CXTPGridRecordItem*> m_arrItems; /**< An internal storage for record
																	items. */

	CXTPGridRecordItemPreview* m_pPreviewItem; /**< Preview item for record. */

	CXTPGridControl* m_pControl;  /**< Pointer to the parent Grid control. */
	CXTPGridRecords* m_pRecords;  /**< Parent records collection. */
	CXTPGridRecords* m_pChildren; /**< A collection of children records. */

	BOOL m_bExpanded; /**< TRUE if the record is expanded, FALSE otherwise. */
	BOOL m_bEditable; /**< TRUE if the record is editable, FALSE otherwise. */
	BOOL m_bVisible;  /**< TRUE if the record is visible, FALSE otherwise. */
	BOOL m_bLocked;   /**< TRUE if the record is locked, FALSE otherwise. */
	BOOL m_bSelected; /**< TRUE if the record is selected, FALSE otherwise. */

	int m_nFreeHeight;	/**< Height of a visual row in FreeHeight RC mode. */
	int m_nIndex;		  /**< Index of the record within the collection records. */
	VARIANT m_vtBookmark; /**< Bookmark to data source record for data binding. */

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

	DECLARE_OLETYPELIB_EX(CXTPGridRecord);
	DECLARE_OLECREATE_EX(CXTPGridRecord);

	int OleGetItemCount();
	afx_msg LPDISPATCH OleGetItem(long nIndex);
	afx_msg LPDISPATCH OleAdd(const VARIANT& lpValue);
	afx_msg LPDISPATCH OleGetChilds();
	afx_msg LPDISPATCH OleGetParentRecord();
	afx_msg LPDISPATCH OleGetRecords();
	afx_msg void OleAddEx(LPDISPATCH lpDisp);

	DECLARE_ENUM_VARIANT(CXTPGridRecord)

	afx_msg BSTR OleGetPreviewText();
	afx_msg void OleSetPreviewText(LPCTSTR lpszText);
	afx_msg LPDISPATCH OleGetPreviewItem();
	afx_msg int OleGetFreeHeight();
	afx_msg void OleSetFreeHeight(int nFreeHeight);

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

	COleVariant m_oleTag;

public:
	static CXTPGridRecord* AFX_CDECL FromDispatch(LPDISPATCH pDisp);

/** @endcond */
#	endif /*_XTP_ACTIVEX*/
};

AFX_INLINE int CXTPGridRecord::GetItemCount() const
{
	return (int)m_arrItems.GetSize();
}

AFX_INLINE CXTPGridRecordItem* CXTPGridRecord::GetItem(int nIndex) const
{
	return nIndex >= 0 && nIndex < GetItemCount() ? m_arrItems.GetAt(nIndex) : NULL;
}

AFX_INLINE BOOL CXTPGridRecord::IsVisible() const
{
	return m_bVisible;
}

AFX_INLINE void CXTPGridRecord::SetVisible(BOOL bVisible)
{
	m_bVisible = bVisible;
}

AFX_INLINE BOOL CXTPGridRecord::IsEditable() const
{
	return m_bEditable;
}

AFX_INLINE BOOL CXTPGridRecord::IsExpanded() const
{
	return m_bExpanded;
}

AFX_INLINE BOOL CXTPGridRecord::IsLocked() const
{
	return m_bLocked;
}

AFX_INLINE void CXTPGridRecord::SetLocked(BOOL bLocked)
{
	m_bLocked = bLocked;
}

AFX_INLINE BOOL CXTPGridRecord::IsSelected() const
{
	return m_bSelected;
}

AFX_INLINE void CXTPGridRecord::SetSelected(BOOL bSelected)
{
	m_bSelected = bSelected;
}

AFX_INLINE int CXTPGridRecord::GetFreeHeight()
{
	return m_nFreeHeight;
}

AFX_INLINE void CXTPGridRecord::SetFreeHeight(int nFreeHeight)
{
	m_nFreeHeight = nFreeHeight;
}

AFX_INLINE void CXTPGridRecord::GetItemMetrics(XTP_GRIDRECORDITEM_DRAWARGS* pDrawArgs,
											   XTP_GRIDRECORDITEM_METRICS* pItemMetrics)
{
	UNREFERENCED_PARAMETER(pDrawArgs);
	UNREFERENCED_PARAMETER(pItemMetrics);
}

AFX_INLINE BOOL CXTPGridRecord::UpdateRecordField(int /*row*/, int /*index*/, CString /*sText*/)
{
	return TRUE;
}
AFX_INLINE CXTPGridRecords* CXTPGridRecord::GetRecords() const
{
	return m_pRecords;
}
AFX_INLINE void CXTPGridRecord::SetBookmark(VARIANT vtBookmark)
{
	m_vtBookmark = vtBookmark;
}
AFX_INLINE VARIANT CXTPGridRecord::GetBookmark() const
{
	return m_vtBookmark;
}
/** @cond */
AFX_INLINE void CXTPGridRecord::SetReportControl(CXTPGridControl* pGridControl)
{
	SetGridControl(pGridControl);
}

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