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

TcxCustomGridTableView.OnEditKeyDown Event

Allows you to respond to keystrokes in an active in-place cell editor.

#Declaration

Delphi
property OnEditKeyDown: TcxGridEditKeyEvent read; write;

#Remarks

You can handle the OnEditKeyDown 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 any predefined keyboard commands depending on certain conditions in your application.

#Event Occurrence

The OnEditKeyDown event occurs every time a user presses a key while an in-place cell editor is active, before OnEditKeyPress and OnEditKeyUp events.

#Event Parameters

The following parameters are available within an OnEditKeyDown event handler:

Sender
Provides access to the grid Table View that raised the keyboard interaction event.
AItem
Provides access to the column whose active in-place editor is about to accept the keystroke (Key and Shift).
AEdit
Provides access to the active in-place cell editor.
Key

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.

Tip

You can assign 0 to the Key parameter within an OnEditKeyDown event handler to prevent the corresponding predefined action from being executed.

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

Refer to the TcxGridEditKeyEvent procedural description for detailed information on all parameters accessible within an OnEditKeyDown event.

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

#Limitations

The TcxGrid control always interprets all alphanumeric keystrokes as the active cell editor input. You cannot assign 0 to the Key parameter in an OnEditKeyDown event to prevent alphanumeric input.

Tip

To prevent or modify alphanumeric keystrokes, handle the OnEditKeyPress event instead.

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

See Also