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

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

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

class CXTPGridControl;
class CXTPGridRow;
class CXTPGridHeader;
class CXTPGridColumn;

/**
 * @brief
 * Utility class, handles Grid control item navigation.
 * @see
 * CXTPGridControl overview
 */
class _XTP_EXT_CLASS CXTPGridNavigator : public CXTPCmdTarget
{
	friend class CXTPGridControl;

public:
	/**
	 * @brief
	 * Default navigator constructor, handles properties initialization.
	 * @param pGridControl Pointer to a CXTPGridControl object
	 * @see
	 * RefreshMetrics
	 */
	CXTPGridNavigator(CXTPGridControl* pGridControl);

	/**
	 * @brief
	 * Default navigator destructor, handles member items deallocation.
	 */
	virtual ~CXTPGridNavigator();

	/**
	 * @brief
	 * Call this method to begin editing the currently focused item.
	 */
	virtual void BeginEdit();

	/**
	 * @brief
	 * Moves the focused row down by one.
	 * @param bShiftKey   TRUE to select a new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row down by one.
	 * @see
	 * MoveUp, MovePageDown, MovePageUp, MoveFirst, MoveLast
	 */
	virtual void MoveDown(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row down by one.
	 * @param bShiftKey   TRUE to select a new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row down by one.
	 * @see
	 * MoveUp, MovePageDown, MovePageUp, MoveFirst, MoveLast
	 */
	virtual void MoveDownStep(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row up by one.
	 * @param bShiftKey   TRUE to select a new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row up by one.
	 * @see
	 * MoveDown, MovePageDown, MovePageUp, MoveFirst, MoveLast
	 */
	virtual void MoveUp(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row up by one.
	 * @param bShiftKey   TRUE to select a new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row up by one.
	 * @see
	 * MoveDown, MovePageDown, MovePageUp, MoveFirst, MoveLast
	 */
	virtual void MoveUpStep(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row down by one page.
	 * @param bShiftKey   TRUE to select rows up to the new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row down by one page
	 * (and count the visible rows in a view).
	 * @see
	 * MoveDown, MoveUp, MovePageUp, MoveFirst, MoveLast
	 */
	virtual void MovePageDown(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row up by one page.
	 * @param bShiftKey   TRUE to select rows up to the new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row up by one page
	 * (and count the visible rows in a view).
	 * @see
	 * MoveDown, MoveUp, MovePageDown, MoveFirst, MoveLast
	 */
	virtual void MovePageUp(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row to the beginning of the grid view.
	 * @param bShiftKey   TRUE to select rows up to the new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row to the top of the rows list.
	 * @see
	 * MoveDown, MoveUp, MovePageDown, MovePageUp, MoveLast
	 */
	void MoveFirstRow(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row to the end of the grid view.
	 * @param bShiftKey   TRUE to select rows up to the new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row to the bottom of the rows list.
	 * @see
	 * MoveDown, MoveUp, MovePageDown, MovePageUp, MoveFirst
	 */
	void MoveLastRow(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row to a specified row index.
	 * @param nRowIndex   Row index to move the focused row to.
	 * @param bShiftKey   TRUE to select rows up to the new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused row to the specified row index.
	 * @see
	 * MoveDown, MoveUp, MovePageDown, MovePageUp, MoveFirst
	 */
	void MoveToRow(int nRowIndex, BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused column to the beginning of the currently selected row.
	 * @see
	 * MoveLastColumn
	 */
	void MoveFirstColumn();

	/**
	 * @brief
	 * Moves the focused column to the end of the currently selected row.
	 * @see
	 * MoveFirstColumn
	 */
	void MoveLastColumn();

	/**
	 * @brief
	 * Moves the focused column left by one.
	 * @param bShiftKey   TRUE to select a new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused column left by one.
	 * @see
	 * MoveUp, MovePageDown, MovePageUp, MoveFirst, MoveLast
	 */
	void MoveLeft(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused column right by one.
	 * @param bShiftKey   TRUE to select a new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @details
	 * Moves the currently focused column right by one.
	 * @see
	 * MoveDown, MovePageDown, MovePageUp, MoveFirst, MoveLast
	 */
	void MoveRight(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused column to a specified column index.
	 * @param nColumnIndex         Column index to move the focused column to.
	 * @param bClearIfNonFocusable Used in the event that the column specified by
	 * nColumnIndex is not focusable. TRUE to clear
	 * the column focus (resulting in no column having
	 * focus), FALSE to prevent the focused column
	 * from being changed.
	 * @details
	 * Moves the currently focused column to the specified column index.
	 * @see
	 * MoveDown, MovePageDown, MovePageUp, MoveFirst, MoveLast
	 */
	void MoveToColumn(int nColumnIndex, BOOL bClearIfNonFocusable = FALSE);

	/**
	 * @brief
	 * Sets the current focus (selected row) to header rows.
	 * @param bCurrentFocusInHeadersRows TRUE to set the current focus to header rows,
	 * FALSE otherwise.
	 * @see
	 * GetCurrentFocusInHeadersRows
	 */
	void SetCurrentFocusInHeadersRows(BOOL bCurrentFocusInHeadersRows);

	/**
	 * @brief
	 * Sets the current focus (selected row) to footer rows.
	 * @param bCurrentFocusInFootersRows TRUE to set the current focus to footer rows,
	 * FALSE otherwise.
	 * @see
	 * GetCurrentFocusInFootersRows
	 */
	void SetCurrentFocusInFootersRows(BOOL bCurrentFocusInFootersRows);

	/**
	 * @brief
	 * Determines if the current focus (selected row) belongs to header rows.
	 * @return
	 * TRUE if the current focus (selected row) belongs to header rows,
	 * otherwise FALSE.
	 * @see
	 * SetCurrentFocusInHeadersRows
	 */
	BOOL GetCurrentFocusInHeadersRows();

	/**
	 * @brief
	 * Determines if the current focus (selected row) belongs to footer rows.
	 * @return
	 * TRUE if the current focus (selected row) belongs to footer rows,
	 * otherwise FALSE.
	 * @see
	 * SetCurrentFocusInFootersRows
	 */
	BOOL GetCurrentFocusInFootersRows();

protected:
	/**
	 * @brief
	 * Moves the focused column left/right.
	 * @param bBack       TRUE to move left, FALSE to move right.
	 * @param bShiftKey   TRUE to select a new focused row.
	 * @param bControlKey TRUE to ignore the current rows selection.
	 * @see
	 * MoveDown, MovePageDown, MovePageUp, MoveFirst, MoveLast
	 */
	virtual void MoveLeftRight(BOOL bBack, BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	/**
	 * @brief
	 * Moves the focused row to the first visible row of a target section:
	 * body, header, or footer.
	 * @param RowType Target section for the focused row; must be one of the values
	 * defined by the XTPGridRowType enumeration.
	 * @details
	 * Moves the focused row to the first visible target row.
	 * @see
	 * SetCurrentFocusInHeadersRows, SetCurrentFocusInFootersRows
	 */
	void MoveFirstVisibleRow(XTPGridRowType RowType);

	/**
	 * @brief
	 * Moves the focused row to the last visible row of a target section:
	 * body, header, or footer.
	 * @param RowType Target section for the focused row; must be one of the values
	 * defined by the XTPGridRowType enumeration.
	 * @details
	 * Moves the focused row to the last visible target row.
	 * @see
	 * SetCurrentFocusInHeadersRows, SetCurrentFocusInFootersRows
	 */
	void MoveLastVisibleRow(XTPGridRowType RowType);

	/**
	 * @brief
	 * Checks for a dead end row by moving down/up.
	 * @param bMoveDown TRUE to move down, FALSE to move up.
	 * @return
	 * The index of the dead end row.
	 * @see
	 * SetCurrentFocusInHeadersRows, SetCurrentFocusInFootersRows
	 */
	int CheckDeadEnd(BOOL bMoveDown);

protected:
	CXTPGridControl* m_pGridControl; /**< Associated Grid control. */

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

	DECLARE_OLETYPELIB_EX(CXTPGridNavigator);

#		define DECLARE_OLE_MOVE(Direction)                                                        \
			void OleMove##Direction(const VARIANT& oleSelectBlock,                                 \
									const VARIANT& oleIgnoreSelection);

	DECLARE_OLE_MOVE(Up)
	DECLARE_OLE_MOVE(Down)
	DECLARE_OLE_MOVE(PageUp)
	DECLARE_OLE_MOVE(PageDown)
	DECLARE_OLE_MOVE(FirstRow)
	DECLARE_OLE_MOVE(LastRow)
	DECLARE_OLE_MOVE(Left)
	DECLARE_OLE_MOVE(Right)

	void OleMoveToColumn(int nColumnIndex, const VARIANT& oleClearIfNonFocusable);
	void OleMoveToRow(int nRowIndex, const VARIANT& oleSelectBlock,
					  const VARIANT& oleIgnoreSelection);

	void OleMoveFirstVisibleRow();
	void OleMoveLastVisibleRow();

/** @endcond */
#	endif
};

/**
 * @brief
 * Utility class, handles Grid control icon navigation.
 * @see
 * CXTPGridControl overview
 */
class _XTP_EXT_CLASS CXTPGridIconNavigator : public CXTPGridNavigator
{
	friend class CXTPGridControl;

public:
	/**
	 * @brief
	 * Default navigator constructor, handles properties initialization.
	 * @param pGridControl Pointer to a CXTPGridControl object.
	 * @see
	 * RefreshMetrics
	 */
	CXTPGridIconNavigator(CXTPGridControl* pGridControl);

	/**
	 * @brief
	 * Default navigator destructor, handles member items deallocation.
	 */
	virtual ~CXTPGridIconNavigator();

public:
	virtual void BeginEdit();

	virtual void MoveDown(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);
	virtual void MoveUp(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	virtual void MoveDownStep(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);
	virtual void MoveUpStep(BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);

	virtual void MovePageDown(BOOL bShiftKey, BOOL bControlKey);
	virtual void MovePageUp(BOOL bShiftKey, BOOL bControlKey);

	virtual void MoveLeftRight(BOOL bBack, BOOL bShiftKey = FALSE, BOOL bControlKey = FALSE);
};
/** @cond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif //#if !defined(__XTPGRIDNAVIGATOR_H__)
	   /** @endcond */