TTouchKeyboard component: Customization, custom layout, and custom paint

Overview

Today the most widely applied ways of user interaction with apps are either gestures (which is explained by the use of mobile devices) or a computer mouse. But these methods are convenient when we are viewing content. For inputting data we still use a keyboard just like it was some years ago. It can be a virtual keyboard or a real physical device.

In this article, let’s have a look at the developer’s interaction with a virtual keyboard. When we deal with keyboards on mobile Android and iOS devices, 90% of the work is fulfilled by the operating system and framework, and the rest 10% is massively covered in hundreds of articles. If we are talking about the development of solutions for MS Windows, including Delphi, and the VCL framework in particular, the chances to find articles with any ideas and tips for solving typical problems are not very high. But we want to change this situation and we believe that writing this article is one of the ways to do it.

So, it’s time to proceed to the TTouchKeyboard component and the history of its use for the realization of a real task from a client.

TTouchKeyboard use case 

When is it recommended to use this component?

• The first reasonable case to use it is when we have a touchscreen. In any case, it is faster to type the necessary data, especially if there is a huge volume of info to add, using a physical device but if you need to input just a few characters (for example, a user’s name, phone number, order number, etc.) and there is a touchscreen, in this case, it can be more convenient to use it without the necessity to turn to a physical device.
• The second use case when it is reasonable to use a virtual keyboard is when the required set of keys is limited. The calculator app is a bright example of the reasons why in such cases it is possible to use a virtual keyboard. It allows users to comfortably input numbers and conduct calculations and view the available functionality of the app. Looking at a virtual keyboard, a user can understand whether the program can calculate sine and cosine, convert values, or can perform only addition and subtraction operations.

If you have access to a touchscreen and the set of the required characters is limited, you should definitely use a virtual keyboard. Of course, you can use a system virtual keyboard. But first of all, it will always look alien in your interface, secondly, you can’t restrict the number of characters, and, thirdly, we, as developers, always feel like inventing something new.

Task setting

We need to build a program that will allow drivers to sign up in a queue for loading goods. The process of registration will be conducted via terminals with a touchscreen in a so-called kiosk regime where a user can get access only to one program that is automatically started in full screen. In the program, a user will need to accept the terms of use, enter an order number and a telephone number, get a registration confirmation code via SMS and enter it, take a printed document, and wait for a new SMS that will notify that it’s already user’s turn to load goods.

Realization

As you can understand from the task itself, we must use TTouchKeyboard. Let’s omit all the points of program realization that are not related to our topic and analyze only the interface.

If it is Wizard, we need to allocate the key place to TCardPanel, this component perfectly suits such tasks and can show a particular Wizard step on every card.

The top part of the form will be a header, let’s paint it in corporate colors and add logos. In the bottom part, let’s add buttons for moving from one step to another, and let’s proceed to the realization of our step of entering an order number.

In the top part of our card, we need to write clarifications. Below, we should add an input field for entering a number and a virtual keyboard. We need to adjust the fonts to the sizes of a 19-inch TouchScreen and add a simple icon in order to use free space in the left part of the screen.

By default, TTouchKeyboard shows the current keyboard layout. As a result, a lot of free space is occupied, keys are small and 90% of the keyboard is not functional in our case due to the fact that an order number includes only 8 numbers and letters won’t be used at all.

Let’s have a look at the customization options that are provided in Object Inspector:

• Color changes the color of a keyboard background
• DrawingStyle changes a background color either by applying color fill from the Color property or gradient fill.
• GradientStart is a gradient fill’s start color
• GradiendEnd is a gradient fill’s end color
• KeyCaptions is a collection for redefining captions on special keys (Esc, Del, Enter, Space, Tab, etc…)
• Layout is a keyboard layout setting, it has two values (Standard and NumPad). 

Please pay attention to the fact that the component doesn’t have Events and, consequently, we can’t use them for affecting the behavior and look of the keyboard.

But let’s return to the Layout property. A user needs to input an order number (an 8-digit number), a telephone number (an 8-digit number), and a code from SMS (a 4-digit number) and it means that we can change the layout property to the value NumPad and the situation will be significantly improved.

As we do not need a group of buttons, they can be excluded. The keyboard has become more compact and convenient. In such a way, the code could be even suitable for being implemented in production but a grey and black gradient on buttons as well as additional keys with “/”, “-”, “+”, “*”, “.” still spoil the situation. Let’s proceed to the most interesting part – the analysis of sources.

Analysis of original sources

The sources of the TTouchKeyboard code are contained in the Vcl.Touch.Keyboard.pas file. The hierarchy is not complicated at all: TTouchKeyboard-> TCustomTouchKeyboard-> TCustomControl and then a standard hierarchy for all Control in VCL. As it is common in Delphi, a final class TTouchKeyboard doesn’t have any functionality and only adds the preliminarily declared properties to “published”. The TCustomTouchKeyboard class is mainly responsible for the selection of the necessary keyboard layout, sending and modifying messages about button clicks as well as rendering of background under the keys. That’s why TTouchKeyboard has such a small customization set in Object Inspector. The major part of the functionality is hidden in the section dubbed private and its redefinition can’t help to delete extra keys or change their design.

