Learn How To Use Key Events In C++ FMX Applications on Windows

C++ is one of the best programming language to develop games and simulations. One of the key things to master when learning to write a game in C++ is how to handle key events. This is the ability to perform actions inside the game in accordance with key events such as a key being held down or a key press (key down, key up) being completed. In this article, we explain how you can use key events of C++ FMX applications on Windows.

How to use key events in C++ FMX applications on Windows

C++ Builder has very modern Key event handlers that you can easily use to read key inputs in your VCL and FMX applications. In C++ Builder, events that can occur can be divided into the following main types:

• User events (OnClick, OnKeyPress, OnKeyDown, OnKeyUp, OnDblClick, … etc.)
  FMX.Controls.TControl.OnClick
• System events (OnTimer, etc.)
• Internal events (OnPost, etc.)

Key Events are the User Events that the user initiates by physically pressing a keyboard – either an actual piece of hardware or a touch-screen emulation of one. Here are some examples of user events,

• OnClick (the user clicked the mouse;  FMX.Controls.TControl.OnClick)
• OnDblClick (the user double-clicked a mouse button;  FMX.Controls.TControl.OnDblClick)
• OnKeyDown (the user pressed to a key, FMX.Controls.TControl.OnKeyDown) with KeyDown Method
• OnKeyUp (the user released a pressed key, FMX.Controls.TControl.OnKeyUp) with KeyUp Method
• OnTap (the user taps the control, a screen etc. FMX.Controls.TControl.OnTap)

In C++ Builder it is very easy to detect key events. In addition to the events listed above, there are 2 more key events that can be useful in game development; these are OnKeyDown, OnKeyUp events. In this article we will explain how to use these events. You can use these events from Object Inspector as shown below,

Just double click to create a method for that event, then add your codes inside this method. Before we show you an example, let’s see these events in detail.

How to use key events in C++ FMX applications using the OnKeyDown event?

OnKeyDown is an event handler of type FMX.Types.TKeyEvent. OnKeyDown property occurs when a key is pressed while the control has focus.

OnKeyDown is called from KeyDown methods of GUI components, for example, of controls and forms. Write an event handler for OnKeyDown to specify what happens when a control or a form has the input focus and a key is pressed.

Here is the Syntax of OnKeyDown;

How to use key events in C++ FMX applications using the KeyDown method?

FMX.Controls.TControl.KeyDown provides a response when a key is pressed down while the control has the keyboard focus. If the pressed key is the Applications key (Key = vkApps), then KeyDown shows the context menu of the control. Otherwise, KeyDown calls the OnKeyDown event handler if one is assigned.

TCommonCustomForm and descendant of TControl classes–like TCustomGrid–call KeyDown from their methods handling key pressing. They decode the message parameters into the key code, character code, and shift state. They pass them into the called KeyDown method in the Key, KeyChar, and Shift parameters, respectively:

Parameters	Descriptions
Key	Is the scan code of the pressed keyboard key or $0.If a pressed key combination can be a shortcut, then Key <> 0 is a virtual key and KeyChar = #0.Physical scan codes of the same key can differ under different platforms (Windows or iOS). Platform-specific units (for example FMX.Platform.Mac.pas) should translate native scan codes to corresponding Windows codes defined in the UITypes unit. For example,vkReturn = $0D; { 13 } corresponds to the RETURN keyboard key.vkF2 = $71; { 113 } corresponds to the F2 keyboard key.
KeyChar	Is the pressed character (digit) or #0.If a pressed key combination can be treated 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.
Shift	Indicates which shift keys–SHIFT, CTRL, ALT, and CMD (only for Mac)–were down when the specified key was pressed with the control in focus.

If the control has successfully processed the pressed key combination and no additional processing is required, then KeyDown assigns Key = 0 and KeyChar = #0.

Override the protected KeyDown method to provide other responses when a key is down while the control has keyboard input focus.

See TCommonCustomForm.KeyDown for more information about parameters.

Here is the Syntax of FMX.Controls.TControl.OnKeyDown;

