With this template you can add a new Numeric Keyboard component to your project. Numeric Keyboard component provides a grid with keys the user can touch. Activating a key feeds the corresponding event to the application as if the user had pressed the key on a real keyboard.

Components created with this template are intended to be adapted to your particular design expectations. After adding the new Numeric Keyboard you should edit the component, change its appearance and if desired also its behavior. Once you have adapted the component, you can embed instances of this Numeric Keyboard wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Numeric Keyboards created by the template are working widgets. If desired, they can already be used as they are. The following figure demonstrates the default appearance of the Numeric Keyboard created by using the here described component template:

The approach with component templates has two functions. Primarily the templates should simplify the development of new components. Instead of creating the Numeric Keyboard from scratch you can use the available template. The second function is more educative. The template implements fully working Numeric Keyboard component you can investigate and learn about the corresponding programming aspects. The template is well documented. It contains annotations and inline comments with instructions helping you to understand how the component works and how it can be adapted to your particular needs.

This chapter provides an overview how the Numeric Keyboard component template is used within your own application and how you adapt this component according to your particular needs. You will find here also further details concerning the internal implementation of the Numeric Keyboard component.

To create a new Numeric Keyboard component from a template you simply Drag & Drop it between the Templates window and the Composer with an opened unit. This is important in that by using the component templates you add in fact a new class to your project. Classes, in turn, can exist within units only. The following are the typical steps to create a new Numeric Keyboard component from a template:

The new created Numeric Keyboard component appears accompanied by annotation providing helpful tips how to proceed. If undesired, you can select and delete the annotation.

Once you have created the Numeric Keyboard component, you can use it to assemble more complex components. Technically seen, you embed an instance of the Numeric Keyboard class in-place within some superior GUI component. At the runtime, the superior GUI component takes care of the correct initialization and the displaying of all embedded components, so they appear similarly as you have composed them at the design time. Usually, the superior component where you embed the keyboard instance will be the Application component.

The following are the typical steps to create a new instance of an already existing Numeric Keyboard component:

As long as the Numeric Keyboard is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below. This is in so far worth mentioning as diverse features of the Numeric Keyboard are controlled by the corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

The Numeric Keyboard component descends from the Mosaic class Core::Group. Consequently, all of the properties listed in the above screenshot are inherited from this base class. The Numeric Keyboard itself does not add any new property.

Once added to the Application component, you can freely move the Numeric Keyboard instance, or you simply grab one of its corners and resize it in this way. You can control the position and the size of the component also by directly modifying its property Bounds.

Once you have embedded the Numeric Keyboard instance in your Application component, it is visible whenever the Application component is visible. However, in many applications the virtual keyboard should only appear when the user needs to enter data - for example, when a text editor is focused. The rest of the time, the keyboard should remain hidden to save screen space.

You can control the visibility of the keyboard by modifying its Visible and Enabled properties. To make the keyboard hidden by default, configure both properties to false when the keyboard instance is selected in the Composer:

When the user needs to enter data (for example, when a text editor gains focus), you show the keyboard by setting its properties Visible and Enabled to true and assigning the keyboard instance to the VirtualKeyboard property of the Application component:

Assigning the keyboard instance to the VirtualKeyboard property is essential for the keyboard to work correctly. This ensures that:

When the user finishes entering data (for example, by pressing Enter or when the text editor loses focus), you can hide the keyboard again:

If you want the keyboard to slide in from the bottom of the screen (or perform any other animation) when shown, the most sophisticated approach is to use a fader. Faders provide professional fade-in and fade-out transitions with automatic component management. Following example demonstrates how to present the keyboard using the Effects::PositionFader:

This approach provides smooth animations and handles the keyboard presentation professionally. The FadeGroup() method is available in the Core::Group class (Base class of the Application component) and manages the fade transitions automatically.

Alternatively, if you prefer to use animation effects directly, you can modify the keyboard's position together with visibility. For this purpose you can use the Move and resize rect effect:

Then, to show the keyboard, just start the effect. Following code demonstrates the initialization of the effect to slide the keyboard from the bottom edge of the Application component:

Component templates are intended to create widgets which can be adapted and enhanced to your particular design expectations. For this purpose, once you have added a new Numeric Keyboard component to your project, you can open the component class for editing. Thereupon the implementation of the component appears in a new Composer page:

Originally, if not yet modified, the Numeric Keyboard appears displaying a grid of digit keys (0-9) as text views and special keys (Clear, Enter) as image views. A white background is surrounded by a border. When a key is pressed, it is highlighted with a red rectangle. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. The keyboard can react to touch inputs and provides visual feedback with a flash effect for quick taps.

This default functionality is implemented by following members belonging to the Numeric Keyboard. These members are explicitly intended to be modified. Understanding this internal structure is thus the first step before you start to adapt the keyboard to your particular needs:

Icon	Member	Description
	TouchHandler	This simple touch handler enables the user to interact with the keyboard by touching and dragging. It covers the entire keyboard area and reports touch events to the corresponding slot methods.
	onPressTouch	This internal slot method is called when the user touches the keyboard. It updates the recentPosition variable and requests a keyboard appearance update.
	onDragTouch	This internal slot method is called when the user drags the finger across the keyboard. It updates the recent touch position and triggers visual feedback for the key at the new position.
	onReleaseTouch	This internal slot method is called when the user releases the finger from the keyboard. Depending on the touch duration, it either immediately activates the key or starts the flash timer for quick taps.
	FlashTimer	This timer object provides a short visual feedback flash effect when the user taps a key very quickly. The default duration is 50 milliseconds.
	onFlashTimer	This internal slot method is called when the FlashTimer expires. It ends the flash feedback effect and activates the pressed key.
	activateKey	This internal slot method is called when a key should be activated. It determines which key was pressed and generates the corresponding keyboard event for the application.
	Background	This Filled Rectangle view displays the background of the keyboard. The background is white per default.
	Border	This Border view displays the border of the keyboard with 3 pixel thickness in black color per default.
	Highlight	This Filled Rectangle view provides visual feedback by highlighting the pressed key. It is moved to the position of the pressed key and displayed in red per default.
	TextKey0 .. TextKey9	These Text views represent the digit keys 0 through 9. Each displays one digit using the Resources::FontLarge font.
	ImageKeyClear	This Image view represents the Clear (Backspace) key using an icon from Resources::KeyIconsMedium bitmap resource.
	ImageKeyEnter	This Image view represents the Enter key using an icon from Resources::KeyIconsMedium bitmap resource.
	UpdateViewState	This method is invoked automatically after touch events. The method updates the keyboard views to reflect which key is currently pressed and provides visual feedback.
	keyView	This variable stores a reference to the view representing the currently pressed key. It is null if no key is pressed.
	recentPosition	This variable stores the most recent touch position within the keyboard area.

During its lifetime, the Numeric Keyboard will react to user touch interactions. To track which key is currently pressed, the keyboard manages the above mentioned variable keyView. This variable either refers to the view representing the pressed key or is null if no key is pressed. The variable is evaluated and updated within the implementation of the method UpdateViewState. This method determines which key the user is currently touching by searching for a view at the recent touch position:

The local variable isKeyView will refer to the view at the current touch position. The keyboard then updates the appearance by comparing isKeyView (the currently pressed key) with keyView (the previously pressed key). If they differ, the keyboard updates the visual feedback accordingly - highlighting the new key and removing highlight from the previous key.

Depending on your design expectations, the default state management may require adaptations. Generally, you are free to modify the method UpdateViewState, add further state variables to your keyboard, or change how visual feedback is provided when keys are pressed.

Originally, if not yet modified, the Numeric Keyboard appears displaying digit keys as black text on white background, special keys as black icons, and a red rectangle that highlights the pressed key. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. It's up to you to adapt the keyboard to have the expected appearance. The available possibilities are explained in the following sections. Please note, that you can combine the different approaches according to your application case:

The Numeric Keyboard template contains per default the views Background, Border, Highlight and the key views (TextKey0 .. TextKey9, ImageKeyClear, ImageKeyEnter). If desired, you can modify these views. For example, you can change the colors, fonts, or highlight style. For this purpose you change the implementation of the above explained method UpdateViewState responsible for providing visual feedback when keys are pressed.

When you open the method UpdateViewState you will see that it updates the key views depending on whether they are pressed or released. Text key views change their color from black to white when pressed, and image key views do the same. Additionally, the Highlight view is positioned behind the pressed key. By simply modifying this implementation you change the appearance. For example, you can change the highlight color from red to blue:

Or you can change the pressed text color to yellow instead of white:

If not needed, you can delete some of the per default existing key views. For example, if you don't need the Clear and Enter keys, you can remove the ImageKeyClear and ImageKeyEnter views. Doing this, please don't forget to also remove all references to the deleted views from the implementation of the UpdateViewState and activateKey methods. Otherwise you will get error messages next time the Composer contents is reloaded. To avoid this error message we recommend to perform the steps in following order:

Similarly, if you want to remove all text keys and keep only image-based keys, you should adapt the UpdateViewState and activateKey methods accordingly before deleting the text key views.

You can add more keys to your keyboard. For example, you can add decimal point, plus/minus sign, or other special characters. Following steps explain the workflow:

Also possible, you can replace the existing key views by other views. For example, you could replace all text-based digit keys with image-based keys for a more graphical appearance. For this purpose:

You can add further views to your keyboard for decoration purposes. For example, you can add separator lines between keys, a background image, or a caption text. Following steps explain the workflow:

Decoration views don't participate in key press detection, so you don't need to modify the UpdateViewState or activateKey methods for them.

The initial size of the Numeric Keyboard is determined by the thick blue border surrounding the Canvas area. You can configure the Canvas area size by clicking and dragging the edges of the surrounding border (see also Resize the Canvas area). For example, to make the keyboard wider, drag on its right edge:

The views existing per default in the Numeric Keyboard template are automatically adjusted to fill the area of the component when it is resized. All other views you have eventually added later to the component are not adjusted automatically.

To control the adjustment you have to explicitly configure for each view its Layout property (see also Configure component layout). Let's assume, in order to display a caption text you have added a Text view to the Numeric Keyboard. Then you have arranged the view within the Canvas area according to your design expectation. If you want that the view remains aligned at the top edge filling the width of the component when it is resized, you configure its Layout property as shown below:

When creating your own Numeric Keyboard component you should ensure that instances of the keyboard can be configured to control all the features implemented in it. For example, if you have enhanced the keyboard by a caption text (e.g. "Enter PIN code"), you should add a property to specify this caption text. In this way keyboard instances can be configured to display different captions.

To control the features in your keyboard you use properties. A property can be understood as variable where the corresponding setting is stored, e.g. the caption text, color value, etc.. When the value of the property changes, the keyboard can react to it and update its appearance accordingly. The properties reflect thus the settings within your keyboard. Together they form the interface of the component.

Usually, each particular setting within a component is represented by the corresponding property. In its original version, the Numeric Keyboard doesn't contain any properties - all settings are fixed in the component's design. In order to enhance this interface by your own properties, following steps are necessary:

That is all. Now when you deal with instances of the Numeric Keyboard component, you can evaluate and modify the properties similarly to how you access variables. Especially, when the keyboard instance is selected, you see in Inspector window the property and can change it there. The modification is immediately visible in the Composer window.

If desired, the properties can also be modified at the runtime of your application. For example, the caption text can be changed dynamically. For this purpose you access and modify the affected property directly within Chora code:

The Numeric Keyboard is an interactive component that responds to touch and mouse inputs. For this purpose the template contains the Simple Touch Handler object named TouchHandler. The touch handler covers the entire keyboard area where keys are located. To this handler are associated three slot methods: onPressTouch, onReleaseTouch and onDragTouch. As their names imply the methods are invoked at the beginning of the interaction (press), at its end (release) and repeatedly while then user drags the finger (mouse pointer) inside the handler's area:

When the user initially touches the keyboard, onPressTouch is called. This method:

When the user drags the finger across the keyboard, onDragTouch is called. This method:

This allows the keyboard to highlight different keys as the user drags between them, providing immediate visual feedback.

When the user releases the finger, onReleaseTouch is called. This method:

If the user held the key long enough (more than 50ms specified by default in FlashTimer), the key is activated immediately. For very quick taps, the FlashTimer is started to provide a brief visual feedback before activation.

Usually you will not need to edit the implementation of these methods. They correspond already to whatever typical virtual keyboards do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your keyboard.

The Numeric Keyboard provides visual feedback when keys are pressed. For longer key presses, the feedback is immediate - the key appearance changes while the user holds it. However, for very quick taps (shorter than 50ms), the key press and release happen so fast that the user might not see any feedback. To solve this, the keyboard uses a flash effect timer. The flash effect is implemented using the Core::Timer object named FlashTimer. The timer prolongates thereupon the visual effect. As soon as the timer expires, it signals its associated slot method: onFlashTimer:

This method takes care of two tasks. At first it requests an invocation of the UpdateViewState method to update the visual appearance of the virtual keyboard. The key at the recently touched position should not appear pressed anymore. The second task is to send a signal to the slot method activateKey. Following code demonstrates this implementation:

The FlashTimer object is configured per default with the value 50 milliseconds. If necessary you can change this behavior and specify other delay. The timer provides for this purpose the property Begin. For example, if you want the feedback effect to take 250 ms, change this property to the value 250. For more details, see Specify the timer interval and the initial delay.

The Numeric Keyboard component generates keyboard events that can be received by other GUI components in your application, such as text editors. The event generation happens in the activateKey slot method. When a key is activated (either immediately after a long press or after the flash effect for quick taps), the activateKey method is called. This method:

For each key press, the method generates two events: (1) press event (DriveKeyboardHitting( ..., true )) and (2) corresponding release event (DriveKeyboardHitting( ..., false )). This pair of events simulates the complete key press cycle, just as if the user had pressed a key on a physical keyboard. Depending on the taped view, the method distinguishes between two types of keys:

When you add new keys to your keyboard, you need to adapt the activateKey method to handle them:

You can find available key codes in the Core::KeyCode enumeration documentation.

Similar to events generated by a physical keyboard, the events generated by a virtual keyboard are delivered to GUI components along the so-called focus path:

This approach follows the standard keyboard event handling pattern in Embedded Wizard, ensuring your virtual keyboard integrates seamlessly with other GUI components. For more details see Handling keyboard events and Keyboard events and the focus path.

In the section Adapt the appearance of the component you learned how the keyboard updates its appearance when keys are pressed and released. Accordingly, when the user touches a key, the key appears highlighted instantly. When the user releases the key, it returns to its normal appearance immediately. The default implementation performs such appearance updates instantly, just in the moment when the respective state change took place.

If desired, you can modify the Numeric Keyboard to update its appearance with animations. For example, instead of instantly switching the highlight color, the keyboard can smoothly fade between colors, or scale the key size for a "bounce" effect. For this purpose you use the Animation Effects. With an Animation Effect you can animate a property of a view existing in the keyboard. Following are the steps how to do this: