ViSi-Genie: Advanced Buttons

Details

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

Description

This Application Note explores the possibilities provided by ViSi-Genie for the Button object:

• Simple button
• Button with an icon
• On/Off button
• Group of buttons
• Menu based on buttons
• Menu based on buttons with messages

Document PICASO DIABLO-16

Prerequisites

• General: How to Update the PmmC for DIABLO-16
• General: Migrating from PICASO-SGC-GFX to PICASO
• General: How to Update the PmmC for PICASO
• General: Partitioning a micro-SD into FAT and RAW Components

Application Overview

The button is the key element of a graphical user interface.

In ViSi-Genie, the button corresponds to different standard elements:

• Used alone, it triggers an action when pressed. This is the simple button.

• The button can keep trace of its state, off and on, and provides a feed-back. The equivalent is a check-box.

• Grouped with other buttons, selecting one unselects the others. The equivalent is a group of radio-buttons.

• Finally, combining forms and buttons allow building menus with sub-menus. The equivalent is a menu.

The different sections of this application notes have been redacted on a progressive order. It is thus recommended to read this document sequentially.

Setup Procedure

This application note comes with zip files which contains multiple ViSi-Genie projects for each processor type.

You can find the projects under Downloadable Resources section.

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:

• ViSi-Genie: Getting Started with PICASO Displays
• ViSi-Genie: Getting Started with DIABLO-16 Displays

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 note

• ViSi-Genie: Getting Started with PICASO Displays
• ViSi-Genie: Getting Started with DIABLO-16 Displays

Add a Button Object

Select the Home menu to display the objects:

The Button object is located on the Buttons pane:

Click first on the Button icon

and then click on the WYSIWYG screen to place it:

The Object Inspector of the right part of the screen displays all the properties of the WinButton0 object:

Simple Button

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

Here is a simple button:

This is the equivalent of the standard button:

To edit the properties of the button, click on it on the WYSIWYG screen:

A dotted green line appears.

On the right part of 4D Workshop, the Object Inspector displays all the properties of the Winbutton0 button:

The caption of the button is defined by the Caption property.

By default, the caption has the same value as the name of the object, here Winbutton0:

To change the caption, select the line of the property, type in the new caption, here Button, and press Enter:

The WYSIWYG screen is updated accordingly:

The font, the size and the colour of the caption are under the Font node:

Click on the to show the details:

For example, change the font size from 8 to 12:

The button is updated accordingly:

By default, the buttons have a glossy appearance. The appearance properties are under the Appearance node:

Click on the to show the details:

For example, change SimpleLayout from No to Yes to obtain a flat button:

The button is updated accordingly:

Feel free to play with the many options of colours, alignment, bevel to customise the button to your specific needs.

Button with Icon

You can load the example project Simple Button: Button with Icon under the Downloadable Resources section or follow the procedures described hereafter.

A button can display an icon.

Click on and the standard Open window asks for a image:

Select the image you want, here player_play, and click on

The object property is updated with the name of the image

and the WYSIWYG screen shows the new button:

To resize the button, either enter the values for Height and Width

or click on the green dotted rectangle and resize the button:

Set SimpleLayout to Yes to hide the bevel:

Final result is:

On/Off Button

You can load the example project On-Off Button under the Downloadable Resources section or follow the procedures described hereafter.

To convert a momentary button into an on/off button, set the Momentary property to No:

Pressing the button turns it on, pressing again turns it off.

However, the lack of visual feed-back doesn't make this on/off button very easy to use.

Let's add some visual feed-back:

• Green OFF when the button is off
• Red ON when the button is on.

This is the equivalent of the standard check-box, off

and on.

The green OFF and red ON captions are set under the StatusWhenOff and StatusWhenOn properties, respectively:

Click on the to show the details:

Let's start with the green OFF under StatusWhenOff:

Click on the BGColor line property:

A symbol appears. Click on it.

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

Colours are grouped under Windows, Theme and 4DGL.

Manual values can also be set for Hue-Saturation-Luminance or Red-Green-Blue components.

Select Green under 4DGL Colours and then click OK.

The colour of the status is updated accordingly:

Select the new line, Caption

and type in the caption, OFF, then press Enter:

The button on the WYSIWYG screen is updated accordingly:

Keep Visible with the value Yes, otherwise the caption wouldn't be visible.

Final result looks like:

Proceed the same way with the ON caption under StatusWhenOn:

Build and run the project.

The screen shows the button turned OFF:

Touching the button turns it ON:

Touching again turns it OFF again:

Now, let's get rid of the OFF caption to keep only the ON caption.

Go to the Visible property under StatusWhenOff and changed it to No:

The form displays the button OFF with no caption:

Touching the button turns it ON:

Touching again turns it OFF again:

Group of Buttons

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

Simple button and on/off button are not the only uses of the buttons. Very often, different buttons are used together to bring a choice among different options. Selecting one option cancels the previous one.

This is the equivalent of the radio-buttons:

With ViSi-Genie, such a group is called a matrix.

To link the buttons together, just change the value of the matrix from -1 for no matrix

to the number of the matrix, here 1:

It is important that all buttons grouped share the same number of matrix, otherwise pressing on one button will not release the other buttons of the group.

Let's start with the first button, Red.

• Set the caption to Red:

  

• Enter the number of the Matrix, 1:

  

• And set Momentary to No:

  

• Finally, define the StatusWhenOff and StatusWhenOn parameters as seen in the previous section:

Do the same for the Green and Blue buttons with their respective values, update the Caption, enter the number of the Matrix and set Momentary to No.

For the Green button

For the Blue button

Build and run the project.

The form displays the buttons and no one is selected:

Press on the Red button:

Red is selected.

Press on the Green button:

Red is released and Green is selected.

Press on the Blue button:

Green is released and Blue is selected.

Button-Based Menu

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

Another use of the buttons is building a menu. A standard menu with sub-menus doesn't fit into a 3.2" or 4.3" screen.

Instead, each menu is going to be shown as a screen, or form, with the sub-menus as buttons, plus a backward button to return to the former level.

Below a menu with two levels:

• Top level:

• First level, with the Menu 1 option highlighted:

• Second level, for the sub-menu of Menu 2, and with the Menu 2.2 option highlighted:

In this example, Menu 1, Menu 2.1 and Menu 2.2 are terminal options. They have no sub-menus associated.

Translate a Menu into Forms and Buttons

With ViSi-Genie, this whole menu including all its sub-menus is going to be translated into 3 forms, with each form containing the options of the corresponding sub-menu:

• Top level:

• First level, with two options:

• Second level with the 2 options for the Menu 2 sub-menu:

For better ergonomics, a yellow Back button is included:

The Back button returns to the previous node. Above, it goes to the first level.

Each terminal option, Menu 1, Menu 2.1 or Menu 2.2, ends to a landing page. Here the example for Menu 1:

Go from a Button to a Sub-Menu

Each form includes the options of the menu as buttons.

The Button object generates the event onChanged when pressed:

When pressed, the button associated with an option opens the form which contains the sub-menus of the option selected, just like the classic way:

Here, pressing on the Menu button opens the forms with the Menu 1 and Menu 2 options:

Summarise Forms and Buttons

Here is the summary of the forms and the buttons, with their associated actions:

Form0 - Top Level

Button	Action = Command
Menu	Open first level = activate Form 1

Form1 - First Level

Button	Action = Command
Menu 1	Go to Menu 1 landing page = activate Form 3
Menu 2	Open second level of Menu 2 = activate Form 2
Back	Return to top level = activate Form 0

Form2 - Second Level of Menu 2

Button	Action = Command
Menu 2.1	Go to Menu 2.1 landing page = activate Form 4
Menu 2.2	Go to landing Menu 2.2 landing page = activate Form 5
Back	Return to first level = activate Form 1

Form3 - Menu 1 Landing Page

Button	Action = Command
Back	Return to last menu = activate Form 1

Form4 - Menu 2.1 Landing Page

Button	Action = Command
Back	Return to last menu = activate Form 2

Form5 - Menu 2.2 Landing Page

Button	Action = Command
Back	Return to last menu = activate Form 2

Build the Menu

First, create as many forms as levels and landing pages, 6 in the example.

To create a form, select the System pane of objects

click on the Form object

an empty form appears on the WYSIWYG screen:

Top Level Form

Form0 corresponds to the top level of the menu:

Add a button to the form, WinButton0:

Select WinButton0 and rename it to Menu:

The Button object generates the event onChanged when pressed.

Select the Events pane on the Object Inspector and click on the line onChanged:

A symbol appears. Click on it.

A drop-down list appears with a list of commands:

Five of the six forms we created before appear. Form0 is not listed as WinButton0 belongs to that form.

Here, the Form1Activate command stands for the activation of the Form1, which corresponds to the first level of the menu, with Menu 1 and Menu 2 options.

When WinButton0 Menu is pressed, the first level of the menu is displayed by Form1:

Form1 is empty for the moment.

First Level Form

Form1 correspond to first level of the menu, with two options, Menu 1 and Menu 2:

Add two buttons, call them Menu 1 and Menu 2 and define the following events:

Button	Event	Command
Menu 1	onChanged	Form3Activate
Menu 2	onChanged	Form3Activate

The WYSIWYG screen displays:

Optionally, add the the yellow Back button

and define its event:

Button	Event	Command
Back	onChanged	Form0Activate

The WYSIWYG screen displays:

Second Level Form

Pressing Menu 2 calls the second level menu, with Menu 2.1 and Menu 2.2 options:

Proceed with Form2 with the following buttons:

Button	Event	Command
Menu 2.1	onChanged	Form4Activate
Menu 2.2	onChanged	Form5Activate
Back	onChanged	Form1Activate

Final result is:

Landing Page Forms

The following forms Form3, Form4 and Form5, are landing pages:

Include two StaticText objects, one with Landing page caption and the other with the menu number, here Menu 1.

To add a StaticText object, select the Labels panes

click on the StaticText object

then place it on the WYSIWYG screen

finally, enter its caption:

Each landing page is going to have its specific Menu label, Menu 1, Menu 2.1 or Menu 2.2.

Finally, add one yellow Back button with the following definition:

Button	Button	Event	Command
Form 3	Back	onChanged	Form1Activate
Form 4	Back	onChanged	Form2Activate
Form 5	Back	onChanged	Form3Activate

The landing pages look like:

• Form3 as landing page for Menu 1

  

• Form4 as landing page for Menu 2.1

  

• Form5 as landing page for Menu 2.2

  

Save, build and upload the project.

Congratulations, you have completed a menu with sub-menus!

Button-Based Menu with Messages

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

Instead of displaying landing pages, we want now the screen to send back to the micro-controller connected to the screen the menu selected.

Instead of associating the command activate a form to the onChanged events, the buttons will send a message.

Define the Events for Messages

To do so, delete all the landing page forms, Form3, Form4 and Form5, as they are no longer required.

Then define Message as handler for the onChanged event only for the buttons associated with terminal options, more specifically WinButton1 for Menu 1, WinButton3 for Menu 2.1 and Winbutton4 for Menu 2.2.

On Form1 for the first level menu, WinButton1 or Menu 1 has the event onChanged associated with the action Message:

Button	Event	Command
Menu 1	Onchanged	Report Message

Note

The deleted forms no longer appear. Form1 is the active form and thus isn't listed.

Do the same for Form2 corresponding to the second level menu:

Button	Event	Command
Menu 2.1	Onchanged	Report Message
Menu 2.2	Onchanged	Report Message

Read the Messages

Save, build and upload the project.

In order to read the messages, we are going to use the built-in debugger.

To debug the project, select on the Tools menu

and launch the Codeless Executive Test Instrument:

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

Let's start!

The screen shows the main menu:

• press Menu

  

• the screen is refreshed with the top level menu

  

• then press Menu 1

  

• the debugger shows now:

  

Read the Menu Selected

The white area on the right of the Codeless Executive Test Instrument window, displays the messages sent by the screen: Winbutton Change 14:21:53.004 [07 06 01 00 00 00]

07 06 01 00 00 00 is the message sent by WinButton1. 06 stands for WinButton object type and 01 for number 1.

The WinButton1 button corresponds to the first Button object, Menu 1:

Go back to the main menu by pressing .

Now, from the main menu, press the sequence

The debugger displays the message: Winbutton Change 14:23:16.965 [07 06 03 00 00 02]

07 06 03 00 00 02 is the message sent by WinButton3. 06 stands for WinButton object type and 03 for number 3.

All codes are in hexadecimal.

The WinButton3 button corresponds to Menu 2.1:

Understand the Messages

As WinButton4 button corresponds to Menu 2.2

we might expect a message like 07 06 04 00 00 05, with 06 for WinButton object type and 04 for number 4.

Let's check it!

Go back to the main menu by pressing twice.

Now, from the main menu, press the sequence

The debugger displays the message Winbutton Change 14:24:43.514 [07 06 04 00 00 05] just as expected.

Prepare a Table with Messages

A good idea is to prepare a table with the different messages:

Form	Button	Caption	Event	Message
Form 1	WinButton1	Menu 1	onChanged	07 06 01 00 00 00
Form 2	WinButton3	Menu 2.1	onChanged	07 06 03 00 00 02
Form 2	WinButton4	Menu 2.2	onChanged	07 06 04 00 00 05

This table is very useful for interpreting the messages sent by the screen.

Note that the other buttons doesn't need to send messages, as they manage the user interface and display another form. Only the terminal options need to send messages.

Summary

Button

Standard	ViSi-Genie	Comment
		Simple WinButton

Checkbox

Standard	ViSi-Genie	Comment
		Momentary set to No StatusWhenOff and StatusWhenOn defined
		Momentary set to No StatusWhenOff and StatusWhenOn defined

Radio Button

Standard	ViSi-Genie	Comment
		Matrix with number Momentary set to No StatusWhenOff and StatusWhenOn defined

Menu

Standard	ViSi-Genie	Comment
		One Form per menu One WinButton per option, buttons grouped per sub-menu Message for terminal options Back button recommended