Application Development Kit (Version 4.7)

This document is for programmers and developers who want to understand and use the ADK-GUI framework.

Audience

This guide provides information on the usage of the ADK-GUI system based on FLTK. With version 2.x, the support of the ADK-GUI variant running in a Web browser has been dropped since only the FLTK based variant was deployed in the field due to limited terminal resources.

Version 2.x focuses on issues that could not be fixed while preserving 100% compatibility with version 1.x. Minor changes are introduced that requires code changes when switching from version 1.x to 2.x. See Migrating from Version 1.x to 2.x for a detailed description of these changes.

Organization

Chapter 1, Introduction: Provides a general introduction to ADK-GUI

Chapter 2, Getting Started: Presents an introduction in ADK-GUI usage.

Chapter 3, Programming: Supplies ADK-GUI programming information.

Chapter 4, System Setup and Requirements: Presents environment setup and dependencies.

Chapter 5, Troubleshooting: Gives solutions for possible issues in ADK-GUI.

Annex A, Migrating from version 1.x to 2.x: Provides instructions for migrating from version 1.x to 2.x of ADKGUI

Introduction

ADK-GUI allows applications to define HTML based user dialogs and screen contents. This includes standard HTML support for static text, fonts, tables, images, input elements for numeric, textual, menus, buttons, etc. Specific support for PIN input is provided.

The application programming interface allows generic invocation of such pre-defined HTML documents with exchange of the relevant dialog parameters between the application logic and the GUI system supporting variable data definitions in the HTML documents.

In addition, specific APIs are provided for typical use cases such as menus, confirmations, and data inputs. These specific functions rely on HTML templates that get filled-in during runtime.

ADK-GUI implements a subset of HTML and CSS to be able to provide a fast and efficient solution with a small footprint.

ADK-GUI uses UTF-8 encoding to support international characters. However, to make full use of unicode the installed fonts need to support the characters in use. Providing an appropriate font is in the scope of the respective application.

Concepts

Platform Independent Application

HTML dialogs are separated from the application and stored in platform specific subdirectories. By this the application itself becomes platform independent. The platform dependent layout of dialogs is moved to HTML files. Therefore, the same application binary may be used on different platforms while only the HTML dialog files are different. Since also the input and keyboard handling is handled by HTML dialogs the whole bandwidth of devices can be covered, from small B/W displays with function keys up to large true color displays with touch screen.

Screen Layout

Most terminals display different types of information on screen, which are updated independently.

Example:

The above example shows a status bar that displays the date and time (along with other information) that is updated separately.

This concept is covered by UI regions. Each region has a unique ID used for displaying a dialog in a specific area on the screen. Region 0 is the default region and is usually assigned to the main part of the screen (i.e. the main application dialog).

Keyboard Navigation

Actions may be bound to function keys by using invisible buttons. For devices without touch screen capabilities, this is the only way of operating the device. Two different concepts are supported:

• Each key has a dedicated function, just like a button on a Web page. This is useful when there is an association that links a function key to a function displayed on screen (e.g. if there is a button on screen close to a function key).
  
  Example: VX520 functions keys
• Cursor like navigation uses some function keys to move an active element on screen like using a joystick. Another button is used to trigger an action on the active element.
  
  Example: V200c 4-directional navigation keys

The selection of the concepts depends on the device. For example VX520 with its function keys around the display might be suited better for the first type of navigation while V200c with its 4-directional navigation key is a candidate for the second approach.

Variable Data

Most dialogs contain some dynamic data that needs to be controlled by the application. For this purpose, XML processing instructions are used to insert data provided by the application into dialogs. The following use cases are supported:

• Insert some text provided by the application
• Insert text found in a catalog (translation) file
• Insert barcode images

Multi-Language Support

There are two ways to display dialogs in multiple languages:

• Using catalog files to provide texts in different languages
• Switching between different sets of dialogs

Printer support

Printer support is covered in ADK-PRT. However, since ADK-PRT and ADK-GUI share quite some code, a combined server has been developed to reduce resource consumption, that provides both GUI and Printer support. However, for the user this combined server behaves just like two separate servers so that no special handling is required for using the combined server.

Getting Started

The GUI system comes with a sample application that demonstrates system features and provides a starting point for application developers who use the GUI system. It can be found in the example folder of the documentation package. The file README.txt in this folder gives exact instructions for compiling the example.

The GUI system is provided on different target platforms. The following sections describe how to use the GUI sample application on these platforms. In addition, this chapter gives general information about required components to run ADK GUI (runtime libraries, installing fonts).

Running ADK-GUI on V/OS

On V/OS the following optional OS download packages need to be installed for using ADK-GUI:

• FLTK
• libpng

In addion it may be required to install font packages containing true type fonts to be used.

ADK-GUI uses ADK-IPC for setting up TCP connections and pipes. For this the application needs to be linked with libvfiipc in addition to the ADKGUI libraries.

Using static libraries:

<library path>/libvfiipc.a 

Using shared libraries:

-L<library path> -lvfiipc 

<library path> is the path, where libvfiipc is located.

When shared libraries are used, the corresponding ADK-GUI and ADK-IPC packages need to be installed on the terminal.

• dl.libvfiguiprt-X.X.X-X.tar
• dl.libvfiipc-X.X.X-X.tar

Please always use the newest version of libvfiipc, which comes along with ADK components packages.

Packaging Resource Files on V/OS

For ADK-GUI using guiserver, resource files have to be accessed from processes running as a different (system) user. This has to be considered when packaging resource files so that access rights for these files are set up appropriately.

The recommended way is to have a separate package for the resource files (i.e. directory "www") and set group "system" when creating it.

See also the documentation of Package Manager or Packman Tool depending on the V/OS release.

Installing Fonts on V/OS

Providing fonts for the GUI system on V/OS requires the installation of a user font package containing font files in true type format (TTF). Detailed information on how to create user font packages can be found in the document V/OS Secure Installer ERS. An example user font package comes with the demo application in the documentation distribution package.

Earlier versions of Secure Installer required the file fonts.dir to be present. This is no longer required. It is generated automatically during installation.

Please note that the font name is not the same as the font file name. For use in HTML you need to use the font family name, not the file name. Also note that bold, italics, etc. are not part of the font family name but are controlled via the CSS font-weight and font-style properties.

Running on Microsoft Windows

Following is required:

• Visual Studio 2008
• FLTK 1.3.x library for Windows
• Boost library

A Visual Studio 2008 solution file is provided to compile the demo application.

Resource Folder

The demo application comes with a resource folder that contains several sample templates, dialogs and images for different platforms.

Programming

ADK-GUI Deployment Options

While ADK-GUI system provides a single header file (html/gui.h) that exports the GUI system API function calls, different client side libraries are provided to link with applications. These libraries provide the same interface but offer different deployment options (creating a monolithic executable or running the application with a separate GUI server).

Headers and binary deliveries

The ADK-GUI system is composed of the following deliveries:

All header files can be found in the 'html' directory.

An application has to be linked either with libvfiguiprt or with libfltkgui (see deployment options below).

Parameter Overloading

ADK-GUI uses C++ overloading to provide different variants of a function so that parameters can be omitted that have a default value. Unlike C++ default parameters these need not be found at the end of the parameter list. The following parameters are affected:

• display - if not provided, output goes to the display 0
• region - if not provided, output goes to region UI_DEFAULT_REGION (=0). Omitting the region is only possible if the default display is used
• key value map - an empty key value map is used if left out

Running ADK-GUI with GUI server

On V/OS the GUI service runs as a separate process with privileged rights to access HTML and graphical resource files accompanied with the applications. Different applications typically run in separate user spaces.

Using this deployment option more than one application can be run at the same time as long as they synchronize their access to the server and/or use different GUI regions. Synchronization between applications is not part of the GUI system and has to be provided separately. One solution for this is MAC, which is provided by ADK-SYS.

Applications link with the GUI client library to access the GUI API functions. They can either pass a URL to the UI resource files or send HTML documents directly. They also pass dynamic data over the inter-process interface into the GUI service. The GUI server then returns the result from the executed dialogs.

UI resources are assumed to be authentic (i.e. there is no additional authentication of UI resources within the GUI service). If required, the application provides the additional authentication for external resources.

For this setup applications need to link with libvfigui library of the GUI system.

The GUI server and client library use the environment variable GUI_DISPLAY to control the port used for communication between the two entities. Both, named pipes and TCP may be used for communication. For this GUI_DISPLAY either contains the absolute path name of the named pipe or the entry '<hostname>:<port-offset>'. The base for the <port-offset> is 5900. On V/OS, the overall default is ":\b 0" (TCP on localhost port 5900).

Meaning of field <hostname> for TCP connections:

For GUI server this field is ignored. For V/OS non-development devices, this port only accepts connections from localhost (<hostname> is always "127.0.0.1") for security reasons. V/OS development devices have external access enabled (<hostname> is always "0.0.0.0").

For GUI client library field <hostname> is not restricted and specifies the IP address or hostname of the GUI server, which library should connect to. An empty field <hostname> means connection is established to localhost (default on V/OS).

Examples:

GUI_DISPLAY=:0   (default)GUI_DISPLAY=:1   (access via port 5901)GUI_DISPLAY=/tmp/guipipe   (access via named pipe /tmp/guipipe)

Instead of GUIserver, the combined GUI and printing server guiprtserver may be used. It is the result of merging guiserver with the HTML printer server and supports the same set of GUI functions as guiserver but uses less resources than running guiserver and prtserver as separate binaries.

Setting up keepalives

TCP keepalive probes can speed up the detection of broken TCP links. For enabling keepalives invoke uiSetKeepalive() as first command before invoking other ADKGUI functions.

Running ADK-GUI as GUI Library

The GUI service can also be used as static library to be linked with an application process. In this setup the application links directly with the libfltkgui library of the GUI system. The result is a monolithic application that as everything in one executable.

Please note that monolithic applications needs to link additional static libraries to resolve symbols of library libfltkgui.a. These libraries come along with following distribution packages:

• V/OS: guiprt-contriblibs-vos-dev-X.X.X-X.zip
• V/OS2: guiprt-contriblibs-vos2-dev-X.X.X-X.zip

UI Resources

User interface resources are describing the content, layout and behavior of user dialogs.

The following items are supported:

• HTML documents (files) describing the content and layout of a single dialog
• HTML template file(s) describing the layout of standard dialogs. Dynamic data is entered prior representation.
• Image resource files
• CSS style sheet files
• Catalog files for Multi-language support

Resources accompany the application packages (i.e. they reside in the same user space as the related application).

Resource files are looked up in the resource directory. A search path for base resource directories can be provided in the environment variable GUIPRT_WWW_PATH. It may contain several directories separated by ':'. To refer to the current working directory, "$CWD" may be used and to refer to the directory, where the executable resides "$ORIGIN" can be used (on Linux only). These need to be found at the beginning of a path component, e.g. "$CWD/www". The first existing directory in this path is chosen for the base resource directory. If GUIPRT_APPNAME is set (see also Multi-Application-Controller Resource Subfolder Support), it also needs to contain the application subfolder to be chosen.

If not set the default is "$CWD/www", i.e. the www directory in the current working directory.

On x86 Linux the default is "$ORIGIN/../share/www:$ORIGIN/../www:$CWD/www".

By default, UI resource files are looked up in the "<platform>" subdirectory of this base resource directory. The platform is automatically determined by use of an OS function (e.g. for P400 this is "P400").

If this directory does not exist, UI resources are looked up in a directory whose name is constructed based on the type of display and keyboard. Its name is constructed as follows:

