Skip to content
Copyright © 2024 4D Systems

ViSi-Genie Magic: Keyboard Edit

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

Description

This application note primarily shows how to create a simple keyboard editor using magic Keyboard + ColorPicker Event Magic, and Magic Codes.

Note

Workshop4 Pro is needed for this application.

Downloadable Resources

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

Project File

Prerequisites

Application Overview

In the past, creating a ViSi-Genie application that could print the characters pressed on a keyboard widget to a Strings widget was impossible without the aid of an external host controller, like an Arduino board. With the addition of Magic features to ViSi Genie, this becomes possible specifically using the Keyboard + ColorPicker Magic Event.

application-overview

The application in this document will prompt the user to input a password. If the password is correct, it will proceed to a different form. If the input password is incorrect, it will print 'Fail' on the display.

Setup Procedure

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

setup-procedure

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:

The project file used in this project is available in Downloadable Resources section.

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

Design the Project

For this application note, we will be using a gen4-uLCD-24PT. You can also use other 4D Systems display modules with DIABLO-16, PICASO, and PIXXI processors.

Add a Static Text Widget to Form0

To add a Static Text:

  1. Go to Home menu.
  2. Navigate to Labels pane.
  3. Select Static Text from the available widgets.

add-static-text

Then, click on the screen to place the StaticText widget.

place-static-text

Set the Static Text properties from the Object Inspector as shown.

static-text-properties

On the Caption property put the text.

A simple keyboard editor.\nWhen 'enter' is pressed the string entered is compared to a password.\nThe password is 1234

The updated graphical interface for Form0 will now show.

form0-static-tetxt

To know more about Static Text, its properties and how they are added to a project, refer to the application note ViSi-Genie: Labels, Texts, and Strings

Add a Keyboard Widget to Form0

To add the keyboard widget:

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

add-kb

Click on the screen to place the keyboard widget.

place-kb-widget

To change a keyboard type:

  1. Go to Object Inspector and make sure that you selected the Keyboard0 widget.
  2. Select Property tab.
  3. Go to KeyboardType property and click the value ktQWERTY and a 3 dot button will appear.
  4. Click the 3 dot button.

select-kb-type

A Keyboard Editor window will appear. On the Keyboard Type select the Cellphone type.

select-kb-types

Then we customized the keys by changing the * (asterisk) key to Enter key and change its Key Value to 13.

change-*-key

Then change Key colors.

Go to Color column and click on the current color. A color picker window will appear, set the RGB color values to (150, 235, 170) and click OK.

change-keys-color

You will notice that the Back key didn't change because it has a different color. Click on the color column of the Back key.

A color picker window will appear again, set the RGB color values to (79, 222, 112) and click OK.

change-back-color

The updated customized cellphone will now look as shown.

updated-cp-type

Click the OK button to apply the changes and exit the keyboard editor window.

We will now set the Keyboard properties as shown.

kb-properties

The final user interface of Form0 will now show the StaticText and Keyboard widgets.

updated-form0-ui

To know more about customizing a Keyboard widget, refer to the application note ViSi-Genie Customised Keyboard

Add a New Form

We will need to add a new Form as a landing page once the password entered is correct.

To add a new form:

  1. Go to Home menu.
  2. Navigate to System/Media pane.
  3. Click the Form.

add-new-form

It will automatically turn the display screen to a new blank form.

Add a StaticText Widget to Form1

Add another StaticText widget to Form1 and set the properties as shown.

form1-static-text

Add a Fancy Button Widget

To add a Fancy button to Form1:

  1. Go to Home menu.
  2. Navigate to Button pane.
  3. Select Fancy Button widget.

add-fancy-btn

Click on the screen to place the widget.

place-fancy-btn

Set the properties for the Fancy Button as shown.

fancy-btn-properties

The final user interface for Form1 will now show Static Text and the Fancy Button.

final-form1-ui

Add Magic Code

Magic Code can be use to add 4DGL code to the specific code positions such as:

  • Constant/Global/Data Definitions
  • Mainloop
  • Pre/Post Activate Form
  • Pre/Post Genie Initialization

To add a Magic Code follow the steps below.

  1. Go to Home menu.
  2. Navigate to Magic pane.
  3. Click Magic Code.

add-magic-code

The Magic Code will automatically added on Form0.

Note

All magic code/events are only added in Form0.

Magic Code 0

Once the magic code is added, go to object inspector and set the properties as shown below.

mo0-properties

To open the MagicCode0, go to Code property and click the MagicCode0.inc to show a 3 dot button. Click the 3 dot button to open the code editor.

open-mc0

Once the code editor is opened, type the code below: 

#constant maxresp 4             // maximum input length of string/password
#constant lft     10            // start position for echo of *s
//
var respchp, chars ;
var Response[3] ;               // enough space for 5 characters plus #0 at end

func resetchars()               // Timer routine used to blank 'Failed' from screen
    txt_MoveCursor(6,lft);
    print("     ") ;
    txt_MoveCursor(6,lft);
endfunc

The 4DGL code above is the declarations of constants, varables and a routine function. The maxresp constant is the maximum number of input for the password. The lft constant is the start column position to write the string. The resetchars() function is a timer routine used to blank Fail text from the screen.

Magic Code 1

To add another magic code, refer back to Add Magic Code. The new magic code can be selected from object inspector from Form0.

  1. Click on the Object dropdown.
  2. Select MagicCode1.

select-mc1

Set the properties for MagicCode1 as shown.

mc1-properties

Open MagicCode1.inc.

open-mc1

Once the code editor for MagicCode1 is opened, type the following code:

if (CurrentForm == 0)
    respchp := str_Ptr(Response) ;      // set keyboard response to start
    chars := 0 ;                        // show we don't have any chars type yet
endif

The MagicCode1 insertion point is set to PostActivateForm where it gets the value of the current Form. The if statement will check if the CurrentForm == 0 and reset the string pointer of the buffer (Response) to start and set the variable chars to 0.

Add a Keyboard + ColorPicker Magic Event

This Magic Event receives the value inputted on the keyboard widget. The value is stored in var value. If multiple keyboard widgets exist in a project, then their OnChanged event should be set to the 'Keyboard + ColorPicker Event Magic' that will handle the input value.

To add a Keyboard + ColorPicker event, click Keyboard + ColorPicker Magic Event from Magic pane.

add-kbcp

Set the Keyboard + ColorPicker properties and open the code editor by clicking the 3 dot button.

set-kbcp-properties

Once the code editor is opened, type the code below:

func rMagicKbClrEvent0(var reportID, var objType, var objHash, var value)
    var i ;
    if (value == 8) // 'back'
        if (chars)
            respchp-- ;
            chars-- ;
            txt_MoveCursor(6,lft+chars);
            putch(' ') ;
            txt_MoveCursor(6,lft+chars);
        endif
    else if (value == 13) // 'enter'
        str_PutByte(respchp++, 0) ;
        i := str_Ptr(Response) ;
        txt_MoveCursor(6,lft);
        if (str_Match(&i, "1234"))
    //            print("Match") ;
            ActivateForm(1) ;
        else
            txt_FGcolour(RED);             // 0  text foreground colour
            print("Fail") ;
            txt_FGcolour(LIME);             // 0  text foreground colour
            sys_SetTimerEvent(TIMER0, resetchars);
            sys_SetTimer(TIMER0,500) ;
        endif
        respchp := str_Ptr(Response) ;
        chars := 0 ;
    else if (chars < maxresp)
        str_PutByte(respchp++, value) ;
        txt_MoveCursor(6,lft+chars);
        chars++ ;
    //    putch(value) ;
        putch('*') ;
    endif
endfunc

The 4DGL code above will check and analyze the value of the key pressed from the Keyboard widget.

The function rMagicKbClrEvent0() has 4 parameters:

  • reportID which is always a REPORT_EVENT
  • objType is the object type, either tKeyboard or tColorPicker, in this case since we are working with keyboards, it should be tKeyboard
  • objHash object number/index which identifies from which keyboard/color picker the event came from, and;
  • value which is the key value pressed that we will evaluate

If the value is 8, which is a Back key, it will check the variable chars. If chars is true (non-zero), it will decrement the variable chars and respchp by 1, then print a space (' ') on the screen after moving the text cursor to the deleted character.

If the value == '*' or decimal value 42 (0x2A) which is an Enter key, it will use string functions str_PutByte() and str_Ptr(). The str_Match() function will check if the imput character that is save on string buffer is match with the code 1234. If it is true, then it will activate the Form1 with the function ActivateForm(1);. Otherwise, it will show a text Fail on the screen for 500 milliseconds and blank it using the function resetchars.

If the value is from the number keys 0 to 9, it will append key to the string buffer. This increases the cursor's column and then prints asterisk *. If you want to print the value for testing, then uncomment putch(value) then comment out putch('*').

To know more 4DGL programming, please refer to the Manuals below.

Adding Event to the Keyboard Widget

As mentioned in the previous section, the keyboard widget's OnChanged event should be set to trigger the rMagicKbClrEvent0.

To do this, follow the steps below:

  1. Go to Object Inspector. Change Form to Form0 and select Keyboard0 widget.
  2. Select the Event tab.
  3. Click the 3 dots button from OnChanged event to open the On event selection window.
  4. Select the MagicKbClrEvent0(Keyboard Key Press) under Form0.
  5. Click the OK button.

magickb-event

Adding Event to the Fancy Button

To go back to form0 or input password form once the Lock button is touched. We will add an event to the Fancy button object.

  1. Go to Object Inspector. Change Form to Form1 and select the Object Winbutton0.
  2. Select the Event tab.
  3. Click the 3 dots button from OnChanged event to open the On event selection window.
  4. Under Form0 select Form0Activate.
  5. Click the OK button.

fancy-btn-event

After adding an event to the button widget, it is now ready for build and upload to the target display.

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