From RAD Studio API Documentation
Jump to: navigation, search


procedure KeyDown(var Key: Word; var KeyChar: System.WideChar; Shift: TShiftState); virtual;


virtual void __fastcall KeyDown(System::Word &Key, System::WideChar &KeyChar, System::Classes::TShiftState Shift);


Type Visibility Source Unit Parent
FMX.Forms TCommonCustomForm


Executed when a key is pressed while this form has the input focus.

In FireMonkey framework KeyDown is the main method to process pressing of keys in forms. KeyDown is executed each time a key is pressed, when this form has the input focus. KeyDown is used internally: to activate menus and actions and to treat TAB requests to cycle through the children controls of this form. Editors can use KeyDown to add symbols into a text being edited.

You can override KeyDown to provide additional key treating in subclasses.

KeyDown has the following parameters:

Parameters Descriptions


Is the scan code of the pressed keyboard key or $0.

The UITypes unit defines Virtual Keys providing symbolic constants for scan codes of keyboard keys.

Physical scan codes of the same key can differ under different platforms (Windows or iOS). Under FireMonkey framework, platform-specific units (for example FMX.Platform.Mac.pas) should translate native (iOS for FMX.Platform.Mac.pas unit) scan codes to the corresponding Windows codes defined in the UITypes unit. As the result Key always has scan code values defined by vkXXXX constants in UITypes. For example,

vkReturn = $0D; { 13 } corresponds to the RETURN keyboard key
vkEscape = $1B; { 27 } corresponds to the ESCAPE
vkSpace = $20; { 32 } corresponds to the SPACE
vkF2 = $71; { 113 } corresponds to the F2 keyboard key

Keys of digits and letters -- independently of the selected input language and case of alphabetic keys -- have values corresponding to the '0'..'9' and 'A'..'Z' symbols. For example, Key = vkP = $50 corresponds to the 'P' keyboard key.

If Key = $0, then KeyChar contains a pressed symbol according to the current keyboard's input language, keyboard mode (CAPS LOCK and NUM LOCK keys), keyboard Shift state, and Input Method Editor (IME) state.

Combinations of the Key and Shift parameters can be translated to shortcut key combinations.


Is the pressed character (digit) or #0.

If a pressed key combination can be handled as a printable character or digit, then Key = 0 and KeyChar contains a pressed symbol according to the current keyboard's input language, keyboard mode (CAPS LOCK and NUM LOCK keys), keyboard Shift state, and IME state. Editors can use this symbol to add into a text being edited.


Determines the state of the CTRL, ALT, SHIFT, and CMD (only for Mac) keys at the moment you press the key.

KeyDown processes pressed keys according to the following algorithm:

  1. KeyDown first calls the IsDialogKey with the same parameters as those specified for KeyDown. The IsDialog parameter returns True if KeyChar < ' ' or Shift is any of the CTRL, ALT or CMD keys. That is, if the KeyChar and Shift combination identifies some control combination -- not a printable character. Otherwise, it returns False. The ' ' character has the $20 ASCII value. ASCII values less than $20 identify control combinations.
  2. If IsDialogKey returns True in the IsDialog parameter, then the pressed key combination is passed, in the following order, to all child controls, menus and action lists in the form until this key combination is processed:
    1. To the control having focus.
    2. To the context menu of the control having focus.
    3. To all other menus and context menus in the form.
    4. To all other controls (not having focus) in the form.
    5. To action lists in the form and in all child components having assigned action list elements.
    6. To menus and action lists in all other forms.
    7. If the pressed key combination was processed during one of the previous steps, then KeyDown sets Key = 0 and KeyChar = #0 and terminates.
  3. If Key = vkTab, then KeyDown moves the focus to the next control in the controls "tab order" and terminates.
  4. If Key <> 0 or KeyChar <> #0, then KeyDown calls the KeyDown method of the control having focus and then calls the OnKeyDown event handler of the form if one is assigned.
  5. In the finally block, KeyDown stores the current date and time in the LastKeyPress and LastUserActive properties of the current application.

See Also