<width>x<height><color><numkeys><touch>

<width> and <height> are the width and height of the display in pixels. <color> is either 'M' for monochrome displays or 'C' for color displays. <numkeys> is the number of keys on the keypad. In case it cannot be determined '0' is used. <touch> is either 'T' if a touch display is present or 'N' if not.

Examples:

P400: 320x480C15T

UX100: 128x64M16N

The advantage of using this scheme is that several different terminals may share the same set of dialogs. For example, VX520C and VX675 have the same display and keyboard layout and therefore, will look up files in the same folder.

On V/OS the resource files and the application are usually located in home folder of the user. For instance, if an application is installed on P400 under /home/usr1 the default resource directory is:

/home/usr1/www/P400or/home/usr1/www/320x480C15T

Due to compatibility reasons, "www/<platform>" is prior to new notation "www/<width>x<height><color><numkeys><touch>".

The default location can be changed by using the UI_PROP_RESOURCE_PATH property of uiSetPropertyString().

An optional prefix may also be set using the UI_PROP_FILE_PREFIX property of uiSetPropertyString(). This prefix is prepended to the file names provided for URLs and template names. If it contains one or more '/', then it will add new directory levels to the path. Otherwise, it only modifies the file name.

With prefix, the resulting file name is: "www/<platform>/<prefix><filename"

Since version 1.3.0, the UI system supports a default directory "www/default" for resource files. These can be considered as fallback in case a dialog is not found in the regular resource directory (e.g. because www/<platform> does not exist). Standard resource folder "www/\<platform>" and default resource folder "www/default" can also be used in parallel and files that are not found in the platform specific folder are secondly looked up the default resource folder. For instance, this is useful for multi-language catalog files that should be used for all platforms, whereas HTML files are still located in standard folder.

The following files types are supported by default resource folder:

• HTML documents (files)
• HTML template file(s)
• GUI system configuration file gui.ini
• CSS style sheet files
• Multi-language catalog files

Please note that image resource files location must be relative to the corresponding HTML document or template file. CSS style sheet files are not supported, since its location is specified in GUI system configuration file.

The default location of the default resource directory can be changed by using the UI_PROP_RESOURCE_DEFAULT_PATH property of uiSetPropertyString().

If the specified resource files cannot be found, the GUI system will automatically generate an error message on the screen. This is helpful during application development and testing and should not show up in a live system if resource files are provided correctly.

Example:

mainmenu.tmpl not found in /home/usr1/www/320x480C15T

Multi-Application-Controller Resource Subfolder Support

Multi-Application-Controller (MAC) is used to run several applications in parallel on a terminal. Since version 2.5.0 the UI system has added support to lookup resources in a separate subdirectory for each application to avoid resource location conflicts. For this, MAC can be configured to set up the environment variable GUIPRT_APPNAME, which provides a name for each application that is used for the subfolder appname:

www/<appname>/<platform>

or

www/<appname>/\<width>x\<height>\<color>\<numkeys>\<touch>

GUIPRT_APPNAME is automatically considered during startup of an application so that most of the MAC handling is transparent to the application. Please note that the variable is just used to set up the default values for UI_PROP_RESOURCE_PATH and UI_PROP_RESOURCE_DEFAULT_PATH. Once an application has set the properties during runtime, value of GUIPRT_APPNAME is ignored.

An application can also set GUIPRT_APPNAME by itself to move the default resource folder. For this the environment variable has to be set using setenv() before calling any ADKGUI function.

GUI System Configuration File

The GUI system has a gui.ini file stored in the resource folder (--> www/<platform>/gui.ini) that provides global configuration and startup parameter for the system. This file has Windows INI-file format with sections and parameter value pairs.

The gui.ini file is automatically read on startup of the program. In case the application has modified gui.ini or changed UI_PROP_RESOURCE_PATH it has to call uiReadConfig() to re-read the file.

Standard Font

The standard font and font size can be adjusted in the [font] section.

Example:

[font]name=dejavu sanssize=10

Decimal and Thousands Separator

The decimal and thousands separator can be adjusted in the [input] section.

Example:

[input]decimal_separator=.thousands_separator=%20

Leading and trailing whitespace in this configuration is stripped, but URL encoding can be used to insert whitespace, e.g. to set the thousands separator to a single space use %20. Note that UTF-8 encoding is used, e.g. for the multipy symbol '×' the sequence %C3%97 would be used.

Alphanumeric Keyboard Definition

The GUI system supports alphanumeric inputs through pressing hard keys multiple times. Each key can be assigned with a number of characters that are selected in given order when pressing the key multiple times during alphanumeric inputs.

The definition of this alphanumeric keyboard is provided in the section [keymap] of the gui.ini file.

Example:

[keymap]1=12=abc2ABC3=def3DEF4=ghi4GHI5=jkl5JKL6=mno6MNO7=pqrs7PQRS8=tuv8TUV9=wxyz9WXYZ0=%200

To use '*' and '#' for character input, add the following rules:

 =*#=#

Without these rules the keys only act as a function key.

Please note that the allowed_chars attribute for input fields operates as filter on the keymap.

Model specific keymaps can be provided as [keymap-standard], [keymap-europe], [keymap-arabic] and [keymap-rnib]. If found they are preferred over the default [keymap].

Standard Display Regions

To configure multiple display regions without using uiLayout(), the display regions in the [layout] section of the GUI configuration file can be specified. For more information, see Display Regions.

Syntax:

[layout-name]<reg_id>=<left> <top> <right> <bottom> [<flags>]...

Section [layout] consists of one or more lines each standing for one display region. Region ID <reg_id> is used as key and value consists of following parameters to be separated by whitespaces:

<left> left position in pixels (+=width if negative)

<top> top position in pixels (+=height if negative)

<right> right position in pixels (+=width if negative)

<bottom> bottom position in pixels (+=height if negative)

<flags> optional region flags, numeric value as found in gui.h

Regions in gui.ini are activated by passing their name to uiLayout().

Example specifying two regions, region with ID 1 has a fixed height of 20 pixels:

[layout]1=0 0 -1 200=0 21 -1 -1

CSS File

ADK-GUI allows specifying a CSS file in gui.ini as follows:

[stylesheet]css=<filename>

The color of the scroll overlay can be set using:

[scroll]color=<RGBA>display=<time>

<RGBA> is the 8-character hex color value including alpha channel. The default is 00000060 which corresponds to a semi transparent black overlay. <time> is the time in milliseconds for which the scroll overlay is displayed after the last change of the scroll position. Setting it to 0 disables the scroll overlay. Setting it to a negative value the overlays are displayed permanently. The default is 1000.

The alpha channel is ignored on B/W devices.

HTML Support in ADK-GUI

Standard HTML elements are used to define the layout of dialogs.

The HTML support in ADK-GUI is limited. All unknown HTML tags are ignored and text without HTML formatting is displayed.

The following HTML tags are supported with ADK-GUI:

<b> - Bold text

<bdi> - Bi-Directional isolation

<bdo> - Bi-Directional override

<body> - Body of the HTML document

<br> - Single line break

<button> - Button

<center> - Center text block

<div> - Section in a document

<em> - Emphasized text

<font> - Font

<h1> ... <h6> - HTML headings

<hr> - Horizontal line

<i> - Italic text

<img> - Image

<input> - Input Field

<li> List item (inside <ul> or <ol>)

<ol> - Ordered list

<option> - Option in a selection list

<p> - Paragraph

<pre> - Preformatted text

<select> - Selection List

<source>

<span> - Section in a document

<strong> - Bold text

<table> - Table

<th> - Table header cell in a table

<td> - Cell in a table

<tr> - Row in a table

<u> - Underline text

<ul> - Unordered list

<video> - Video

<audio> - Audio

Color Names Support:

The following color names are supported: aqua, cyan, black, blue, fuchsia, magenta, gray, green, lime, maroon, navy, olive, orange, purple, red, silver, teal, white, and yellow.

In addition, "transparent" is supported for creating transparent buttons.

Soft Hyphen Support:

Soft hyphens are used to specify a place in text where a hyphenated break is allowed without forcing a line break in an inconvenient place if the text is reflowed.

Use one of the following syntax to insert a soft hyphen.

­­

Bi-Directional Text Support

Bi-directional text is supported, including Arabic text. Note that the selected font needs to have support for the character set used.

Video Support

Depending on platform, the terminal must have installed additional components to meet the applicable prerequisites for video playback.

V/OS and V/OS2 terminals use mplayer which provides hardware accelerated video playback if available. Video support is only available on those platforms that contain mplayer.

ADKGUI on V/OS3 has internal support for video playback.

Compared to ordinary web browsers, video playback with ADK-GUI has some limitations:

• On V/OS and V/OS2 the HTML rendering engine has no access to properties of the video. It cannot determine width and height of the video. The width and height must be specified using the corresponding attributes. This limitation is not present on V/OS3.
• On V/OS and V/OS2 the video output window must be completely within the display and cannot be moved once playback has started. Therefore, the page that contains the video must entirely fit within the screen so that no scrollbars show up.
• The HTML rendering engine cannot check for supported video formats. Therefore, when <source> is used to provide several media sources, it always chooses the first file for playback.
• The video file is accessed from another process. It must be stored in a directory where it can be accessed by the guiserver or mplayer.
• The video decoding hardware has some limits with respect to the position of the video playback window on screen. Therefore, the output window may be off by some pixels from the desired position.

HTML video example for playing video in a loop:

<video width="582" height="388" style=";margin-left:auto;margin-right:auto" autoplay loop><source src="file:///mnt/usbstor1/video.avi">Video not supported or video not found.<br>On Mx9 plug in USB device containing video named "video.avi".</video>

Please note that the source path is platform dependent. The specified path for accessing the video file on USB device (see example) only works on V/OS.

HTML Video Widget Functions for Video Control

Some widget functions for video playback control are provided that can be called from an action statement of an event. These functions are executed in the context of the currently active HTML document and refer to the name specified for the video element:

<video width="240" height="206" style=";margin-left:auto;margin-right:auto" name="vid">...</video><button accesskey='&#13;' style='width:100%' action='call vid.play()'>  &#9654;</button>

Please refer to chapter HTML Widget Functions which lists the supported video control functions.

Performing an Action When the Video has Stopped

The following input field detects the end of the video playback:

Example:

<input type="videoend" style="display:none" action="return 42">

GUIPRT Demo and Video Support

Since the size of sample videos would blow up the GUIPRT documentation package, the video extension package (guiprt-doc-video-X.X.X-X.zip) is provided. The video package contains additional documentation and some video files with different resolutions for different displays. Please refer to the enclosed VIDEO-README.txt containing more details about required components to meet the applicable prerequisites for video playback. In addition, you can find helpful instructions for installation of sample video files for GUIPRT demo.

Supported video formats on V/OS2

libsvc_mplayer is reported to support the following formats on V/OS2:

• H.264 Video decoder requirements
• H.264 baseline profile up level 5
• Supports I&P picture decoding
• Supports CAVLC decoding
• Supports Progressive decoding
• Supports all Intra prediction sizes and modes
• Supports all Inter prediction unit sizes
• Container format must be avi

V/OS2 multimedia playback support

Backend

Video playback is ensured by MPlayer (current version being 1.4). Out-of-the box MPlayer supports many audio/video (A/V) encodings in various video container formats but there are some restrictions that are in place for the customized MPlayer version used by V/OS2. Since target devices are of limited space, support for much of the A/V encodings, but for the most commonly used, has been stripped. Additionally, due to relatively slow CPU and no hardware acceleration support for A/V decoding, there is a proprietary 3rd party decoder in use by MPlayer which speeds up the decoding, but applies even tighter restrictions on supported A/V encodings.