Let’s begin with the presence and place of keys. Layouts are responsible for this functionality. The TTouchKeyboard component looks for layouts in TKeyboardLayouts. The TKeyboardLayouts class keeps all the layouts in a strict private class variable FKeyboardLayouts. The Layouts property as well as methods for search and manipulation of the class data are hidden in the private section as well. We have access only to the methods of loading new layouts  LoadFromStream, LoadFromResourceName, as well as LayoutNames with the names of the already loaded layouts.

As it has been found out, developers didn’t try to make this set of components universal. During the initialization, the TKeyboardLayouts class checks all the resources of the app of the RCDATA type and if the resource has the keyword KEYBOARD in its title, TKeyboardLayouts will add it as a layout to its internal list. Where can we get such resources? As there is a string {$R KeyboardLayouts.res} in the Vcl.Touch.Keyboard.pas file, the compiler adds everything that is contained in the KeyboardLayouts.res file to our app. That’s how we get our layouts Standard and NumPad. In reality, we get not just two layouts but the following ones: NumPad and Standard101, Standard102, Standard106 which are variations of the Standard layout for different languages. But we do not need to dive into the details.

From all these facts we can make the following conclusion. For adding a new layout we need either to add it to the resources of our app or to generate it in the runtime and load via TKeyboardLayouts.LoadFromStream.  The second method is easier and more logical. That’s why let’s use it. But we also need to have a look at the structure of the layout itself.

To study the mechanism of virtual keyboard layouts, we need to analyze the contents of the file Vcl.Touch.KeyboardTypes.pas. The realization of the TVirtualKeyLayout class is contained there, which represents the layout,  as well as the realization of all support classes.

TVirtualKeyLayout has a row of properties that are responsible for dimensions but it will be more interesting for us to have a look at KeyboardName, KeyboardType for naming our layout and the Keys collection of the TVirtualKeyboard type

TVirtualKeyboard is a generic list with the TVirtualKeys object type which contains a collection of keys of the TVirtualKey types. TVirtualKeys are rows of keys in the layout and TVirtualKeyboard is a list of rows.

Implementation of keyboard layout

After considering original sources, we’ve understood that for implementing all our plans we need to create our own layout at the initialization stage, then specify its use already in our object TTouchKeyboard, and add to the layout property the same string as it will be indicated in our object of the type TVirtualKeyLayout in the KeyboardType property.

To begin with, we should create our layout and indicate its dimensions by default and minimum dimensions:

Then we need to introduce a cycle that will create three key rows:

We also should add a new cycle into the above-mentioned one. This new cycle will create keys in each row:

Then we need to specify the value of each key. In our first test case, we will emulate numbers from the NumPad keyboard. Number keys NumPad have virtual codes from 0x60 to 0x69 in a hexadecimal number system where 0x60 is the key 0 and 0x69 is 9. You can read more about virtual codes for keys in the official Microsoft documentation (https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes). Consequently, the formula for the key code looks the following way:

Let’s add our key to the key row and the row – to the layout:

Done. Now we can save our layout in the stream and then we can upload it to TKeyboardLayouts from this stream:

Then, we should assign a string with the name of our layout to the layout of our keyboard, and the first test is conducted.

The principle of work is clear which means that we can take out test code as a base and turn the keys in opposite direction and add keys Enter and Backspace.

Now on the screen, we can see only those keys that are required. But we need to understand how we can make them look more up-to-date.

To do it, it is required to return to the implementation of the TCustomTouchKeyboard class and to consider the source code of the Paint method. Here we do not need to pay attention to the part of the code that is related to the background rendering, we should concentrate on the rendering of keys:

From this code, you can see that the code of the keyboard component checks every key in its collection and calls their rendering on its canvas. Each key can draw itself. Now let’s proceed to the class of the button TCustomKeyboardButton and we will see that the rendering method is virtual. It means that it can be redefined in the descendant:

After an attentive consideration of the TCustomTouchKeyboard class we will find the public DefaultButtonClass property. It means that we can use our descendant class on the keyboard. Let’s start the implementation, specify our descendant class, and redefine the rendering method:

The rendering of symbols for the keys Enter and Backspace should be conducted in a manual regime MoveTo\LineTo which doesn’t look very pretty in our layout especially when we have a bold font. That’s why we should make it possible to use icons for these keys. As not we but the keyboard itself will be responsible for the creation and lifecycle management of the TFlatButtonClass objects, we can’t add the necessary parameters for each object. Recompilation will eliminate the possibility to use the same code in other projects, moreover, it is not the best idea from an ethical perspective. That’s why we should create “class variables” and specify them once at the initialization stage:

Also we need to declare a class for opening access to the protected-section of the TCustomTouchKeyboard class:

The realization of the Paint method can be fully copied from TCustomKeyboardButton and in parallel we can start to introduce our changes to it for getting the desired design of keys. For example, in our case the code for rendering the keys Enter and Backspace can look the following way:

As for the constants for rendering background, we can modify them as follows:

We had to eliminate some functionality due to the peculiarities of the class hierarchy. For example, we do not have access to the realization of GetOverrideCaption and GetModifier but it is not a problem as we do not need to have such functionality in our program.

Let’s add the initialization code:

As a result, we will have an acceptable minimalistic design:

Full source code of a module with own keys and layout realization: