Skip to main content

DevExpress v24.2 Update — Your Feedback Matters

Our What's New in v24.2 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

TcxCustomGridTableController.FocusNextItem(Integer,Boolean,Boolean,Boolean,Boolean,Boolean) Method

Moves focus to the nearest available data item that follows or precedes the specified data item.

#Declaration

Delphi
function FocusNextItem(AFocusedItemIndex: Integer; AGoForward: Boolean; AGoOnCycle: Boolean; AGoToNextRecordOnCycle: Boolean; AFollowVisualOrder: Boolean; ANeedNormalizeSelection: Boolean = False): Boolean; virtual;

#Parameters

Name Type Description
AFocusedItemIndex Integer

Specifies the visible index of the focusable data item used as the start position of the current focus movement operation.

The function moves focus to the next or previous available data item depending on the AGoForward parameter value.

AGoForward Boolean

Specifies the direction of focus movement:

True
The function moves focus to the nearest available data item whose visible index exceeds AFocusedItemIndex.
False
The function moves focus to the nearest available data item whose visible index is less than AFocusedItemIndex.
AGoOnCycle Boolean
True
The function restarts the current search operation from the first visible data item once the last visible data item is reached. The AGoForward parameter specifies the search operation.
False
The function finishes the current search operation at the last (if AGoForward is True) or first (if AGoForward is False) visible data item.
AGoToNextRecordOnCycle Boolean

Specifies if focus can navigate between records if AGoOnCycle is True:

True
The function moves focus to the nearest available data item in the next (if AGoForward is True) or previous (if AGoForward is False) record.
False
Focus does not leave the current record. The function restarts the current search operation from the first visible data item in the current record once the last visible data item is reached.
AFollowVisualOrder Boolean

Specifies if the function iterates through data items according to their positions in the grid View layout:

True
The function iterates through data items according to their visual order (from left to right, from top to bottom, or vice versa, depending on the AGoForward parameter value).
False
Affects only Banded Table Views. The function iterates through data items band by band (that is, skips all data items that belong to the processed band).
ANeedNormalizeSelection Boolean

Optional. Specifies if the function clears the current selection and selects the record that contains the focused data item:

False
Default. The current selection state does not change.
True
The function selects the record that contains the focused data item.

#Returns

Type Description
Boolean

True if the focus move operation is successful; otherwise, False.

The FocusNextItem function returns False for AFocusedItemIndex if the FindNextItem function returns -1 for the same item.

#Remarks

You can set an individual data item’s Options.Focusing property to False to prevent users from moving focus to the data item. Such items cannot accept focus, and all keyboard navigation operations skip these items.

Call the FocusNextItem function to move focus to the available data item closest to the required position (visible data item index) passed as the AFocusedItemIndex parameter.

#Code Example: Press Enter to Navigate Between Columns

The code example in this section allows users to press Enter or Shift+Enter in the active in-place cell editor to confirm pending changes and navigate to the next or previous cell in the same record, respectively. You can use the AItem parameter to identify the target column and limit this navigation technique to certain columns in your application.

procedure TMyForm.cxGrid1TableView1EditKeyDown(Sender: TcxCustomGridTableView;
  AItem: TcxCustomGridTableItem; AEdit: TcxCustomEdit; var Key: Word; Shift: TShiftState);
begin
  if Key = VK_RETURN then  // Checks if the Enter key is pressed
  begin
    if Shift = [ssShift] then // Checks if only the Shift modifier key is pressed
      (Sender as TcxGridTableView).Controller.FocusNextItem(AItem.Index, False, False, False, True)
    else
      (Sender as TcxGridTableView).Controller.FocusNextItem(AItem.Index, True, False, False, True);
  end;
end;

Tip

Alternatively, you can set the OptionsBehavior.GoToNextCellOnEnter property to True.

See Also