Supported formats

Audio Support

Depending on platform, the terminal must have installed additional components to meet the applicable prerequisites for audio playback.

V/OS terminals use the service libsvc_sound which provides sound playback. Audio support is only available on those platforms that contain this service. This service also determines the supported audio formats: Currently it supports wav and mp3.

Audio playback is bound to the dialog, i.e. the sound will only play as long as the dialog is active.

Compared to ordinary web browsers, audio playback with ADK-GUI has some limitations:

• The HTML rendering engine has no access to properties of the sound file.
• The HTML rendering engine cannot check for supported audio formats. Therefore, when <source> is used to provide several media sources, it always chooses the first file for playback.
• On V/OS and Rapter devices, the sound file is accessed from another process. It must be stored in a directory where the sound playback service has access rights.

HTML audio example for playing a sound in a loop:

<audio autoplay loop><source src="file:///mnt/usbstor1/sound.mp3">Sound not supported or sound file not found.<br>On Mx9 plug in USB device containing a sound file named "sound.mp3".</audio>

Please note that the source path is platform dependent. The specified path for accessing the sound file file on USB device (see example) only works on V/OS.

HTML Audio Widget Functions for Audio Control

Some widget functions for sound playback control are provided that can be called from an action statement of an event. These functions are executed in the context of the currently active HTML document and refer to the name specified for the audio element:

<audio name="snd">...</audio><button accesskey='&#13;' style='width:100%' action='call snd.play()'>  &#9654;</button>

Please refer to chapter HTML Widget Functions which lists the supported audio control functions.

Performing an Action When the Sound has Stopped

The following input field detects the end of the video playback:

Example:

<input type="audioend" style="display:none" action="return 42">

CSS support in ADK-GUI

Cascading Style Sheets (CSS) are used to change appearance of HTML elements. For ADK-GUI implementation, a limited set of CSS elements is supported.

CSS attributes can be specified directly in the HTML documents by using the inline style attribute for HTML elements. The inline style attributes overwrite styles taken from the CSS file. GUI.INI may be used for specifying a global CSS file.

The CSS functions calc(), min() and max() are supported to calculate length values. calc() expressions are limited to 8 values in the calculation. Note that the operators '+' and '-' need to be surrounded by space as per CSS standard. If an invalid expression is provided or more than 8 values are used, the expression is ignored.

CSS Combinators Support and CSS Limitations

ADK-GUI supports descendant selector and child selector, sibling selectors are not supported. The following elements cannot be used as ancestor in a descendant or child selector rule:

• b
• em
• font
• i
• span
• strong
• u

That is the following rule is not supported

span div {}

Whereas the following rule is supported

div span {}

Currently the following limitations exist in ADK-GUI when using CSS:

• Length values only support the units '%' and 'px'.
• For specifying colors rgba(), hsl() and hsla() are not supported
• linear-gradient is restricted to the following directions:
  • to top / 0deg
  • to right / 90deg
  • to bottom / 180deg
  • to left / 270deg
• Providing several font names that are looked up in that order for attribute font-face is not supported.
• border-style only supports "none" and "solid".
• border-image does not support using GIF images or PBM images.

Global CSS file: All supported CSS properties may be used in the global CSS file and work the same way as when using the style attribute. For CSS selectors the following restrictions apply:

• CSS pseudo elements are not supported
• The following CSS pseudo classes are supported:
  • :focus - element that has input focus
  • :active - button while it is pressed
  • :disabled - disabled button

CSS pseudo class selectors have additional restrictions: Only setting colors (e.g. background color) and background-images considers pseudo classes. In particular, it is not possible to change the size of an object using pseudo classes. Other properties are ignored.

CSS Animation support

ADKGUI supports CSS animations. The following CSS properties can be animated:

• background-color
• border-bottom-color
• border-bottom-width
• border-left-color
• border-left-width
• border-right-color
• border-right-width
• border-top-color
• border-top-width
• bottom
• color
• font-size
• height
• left
• line-height
• margin-left
• margin-top
• margin-right
• margin-bottom
• opacity
• padding-left
• padding-top
• padding-right
• padding-bottom
• right
• top
• width

Event Handling

The GUI system supports a limited set of events that can be processed independently of the application business logic. This event mechanism can be used to keep GUI logic largely independent from the application business logic.

The actions taken on behalf of the dialog event are specified in the HTML with the following syntax:

Chaining

"call" functions may be chained in the action by separating them with ';'. If present, a non call action must be the last component in the action. Example: Disable a button after pressing it:

<button name="foo" action="call foo.disable(); return 42">OK</button>

There can be only one non-call function inside an action.

Custom Events

Custom events allow sending data to an application without terminating the dialog. Custom events depend on using a callback function in combination with an async function (e.g. ::uiInvokeURLAsync). When a custom event is sent, the callback is invoked with ::UI_CB_EVENT. The event code can be accessed using UICBData::result(). If additional values are send, these can be accessed via UICBData::value().

Typeahead Support

Normally key strokes are processed as they happen. However, when switching dialogs this may result in key strokes to be dropped:

The previous dialog has been finished and the next dialog is not yet ready to be shown and to process input.

Now if the user types some key, then there is no use for it and it gets dropped. In certain situation this is not desired, e.g. if the user blindly operates the device and does not wait for visual feedback.



For this use case 'returnwait' and 'loadwait' have been introduced. They differ from 'return' and 'load' in that they suspend GUI and event processing until the next dialog is shown in the same region or until the layout is updated. This enables to atomically replace one dialog with another one so that keyboard input does not vanish in between two dialogs.



Since GUI and event processing is stopped, if the application fails to display the next dialog the GUI is frozen. For this reason, 'returnwait' and 'loadwait' should be used with care.

Long Button Press

Buttons support distinguishing long and short button presses on the touch screen. A button press is considered long if the button is pressed for at least 750ms and no attempt to pan is detected. In this case the action found in the attribute "action2" is performed. If "action2" is not provided then the action found in "action" is performed as fallback.



Example:

<button action="return 1" action2="return 2">Test</button>

Multitouch detection in signature capture

Multitouch detection and triggering action2 supported in older releases is no longer supported. Instead pinch/zoom is disabled during signature capture so that signature capture can continue with the first touch contact even when touching the screen with additional fingers. Overall this should give a better user experience than in older releases.

Palm rejection can be deactivated by setting the attribute palm-rejection="0". Setting it to "1" enables palm rejection, which is also the default.

HTML Widget Functions

Some HTML widget functions are provided that can be called from an action statement of an event. These functions are executed in the context of the currently active HTML document.

Keyboard Binding

The UI system supports binding of keys on the terminal keyboard to HTML button elements. The HTML accesskey attribute is used to define the key binding specifying the key code (e.g. '1' for key 1). For functional keys like F1-F4 accesskey is specified with "&#" followed by a decimal value with ";" (see platform dependent key binding table below).

Please note that the key bindings can be defined for visible and non-visible buttons. A typical use case for non-visible buttons is assigning keys on non-touch screen hardware.

Example:

<button action='call menu.up()' accesskey='&#133;'>SCROLL UP</button> <button action='call menu.up()' accesskey='&#133;' style='display:none'>SCROLL UP</button>

The following table provides an overview on access key values to be used for the available keys on different hardware.

VX675	key	access key value
	M0	'…'
M1	'†'
Middle	'‡'
Up	''
Left	'‚'
Right	'ƒ'
Down	'„'
M2	'ˆ'
M3	'‰'
0 - 9	'0' - '9'
* (-)	'Š'
# (+)	'‹'
	''
	''
	'
'

VX820	key	access key value
	0 - 9	'0' - '9'
*	'Š'
#	'‹'
	''
	''
	'
'

e285	key	access key value
	0 - 9	'0' - '9'
*	'Š'
#	'‹'
	''
	''
	'
'

Mx9xx	key	access key value
	0 - 9	'0' - '9'
	''
	''
	'
'

Ux100/Ux100	key	access key value
	0 - 9	'0' - '9'
DOWN ( )	'ˆ'
UP ( )	'†'
	''
	''
	'Œ'
	'
'

P200/V200c	key	access key value
	M0	'…'
F1	''
F2	'‚'
F3	'ƒ'
F4	'„'
M3	'‰'
0 - 9	'0' - '9'
F10	'Š'
F11	'‹'
	''
	''
	'
'

V200t/V205c	key	access key value
	M0	'…'
F1	''
F2	'‚'
F3	'ƒ'
F4	'„'
M3	'‰'
0 - 9	'0' - '9'
F10	'Š'
F11	'‹'
	''
	''
	'
'

P400/V400/P630 (V/OS3)	key	access key value
	0 - 9	'0' - '9'
F10	'Š'
F11	'‹'
	''
	''
	'
'

V240m	key	access key value
	0 - 9	'0' - '9'
*	'Š'
#	'‹'
	''
	''
	'
'
Camera button (only devices with camera)	'Ž'

V400m	key	access key value
	0 - 9	'0' - '9'
*	'Š'
#	'‹'
	''
	''
	'
'

e280	key	access key value
	POWER	''

Trigger action on key release

Function keys (not normal keys) may trigger an action on release. For this add 18 to the function key value, e.g.

<button action='return 0' accesskey='&#142;' style="display:none"></button>

triggers the action on pressing of the camera button and

<button action='return 0' accesskey='&#160;' style="display:none"></button>

triggers on release of the camera button.

Key Combinations

For <button> elements more than one key may be specified in "accesskey" to set up a key combination. The keys have to be separated by '+'. Key combinations only work for invisible buttons (display:none).

Example display status screen when pressing <Enter>+'1':

<button action='load statuspage.html' accesskey='&#13;+1' style="display:none"> </button>

Virtual Keyboard Support

Virtual keyboard support in ADK-GUI works as follows:

• A set of HTML pages must be set up as virtual keyboard. It consists of a set of buttons that use action "active.sendkey()" to generate key strokes. sendkey takes the decimal Unicode value of the character to be inserted as parameter. By providing more than one value it can be used to send sequences of key strokes.
• The buttons in the virtual keyboard must have the attribute set to "nofocus" so that the input focus is not changed when clicking the button.
• "Shift" or other means of switching to a different character set are implemented by loading a new virtual keyboard page using action "load".
• A separate region has to be defined for the virtual keyboard using uiLayout(). The coordinates of the region may be specified in gui.ini and referenced by name.
• In the application, the virtual keyboard is displayed using uiInvokeURLDetached() which runs the dialog in the background.
  
  Important: Make sure that timeout handling is disabled for the virtual keyboard, either by setting UI_PROP_TIMEOUT to -1 (the default value) or by adding an infinite timeout to the virtual keyboard dialog using <input type='timeout' value='-1'>. Failing to do so, the virtual keyboard will stop working after the timeout elapses.
• Control keys have been mapped to the following key codes:

Dynamic Keyboard Switching

ADKGUI sends the IPC notification "_uiInputFocus" when focus is given to or removed from an input field. This can be used to dynamically show a virtual keyboard whenever the user clicks into an input field and remove it when focus is withdrawn from the input field . The _uiInputFocus notification sends the following information:

Dialog Timeout Handling

A global dialog timeout property UI_PROP_TIMEOUT for all dialogs can be set using uiSetPropertyInt() call. It applies to any dialog invoked using the uiInvoke() and uiInvokeURL() or one of the other standard dialog client API functions. The API functions return with a UI_ERR_TIMEOUT value if the global timeout expires.

Each dialog definition may have one HTML element that specifies the timeout for the specific dialog and one HTML element that specifies the idle timeout. An associated action can be provided also. The HTML <input> element defines a hidden input field which specifies the timeout behavior of the dialog.

Setting the timeout using an HTML <input> element disables the global timeout set by UI_PROP_TIMEOUT.

Setting the timeout to a negative value disables the global default timeout (i.e. using an infinite timeout).

Example:

<html><body>1 sec timeout<input type="timeout" value="1" style="display:none" action="load timeout1.html"></body></html>

<html><body>500ms timeout<input type="timeout" value="500ms" style="display:none" action="load timeout2.html"></body></html>

Dynamic Data Placeholder in HTML Files

HTML resource files may contain placeholders for dynamic data elements. These placeholders are replaced before actual HTML rendering process takes place. The content is obtained from the key value map provided by the application (see section Passing Data to/from Dialogs).

The following syntax (XML processing instruction syntax) is supported at any place of the HTML file:

<div style="width:100%;height:100%;background-image:url('<?fadedscreen #00000080?>')">  <div style="position:absolute;width:80%;height:20%;top:30%;right:10%;background-color:#fff">    Popup Text    <center><button action="return 0">OK</button></center>  </div></div>

Unless <?varhtml name?> is used when inserting values, HTML special characters are escaped so that they will be displayed on screen (e.g. '<' will be substituted by '&lt;'). The application may not break the HTML structure but will also not be able to insert HTML tags via this mechanism. To dynamically insert HTML tags, <?varhtml name?> must be used instead.

Example:

<p>IP-address: <?var ipaddr?></p> <?foreach tabledata                 |(table border=1)(tr)(th)JSON(/th)(th)Name(/th)(th)Value(/th)(/tr)                 |(tr)(td)[](/td)(td)[name](/td)(td)[value](/td)(/tr)                 |(/table)                 |Empty table(br)                 ?>

Barcode Display Support

(For scanning barcodes see Barcode)

The GUI system supports rendering barcodes and displaying them on screen.

The barcode can be specified in the HTML files using the following XML processing instruction:

<?barcode type data maxwidth maxheight?>

<?barcodevar type variablename maxwidth maxheight?>

<?barcodevar2 variablename?>

Supported Barcode Types

Data format:

The type and length of supported data depends on the type of the barcode (e.g. EAN-13 only supports digits). Check the corresponding standards for more information. The data is percent-encoded, i.e. special characters are escaped by "\%hex". Null bytes are currently not supported.

Example: %20 equals to a space character.

maxwidth, maxheight:

This specifies the maximum width and height (in pixel) of the generated barcode image.

Example: EAN barcode with a maximum size of 384x60 pixels containing the data '4104640025303':

<?barcode ean-13 4104640025303 384 60?>

Dynamic data:

<?barcodevar ... ?> takes the value for the barcode from a variable so that dynamic data may be passed from the application. The variable name refers to an entry in the value map passed on to uiInvokeURL().

In addition <?barcodevar2 ... ?> allows not only controlling the content but also the type, width and height of the barcode from the application. Also in this case the variable name refers to an entry in the value map passed on to uiInvokeURL(), but this time the content of the variable needs to be JSON encoded and contain the following fields:

• data content of the barcode
• type type of the barcode
• width target width of the barcode in pixels
• height target height of the barcode in pixels

Example: '{"data":"4104640025303","type":"ean-13","width":384,"height":60}'

Code-128 and EAN-128

EAN-128 is a subset of Code-128 that uses the function code FNC1 to implement a specific formatting of the contained data. To issue the required function codes use the following ASCII values:

Generic Scripting Support

ADKGUI comes with a set of different scripting processors pre-installed for handling dynamic data (e.g. <?varhtml ... ?>). For more demanding applications additional libraries can be used to register a XML processors that preprocess the HTML code (e.g. for JavaScript, see chapter JavaScript support). Each script processor will be invoked for the XML processing instruction for which it has been registered. It receives the content of the XML processing instruction along with the global key value map as input. The output of the script is inserted into the HTML document. Preprocessing happens until no more XML processing instructions are found for which XML processors have been registered.

XML processing syntax is used to run scripts that generate output on the fly. All XML processing instructions have the form:

<?name script_source_code?>

name refers to the name of the scripting language and selects the script processor to be used. If a corresponding script processor has been found, the XML processing instruction is replaced by the output of the script, which in turn can contain HTML code or new XML processing instructions. If new XML processing instructions have been generated, these will be processed in the next pass until either no XML processing instruction remains or until an internal limit is hit that is used to break infinite recursion.

Note that the script must not contain '?>' as this indicates the end of the script source code and other representations need to be used if '?>' is required. For example, in JavaScript '?>' can be constructed by concatenating two strings "?" + ">" which eliminates the sequence '?>' from the source code.

New script processors can be installed using htmlSetScriptProcessor() that takes the name of the script language and a function pointer that is invoked to process the script.

htmlSetScriptProcessor(name, callback_func, cb_data);

'name' refers to the name in the XML processing instruction (i.e. the name immediately following '<?').

The script has access to the key value map supported by most dialog functions (see Passing Data to/from Dialogs). The script may write data to two strings corresponding to stdout and stderr. The data written to the first string is inserted into the document while the second is used for error reporting.

JavaScript support

Since version 2.1.1 the XML processor for JavaScript/ECMAScript is part of standard GUIPRT distribution package. The library libjsproc is provided as static or as dynamic library as a kind of plugin for V/OS, V/OS2. Following files and packages are available:

V/OS:

• jsproc.h, libjsproc.a, libjsproc.so (part of development package guiprt-vos-dev-X.X.X-X.zip)
• dl.libjsproc-X.X.X-X.tar (part of load package guiprt-vos-load-X.X.X-X.zip)

V/OS2:

• jsproc.h, libjsproc.a, libjsproc.so (part of development package guiprt-vos2-dev-X.X.X-X.zip)
• dl.libjsproc-X.X.X-X.tar (part of load package guiprt-vos2-load-X.X.X-X.zip)

V/OS3:

• jsproc.h, libjsproc.a, libjsproc.so (part of development package guiprt-vos3-dev-X.X.X-X.zip)
• dl.libjsproc-X.X.X-X.tar (part of load package guiprt-vos3-load-X.X.X-X.zip)

JavaScript has to be added manually by the application before it can be used like this:

#include "html/jsproc.h"...htmlSetScriptProcessor("js",js::jsProcessorExt,0);

Furthermore, the address of a local Http proxy should be set like this:

jsSetHttpProxy("http://localhost:12345");

In addition the program need to be linked against one of the libjsproc library variants. Header files and libraries for linking are found in the js development package. After that, JavaScript scripts can be provided inside the <?js ... ?> XML processing instruction. The XML processing instruction is replaced by the output of the JavaScript script that was written to stdout using print(). The key value map that was passed on to e.g. uiInvokeURL() is passed on to the script as object "ARGV". Values written to this object are passed on to the dialog and are also returned to the application.

The script may generate other XML processing instructions and these will be processed in another pass over the document. This can be used, for example, to insert barcodes or translated texts into the document.

The following example inserts all keys and values as is into the HTML document:

<?jsfor(i in ARGV) {   print(i,":",ARGV[i],"<br>\n")}?>

For security reasons JavaScript processing is done on client side. This ensures that it is running with the same permissions and privileges as the main application and cannot be used to gain additional permissions which could present a security risk.

The scripting engine internally uses Duktape (http://www.duktape.org) which conforms to ECMAScript version 5.1.

JavaScript Extensions

The following extensions have been added to JavaScript for interfacing with ADKGUI:

JavaScript Security Considerations

JavaScript limits file access to the subdirectory of the file system that has been set in ::UI_PROP_JS_ROOT. The application has to make sure that this subdirectory does not contain any sensitive information that could be leaked.

JavaScript provides network access via the XMLHttpRequest object. It is considered to be used with a local http proxy installed on the terminal. This proxy provides two functions:

• Check if connection is allowed
• Provide encryption, e.g. https/SSL

Since the proxy need to have access to the content of the messages for performing security checks, the provided XMLHttpRequest object does not support HTTPS/SSL. This is the task of the http proxy to provide appropriate encryption.

JavaScript Modules

ADKGUI supports the use of JavaScript modules by implementing Duktape.modSearch(). Modules are looked up in the modules folder next to the platform specific folders. By default this is www/modules for standard applications or www/<app-id>/modules for CP applications. The file name is the module name plus extension ".js". Modules are loaded using the global require() function.

Example:

<?js   var lib=require("hello");   lib.hello();?>

Variables and functions inside the module are local to the module and do not affect the global object. Modules export their symbols by assigning them to the exports object:

// file hello.jsexports.hello=function() {   print("Hello");}

More information regarding module support can be found here: http://www.duktape.org/guide.html#modules

HTML Templates

HTML template files are used to define the look of the standard dialogs. They represent the content of an HTML file that is found between <body> and </body> in a regular HTML file. Place holders are used to insert the parameter values of the standard functions into the template. The following place holders are supported:

Template files have a .TMPL file extension. The extension is automatically added and must not be passed to the UI functions.

Example: Menu Template

The following template demonstrates the use of template parameter described above. The dialog consists of a table with a headline that is filled using the <?insert text?> place holder. The second row of the table contains the menu. The <option> tags for that menu are filled using the <?insert menu?> place holder. The last row of the table is filled with buttons for "UP", "OK", "DOWN" linked to corresponding keys on the keypad using accesskey attribute and related actions using the action attribute.

<table border='0' style='height:100%;width:100%'>  <tr><td style='height:1px;vertical-align:top'><?insert text?></td></tr>  <tr><td style='height:100%'>      <select name='uimenu' size='2' style='height:100%;width:100%'>        <?insert menu?>      </select>  </td></tr>  <tr><td style='height:1px'>    <table style='width:100%'>      <tr><td style='width:33%'>        <button accesskey='&#133;' style='width:100%' action='call uimenu.up()'>UP</button>      </td><td style='width:34%'>        <button accesskey='&#13;' style='width:100%;background-color:green' action='call uimenu.action()'>OK</button>      </td><td style='width:33%'>        <button accesskey='&#137;' style='width:100%' action='call uimenu.down()'>DOWN</button>      </td></tr>    </table>  </td></tr></table>

Multi Language Support

Multi-language support with catalog files:

Since version 1.2.0, the UI system supports using catalog files for multi-language support. By using catalog files, an application is able to separate texts from the HTML code making it possible to create language independent HTML and template files.

A catalog file contains a text map, which consists of several lines of name-value text pairs, each having the following syntax:

name=value

name represents the key for text value both separated by '='. During runtime the UI system will look up name and inserts the value into the HTML document dynamically. The value should be UTF-8 encoded and allows usage of HTML elements and XML processing instructions like placeholder <?var ... ?>.

Example:

headline=Multi-languagetext1=Sample dialog <?var sample?> demonstrates Multi-language support with catalog files.text2=Just use placeholder &#60;?text <i>name</i>?&#62; inside HTML documents.

The catalog file is loaded to the UI system with following API function:

int uiSetCatalog(const std::string &filename)

The current catalog can be unloaded with filename=="" or by loading another catalog file.

By default, UI system expects catalog files in the UI resource folder (see UI_PROP_RESOURCE_PATH) as described in UI Resources : "www/\<platform>". Please note that uiSetCatalog() does not use file prefix UI_PROP_FILE_PREFIX for catalog files.

HTML and template files may access entries of the current catalog with the following dynamic data elements:

Syntax:

<?text name [default_text]?>

or

<?textvar var [default_text]?>

(since version 1.5.1)

The placeholder <?text ... ?> (XML processing instruction syntax) is supported at any place in the HTML document and is replaced with the corresponding text from the catalog specified by name before actual HTML rendering process takes place.

In case no valid entry has been found in the catalog file, the (optional) default text is used instead of a translation. In the default text the characters '()' have to be used instead of '<>' to write HTML tags. For example having a bold default text would look like:

<?text name (b)Bold default text(/b)?>

Dynamic data placeholders (e.g. <?var ... ?>) may be used in the catalog file. It will be processed in a second step after inserting the text from the catalog file. For more information see Dynamic Data Placeholder in HTML Files.

Additionally (since version 1.5.1), the XML processing instruction <?textvar ... ?> is provided. This allows the application to pass the catalog key name as a variable in map value (UI function parameter). In the following code example, value["hl"] stores "headline" for placeholder <?textvar hl?> used in the HTML document. In this case, the placeholder equals the following expression: <?text headline?>. Here, "headline" is used as name for the lookup.

Code Example:

map<string,string> value;value["sample"]="multilang.html"; // value for built-in variablevalue["hl"]="headline"; // variable name for HTML catalog lookupuiSetCatalog("en.ctlg"); // load the catalog fileuiInvokeURL(value,"multilang.html");uiSetCatalog("de.ctlg");uiInvokeURL(value,"multilang.html");uiSetCatalog(""); // unload

It is up to the application to use one catalog file per language (e.g. de.ctlg, en.ctlg etc.) or to use different catalogs files in same language for several HTML documents.

When the uiSetCatalog() function is invoked, the catalog is applied to all subsequent UI functions calls in the current UI thread context.

Using Catalogs in Multi-Threaded Applications:

uiSetLocalProperties() affects the handling of catalog files. If thread local properties have been enabled, a thread may set its own catalog file not affecting other threads.

Catalog files are cached and are released when the last UI thread using a catalog has unloaded the catalog or has terminated.

Applications may look up a text from current catalog and use it for other purposes than HTML files. Following API function is provided for that:

std::string uiGetText(const std::string &name, const std::string &deflt="");

The name parameter specifies the key for the text that should be found and returned. If no catalog is loaded or the text is not found in the current catalog, the function returns the string deflt (which is an empty string by default). Please note that every UI thread has its own catalog. The used catalog depends on the calling thread.

Please note that function uiGetText() has limitations over using gettext(): UI catalogs are tuned to contain HTML code, this is the reason why it is not possible to have some control characters inside (e.g. most notably, strings cannot contain newline characters \n). Thus, using catalogs is not a replacement for using gettext().

b) Multi-language Support with UI_PROP_FILE_PREFIX:

Another approach for multi-language support is the use of a file prefix to switch between different sets of HTML pages and templates.

Use uiSetPropertyString() with UI_PROP_FILE_PREFIX property for that purpose. There is no predefined set of prefixes for choosing languages. It is up to the application to define some.

c) Other Multi-language Concepts:

Optionally, it can be considered to use a gettext() based framework for language support since it is not limited to the GUI but also covers other functions such as printing or sending texts to remote devices (e.g. electronic cash registers).

Images Support

Static as well as animated images are supported. In case of ADK-GUI JPEG, PNG, BMP, PAM and (animated) GIF are supported.

Syntax:

<img src='url'>

The <img> tag has to be used to specify an image file in an HTML document. The src attribute specifies the URL of the image file relative to the current HTML document location. For ADK-GUI, the URL must refer to a file on local disk.

Background images can be specified using the CSS background-image attribute, see CSS support in ADK-GUI.

Interactive Dialog Elements

The following input types are supported:

• text - input
• number - numeric input
• password
• mask
• checkboxes
• radio buttons
• push buttons
• selection menus
• range (slider)
• barcode
• photo
• plugin
• hidden

The name attributes of HTML <input>, <button> and <select> tags are used to provide a unique name to an interactive element.

The action attribute is used to specify actions such as dialog exit points, references to other dialogs or an internal dialog action to be triggered (see Event Handling).

At least one element in an HTML document must contain a "load" or "return" action in order to provide an exit point for the dialog.

The name of the input elements links to the key value map provided during invocation of the dialog (see Passing Data to/from Dialogs). When displaying the dialog, the input fields are initialized using the value found in key value map. The name of the input element is used as a key to look up the corresponding value. When the dialog is closed, the current values of the input fields are stored back in the key value map and returned to the application.

If cursorname is provided, the cursor position of the input field is set from the value in the key value map and when the dialog is closed, the current cursor position is stored in the key value map.

Numeric Input

Syntax:

<input type='number'       size='nnn'       name='nnn'       action='aaa'       maxlength='x'       precision='x'       format='aaa'>

This type is used for entering fixed point decimal numbers. The following attributes are supported:

• size - Visible width of the input field in characters
• maxlength - Maximum number of characters
• precision - Number of decimal digits

ADK-GUI in addition supports:

• autosize - If set, use the largest font so that the value fits the input field. The font size specified via CSS is used as minimum font size
• prefix - Prefix to be displayed
• postfix - Postfix to be displayed
• dsep - decimal separator
• tsep - thousands separator
• sepkey - If provided with a key code, numeric input starts with the integer part of the number and pressing the selected key switches to the fractional part.
• format - custom numeric format for display, '?' represents optional digits, '#' represents mandatory digits (e.g. leading '0'). In addition it sets the allowed length of the input. Display of English format could be achieved by setting format="??.???.??#,##". Unused portions of the format string are removed for display. Using format overrides maxlength and thousands and decimal separators.

The formatting of the value depends on the configured properties for decimal point (UI_PROP_DECIMAL_SEPARATOR) and thousands separators (UI_PROP_THOUSANDS_SEPARATOR).

The input value is returned as string without any separators.

Range Input

Syntax:

<input type='range'       name='name'       min='nnn'       max='nnn'       step='aaa'       orient='vertical'       action='...'>

This type is used for entering a decimal value in the range [min,max] using a slider. The returned value is a multiple of step. When provided the action is triggered when the slider is released. orient determines the orientation of the slider which is horizontal by default.

CSS:background-color and CSS:color may be used to set the colors of the slider

The input value is returned as string containing the decimal value.

String Input

Syntax:

<input type='text'       size='nnn'       name='nnn'       action='aaa'       allowed_chars='abcd'       maxlength='x'>

This type is used for entering alpha-numeric texts in insert mode with cursor. The initial cursor position is at the end of the string. The following attributes are supported:

• size - Visible width of the input field in characters
• maxlength - Maximum number of characters
• allowed_chars - Allowed characters accepted in the input field

ADK-GUI in addition supports:

• autosize - If set use the largest font so that the value fits the input field. The font size specified via CSS is used as minimum font size
• prefix - Prefix to be displayed
• postfix - Postfix to be displayed

Password Input

This type is used for entering a password. Same as type=text, except that characters are not shown in clear text, but with a configurable password character.

An optional mask may be used to provide an input mask for password input, see Mask Input for more details.

The attribute show may be used to indicate that specific characters of the password should be displayed as clear text: Each character in the input for which the attribute show has a '1' at the corresponding position, the character is displayed as clear text. For example show="1101" would display the first, second and fourth character as clear text during password entry.

In order to set the password input characteristics, the following properties can be used with uiSetPropertyInt():

Mask Input

Syntax:

<input type='mask'       size='nnn'       name='nnn'       action='aaa'       allowed_chars='abcd'       maxlength='x'       mask='mmmm'       rfill       mask_char='a'>

This type is used to input a formatted string based on a mask definition in overwrite mode.

The following attributes are supported:

• size - Visible width of the input field in characters
• maxlength - Maximum number of characters
• mask - Input mask: The wildcard character (default: '*') represents an input character
• allowed_chars - Allowed characters accepted in the input field
• rfill - If set, the mask is filled from the end
• mask_char - Character that is displayed at empty places in the mask. If not present '_' is used by default.
• wildcard - Character to be used for representing input characters, default: '*'.

ADK-GUI in addition supports:

• autosize - If set, use the largest font so that the value fits the input field. The font size specified via CSS is used as minimum font size
• prefix - Prefix to be displayed
• postfix - Postfix to be displayed

Radio Button

Syntax:

<input type='radio'       name='nnn'       action='aaa'       value='vvv'>

This type is used to define a radio button group.

The name attribute of the input tag allows the user to make a selection. If the user checks a radio button, all other radio buttons with the same name are unchecked.

The radio buttons return the value of the selected radio button specified in the HTML value attribute.

Checkbox Button

Syntax:

<input type='checkbox'       name='nnn'       action='aaa'>

This type is used to define a checkbox.

Checkboxes return "1" or "0" depending on whether they are checked or not.

When invoked, the parameter value may be used to initialize the default content/setting of the input fields.

PIN Input

Syntax:

<input type='pin'       name='nnn'       action='aaa'       minlength='x'       maxlength='x'>

This type is used to define a PIN input prompt. Note that the PIN is not returned to the application. In case of a successful PIN entry, just the number of entered digits is returned. In case of an error, "error" is returned. If the user presses CANCEL button, the dialog returns "cancel". A PIN entry timeout detected in the security device returns "timeout" and PIN bypass returns "bypass". The PIN itself is stored in a secure place for further processing.

The following attributes are supported:

• minlength - Minimum PIN length
• maxlength - Maximum PIN length

In order to set the PIN input characteristics the following properties can be used with uiSetPropertyInt():

PIN Input via Touchscreen

On devices that do not have a real keypad PIN entry has to happen via a virtual keypad on the touch screen. The input field is the same as for normal PIN entry (see previous section). To protect PIN input a virtual keypad has to be used that uses a special mode to directly process PIN input in the security module. This is accomplished by using the pinkey attribute to mark buttons as PIN entry buttons and define the ASCII value to be returned by them.

A virtual keypad could look like this:

<table style="width:50%"><tr>  <td style="width:33%"><button style="width:100%" pinkey="1">1</button>  <td style="width:34%"><button style="width:100%" pinkey="2">2</button>  <td style="width:33%"><button style="width:100%" pinkey="3">3</button><tr>  <td><button style="width:100%" pinkey="4">4</button>  <td><button style="width:100%" pinkey="5">5</button>  <td><button style="width:100%" pinkey="6">6</button><tr>  <td><button style="width:100%" pinkey="7">7</button>  <td><button style="width:100%" pinkey="8">8</button>  <td><button style="width:100%" pinkey="9">9</button><tr>  <td>  <td><button style="width:100%" pinkey="0">0</button>  <td><tr>  <td><button style="width:100%" pinkey="&#27;">X</button>  <td><button style="width:100%" pinkey="&#8;">&lt;</button>  <td><button style="width:100%" pinkey="&#13;">OK</button></table>

