Facebook Pixel

AN-00082 ViSi Gauges Objects Part I


Description Gauge objects are very useful in providing a real-life like visual for displaying speed, angular displacement, voltage, current, pressure, and other quantities. Depending on the user’s preferences, colours, meter values, and meter names/units can be set using the objects’ properties tab in the Object Inspector of the ViSi environment.
Supported Processor PICASO, DIABLO16
Supported Environment ViSi



File Downloads


This application note is intended to demonstrating to the user the basic of use of the gauge objects – cool gauge, meter and angular meter in ViSi. Before getting started, the following are needed. Before getting started, the following are required:

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.

  • 4D Programming Cable or µUSB-PA5
  • micro-SD (µSD) memory card
  • Workshop 4 IDE (installed according to the installation document)
  • 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

This document is mainly focused on showing the simple use of the Gauges object of the ViSi Genie environment of the Workshop IDE. This objects are very useful in providing a real-life like visual for displaying speed, angular displacements, voltages, currents, pressure and many more. Depending on the user’s preferences, colours, meter values, and meter names/units can be set using the objects’ properties tab in the Object Inspector of the ViSi environment.

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

Adding the Gauges objects for a project created in the ViSi environment is relatively easy. The Gauges tab can be located under the Widgets menu.

Widgets >> Gauges >> Cool Gauge/Angular Meter/Meter


Setting up the objects in the likeness of the project presented here is also easy. The objects can be placed and positioned according to the need of the user. There are particular options on the object inspector that greatly helps the user in achieving their desired graphic user interface.

The properties shown on the side shows that of the meter gauge object.


 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. Three other files are included automatically during creation of the new project, namely:  4DGL_16bitColours.fnc, the VisualConst.inc, and user_imgConst.inc.  Notice that one of the include file is almost the same as the project filename. This file is automatically generated as soon as project saving is done.


The Main Program

The main program contains a simple program that first detects and initializes the micro SD card, the initial displaying of the objects used in the project and an endless loop that includes a random number from 0 to 100 in value. The generated value is saved on a global variable named ‘frame’ and is applied to the gauges objects as their respective sub-routine is called and executed.

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. Another 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’.  In addition, the filenames for the dat and gci files are automatically changed to the project filename as soon as the project is saved.

The screen orientation is set to portrait thereby providing an 800x480 pixel dimension. This setup is attained using the gfx_Set() function.  A gfx_Cls() function is inserted after the statements for mounting the micro-SD drive. This is done to clear the displayed ‘Drive not mounted’ message following the completion of the micro-SD initialization.

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 Objects

In this part of the program, the img_Show() function simply calls out the object image and information found in the micro-SD drive.  This set of statements call out the images from their handler and are displayed on screen. These set of statements plainly display the images as how they are placed into the form viewer of the Workshop IDE- ViSi environment.


The Repeat-forever Loop

The endless loop repeat-forever contains several statements.  The first of these statements contains a random number generating statement. The function RAND() simple generates a random number that is both signed and unsigned. If merged with a modulo-100 this limits the signed numbers produced to be between -100 and 100. To make this value acceptable for the gauge objects another function is used to convert all the generated random number into positive – the ABS() function.

Gauge objects contain a couple of frames that are specific to a certain dial position. These position of the affected by the settings of the gauges itself. The Workshop IDE generates the number of frames declared for a particular gauge object.

** The greater the maximum value set for the gauge the greater the size of the generated image file.


After a random number is generated and saved to the variable ‘frame’ , the next is to apply this to the gauge objects. The statements that change the displayed value of the gauges are contained in the gauges’ respective sub-routine.

Seen above are the sub-routines for the gauge objects. A common variable ‘frame’ can be seen displayed above. This variable ‘frame’ takes the pre-saved value and is made the reference value for the ‘IMAGE_INDEX’  of the gauges.  Observe that the frame number must first be set using the set_Word() function and then followed by the img_Show() function.


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 uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other displays.