OnKeyDown is called from KeyDown methods of GUI components, for example, of controls and forms. Write an event handler for OnKeyDown to specify what happens when a control or a form has the input focus and a key is pressed.

Here is the Syntax of KeyDown;

How to use key events in C++ FMX applications using the OnKeyUp event?

OnKeyUp is an event handler of type FMX.Types.TKeyEvent.Occurs when a key is released while the control has focus. OnKeyUp also occurs when KeyUp is called. Write an event handler for OnKeyUp to specify what happens when the control is in focus and a key is released.

FMX.Controls.TControl.KeyUp provides a response when a key is released while the control has keyboard focus. KeyUp calls the OnKeyUp event handler if one is assigned.

Here is the syntax for the OnKeyUp;

How to use key events in C++ FMX applications using the KeyUp method?

KeyUp method is an OnKeyUp event dispatcher. KeyUp provides a response when a key is released while the control has keyboard focus. KeyUp calls the OnKeyUp event handler if one is assigned.

A control calls KeyUp in response to any key-up messages, decoding the message parameters into the key code, character code, and shift state. The control passes them in the Key, KeyChar, and Shift parameters, respectively:

• Key is the scan code of the released keyboard key.
• KeyChar is the character code of the released key.
• Shift indicates which shift keys–SHIFT, CTRL, ALT, and CMD (only for Mac)–were down when you release the previously pressed key with the control in focus.

Override the protected KeyUp method to provide other responses when a key is released while the control has keyboard input focus.

Here is the syntax for the KeyUp;

How to use arrow key events in C++ FMX applications on Windows?

In C++ Builder, we can use OnKeyDown and OnKeyUp events to detect which keys are presses (down), released (up) or we can detect single character inputs from key presses.

To represent a single key, you may use either a code or a string. There are tables that show a complete list of codes and strings that you may use to represent each key. These tables do not show a string representation for some keys because the UI framework is not responsible for the string representation of those keys. Instead, the operating system where your application is running provides the string representation of those keys. These tables do not show those string representations provided by the operating system because they may vary; for example, Windows provides locale-specific key names.

Here, Microsoft listed windows keys and their decimal values here: https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes

For example, to detect arrow keys, we can use Virtual Key Codes as listed below,

Constant	Value	Description
VK_LEFT	0x25	LEFT ARROW key
VK_UP	0x26	UP ARROW key
VK_RIGHT	0x27	RIGHT ARROW key
VK_DOWN	0x28	DOWN ARROW key

For more windows keys and their decimal values, please check MS page here: https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes

Also, windows keys and shortcuts are officially listed in Embarcadero’s DocWiki here : https://docwiki.embarcadero.com/RADStudio/Alexandria/en/Representing_Keys_and_Shortcuts

Is there an example of how to use arrow key events in C++ VCL applications on Windows?

Here is a full example of how to use arrow keys in a C++ Builder FMX application. In this example we have a shape on the form, and we will move this shape by arrow keys.

To do this;

Just create a new C++ Builder Multi-Device application, drag a Ellipse (TEllipse) component from Palette Window on to the form, go to events of form in Object Inspector Window, and double click to OnKeyDown event. This will create FormKeyDown() method that will be used in this event. To move your ellipse shape up, down, left and right, just add switch() as in code as below,

As in this example, you can use any keys or you can use key combinations too. Just check the list key codes and add them in your actions. As you see RAD Studio, C++ Builder is very easy to develop VCL or FMX C++ games that uses key presses. Note that you can use these keys to move shapes, to modify bitmaps, to move 3D shapes in 3d environment, or you can use them to play sounds like piano applications. C++ is really amazing and allows you do everything you want to.

C++ Builder is the easiest and fastest C and C++ IDE for building simple or professional applications on the Windows, MacOS, iOS & Android operating systems. It is also easy for beginners to learn with its wide range of samples, tutorials, help files, and LSP support for code. RAD Studio’s C++ Builder version comes with the award-winning VCL framework for high-performance native Windows apps and the powerful FireMonkey (FMX) framework for cross-platform UIs.