The keypad must define all keys '0'-'9', Cancel (&#27;), OK (&#13;) and Correction (&#8;).

PIN Input via touchscreen for the visually impaired

ADKGUI has special support for PIN input for visually impaired persons in case of PIN input via touchscreen. This mode is activated by adding mode='navigator' or mode='navigator2' to the input element. It is considered to be used with a full screen virtual PIN input keypad. Activating navigator mode has the following effects:

• the PIN input field is hidden
• touching the screen does not enter a digit, instead PIN state notifications are sent that indicate changes in the touched key
• when the user moves the finger across the screen, each time a new key is reached a new PIN state notification is sent
• double tapping on the screen (mode='navigator') or pressing the confirmation button (mode='navigator2') enters a PIN digit or one of the other keys.

It is considered that an external application (e.g. on Android side on X10) registers for the notification and plays appropriate sound files as feedback to the user, so that he can determine the position on the keypad.

Example:

<html><body>   <input name='pin' type='pin' mode='navigator' action='return 0'>   <table style='width:100%;height:100%'>      <tr>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='1'>1</button>        <td style='width:34%'><button style='width:100%;height:100%' pinkey='2'>2</button>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='3'>3</button>      <tr>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='4'>4</button>        <td style='width:34%'><button style='width:100%;height:100%' pinkey='5'>5</button>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='6'>6</button>      <tr>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='7'>7</button>        <td style='width:34%'><button style='width:100%;height:100%' pinkey='8'>8</button>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='9'>9</button>      <tr>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='&#27;'>X</button>        <td style='width:34%'><button style='width:100%;height:100%' pinkey='0'>0</button>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='&#13;'>OK</button>   </table></body></html>

The following information is sent in the PIN state notification:

EXT_SYS_PINSTATE_NTF (broadcast)

The "key" tag is optional and only sent when the information is provided by the OS. The "digitcnt" tag is sent in states "ok" and "confirmed".

When using an external bluetooth conformation button, it is considered that this button triggers a EXT_SYS_CUSTOM_EVENT_NTF notification with the following content:

EXT_SYS_CUSTOM_EVENT_NTF

PIN Input training via touchscreen for the visually impaired

ADKGUI supports a training mode for PIN input for visually impaired persons in case of PIN input via touchscreen. This mode is activated by adding mode='training' to the input element. It is considered to be used with a full screen virtual PIN input keypad. Activating training mode has the following effects:

• the PIN input field is hidden
• touching the screen does not enter a digit, instead PIN training notifications are sent that indicate changes in the touched key
• when the user moves the finger across the screen, each time a new key is reached a new PIN training notification is sent
• double tapping on the screen confirms the selected key.

Important: The pin training input element must follow the buttons in the HTML document to work correctly.

Palm rejection can be activated by setting the attribute palm-rejection="1". Setting it to "0" disables palm rejection, which is also the default.

It is considered that an external application (e.g. on Android side on X10) registers for the notification and plays appropriate sound files as feedback to the user, so that he can determine the position on the keypad.

Example:

<html><body>   <table style='width:100%;height:100%'>      <tr>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='1'>1</button>        <td style='width:34%'><button style='width:100%;height:100%' pinkey='2'>2</button>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='3'>3</button>      <tr>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='4'>4</button>        <td style='width:34%'><button style='width:100%;height:100%' pinkey='5'>5</button>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='6'>6</button>      <tr>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='7'>7</button>        <td style='width:34%'><button style='width:100%;height:100%' pinkey='8'>8</button>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='9'>9</button>      <tr>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='&#27;'>X</button>        <td style='width:34%'><button style='width:100%;height:100%' pinkey='0'>0</button>        <td style='width:33%'><button style='width:100%;height:100%' pinkey='&#13;'>OK</button>   </table>   <input name='pin' type='pin' mode='training' action='return 0'></body></html>

The following information is sent in the PIN state notification:

EXT_SYS_PINTRAINING_NTF (broadcast)

Signature Capture

Syntax:

<input type='signature'       output='ooo'       linewidth='x'       name='nnn'       trigger='n'       action='act'       loadsig       readonly       dpi='resolution'>

This type is used to define a signature capture input field. Depending on the output attribute, different ways exist of returning the signature data. The following values of output are supported:

• raw: The signature is returned as JSON encoded array of x/y coordinates. (-1,-1) is used to separate different strokes of the signature. In addition to the x/y coordinates each entry contains a timestamp t in milliseconds. The timestamp of separators is set to 0.
• tiff: A TIFF image is created containing the signature. The name of the file is returned.
• png: A PNG image is created containing the signature. The name of the file is returned.
• screenshot: A screenshot of the signature capture field is written to a file and the file name is returned. The format of the file is binary PPM (Portable PixMap / P6). The screenshot contains everything that is seen on screen. This can be used to put a signature on top of some text and save everything to an image.
• pngscreenshot: Like "screenshot" but using PNG instead of PPM.
• realtime: Signature coordinates are sent as update events in realtime as JSON encoded structure (no array as in raw). (-1,-1) is used to separate different strokes of the signature. When the dialog returns, the returned value is empty, the coordinates are not sent a second time. Update events must have been enabled when using realtime signature input.

The size of the signature capture input field may be configured using CSS width and height attributes. The line width may be controlled using the linewidth attribute, taking the width in pixels. The default width is 1. For geometric symmetry reasons even line widths are increased by one to get an odd line width when generating TIFF or PNG images, e.g. setting line width to 2 creates the same output as setting it to 3.

The action 'act' is triggered after the user has painted a number 'n' of strokes given in the trigger attribute. This can be used for example to enable a confirmation button after the first signature stroke.

By default the signature capture input field starts empty even if the key value map contains some data for this input field. By setting the attribute loadsig the input field can be initialized to contain some signature data on start. The initialization values are read from the key value map in this case just like for any other input field. The data format is that of the "raw" signature output format, i.e. the output data of a "raw" signature input field can be used to initialize another one. Strokes provided via loadsig are not considered for the trigger attribute. trigger only counts new strokes.

If the signature is just to be displayed by loadsig but not to be changed or continued, the readonly attribute can used to prevent modification.

dpi can be used to set the dpi value that gets written to a TIFF signature. This only affects the DPI property but does not change the image data written. By default 150 is used.

Example receipt with signature on top:

<html><body> <table style="width:100%;height:100%" border="0">   <tr><td style="height:1px">Signature:   <tr><td>      <div style="height:0px"><div style="padding:5px">         Some receipt text<br>Please sign here:      </div></div>      <input type="signature" output="screenshot" name="signature"          style="width:100%;height:100%;background-color:transparent" trigger="1" action="call ok.enable()">    <tr><td style="height:1px"><center><button name="ok" action="return 0" disabled>OK</button>   </center></table></body></html>

Mimimum example for realtime signature input, printing captured coordinates to console:

#include <html/gui.h>#include <stdio.h>#include <unistd.h>#include <pthread.h> using namespace vfigui; pthread_mutex_t mutex=PTHREAD_MUTEX_INITIALIZER;pthread_cond_t cond=PTHREAD_COND_INITIALIZER;int done; void async(void * datap, vfigui::UICBType type, vfigui::UICBData &data){   stringmap &v=data.value();    if(type==UI_CB_UPDATE) {      JSObject j;      j.load(v["sig"]);      printf("x: %ld  y: %ld  t: %ld\n",j("x").getInt(),j("y").getInt(),j("t").getInt());   }   if(type==UI_CB_RESULT) {      pthread_mutex_lock(&mutex);      done=1;      pthread_cond_signal(&cond);      pthread_mutex_unlock(&mutex);   }} int main(){   uiSetPropertyInt(UI_PROP_UPDATE_EVENTS,1);   uiInvokeAsync("<input type='signature' name='sig' output='realtime' style='width:100%;height:90%;box-sizing:border-box'>"                 "<button action='return 0'>OK</button>",async,0);    pthread_mutex_lock(&mutex);   while(!done) pthread_cond_wait(&cond,&mutex);   pthread_mutex_unlock(&mutex);   return 0;}

Signature Capture on remote displays

Normally in case of signature capture of output type png, tiff, screenshot or pngscreenshot, the captured signature is written to a file in the file system and the file name is returned. In case of a remote display, this would be the file system of the remote display, which is not really useful in most cases. Therefore, in case of a remote display, the signature is returned as data URL to the application instead of as a file name.

The application can use the functions uiDataURLType() to check for a data URL and use uiDataURLToFile() to store it to the local file system.

Push Buttons

Syntax:

<button       name='nnn'       action='aaa'       autofocus       nofocus       value='vvv'       disabled       pushsound='file'>

Buttons may be specified using the HTML <button> tag. The value found in the value attribute is returned as return value of the dialog.

Selection Menu

Syntax:

<select name='nnn' size='2' style='height:80px'>  <option value='vvv' action='aaa'>MENUTEXT 1</option>  ...  <option value='vvv' action='aaa'>MENUTEXT n</option></select>

Single item selection menus are specified using the HTML <select> tag. Each selection item is specified using the <option> tag. Each <option tag> might specify its own action attribute.

Barcode

This input type is only available on devices equipped with a camera and barcode scanning support. For barcode scanning support the optional libhoneywell bundle needs to be installed.

Syntax:

<input type='barcode'       name='nnn'       enable='a,b,...'       action='...'       focus='auto|center|nnn'       zoom       aimer       illumination       pick       trigger[='key']       power_line_freq='0|50|60'       nofullscreen>

The barcode input shows the camera image on screen to aid in pointing to the barcode. The size of the image is scaled to fit within the specified size. Note that for performance reasons, only a predefined set of sizes is supported and, therefore, the size of the image may actually be smaller than specified. The image is shown as black and white image with a red crosshair in the center. In case of auto focus it indicates where focussing will happen. If the pick attribute is set, it indicates which barcode is to be returned to the application. If not set all barcodes in the view of field are considered.

Barcode scanning is performed continuously on every video frame delivered by the camera unless the trigger attribute has been set. In continuous mode when a barcode is detected it is marked by a red frame on screen and the action is triggered if supplied. With the trigger attribute set the video preview just shows the captured scene but no scanning of barcodes takes place. This improves performance of the video preview as no scanning is performed. When the optional trigger key is pressed or the scan action is invoked the next video frame is scanned for barcodes. If a barcode is detected, the preview is stopped for some time and the detected barcode(s) are marked by a red frame on the screen. If an action has been supplied it is run.

If update events are activated, an update event is sent for each barcode scanned. By this several barcodes can be scanned in a row and also if several barcodes come into view at the same time, all of them will be scanned.

Unless a trigger key has been set when a barcode has been scanned, scanning a barcode with the same content is suppressed for some time to prevent that the same barcode is reported again and again for each video frame.

The barcode symbologies to be supported are passed as a comma separated list in the enable attribute. The follogwing symbologies are supported:

Giving a group name enables all barcodes in that group.

In addition to the symbologies above one of the following postal codes may be selected:

If the enable attribute is not provided, barcodes in the groups "1d" and "2d" are enabled by default.

Some barcodes support options controlling additional properties. Options are passed in the enable attribute along the selection of barcodes. To set an option, the barcode (or group containing it) needs to be provided as well.

Options consist of a name and a value separated by '=' (without space in between). Only one value can be assigned to an option name. Trying to assign more than one value the result is undefined.

The following options and values are supported:

Obtaining the symbology of a scanned barcode:

The option o-tx-sym controls whether only the data or also the symbology is returned.

Focus can be controlled using the focus attribute. It takes the following values:

• "auto": Auto focus
• "center": Auto focus that is tuned to focus the center of the image
• decimal number: Manual focus using the number as focus setting. Higher values mean closer focus. The focus range is in 0..610.

If the focus attribute is not provided, "center" is used as default.

The following table lists the focus distance depending on the focus setting:

Attribute zoom enables digital zoom to support larger scanning distances (at lower frame rates) when present.

Attributes aimer and illumination switch on the corresponding LED on the camera module when present.

Attribute power_line_freq is used to set the power line frequence to reduce interference with electric lighting.

On Android using ARRS barcode scanning is handled by a separate barcode scanning service. By default this is displayed full screen. Using attribute nofullscreen the size and position of the scanning service can be controlled using CSS. In this case it is displayed as overlay on a faded background. On V/OS nofullscreen does not have any effect and is ignored.

Normally all barcodes in the view of field are reported. With the pick attribute set, only the barcode found under the red crosshair is returned.

Attribute trigger is used to set a key that triggers barcode scanning. If unset all video frames are scanned for barcodes.

Example for single shot scanning:

<html><body><input type="barcode" style="width:100%;box-sizing:border-box" name="barcode" action="return 0"><center><button action="return -1">Cancel</button></body></html>

Example for scanning several barcodes (update events need to be enabled):

<html><body><input type="barcode" style="width:100%;box-sizing:border-box" name="barcode"><center><button accesskey="&#27;" action="return -1" style="display:none"></button></body></html>

Example for scanning barcode unter the red crosshair on keypress (OK or '0' key) (update events need to be enabled):

<html><body><input type="barcode" focus="center" pick trigger="&#13;" style="width:100%;box-sizing:border-box" name="barcode"><center><button accesskey="0" action="call barcode.scan()" style="display:none"></button><button accesskey="&#27;" action="return -1" style="display:none"></button></body></html>

Photo

This input type is only available on devices equipped with a camera.

Syntax:

<input type=photo       name='nnn'       action='...'       power_line_freq='0|50|60'>

The photo input shows the camera image on screen. Taking a photo is triggered by invoking the photo function. In this case the preview area is brightened to give a visual feedback. When a photo has been taken the action in the photo input is processed and the input element returns the name of the file containing the photo.

Photos are taken at maximum resolution using MJPEG mode of the camera and are stored as JPEG image. Since the compression happens inside the camera compression parameters cannot be changed.

The file is only valid until the next photo has been taken.

Example:

<html><body>  <input type="photo" style="width:100%;box-sizing:border-box" name="photo" action="load photo2.html">  <table style="width:100%">    <tr>      <td style="width:45%">        <button accesskey="&#27;" style="width:100%" action="return -1">Cancel</button>      <td>      <td style="width:45%">        <button accesskey="&#13;" style="width:100%" action="call photo.photo()">Photo</button>  </table></body></html>

Input plugins

Input plugins provide a way of accepting input from devices like barcode or card readers. Plugins are shared libraries that need to be installed in the plugins directory next to guiserver/guiprtserver. The name of the shared library is constructed as follows: input_<plugin-name>.so

Only the following characters are allowed in the plugin name: 'a'-'z', 'A'-'Z', '0'-'9', '_', '-'

The plugin name and options are passed in the plugin attribute. The plugin name is separated by whitespace from the plugin options. The plugin options are passed as string to the input plugin. The format of the options is dependent on the input plugin. Plugin options may contain arbitrary characters including whitespace.

The value of the input element is set to the value returned by the input plugin (e.g. it contains the read barcode). If present, the action is triggered when some input has been captured.

When the beep attribute is found, a beep is played when the input plugin provides input data. Default is not to play a beep.

Syntax:

<input type='plugin'       plugin='<plugin-name> <plugin options>'       name='nnn'       action='aaa'       style='visibility: hidden'       beep>

For more information about supported input plugins check the section Input plugins

Hidden Input

Syntax:

<input type='hidden'       name='nnn'       value='aaa'>

This input type only inserts data into the returned key value map. It does not show any input field.

Invoking Dialogs

The API provides functions to invoke dialogs from HTML files (based on a given URL) or HTML documents passed directly by the calling application. The dialogs can be invoked either synchronously or asynchronously.

All API functions are available as synchronous and asynchronous variants.

See reference part of this documentation for a complete list of supported functions.

Synchronous API

The synchronous API is used to display a dialog and wait until the user has finished entering data. Since the function waits until the dialog has been finished only one dialog can be shown per thread at a time. While the dialog is shown the thread is blocked and cannot perform some other tasks.

Example for a synchronous API:

// invoke the dialog and wait for completion, return the dialog parameteruiInvokeURL(values, url);

Most synchronous functions offer the use of a callback function. This callback function is invoked about 5 times a second and can be used to cancel the current dialog: If the callback returns false the dialog is cancelled, if it returns true the dialog continues to be displayed.

Asynchronous API

Using the asynchronous API displaying the dialog and reading the result has been split in two separate parts. This allows displaying more than one dialog per thread and allows processing of data in the background without having to create a new thread.

Two modes of operation are supported:

1. wait for result of the dialog via uiInvokeWait or similar
2. use of a callback function, that gets invoked if some new data is present

These two modes cannot be combined. Either the first or the second is used. The distinction is made by passing a pointer to a callback function or by passing NULL.

Asynchronous API Using Wait Function

This mode of operation used the wait function that corresponds to the asynchronous invocation function, e.g. using uiInvokeURLAsync with uiInvokeWait. The asynchronous function returns a transaction ID that is used in the wait function to wait for the result of the dialog. As long as UI_ERR_WAIT_TIMEOUT is returned, the dialog has not been finished within the specified timeout. In this case the wait function has to be invoked again to obtain the result. Compared to ADKGUI 1.x the interface of the wait functions has been simplified: Only in case of UI_ERR_WAIT_TIMEOUT the function has to be invoked again, now all other cases are handled internally and are not passed on to the application.

Instead of waiting for the result, a dialog can also be cancelled using uiInvokeCancel.

Both ui*Wait and uiInvokeCancel release the memory occupied by the dialog result.

In case the dialog result is not read some simple garbage collection has been added: Each time a new dialog is shown in the same region, a counter kept within the dialog result is increased and once it reaches a certain limit the result is considered garbage. In this case the result is deleted to prevent a memory leak.

Example for corresponding asynchronous API:

int txn_id; // send the dialog invocation request to the GUI servertxn_id =uiInvokeURLAsync(values, url); // do some other processing // wait for the response with a timeout of 1000 ms and get the returned// dialog parameterif(txn_id>=0) {   while(uiInvokeWait(txn_id, values,1000)==UI_ERR_WAIT_TIMEOUT) {     // do some more processing   }}

Asynchronous API Using a Callback

Instead of using one of the wait functions ui*Wait a callback can be provided to the asynchronous function, e.g.:

int uiInvokeURLAsync(   int region_id,    const std::map<std::string,std::string> &value,    const char *url,    uiAsyncCallback cb=0, void *data=0);

The callback function is invoked if new data is available regarding the dialog. The callback has the following prototype:

void callback(void *data, UICBType type, UICBData &uidata);

'data' is the data pointer that was passed to the asynchronous function. It is forwarded to the callback as is and can be used to provide the callback function with additional application specific data. 'type' refers to the reason why the callback was invoked. Currently the following cases exist:

• UI_CB_RESULT: The dialog has finished and the result can be read. UI_CB_UPDATE: Some input field has been updated
• UI_CB_LOAD: A new dialog has been loaded
• UI_CB_ERROR_LIST: An error was recorded in the error list. The error list is reset just after the callback was invoked.
• UI_CB_STATISTICS: Statistics data is available.

UI_CB_RESULT indicates that the dialog (sequence) has finished and that the result can be read.

UI_CB_UPDATE and UI_CB_STATISTICS are only generated in case the corresponding property has been activated.

In call cases the uidata object is used to obtain entered data and other information. It allows reading the following data:

• int result(): return code of the dialog
• int txn_id(): Transaction ID (this is the same ID that is returned by the asynchronous function)
• stringmap &value(): Key value map containing input data. It is only updated in case of UI_CB_RESULT and UI_CB_UPDATE
• std::string &url(): URL of the currently shown dialog as provided by the application or by action='load ...'
• std::vector<UIErrorEntry> &error():Error list
• UIStatistics &statistics(): Statistics data

If a callback function is provided uiInvokeWait and the other wait functions cannot be used and return UI_ERR_INVALID.

Passing Data to/from Dialogs

All interfaces allow passing a (sometimes optional) key value map to the dialog. This key value map serves several purposes:

• It is used to set the initial value of input fields and return entered data. The key used is determined by the name specified in the input field (see Interactive Dialog Elements).
• It is used to provide data that gets inserted into the HTML document dynamically, e.g. by using <?var ... ?> (see Dynamic Data Placeholder in HTML Files).

Obtaining partial input

If an application needs to have access to the input as it is typed in, it may activate update events by setting the property UI_PROP_UPDATE_EVENTS and use a callback function along the asynchronous set of dialog functions. If active each time one of the input fields changes the callback function is invoked with UI_CB_UPDATE and the updated values can be obtained using the object passed on to the callback function

GUI System Runtime Properties

The GUI system supports changing some properties during runtime. Refer to the uiGetPropertyInt(), uiGetPropertyString(), uiSetPropertyInt(), uiSetPropertyString() functions for that purpose.

See UIPropertyInt and UIPropertyString enumerators for supported properties.

By default the properties are global to the application. If required uiSetLocalProperties() can switch to thread local properties. In this case the current thread receives a copy of the global properties and changes only affect this thread while other threads continue to use the global set of properties.

GUI Server Properties

For achieving a consistent look and feel across different applications, server properties are supported that may overwrite application settings. Server settings can be read and written using uiGetServerProperty() and uiSetServerProperty(). Check #UIServerProperty for a description of the available properties.

Display Regions

The GUI system provides support for definition of independent non-overlapping display regions. The content of a region can be updated independently of any other regions content.

A GUI region is defined by a set of absolute coordinates and identified by a unique identifier. A default region ID is used if no region is created.

Example applications for the use of display regions might be regions for displaying

• User interactions (default region)
• System status information
• Contactless LED emulation
• Customer Banners

The GUI system API supports regions with the uiLayout() function call that accepts a list of region definitions and thus defines the layout of the display. Changing the layout cancels the dialogs in those regions that no longer exist.

Regions are described by the following structure:

struct UIRegion {   int id;    int left;      int top;       int right;     int bottom;    int flags;  };

The current region layout may be obtained using uiGetLayout();

Regions can be hidden by setting the UI_REGION_FLAG_HIDDEN flag. This may be used to temporarily hide a dialog and display another one in the same place:

Use uiGetLayout() / uiLayout() to set UI_REGION_FLAG_HIDDEN in the region to be hidden and add a new region using the same coordinates for the new dialog. If the new dialog has finished, remove its region and unset the UI_REGION_HIDDE_FLAG to unhide the old dialog again.

Dialogs in hidden regions continue to work, i.e. timeout remain still in place and will be processed. Invoking new dialogs in hidden regions is supported.

Important: Visible display regions must not overlap. If there is some overlap undefined behavior may result.

uiLayout can be used to move and resize existing regions: When a region ID already exists, the region is moved and resized according to the new coordinates and then redrawn at the new location. If this is not desired, uiClear() may be used to remove the content of a region before moving and resizing the region.

Region Hierarchy

Starting ADK-GUI version 2.x regions form a hierarchy so that regions may be subdivided into smaller regions. Effectively regions form a tree and dialogs can be displayed at the leaves of this tree.

uiEnterRegion() and uiLeaveRegion() are used to navigate in this tree. uiEnterRegion() makes the provided region the current region and from then on all functions work relative to it.

After descending in the tree using uiEnterRegion() a new default region is created automatically. It can be replaced by new sub-regions using uiLayout().

Displaying a dialog in a region that is no leaf of the tree automatically prunes the tree and all affected dialogs are cancelled.

Example:

// create two regionsUIRegion r[]={   {0,  0,0, -1,19},   {1,  0,20,  -1,-1}};uiLayout(r,2); // display something in region 0uiInvoke("Region 0"); // descend to region 1uiEnterRegion(1); // subdivide into two regionsuiLayout(r,2); // display something in the two regionsuiInvoke("<div style='height:100%;background-color:#aaa'>"         "Region 1/0</div>");uiInvoke(1,"<div style='height:100%;background-color:#ff0'>"           "Region 1/1<br>"           "<button action='return 0'>OK</button>"           "</div>"); //ascend one leveluiLeaveRegion(); // display dialog removing old dialogsuiInvoke(1,"<div style='height:100%;background-color:#0ff'>"           "Region 0/1<br>"           "<button action='return 0'>OK</button>"           "</div>");

Multi-Display Support

ADKGUI has support for accessing multiple displays from one application. Multi-display support is activated by providing more than one address in the environment variable GUI_DISPLAY separated by whitespace when running the client. For example:

GUI_DISPLAY=":0 192.168.0.1:5"

This would set up the client to use two displays, the first resides on localhost port 5900 and the second is accessed on 192.168.0.1 port 5905.

In the program the display is selected by passing the display parameter. The display parameter is in the range 0 .. uiDisplayCount()-1

Virtual LED support

Not all terminals are equipped with status LEDs required for contactless payments. On these devices the LEDs have to be emulated on the display. Due to the very tight timing constraints HTML cannot be used in most cases. ADKGUI offers a set of functions for emulating these status LEDs.

Using virtual LEDs consists of two steps:

• Configuring the LEDs
• Switching LED states

Two variants of virtual LEDs are supported:

• Separate LED area, that is independend of HTML dialogs
• HTML LED element for use inside HTML dialogs.

The first variant installs a permanently visible area on screen, similar to GUI regions, that displays the LEDs. Accessing the LEDs has less overhead compared to the second variant but has restrictions placing the LEDs on screen. The second variant allows placing the LED area at an arbitraty position but has higher overhead and may suffer from complex HTML dialogs. Therefore, in this variant it is the responsibility of the application to make sure that timing constraints are met.

In both cases uiSetLED() is used to switch LEDs on or off.

Separate LED Area

The LEDs are configured using one of:

• uiConfigLEDs(UILEDShape shape, int width, int height, unsigned off_rgba, unsigned on0_rgba, unsigned on1_rgba, unsigned on2_rgba, unsigned on3_rgba)
• uiConfigLEDs(const char *filename)

The first sets up LEDs using a standard shape, width and height is the size of a single LED. The remaining parameters provide the colors of the LEDs in off state (same color for all) and on state. The color values are RGBA values, the alpha channel is ignored.

The second sets up LEDs based on a PNG image. The PNG image has to contain 5 LED images next to each other. The first showing the off state, the other 4 showing the on state of the respective LEDs.

Example:

The alpha channel of the PNG image may be used to create non-rectangular LEDs.

The virtual LEDs are activated using uiShowLEDArea(). The edge close to which the LEDs are displayed can be chosen as well as the size of the area. If the area is smaller than the display, it is centered along the edge. LEDs are distributed automatically within this area. uiShowLEDArea() resets the LED state to the off state. The area is removed using uiHideLEDArea().

If uiShowLEDArea() is called more than once, the same number of uiHideLEDArea() is required to remove the virtual LEDs from the screen. Only the parameters of the first call to uiShowLEDArea() take effect, successive calls just increase an internal reference counter.

When virtual LEDs are active, the window for HTML output is shrunk by the size of the LEDs area. Due to this some regions on screen may be moved and/or resized. Therefore, dialogs that are used while virtual LEDs may be active, should be designed so that they can adjust to different region sizes within some limits.

The LED area will always be shown on display and cannot be put to the background. It is inaccessible to HTML dialogs.

HTML LED Area

<input type='led' src='led_config.png'> is used to set up the LED image and define a LED element that is placed on screen. The image file provided in src is the same format as the image file provided to uiConfigLEDs() (see above). The size and background of the element can be set using CSS. For performance reasons border-radius and a transparent background-color is not supported. Zooming of the LEDs is also not supported.

Use of a transparent background-image for the LED area may degrade the performance, therefore, it is recommended to either use a solid color or use a background-image without transparency.

Within the HTML element the LEDs are distributed evently. The orientation vertical or horizontal depends on the size of the element. If the width is higher or equal than the height, then LEDs are arranged horizontally, if not they are arranged vertically.

Multi-Application-Controller Interface

Multi-Application-Controller (MAC) is used to run several applications in parallel on a terminal. For this it sets up a separate region for each application. Applications then run within this region using sub-regions. For this MAC sets up the environment variable GUI_REGION, which has a whitespace separated list of parent regions, one for each display. GUI_REGION is automatically considered during startup of an application so that most of the MAC handling is transparent to the application.

Thread Support

All API functions of the GUI system are thread-safe. Please note that invoking a dialog from a different thread might cancel currently active dialogs invoked by other threads when using the same region ID.

Formatting Strings with HTML Content

The GUI system provides specific support for handling strings with HTML content. Printf like function calls uiPrint() and uiPrintV() are provided for that purpose.

Animated Screen Transitions

Starting with GUI version 2.x support for animated screen transitions has been added. Animation takes place when changing from one HTML document to another. Various transition types (like slide, crossfade, etc.) are supported. Transition speed and animation direction can be adjusted. Screen transition settings can be applied per display region.

See uiSetTransition() function for more details on available options.

While uiSetTransition sets a global configuration for a region, it is also possible to activate a transition for one dialog only. This works by setting the variables "_transition" and "_transduration" in the key value map. "_transition" is the hex-number of the transition type (e.g. "131" for slide up with ease in and out) and "_transduration" contains the duration in milliseconds.

Backlight Control

ADKGUI supports controlling the backlight brightness using ::uiSetBacklightConfig. It takes a set of brightness levels along with a time, that tells how long they will be used. Initially the first brightness level is used (index 0). When the time has elapsed, the next brightness level is used, and so on until the last entry has been reached. As soon as some user activity has been detected (touch or key press) ADKGUI switches back to the first entry. If there is more than one entry in the list, the last entry is considered the off state. In this state, if brightness is 0, a touch or keypad event is considered a wakeup event, that just activates the backlight but that is otherwise ignored to not inadvertedly trigger some action.

Each time the backlight brightness is changed, a broadcast notification is sent as information for other components. The notification has the ID "_uiBacklight". The parameter object has a single member "brightness" which contains the new brightness in percent (0..100).

The application may switch to a certain level using ::uiSetBacklightLevel. uiSetBacklightLevel(0) activates maximum brightness and uiSetBacklightLevel(-1) switches to minimum brightness or OFF depending on configuration.

Performance Optimizations

When creating HTML documents for a terminal, note that the terminal has much less computing power compared to a desktop computer or even a smart phone. HTML pages and style sheets must be properly designed to avoid resource heavy tasks. The following lists some tweaks to speed up the display of dialogs:

• Avoid large PNGs with alpha channel. Using an alpha channel needs to mix the image with the background. This process has turned out to be quite slow. If possible, transparent areas should be replaced with pixels showing the background, i.e. eliminating the transparency. Note however, that the transparent channel needs to be eliminated altogether since it already slows down things even if all pixels are marked opaque.
• Nested tables need several passes in the layout process. The number of passes depends on the nesting level. If possible use rowspan and colspan to reduce the nesting level of tables.

Pixel level access

For applications that need pixel level access ADKGUI allows installing a canvas in a region using uiCanvas(). uiDraw() is used to draw to the canvas. Drawing primitives are sent in a group to speed up operation. This group is created using a UIDrawing object, that offers different drawing primitives including text and image support.

The canvas element integrates with the UI region concept, i.e. by switching the region it can be resized or moved to the foreground or background. The content is preserved, when hiding a region containing a canvas element.

Touch and keyboard events are delivered via the ::uiEventCallback callback function that has been passed to uiCanvas(). The following events are delivered:

• ::UI_PUSH the user started a touch action
• ::UI_DRAG the user is dragging the finger across the screen
• ::UI_RELEASE the user lifted the finger off the touch screen
• ::UI_KEYDOWN the user pressed a key
• ::UI_KEYUP the user released a key

The following key codes are used for function and control keys:

uiTextMetrics() is provided, so that an application can determine the dimensions of a text. It allows determining the width of several texts in a batch. The following information is returned:

• height: Height of the font in pixels. It may be different from the nominal size of the font to account for accent marks or the like. In general this is the distance two lines of text should have to not overlap.
• width: Width of the text in pixels. This is returned per provided text.
• descent: Size of the descender in pixels (number of pixels text may reach below the base line)

Drawing images the following image file formats are supported:

• GIF (only static GIFs without animation)
• BMP
• PNG
• JPEG
• PAM

File names are relative to the resource directory. These images can also provided as in-memory pointers instead of as file name, see UIDrawing::image()

In addition in-memory images can also provided as raw images, i.e. uncompressed pixels in memory. In this case width and height must be provided separately. The following raw image formats are supported:

• Grayscale: 1 byte per pixel
• Grayscale with alpha: 2 bytes per pixel
• RGB: 3 bytes per pixel in the order red, green, blue
• RGBA: 4 bytes per pixel in the order red, green, blue, alpha

The canvas element is active until some other content is displayed in a region (e.g. using ::uiInvokeURL) or when a new canvas element is installed.

Input plugins

Input plugin "sfbarcode"

This plugin is for scanning barcodes on X10 with the help of an Android application. It is using the IPC notification interface to start / stop scanning on Android side and to receive scanned data. The plugin does not take any configuration parameters.

See https://confluence.verifone.com:8443/display/GR/Notify+Message+Android+Server+specifications for more information

Input plugin "se2707"

This plugin is for scanning barcodes on e280 with barcode scanner module SE2707.

The plugin takes the following configuration parameters:

enable=a,b,c

The barcode symbologies to be supported are passed as a comma separated list in the enable option. The follogwing symbologies are supported:

Giving a group name enables all barcodes in that group.

If the enable option is not provided, barcodes in the groups "1d" and "2d" are enabled by default.

Some barcodes support options controlling additional properties. Options are passed in the enable attribute along the selection of barcodes. To set an option, the barcode (or group containing it) needs to be provided as well.

Options consist of a name and a value separated by '=' (without space in between). Only one value can be assigned to an option name. Trying to assign more than one value the result is undefined.

The following options and values for 1D barcodes are supported:

The following options and values for 2D barcodes are supported:

For restricting the length of scanned barcodes two lengths per barcode may be set. The meaning is as follows:

The following lengths can be set:

Example:

<input type="plugin" plugin="se2707 enable=ean,qr">

Generic options, independent of the symbology:

<input type="plugin" plugin="se2707 enable=1d,2d,o-pick=1">

Input plugin "magtekmicr"

This plugin it for scanning checks using an external Magtek MICRMini check reader connected to a serial port of the terminal.

The plugin takes the following configuration parameters:

port=<port>

<port> can be one of com1, com2, com 3 or com4. These map to the following Linux devices:

The serial port settings are considered to be set to 9600 bits per second, 8 data bits, no parity, 1 stop bit.

When a check has been scanned, the scanned data is returned followed by '/' and a status code.

The data is sent in raw data format using the following characters for non-digits:

E13-B character Set

CMC-7 character set

The following status codes are supported by the scanner: