/**
 * @file XTPGridSelectedRows.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(__XTPGRIDSELECTEDROWS_H__)
#	define __XTPGRIDSELECTEDROWS_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
 * Encapsulates a collection of CXTPGridRow pointers that represent
 * the selected rows in a Grid control.
 * @details
 * Use this class to programmatically manage a collection of
 * CXTPGridRow pointers that represent the selected rows in a
 * Grid control. This class is commonly used to add or remove rows
 * from the collection.
 *
 * Typical work flow is using the Add and Remove methods to change the
 * contents of the selection and using the Contains method to check
 * if a specific row is present in the selection.
 *
 * <b>Example:</b>
 * The following example demonstrates how to programmatically use
 * the CXTPGridSelectedRows class to select rows in the Grid control.
 * <pre>
 * CXTPGridSelectedRows* pSelRows = pGridControl->GetSelectedRows();
 * pSelRows->Add(pRow1);
 * pSelRows->Add(pRow2);
 * _ASSERTE(TRUE == pSelRows->Contains(pRow1));
 * _ASSERTE(TRUE == pSelRows->Contains(pRow2));
 * pSelRows->Remove(pRow1);
 * _ASSERTE(FALSE == pSelRows->Contains(pRow1));
 * pSelRows->Select(pRow1);
 * _ASSERTE(TRUE == pSelRows->Contains(pRow1));
 * _ASSERTE(FALSE == pSelRows->Contains(pRow2));
 * </pre>
 *
 * @see
 * CXTPGridRow, CXTPGridSelectedRows, CXTPGridControl::GetSelectedRows
 */
class _XTP_EXT_CLASS CXTPGridSelectedRows : public CXTPCmdTarget
{
public:
	/**
	 * @brief
	 * Constructs an empty CXTPGridSelectedRows collection.
	 * @param pControl Pointer to the parent Grid control.
	 * @details
	 * This collection can only be created in association with
	 * the CXTPGridControl object.
	 *
	 * <b>Example:</b>
	 * <pre>
	 * // from CXTPGridControl member function
	 * CXTPGridSelectedRows* pSelectedRows = new CXTPGridSelectedRows(this);
	 * </pre>
	 * @see
	 * CXTPGridSelectedRows overview
	 */
	CXTPGridSelectedRows(CXTPGridControl* pControl);

	/**
	 * @brief
	 * Selects a block of rows.
	 * @param nBlockBegin First row index of the block.
	 * @param nBlockEnd   Final row index of the block.
	 * @param bControlKey Indicates the control key button state during
	 * the selection operation.
	 * @details
	 * This function uses nBlockBegin and nBlockEnd as the bounds for the
	 * required selection. It enumerates the parent Grid control rows collection
	 * and adds all rows from nBlockEnd to nBlockEnd inclusively to the selection.
	 */
	void SelectBlock(int nBlockBegin, int nBlockEnd, BOOL bControlKey = TRUE);

	/**
	 * @brief
	 * Clears itself, removing all elements from the selection.
	 * @return TRUE if successful; otherwise FALSE.
	 */
	BOOL Clear();

	/**
	 * @brief
	 * Clears itself, removing all elements from the selection.
	 * @param bNotifyOnClear TRUE to send a clear notification.
	 * @return TRUE if successful; otherwise FALSE.
	 */
	BOOL Clear(BOOL bNotifyOnClear);

	/**
	 * @brief
	 * Adds a row to the selection.
	 * @param pRow Pointer to the row to be added to the selection.
	 * @details
	 * This method adds a provided row pointer to the selection.
	 * After adding, the Contains method will return TRUE for all
	 * checking attempts of this row pointer.
	 *
	 * <b>Example:</b>
	 * See example at CXTPGridSelectedRows overview
	 * @return TRUE if successful; otherwise FALSE.
	 * @see
	 * CXTPGridSelectedRows overview, Remove, Select, Clear, Contains
	 */
	BOOL Add(CXTPGridRow* pRow);

	/**
	 * @brief
	 * Adds a block to the selection.
	 * @param nIndexBegin         First row index of the block to be selected.
	 * @param nIndexEnd           Final row index of the block to be selected.
	 * @param bDeselectIfSelected TRUE to deselect rows if all rows in the new selection
	 * [nIndexBegin:nIndexEnd] were selected before.
	 */
	void AddBlock(int nIndexBegin, int nIndexEnd, BOOL bDeselectIfSelected = FALSE);

	/**
	 * @brief
	 * Removes a row from the selection.
	 * @param pRow Pointer to the row to be removed from the selection.
	 * @details
	 * This method removes a provided row pointer from the selection.
	 * After removing, the Contains method will return FALSE for all
	 * checking attempts of this row pointer.
	 *
	 * <b>Example:</b>
	 * See example at CXTPGridSelectedRows overview
	 * @see
	 * CXTPGridSelectedRows overview, Add, Select, Clear, Contains
	 */
	void Remove(CXTPGridRow* pRow);

	/**
	 * @brief
	 * Determines if a specified row is contained within the selection.
	 * @param pRow Pointer to the row to check for.
	 * @details
	 * Use this method to determine whether the CXTPGridSelectedRows
	 * contains the specified CXTPGridRow pointer.
	 * @return
	 * TRUE if the row is contained within the selection, otherwise FALSE.
	 *
	 * <b>Example:</b>
	 * See example at CXTPGridSelectedRows overview
	 * @see
	 * CXTPGridSelectedRows overview, Add, Remove, Select, Clear
	 */
	BOOL Contains(const CXTPGridRow* pRow);

	/**
	 * @brief
	 * Inverts the selection for a specified row.
	 * @param pRow Pointer to the row to invert the selection for.
	 * @details
	 * This methods checks the specified row for its presence in
	 * the collection and either adds or removes it in the reverse order
	 * depending on the result.
	 *
	 * <b>Example:</b>
	 * <pre>
	 * CXTPGridSelectedRows* pSelRows = pGridControl->GetSelectedRows();
	 * _ASSERTE(TRUE == pSelRows->Contains(pRow1));
	 * pSelRows->Invert(pRow1);
	 * _ASSERTE(FALSE == pSelRows->Contains(pRow1));
	 * pSelRows->Invert(pRow1);
	 * _ASSERTE(TRUE == pSelRows->Contains(pRow1));
	 * </pre>
	 * @see
	 * Add, Remove, Contains
	 */
	void Invert(CXTPGridRow* pRow);

	/**
	 * @brief
	 * Clears the initial selection and selects a specified row.
	 * @param pRow Pointer to the row to select.
	 * @details
	 * This method clears the initial selection and selects only the specified row.
	 *
	 * <b>Example:</b>
	 * See example at CXTPGridSelectedRows overview
	 * @return TRUE if successful; otherwise FALSE.
	 * @see
	 * CXTPGridSelectedRows overview, Add, Remove, Contains, Clear
	 */
	BOOL Select(CXTPGridRow* pRow);

	/**
	 * @brief
	 * Removes block [ib:ie] from the selection.
	 * @param ib         First row index of the block to be deselected.
	 * @param ie         Last row index of the block to be deselected.
	 * @param bCollapsed BOOL flag that specifies if rows are deleted or collapsed. If TRUE,
	 * then the selected rows below block [ib:ie] should be moved upward.
	 * @see
	 * CXTPGridSelectedRows overview, Add, Select, Clear, Contains, Remove
	 */
	void DeselectBlock(int ib, int ie, BOOL bCollapsed);

	/**
	 * @brief
	 * Gets the number of selected rows in the collection.
	 * @return
	 * The number of selected rows in the collection.
	 * @see
	 * CXTPGridRows overview
	 */
	int GetCount();

	/**
	 * @brief
	 * Retrieves a specified row by its index.
	 * @param nIndex Index of the row to retrieve.
	 * @return
	 * A pointer to the specified row.
	 * @details
	 * Recommended to use the GetFirstSelectedRowPosition and
	 * GetNextSelectedRow methods.
	 * @see
	 * GetFirstSelectedRowPosition, GetNextSelectedRow
	 */
	CXTPGridRow* GetAt(int nIndex);

	/**
	 * @brief
	 * Gets the position of the first selected row in the list Grid control.
	 * @return
	 * The position of the first selected row in the list Grid control
	 * if successful, or NULL if no items are selected.
	 * @details
	 * The position of the first selected row in the list Grid control
	 * can be used for iteration or object pointer retrieval.
	 * @see
	 * GetNextSelectedItem
	 */
	POSITION GetFirstSelectedRowPosition();

	/**
	 * @brief
	 * Gets the next selected row in the list Grid control.
	 * @param pos Reference to a POSITION value returned by a previous call
	 * to GetNextSelectedRow or GetFirstSelectedRowPosition.
	 * This value is updated to the next position by this call.
	 * @return
	 * A pointer to the next selected row in the list Grid control.
	 */
	CXTPGridRow* GetNextSelectedRow(POSITION& pos);

	/**
	 * @brief
	 * Determines if the selection was changed.
	 * @return
	 * TRUE if the selection was changed, otherwise FALSE.
	 */
	BOOL IsChanged() const;

	/**
	 * @brief
	 * Specifies if the selection was changed.
	 * @param bChanged TRUE if the selection was changed, FALSE otherwise.
	 * By default, this parameter is TRUE.
	 */
	void SetChanged(BOOL bChanged = TRUE);

	/**
	 * @brief
	 * Swaps two integers.
	 * @param indexB Reference to the first integer.
	 * @param indexE Reference to the second integer.
	 * @details
	 * The swap should only occur if indexB is greater than indexE.
	 * @return
	 * TRUE if the operation was successful, otherwise FALSE.
	 */
	BOOL SwapIfNeed(int& indexB, int& indexE);

	/**
	 * @brief
	 * Specifies if clear notifications are enabled/disabled during
	 * CXTPGridSelectedRows::Select and SelectBlock.
	 * @param bNotifyOnClear TRUE to enable clear notifications,
	 * FALSE to disable clear notifications.
	 * By default, this parameter is TRUE.
	 * @details
	 * If clear notifications are enabled (TRUE), then calling
	 * CXTPGridSelectedRows::Select and SelectBlock will send
	 * xtpGridSelectionClear notifications when the selected
	 * rows are internally cleared (i.e. normal behavior).
	 * If clear notifications are disabled (FALSE), then clear notifications
	 * will not be sent during CXTPGridSelectedRows::Select and SelectBlock.
	 */
	void SetNotifyOnClear(BOOL bNotifyOnClear = TRUE);

	/**
	 * @brief
	 * Determines if clear notifications are enabled/disabled during
	 * CXTPGridSelectedRows::Select and SelectBlock.
	 * @return
	 * TRUE if clear notification are enabled,
	 * FALSE if clear notifications are disabled.
	 * @details
	 * If clear notifications are enabled (TRUE), then calling
	 * CXTPGridSelectedRows::Select and SelectBlock will send
	 * xtpGridSelectionClear notifications when the selected
	 * rows are internally cleared (i.e. normal behavior).
	 * If clear notifications are disabled (FALSE), then clear notifications
	 * will not be sent during CXTPGridSelectedRows::Select and SelectBlock.
	 */
	BOOL GetNotifyOnClear() const;

	/**
	 * @brief
	 * Gets the type of the selected rows (i.e. body, header, or footer).
	 * @return
	 * The type of the selected rows (i.e. body, header, or footer);
	 * one of the values defined by the XTPGridRowType enumeration.
	 */
	XTPGridRowType GetRowType() const;

protected:
	/** @cond */
	BOOL _NotifySelChanging(XTPGridSelectionChangeType nType, CXTPGridRow* pRow = NULL);
	void _NotifyStateChanged(int nBegin, int nEnd);
	void _InsertBlock(int nIndexInsert, int nIndexBegin, int nIndexEnd);
	void _OnExpanded(int nIndex, int nCount);
	void _OnCollapsed(int nIndex, int nCount);

	struct SELECTED_BLOCK
	{
		int nIndexBegin;
		int nIndexEnd;
	};

	CXTPGridControl* m_pControl; /**< Pointer to the parent Grid control. */
	int m_nRowBlockBegin;		 /**< Index of the row where rows block begin from. */
	int m_nPosSelected;
	BOOL m_bNotifyOnClear; /**< If TRUE, then calling CXTPGridSelectedRows::Select and SelectBlock
							  will send xtpGridSelectionClear notifications when the selected rows
							  are internally cleared (normal behavior). If FALSE, then it will not
							  send the clear notifications during CXTPGridSelectedRows::Select and
							  SelectBlock. */

	CArray<SELECTED_BLOCK, SELECTED_BLOCK&> m_arrSelectedBlocks;

	BOOL m_bChanged;
	XTPGridRowType m_nRowType; /**< Only rows of one type can be selected (i.e. body, header, or
								  footer). */
							   /** @endcond */

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

	DECLARE_OLETYPELIB_EX(CXTPGridSelectedRows);

	afx_msg void OleAdd(LPDISPATCH lpRow);
	afx_msg void OleDeleteAll();
	afx_msg LPDISPATCH OleGetItem(long nIndex);
	int OleGetItemCount();

	DECLARE_ENUM_VARIANTLIST(CXTPGridSelectedRows);

	enum
	{
		dispidCount = 1L,
	};

/** @endcond */
#	endif
	/** @cond */
	friend class CXTPGridControl;
	friend class CXTPGridSection;
	/** @endcond */
};

AFX_INLINE void CXTPGridSelectedRows::SetNotifyOnClear(BOOL bNotifyOnClear)
{
	m_bNotifyOnClear = bNotifyOnClear;
}

AFX_INLINE BOOL CXTPGridSelectedRows::GetNotifyOnClear() const
{
	return m_bNotifyOnClear;
}

AFX_INLINE BOOL CXTPGridSelectedRows::IsChanged() const
{
	return m_bChanged;
}

AFX_INLINE void CXTPGridSelectedRows::SetChanged(BOOL bChanged)
{
	m_bChanged = bChanged;
}

AFX_INLINE XTPGridRowType CXTPGridSelectedRows::GetRowType() const
{
	return m_nRowType;
}
/** @cond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif //#if !defined(__XTPGRIDSELECTEDROWS_H__)
	   /** @endcond */