With this template you can add a new Alphanumeric Keyboard component to your project. Alphanumeric 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 Alphanumeric 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 Alphanumeric Keyboard wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Alphanumeric 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 Alphanumeric 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 Alphanumeric Keyboard from scratch you can use the available template. The second function is more educative. The template implements fully working Alphanumeric 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 Alphanumeric 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 Alphanumeric Keyboard component.

To create a new Alphanumeric 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 Alphanumeric Keyboard component from a template:

The new created Alphanumeric 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 Alphanumeric Keyboard component, you can use it to assemble more complex components. Technically seen, you embed an instance of the Alphanumeric Keyboard class in-place within the Application component. At the runtime, the Application 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.

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

As long as the Alphanumeric 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 Alphanumeric 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 Alphanumeric 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 Alphanumeric Keyboard itself does not add any new property.

Once added to the Application component, you can freely move the Alphanumeric 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 Alphanumeric 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 Alphanumeric 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 Alphanumeric Keyboard appears displaying a QWERTZ-layout grid with letter, digit, and special character keys as text views, and special function keys (Tab, Caps Lock, Shift, Clear, Enter) as image views. The space bar is indicated by a border rectangle. A white background is surrounded by a border. When a key is pressed, it is highlighted with a red rectangle. When Shift or Caps Lock keys are active, they are indicated with red borders. 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 Alphanumeric 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, handles layout switching for Shift and Caps Lock keys, and generates the corresponding keyboard event for the application.
	Init	This method is invoked automatically when a new keyboard instance is created. It loads the default keyboard layout (shift off) at initialization time.
	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.
	TextKey01 .. TextKey47	These Text views represent the alphanumeric keys. The keyboard layout determines which character each key displays. Keys are arranged in a QWERTZ layout using the Resources::FontMedium font.
	ImageKeyTab	This Image view represents the Tab key using an icon from Resources::KeyIconsSmall bitmap resource.
	ImageKeyCapsLock	This Image view represents the Caps Lock key using an icon from Resources::KeyIconsSmall bitmap resource.
	ImageKeyShiftLeft and ImageKeyShiftRight	These Image views represent the left and right Shift keys using icons from Resources::KeyIconsSmall bitmap resource.
	ImageKeyClear	This Image view represents the Clear (Backspace) key using an icon from Resources::KeyIconsSmall bitmap resource.
	ImageKeyEnter	This Image view represents the Enter key using an icon from Resources::KeyIconsSmall bitmap resource.
	AreaKeySpace	This Border view indicates the area of the space bar key. It is displayed as a gray border rectangle per default.
	ActiveKeyCapsLock	This Border view indicates when the Caps Lock key is active. It is displayed as a red border around the Caps Lock key and is hidden per default.
	ActiveKeyShiftLeft and ActiveKeyShiftRight	These Border views indicate when the Shift keys are active. They are displayed as red borders around the Shift keys and are hidden per default.
	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.
	loadLayoutFromString	This method loads a new keyboard layout by updating all text key views with characters from the provided layout string. The string's characters correspond to keys according to their z-order.
	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.
	layoutShiftOff	This variable stores the keyboard layout string for lowercase letters and normal characters. The default layout is German QWERTZ.
	layoutShiftOn	This variable stores the keyboard layout string for uppercase letters and shifted special characters. The default layout is German QWERTZ.

During its lifetime, the Alphanumeric 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.

Additionally, the Alphanumeric Keyboard maintains the state of the Shift and Caps Lock keys. When a Shift key is pressed, the keyboard shows red borders around both shift keys (ActiveKeyShiftLeft and ActiveKeyShiftRight become visible) and loads the shifted layout. After the next character key is pressed, the keyboard automatically returns to the unshifted layout. The Caps Lock key works similarly but keeps the shifted layout active until Caps Lock is pressed again.

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.

The Alphanumeric Keyboard component uses a flexible layout mechanism that allows easy customization of which characters appear on each key. The layout is controlled by two string variables:

Each character in these strings corresponds to one text key on the keyboard. The default layout is German QWERTZ:

The order of characters in the layout strings corresponds exactly to the z-order of the text views TextKey01 through TextKey47 within the component. For example, the first character in the string ('1' in layoutShiftOff) is displayed on TextKey01, the second character ('2') on TextKey02, and so on.

When the keyboard needs to change its layout, it calls the loadLayoutFromString() method with the desired layout string as parameter. This method traverses all text key views in their z-order and assigns each one the corresponding character from the layout string:

The layout switching is triggered automatically by the activateKey slot method:

To customize the keyboard layout for your language or requirements, you simply modify the layoutShiftOff and layoutShiftOn strings. For example, to create an English QWERTY layout:

Please note the peculiarity of the $ sign being interpreted as beginning of a macro. Therefore double $$ has to be used. Also several signs require a backslash as prefix. Note the string literal syntax for more details.

Originally, if not yet modified, the Alphanumeric Keyboard appears displaying alphanumeric keys as black text on white background, special function keys as black icons, a gray border indicating the space bar, and a red rectangle that highlights the pressed key. When Shift or Caps Lock are active, red borders appear around the respective keys. 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 Alphanumeric Keyboard template contains per default the views Background, Border, Highlight, the key views (TextKey01 .. TextKey47, ImageKeyTab, ImageKeyCapsLock, ImageKeyShiftLeft, ImageKeyShiftRight, ImageKeyClear, ImageKeyEnter), the space bar indicator (AreaKeySpace), and the active key indicators (ActiveKeyCapsLock, ActiveKeyShiftLeft, ActiveKeyShiftRight). 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:

Similarly, you can modify the appearance of the active key indicators. For example, to change the Shift indicator from red border to blue:

If not needed, you can delete some of the per default existing key views. For example, if you don't need the Tab key, you can remove the ImageKeyTab view. 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:

If you want to remove some of the text keys (for example, to create a numeric-only alphanumeric keyboard), remember that the keyboard layout mechanism depends on the z-order of text views. After removing text keys, you must:

You can add more keys to your keyboard. For example, you can add function keys, additional special characters, or language-specific letters. Following steps explain the workflow:

Also possible, you can replace the existing key views by other views. For example, you could replace some text-based 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 key rows, 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 Alphanumeric Keyboard component allows you to easily customize which characters appear on each key by modifying the layout strings. The default layout is German QWERTZ, but you can adapt it for any language or special purpose.

To customize the keyboard layout, modify the string variables layoutShiftOff and layoutShiftOn:

The layout strings must have exactly as many characters as there are text key views in your keyboard (47 by default). Each character in the string corresponds to one text key according to the z-order of views TextKey01 through TextKey47.

Here are examples of layout strings for different keyboard layouts:

Please note the peculiarity of the $ sign being interpreted as beginning of a macro. Therefore double $$ has to be used. Also several signs require a backslash as prefix. Note the string literal syntax for more details.

If you have added or removed text keys, you must ensure the layout strings have the correct length:

For example, if you removed 5 text keys and now have 42 keys, your layout strings must each have exactly 42 characters.

The initial size of the Alphanumeric 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 Alphanumeric 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 Alphanumeric 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 Alphanumeric 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 password"), 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 Alphanumeric 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 Alphanumeric 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, or you could even provide properties to dynamically change the keyboard layout. For this purpose you access and modify the affected property directly within Chora code:

An interesting application of properties in the Alphanumeric Keyboard would be to add properties for controlling the layout strings dynamically. For example:

The Alphanumeric 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 Alphanumeric 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 Alphanumeric 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 regular 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 three 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. When Shift or Caps Lock keys are activated, their indicator borders appear instantly. 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 Alphanumeric 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. Similarly, the Shift and Caps Lock indicators can fade in/out smoothly. 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:

You can also animate the Shift and Caps Lock indicators. For example, to animate the ActiveKeyShiftLeft border's opacity: