ViSi-Genie: Customized Keyboard

Details


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

Description

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.

Prerequisites

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

form0

Setup Procedure

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

project-file

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:

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

add-kb

Click on the screen to place the keyboard object.

keyboard_widget

Select the Keyboard Type

The object inspector shows all the properties of the keyboard:

object0inspector

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

keyboard-type

To do so, click on the KeyboardType line:

keyboar-type1

Click on the button with the three dots Symbol

Note

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

A new window appears: The Keyboard Editor.

keyboard-editor

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

keyboard-types

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

QWERTY keyboard, by default,

qwerty

Cell-phone keyboard

cellphone

Numeric keyboard

numeric

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

form0

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:

form0

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.

cellphone

Select the Cellphone from the keyboard type selection.

select-cp

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.

change-asterisk

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

change-to-cancel

Change Back Key to Validate

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

change-to-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.

Note

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).

key-value-cancel

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.

change-key-validate

Resize the Keyboard

The initial keyboard looks like

initial-cp-type

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.

default-cp-size

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

set_cp_size

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_wxy The 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

checked-change-matching-column-colors

Now, click on the SILVER colour of any key:

colour

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

colour-picker

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:

change-color

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

set-colordown-silver

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

unchecked-change-matching-column-colors

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

colour-picker-yellow

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:

change-specific-color

And the detail is:

set-colordown-specific

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:

final-color

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.

Note

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:

change-font

On the Object Inspector, look for the entry

entry

Click on the + to display the details:

display-details

Replace 8 by 16 and press Enter.

size

The keyboard is updated:

numeric-fontsize-16

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.

entry

Click on the + to display the details:

display-details

Replace 7 by 14 and press Enter.

size

This is the final screen, which is much better:

final-font

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

load-kb-type

The line changes for

change-kb-type

Click on the button.

The Keyboard Editor shows up:

loaded-kb-editor

On the Keyboard Editor window, click on

load

A Windows Open window shows the keyboards available:

keyboards-available

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

Back to the Keyboard object Properties, the KeyboardType shows:

keyboardtype

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:

form0-final

Launch the Debugger

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

launch-gtx

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

gtx_init

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:

debugger

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.

Note

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:

keyboar-message

Note

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]