Facebook Pixel

AN-00073 ViSi Keyboard

Description The main focus of this application note is to demonstrate the use of the ViSi Keyboard object on a uLCD-70DT display module. Alphanumeric inputs are one of the most useful medium of inputs. In this application documentation, a ViSi based keyboard is used to type and edit characters on-screen. The keyboard object of the attached project can be resized to fit a smaller target screen.
Supported Processor PICASO, DIABLO16
Supported Environment ViSi
Difficulty Medium


File Downloads


This application note is intended to demonstrating to the user the usage of the keyboard widget from the Workshop IDE-ViSi Environment.

and other superseded modules which support the ViSi Genie environment

Visit www.4dsystems.com.au/products to see the latest display module products that use the Diablo16 processor. The display module used in this application note is the uLCD-32PTU, which is a Picaso display. This application note is applicable to Diablo16 display modules as well.

When downloading an application note, a list of recommended application notes is shown. It is assumed that the user has read or has a working knowledge of the topics presented in these recommended application notes.


Application Overview

The main focus of this application note is to demonstrate the use of the ViSi Keyboard object on a uLCD-70DT display module. Alphanumeric inputs are one of the most useful medium of inputs.  In this application documentation, a ViSi based keyboard is used to type and edit characters on-screen. The keyboard object of the attached project can be resized to fit a smaller target screen.


Setup Procedure

For instructions on how to launch Workshop 4, how to open a ViSi project, and how to change the target display, kindly refer to the section “Setup Procedure” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16


Create a New Project

For instructions on how to create a new ViSi project, please refer to the section “Create a New Project” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16


Design the Project

The ViSi environment keyboard is a customizable widget from the Workshop IDE – ViSi environment. It an input object which can be added from the Widgets Menu >>Input Tab.


After adding the Keyboard object into the project, several object properties are displayed on the Object Inspector. As shown in the figure below.


As mentioned from the previous section, the keyboard object can be configured according to the user’s need. To set the desired configuration, click on the Keyboard Type setting option from the object inspector.  Click on the right-end of the option same as the one shown below.


The keyboard editor is a visual assistant that simplifies the editing of the keyboard input. There are four available keyboard types. A complete 106-key keyboard named -   ‘QWERTY’, a ‘Numeric’ type, a ‘Cellphone’ type, and a user customized ‘Custom keyboard.’


The user can have a key added and removed depending on the requirements of a project. For this project, a complete 106-key QWERTY type is used. A simplified approach to explaining the process of setting up the object is presented in this application documentation. The setup and use of the ViSi Keyboard object is not simply done by just adding the object to a project. The setup involves an assignment of character(s) to a particular key and an assigned output value. The assigned output value is the resulting value whenever a key is pressed.


A value of ‘1’ is assigned to the “ ~ ” character on the keyboard. The numerical value ‘1’ is returned each time the key is pressed. This is also the same for Shift + Key characters. The keys on the board maybe named according to the requirement of user. For this application project, the assigned valued were assigned successively. This was done to prevent confusion during coding. The colours were also changed to identify the alpha-numeric keys with that of the special ones.


For all the keys that are intended to be used a value must be assigned. If the key is not to be used then a -1 would make the key inactive but visible.


The ViSi-based Keyboard application

This project is very simple. It includes a custom keyboard with a string object to point where the characters will be placed.



Also, for a better understanding of the functions and statements used in this projects, please refer to DIABLO16 Internal Functions and 4DGL Programmer’s Reference manual.

 After all the objects have been laid-out, let’s continue with the other half which involves the coding of the project. This will be presented in a sectional manner so as not to create confusion with the project. For an in-depth detail of the functions used in this application note please refer to the DIABLO16 Internal Functions Reference Manual.


The include section

This project starts with the identification of the platform being used as declared by the #platform function. For the program to be able to function properly files are included herein using the #inherit function. An additional inherited files is named “KBROUTINES.inc”. This is an included file that supports the custom functions used with the keyboard which will be presented at the later parts of this document.


The main program

The main program for this projects contains several sections: the initialization and the mounting of the micro-SD card, the initial displaying of the keyboard image, and a continuous repeat-forever loop.


The micro-SD initialization

Let’s start with the initialization of the uSD card. The uSD card contains all the image information about the objects used in the project. The object information and data are saved under a *.DAT and a *.GCI filename extension which is copied to the uSD during project compilation. Mounting of the disk in this application note was done using the following set of program statements.

