TcxCustomGridTableView.OnEditKeyDown Event
Allows you to respond to keystrokes in an active in-place cell editor.
#Declaration
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
andShift
). 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 theKey
parameter within anOn
event handler to prevent the corresponding predefined action from being executed.Edit Key Down 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 OptionsTrue , 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 OptionsTrue
, 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 On
#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 OptionsTrue
.