C++ is one of the best programming languages to develop games and simulations. One of the important elements of developing a C++ Game is handling key events. Understanding how key and keyboard events work means you can get your program to react to the user’s key presses in the game to control the action.In this article, we explain how you can use key events of C++ VCL applications on Windows.
Table of Contents
How to use key events in C++ VCL applications on Windows?
C++ Builder is has very modern Key event handlers, 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.)
- System events (OnTimer, etc.)
- Internal events (OnPost, etc.)
Key Events are the User Events are actions that the user initiates when they press the key of a physical keyboard or a touchscreen virtual keyboard. Here are some examples of user events,
- OnClick (the user clicked the mouse; Vcl::Controls::TControl::OnClick)
- OnDblClick (the user double-clicked a mouse button; Vcl::Controls::TControl::OnDblClick)
- OnKeyDown (the user pressed to a key, Vcl::Controls::TWinControl::OnKeyDown)
- OnKeyPress (the user pressed a key on the keyboard; Vcl::Controls::TWinControl::OnKeyPress)
- OnKeyUp (the user released a pressed key, Vcl::Controls::TWinControl::OnKeyUp
C++ Builder is very very easy to detect key event professionally. In addition to these above, there are 3 more key events that can be useful in game development, these are OnKeyDown, OnKeyUp and OnKeyPress events. In this article we will explain 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 code inside this method. Before we show you an example, let’s see these events in detail.
How to use key events in C++ VCL applications on Windows using the OnKeyDown event?
OnKeyDown is an event handler of type Vcl.Controls.TKeyEvent. OnKeyDown property occurs when a user presses any key while the control has focus. OnKeyDown() method inherits from Vcl.Controls.TWinControl.OnKeyDown. All content below this line refers to Vcl.Controls.TWinControl.OnKeyDown.
You can use the OnKeyDown event handler to specify special processing to occur when a key is pressed. The OnKeyDown handler can respond to keyboard keys, including function keys and keys combined with the SHIFT, ALT, and CTRL keys, and pressed mouse buttons.
An application gets Windows WM_KEYDOWN messages for all keys when the user presses a key. These messages indirectly fire the OnKeyDown event. Setting the Key parameter to #0 prevents any further processing of this message. But for keys that generate characters Windows also produces WM_CHAR. At the time your OnKeyDown event fires, the WM_CHAR message for the key will already be in the message queue. Setting Key to #0 does not stop it from being delivered, so it fires the OnKeyPress event. If you set the Key to #0, OnKeyPress will be prevented from being fired only for keys that do not have chars. For keys that represent characters, OnKeyPress will continue to be fired.
This method of organizing key processing has advantages. Code that only deals with characters, including control characters like #13 for carriage return, #3 for CTRL-C, and so on, should go into the OnKeyPress event. Code that deals with keys that do not generate characters should be put into the OnKeyDown event. See TKeyEvent for a description of the parameters.
How to use key events in C++ VCL applications on Windows using the OnKeyUp event?
OnKeyup is an event handler of type Vcl.Controls.TKeyEvent. The OnKeyUp property occurs when the user releases a key that was pressed. You can use the OnKeyUp event handler to provide special processing that occurs when a key is released. The OnKeyUp handler can respond to all keyboard keys, keys that represent characters, function keys, and keys combined with the SHIFT, ALT, and CTRL keys.
If Key is set to #0, any further processing of the OnKeyUp event will be prevented. See TKeyEvent for a description of the parameters.
How to use key events in C++ VCL applications on Windows using the OnKeyPress event?
OnKeyPress is an event handler of type Vcl.Controls.TKeyPressEvent. OnKeyPress property occurs when a key is pressed. You can use the OnKeyPress event handler to make something happen as a result of a single character key press.
The Key parameter in the OnKeyPress event handler is of type Char; therefore, the OnKeyPress event registers the ASCII character of the key pressed. Keys that do not correspond to an ASCII Char value (SHIFT or F1, for example) do not generate an OnKeyPress event. Key combinations (such as SHIFT+A) generate only one OnKeyPress event (for this example, SHIFT+A results in a Key value of “A” if Caps Lock is off). To respond to non-ASCII keys or key combinations, use the OnKeyDown or OnKeyUp event handler.
An application gets Windows WM_KEYDOWN messages for all keys when the user presses a key. These messages indirectly fire the OnKeyDown event. Setting the Key parameter to #0 prevents any further processing of this message. But for keys that generate characters Windows also produces WM_CHAR. At the time your OnKeyDown event fires, the WM_CHAR message for the key will already be in the message queue. Setting Key to #0 does not stop it from being delivered, so it fires the OnKeyPress event. If you set the Key to #0, OnKeyPress will be prevented from being fired only for keys that do not have chars. For keys that represent characters, OnKeyPress will continue to be fired.
This method of organizing key processing has advantages. Code that only deals with characters, including control characters like #13 for carriage return, #3 for CTRL-C, and so on, should go into the OnKeyPress event. Code that deals with keys that do not generate characters should be put into the OnKeyDown event.
How to use arrow key events in C++ VCL applications on Windows?
In C++ Builder, we can use OnKeyDown, OnKeyUp and OnKeyPress 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 showing how to use arrow keys in C++ Builder VCL 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 VCL application, drag a shape (TShape) component from Palette Window on to the form, goto 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 shape up, down, left and right, just add switch() as in code as below,
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
#include <vcl.h> #pragma hdrstop #include "Key_Events_VCL_App_Unit1.h" //--------------------------------------------------------------------------- #pragma package(smart_init) #pragma resource "*.dfm" TForm1 *Form1; //--------------------------------------------------------------------------- __fastcall TForm1::TForm1(TComponent* Owner) : TForm(Owner) { } //--------------------------------------------------------------------------- void __fastcall TForm1::FormKeyDown(TObject *Sender, WORD &Key, TShiftState Shift) { switch(Key) { case VK_LEFT: Shape1->Left--; // move top left point to the left break; case VK_RIGHT: Shape1->Left++; // move top left point to the right break; case VK_UP: Shape1->Top--; // move top upper point to the up break; case VK_DOWN: // move top upper point to the down Shape1->Top++; break; } } |
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.
There is a free C++ Builder Community Edition for students, beginners, and startups; it can be downloaded from here. For professional developers, there are Professional, Architect, or Enterprise versions of C++ Builder and there is a trial version you can download from here