When starting a new project in the ViSi environment these set of statements are already included in the coding area. The last part of these set of statements uses a function file_LoadImageControl() to call on the object data/information files on the uSD drive. This initializes the data to be called in using the variable ‘hndl’.


Added to the statements above are the screen orientation setup function and the touch enable function. The screen orientation is set to portrait thereby providing a 800x480 pixel dimension. This setup is attained using the gfx_ScreenMode() function.

Having been able to load and initialize the uSD drive, the processor is now able to access the information stored therein. As mentioned from the previous section, the filenames with an extension of DAT and GCI has the image data and information.  Therefore, the next part of the main program is to display all the objects that were placed on the Workshop IDE form viewer.

A special button from the Object Inspector can help reduce the time of coding of this part. The ‘Paste Code” simply pastes object code.


Displaying the text and Images

In this part of the program, the img_Show() function simply calls out the object image and information found in the microSD drive.  This set of statements call out the images from their handlers and are displayed on screen.


The statements shown above configures that the touch feature is enabled for the keyboard object. This was done using the img_ClearAttributes() function. Using the for-next loop this was applied to all the key images present in the keyboard object.


The repeat-forever loop

This section of the main program contains statements that are continually run by the processor.  The statements inside the repeat-forever loop starts with the touch status being checked and saved into a variable ‘status’. A variable ‘n’, on the other hand is used to store the returned image being touched.

Furthermore, the repeat forever contains three conditions that are related to the touch status- a condition during a press and a release of the touch panel.


Referring to the statements below, after a press is detected on the screen is a set of if-conditions. These if-conditions are checks-out which image is touched. If one of the images related conditions is satisfied the statements contained in the conditional loop is executed.

As a start, let us consider the touch related if-condition. For a touch that is moving, the processor is directed to simply read and save the value of the touch x and y position to variables ‘x’ and ‘y’, respectively.


Another one of the if-condition loops is  the ‘touch_pressed’ condition. Whenever there is a press detected on the screen the statements within this condition is executed. For the statements shown above, a sub condition dedicated for the keyboard object is included. The condition for the touch needs to satisfy two things – that a touch must be inside the keyboard object and that is a key inside the keyboard object. With the conditions satisfied the button state is changed. This means that the colour of the button changed according to the setting on the Keyboard Editor. The resulting value of the depressed key is directed to the function ‘kbHandler’. This ‘kbHandler’ function is a user defined function that enables return of preset numerical equivalents of the keys.


The kbHandler sub-routine

The function name kbHandler is part of the integrated development environment generated code. The user may choose to change this or keep this function name.  The kbHandler() is an important part of the keyboard object codes. Recall that on the previous sections, a particular numerical value is assigned for each of the keys of the keyboard. This numerical value is then returned using this kbHandler() function.


For a better idea, please refer to the image on the other column.


The statements above defines a function kbHandler() which has a declared data argument variable ‘Key’. This variable ‘key’ contains the result of the ‘keyboard key pressed’ result. This value is transferred to another variable ‘savekey’. Each time that a key is pressed inside the button then this sub-routine called and executed by the processor.


The succeeding statements is a chain of if-else-if condition loops. After the numerical value of the key is transferred to the ‘savekey’ variable, the next task is to find the equivalent of the value and then execute the contents of the loop. If the resulting value is equivalent to the preset value then a character is printed on-screen.  


Included in the if-else-if conditions are to() and putstr() functions. These functions is intended to enable saving of the characters pressed. The variable array buffer is the location where the to(APPEND) points to. Each time a new character is pressed the character is displayed on-screen and saved into the buffer. 


Note that before the to(APPEND) is to be used, a to(buffer) must first be used. This is done so as to make the variable array buffer the current working variable array.  The new data is attached at the end of the string until the whole allocation for the buffer is filled.


Running the project

First thing to do, is to open the ViSi project entitled ‘KBoard’ in the Workshop IDE. After being able to open all the files, make sure that the Workshop IDE is setup to program the project into the display device’s Flash memory. This programming destination can be changed from the   project menu tab.



Click the download button on the upper right of the menu tabs. Doing so compiles and downloads the program to the display module.


Run the Program

For instructions on how to save a ViSi project, how to connect the target display to the PC, how to select the program destination (this option is not available for Goldelox displays), and how to compile and download a program, please refer to the section “Run the Program” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16

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