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

TcxGridEditKeyEvent Type

The procedural type for keyboard interaction events in data grid in-place editors.

#Declaration

Delphi
TcxGridEditKeyEvent = procedure(Sender: TcxCustomGridTableView; AItem: TcxCustomGridTableItem; AEdit: TcxCustomEdit; var Key: Word; Shift: TShiftState) of object;

#Parameters

Name Type Description
Sender TcxCustomGridTableView

Provides access to the grid Table View that raised the keyboard interaction event.

Cast this parameter value to the corresponding terminal TcxCustomGridTableView class descendant to access all public API members.

Tip

You can call the Sender.ClassType function or use any other RTTI functionality to identify the actual grid View type.

AItem TcxCustomGridTableItem

Provides access to the parent grid column of the target in-place cell editor (AEdit).

Cast this parameter value to the corresponding terminal TcxCustomGridTableItem class descendant to access all public API members.

Tip

The actual grid column type corresponds to the Sender grid View type. Alternatively, you can call the AItem.ClassType function or use any other RTTI functionality.

AEdit TcxCustomEdit

Provides access to the in-place cell editor that raised the keyboard interaction event.

Cast this parameter value to the corresponding terminal TcxCustomEdit class descendant to access all public API members.

Key Word

Specifies the pressed key. If the key corresponds to a predefined action in the grid Table View or the active in-place editor (such as a drop-down window display operation or navigation between cells), the TcxGrid control executes the action.

You can assign a different virtual key code to this parameter to modify the current keystroke. Alternatively, you can assign 0 to this parameter to prevent the corresponding predefined action from being executed. Refer to the following section for details: Predefined Keyboard Commands.

Shift TShiftState

Returns the current state of mouse buttons and modifier keys – Alt, Ctrl, and Shift.

#Remarks

An editor keyboard interaction event occurs every time a user presses a key while an in-place editor is active. You can handle this event to implement custom actions in response to certain keystrokes before the TcxGrid passes them to the active in-place cell editor. For example, you can disable or modify any predefined keyboard commands depending on certain conditions in your application.

#Predefined Keyboard Commands

All keystrokes listed in the table below execute corresponding predefined actions in the grid Table View or the active in-place editor. The state of modifier keys (Shift) may affect the focus movement direction.

Key Virtual Key Code (Key Parameter) Predefined Command
Enter VK_RETURN Applies the pending change in an in-place cell editor and posts the editor value to the underlying dataset field. If the OptionsBehavior.GoToNextCellOnEnter property is set to True, the keystroke moves focus to the next (if Enter is pressed) or previous (if Shift+Enter is pressed) available grid data item.
Esc VK_ESCAPE Discards the pending change in an in-place cell editor and closes it.
Insert VK_INSERT Inserts a new record.
Delete VK_DELETE Deletes the current record.
Tab VK_TAB Applies the pending change in an in-place cell editor, posts the editor value to the underlying dataset field, and moves focus to the next available cell.
Left Arrow VK_LEFT Moves the caret one character to the left in the text box-based editor.
Right Arrow VK_RIGHT Moves the caret one character to the right in the text box-based editor.
Up Arrow VK_UP Applies the pending change in any in-place cell editor except spin editors, posts the editor value to the underlying dataset field, and moves focus to the previous record in the same column. In a spin editor, this key executes the standard increment operation.
Down Arrow VK_DOWN Applies the pending change in any in-place cell editor except spin editors, posts the editor value to the underlying dataset field, and moves focus to the next record in the same column. In a spin editor, this key executes the standard decrement operation.
Page Up VK_PRIOR Applies the pending change in any in-place cell editor except spin editors, posts the editor value to the underlying dataset field, and moves focus to the first fully visible record. If the top visible record has focus, the keystroke moves focus up by the number of currently visible records. In a spin editor, this key executes the fast increment operation.
Page Down VK_NEXT Applies the pending change in any in-place cell editor except spin editors, posts the editor value to the underlying dataset field, and moves focus to the last fully visible record. If the bottom visible record has focus, the keystroke moves focus down by the number of currently visible records. In a spin editor, this key executes the fast decrement operation.

Note

This table describes keystroke behavior for text box-based editors with default settings. Different Data Grid settings and in-place editor types may significantly change keyboard command behavior. For example, if a grid View’s OptionsBehavior.AlwaysShowEditor property is set to True, Enter and Esc keys do not close the active in-place editor.

#Code Examples

#Press F10 to Display a Drop-Down Editor Window

The following code example displays an in-place drop-down editor menu when a user presses the F10 key:

procedure TMyForm.cxGrid1TableView1EditKeyDown(Sender: TcxCustomGridTableView;
  AItem: TcxCustomGridTableItem; AEdit: TcxCustomEdit; var Key: Word; Shift: TShiftState);
begin
  if Key = VK_F10 then  // Checks if the F10 key is pressed
    if AEdit is TcxCustomDropDownEdit then
    begin
      (AEdit as TcxCustomDropDownEdit).DroppedDown := True;
      Key := 0;
    end;
end;

#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.

#Direct TcxGridEditKeyEvent Type Reference

The TcxCustomGridTableView.OnEditKeyDown event references the TcxGridEditKeyEvent procedural type.

See Also