Skip to content

ViSi-Genie: Customized Keyboard


Number 4D-AN-00003
Difficulty Medium
Supported Processors PICASO, DIABLO-16, PIXXI-28, PIXXI-44
Supported Environments ViSi-Genie


This application note demonstrates how to customize a keyboard object. This document is a step-by-step guide on customizing a cellphone-type keyboard and changing the Key Value to your preferred returned data when pressing a key.

Downloadable Resources

You can find the project file used in this application note:

Project File

The target module can be changed to your touchscreen display module powered by any of the supported processors: PICASO, DIABLO-16, PIXXI-28 or PIXXI-44.


Application Overview

This application note focuses on how to customize the keyboard object. The keyboard editor provides an interface for editing / designing the keyboard object. This includes resizing of the keys, changing color and define the output values when a key is pressed.

Below is the Graphical User Interface that we will generate with this document. The form has three objects.

  • A Label
  • A String
  • A Keyboard


Setup Procedure

This application note comes with a zip file which contains a ViSi-Genie project.


For instructions on how to launch Workshop4, how to open a ViSi-Genie project, and how to change the target display, kindly refer to the section Setup Procedure of the application note:

Create a New Project

For instructions on how to create a new ViSi-Genie project, please refer to the section Create a New Project of the application notes

The Keyboard Object

You can load the example project files under the Downloadable Resources section or follow the procedures described hereafter.

Add a Keyboard Object

To add the keyboard widget:

  1. Go to Home menu.
  2. Navigate to Inputs pane.
  3. Select the Keyboard object.


Click on the screen to place the keyboard object.


Select the Keyboard Type

The object inspector shows all the properties of the keyboard:


To customise the keyboard, we need to change the keyboard type:


To do so, click on the KeyboardType line:


Click on the button with the three dots Symbol


The project must be saved before continuing to select the keyboard type.

A new window appears: The Keyboard Editor.


On top of the window, different keyboard types are proposed:


ViSi-Genie comes with various defined ready-to-use keyboards:

  • QWERTY keyboard, by default,


  • Cell-phone keyboard


  • Numeric keyboard


A customized keyboard can be obtained from the ready-to-use keyboard type or loaded from a previously used keyboard.


Keyboard Editor

Before building the customized keyboard, drawing a sketch to have a clear vision of the keys, rows, and columns is a good idea.

It is better to start with a ready-to-use or previously used keyboard for faster development than an empty type.

Here, the keyboard includes a numerical pad plus two specific keys, one to cancel and the second to validate:


Since it is similar to cellphone type keyboard, we can start with this template and apply small changes on color, key size, font size, * (asterisk) and back keys.


Select the Cellphone from the keyboard type selection.


Changing Key Text

Change *(asterisk) Key to Cancel

To change the Key from * (asterisk) to Cancel go to Keys and click the * (asterisk) sign under Key column.


Then, type Cancel. You will notice that as soon as you edit the key it will automatically change to Custom type.


Change Back Key to Validate

To change the Back key to Validate go to Back under Key column and type Validate.


Changing Key Value

By default, keys have a Key Value (or Sh Key Value) of -1 which tells Workshop 4 IDE to automatically use the first character of the label determined by Key (or Shift Key) as the value when the key is pressed. The key values can be changed to something you want to send in the report message.


Using -1 Key Value (or Sh Key Value) requires that the Special Key is set to None.

By using -1 for the number key 0 - 9, the keys will output 0x30 (48 DEC) to 0x39 (57 DEC). You can change the values to be 0x00 (0 DEC) to 0x09 (9 DEC), however, it is not recommended as it requires manually editing each key value. Instead, the values can simply be computed from the default values by simply subtracting 0x30 (48 DEC).

While this is not recommended, some projects can benefit from it since it can reduce the computations even by a little bit as the keyboard will provide integers instead of the ASCII character.

Change the Key Value of Cancel Key

The Cancel key value is currently set as -1 which defaults to the C character, or 0x43 (67 DEC). Since, we don't have any overlaping key, it can stay as -1. However, for best practice, set it to a custom Key that is most suitable. The Cancel ASCII value is 0x18 (24 DEC).


Change the Key Value of Validate Key

The Validate key has a key value of 8 which is actually a backspace ASCII character. This can also be change to more suitable value or as preferred. In this application note, we will change the key value to 0x06 (6 DEC) which is ACK (acknowledgent) character in ASCII.


Resize the Keyboard

The initial keyboard looks like


Since we are using a 320 x 240 display in this example, we will set the keyboard size to 320 x 162.

The default cellphone size has the following values.


Change the default size to width: 320 amd height 162.


Change the Size of a Key

In this example, the width of each keys is 106 and the height is 40.

Set the width, X and Y position of each key with the values shown below.

set_wxyThe X and Y values starts at top left corner. The first row(Y) and first column(X) values are all equal to 1.

To compute the X values for the column is

n column = (width * (n-1)) + 1

To compute the Y values for row is

n row = (height * (n-1)) + 1

where n is the number of row or column with 1 starting from top row or left column.

Change the Colour of All Keys

The keys have 4 colours:

  • Colour of the key
  • Colour of the key, when pressed
  • Colour of the text on the key
  • Colour of the text on the key, when pressed.

To change the colour of all keys, make sure the check-box Change Matching Column Colours is ticked


Now, click on the SILVER colour of any key:


A new window Colour Picker appears and shows all the colours available:


Colours are grouped under Windows, Theme and 4DGL. Manual values can be set for Hue-Saturation-Luminance or Red-Green-Blue components. Select Office 2003 (Blue) then click OK.

The WYSIWYG keyboard is updated accordingly:


Do the same for the Colour Down and select Office 2003 (Silver). The key list displays the new colours:


Change the Colour of One Specific Key

The Cancel and Validate keys have specific colours.

To change the colour of one specific key, make sure the check-box Change Matching Column Colours is unticked


Now, click on the Office 2003 (Blue) colour of the Cancel key. Select Yellow on the colour picker and confirm by OK:


Repeat with Colour Down for the Cancel key and select ORANGE.

Do the same for the Validate key and select GREEN as Colour and GREENYELLOW as Colour Down.

Final result is:


And the detail is:


Save the Keyboard

It's time now to save the keyboard.

To do so, click on


The Keyboard Editor window closes and the form shows the keyboard:


Define the Font and Size of the Keyboard

The keyboard looks nice but it is hard to read, because the font size is too small.


The font is not defined during the layout design of the keyboard. The same keyboard can be used on different screens, and thus be adapted to match each screen. The font is a property like the size of the keyboard.

We are going to change the size of the font.

Select the keyboard by clicking on it. The keyboard is within a green dotted rectangle:


On the Object Inspector, look for the entry


Click on the + to display the details:


Replace 8 by 16 and press Enter.


The keyboard is updated:


Notice that Cancel and Validate keys didn't change size. This is because the Font property only applies to single character keys, as can be set in Key and Shift Key columns of the Keyboard editor.

For the Cancel and Validate keys, the SmallFont property, which instead applies for keys with long Key and Shift Key names, should be used,

On the Object Inspector, look for the SmallFont Property.


Click on the + to display the details:


Replace 7 by 14 and press Enter.


This is the final screen, which is much better:


Load a Keyboard

The keyboards previously defined are saved and can be loaded again for re-use.

To load a keyboard, first open the Keyboard Editor.

To open the Keyboard Editor:

  • On the Object Inspector, select the keyboard and click on the Keyboard Type line


  • The line changes for


  • Click on the symbol button.

The Keyboard Editor shows up:


On the Keyboard Editor window, click on


A Windows Open window shows the keyboards available:


Select the desired keyboard, for example KB1.KBD, and click on Open.

Back to the Keyboard object Properties, the KeyboardType shows:


Build and Upload the Project

For instructions on how to build and upload a ViSi-Genie project to the target display, please refer to the section Build and Upload the Project of the application note

The uLCD-32PTU and/or the uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other displays.

Debug the Project

It's time now to eject the micro-SD card from the PC and plug it in the micro-SD card slot of the screen.

Once this is done, the screen displays the form:


Launch the Debugger

To launch the Genie Test Executor or GTX, select the Tools menu and select the GTX button.


A new screen appears, with the form and objects we have defined.


Test the Keyboard

Press on the screen the keys 1, 2, 3, and 4 in that specific order followed by Validate.

The debugger shows now:


The white area on the right displays the messages sent by the screen:

Set Form Value 12:45:43.910 [01 0A 01 00 00 0A]
ACK 12:45:44.147 [06]
Keyboard Change 12:45:47.109 [07 0D 00 00 31 3B] 
Keyboard Change 12:45:47.830 [07 0D 00 00 32 38] 
Keyboard Change 12:45:48.609 [07 0D 00 00 33 39] 
Keyboard Change 12:45:49.482 [07 0D 00 00 34 3E] 
Keyboard Change 12:45:50.361 [07 0D 00 00 06 0C] 

All codes are in hexadecimal. 0x31 stands for 1, ..., 0x34 for 4.


The key has sent the message 0x06 or [ACKNOWLEDGE] (Refer to ASCII table).

The code entered on the screen is displayed below the Keyboards section:



The key has sent the a non-printable character which is displayed as a boxed character.

On a similar way, let's enter a wrong code and press

Press on the screen the keys 1, 2, 3, and 0 in that specific order followed by Cancel.

The message window displays:

Set Form Value 13:05:23.808 [01 0A 01 00 00 0A]
ACK 13:05:24.036 [06]
Keyboard Change 13:05:26.218 [07 0D 00 00 31 3B] 
Keyboard Change 13:05:26.969 [07 0D 00 00 32 38] 
Keyboard Change 13:05:27.752 [07 0D 00 00 33 39] 
Keyboard Change 13:05:28.593 [07 0D 00 00 30 3A] 
Keyboard Change 13:05:29.435 [07 0D 00 00 18 12]