Graphical User Interface

Data Structures
struct	UIBacklight
class	UICBData
struct	UIErrorEntry
struct	UIMenuEntry
struct	UIRegion
struct	UIStatistics

Typedefs
typedef void(*	uiAsyncCallback) (void *data, UICBType type, UICBData &uidata)
typedef bool(*	uiCallback) (void *data)

Enumerations
enum	{ UI_REGION_DEFAULT =0 }
enum	{ UI_REGION_FLAG_HIDDEN =1 }
enum	{   UI_TRANS_UP =0x1, UI_TRANS_RIGHT =0x2, UI_TRANS_DOWN =0x4, UI_TRANS_LEFT =0x8,   UI_TRANS_DIRECTION_MASK =0xf, UI_TRANS_EASE_IN =0x10, UI_TRANS_EASE_OUT =0x20, UI_TRANS_EASE_INOUT =0x30,   UI_TRANS_EASE_MASK =0x30, UI_TRANS_NONE =0x000, UI_TRANS_SLIDE =0x100, UI_TRANS_SLIDEON =0x200,   UI_TRANS_SWAP =0x300, UI_TRANS_CROSSFADE =0x400, UI_TRANS_TYPE_MASK =0xfff00 }
enum	UICBType {   UI_CB_RESULT, UI_CB_UPDATE, UI_CB_LOAD, UI_CB_ERROR_LIST,   UI_CB_STATISTICS }
enum	UIEdge { UI_EDGE_TOP, UI_EDGE_RIGHT, UI_EDGE_BOTTOM, UI_EDGE_LEFT }
enum	UIError {   UI_ERR_OK = 0, UI_ERR_ABORT = -1, UI_ERR_BACK = -2, UI_ERR_TIMEOUT = -3,   UI_ERR_PROPERTY = -4, UI_ERR_WRONG_PIN = -5, UI_ERR_PARAMETER = -6, UI_ERR_PERMISSION = -7,   UI_ERR_CANCELLED = -8, UI_ERR_REGION = -9, UI_ERR_FAIL = -10, UI_ERR_UNSUPPORTED = -11,   UI_ERR_INVALID = -12, UI_ERR_WAIT_TIMEOUT = -13, UI_ERR_CONNECTION_LOST = -14, UI_ERR_PROTOCOL = -15,   UI_ERR_SCRIPT = -16, UI_ERR_FILE_READ = -17, UI_ERR_RESTRICTED = -18, UI_ERR_MODIFIED = -19,   UI_ERR_ACTION = -20, UI_ERR_DISPLAY = -21, UI_ERR_PIN_ENTRY_DENIED = -22 }
enum	UILEDShape { UI_SHAPE_RECTANGLE, UI_SHAPE_ELLIPSE }
enum	UIMenuOptions { UI_MENU_DISABLED =1 }
enum	UIPropertyInt {   UI_PROP_TIMEOUT =0, UI_PROP_PASSWORD_CHAR, UI_PROP_DEFAULT_FONT_SIZE, UI_PROP_PIN_AUTO_ENTER,   UI_PROP_PIN_CLEAR_ALL, UI_PROP_PIN_BYPASS_KEY, UI_PROP_PIN_ALGORITHM, UI_PROP_PIN_INTERCHAR_TIMEOUT,   UI_PROP_PASSWORD_SHOW_CHAR, UI_PROP_KEEP_DISPLAY, UI_PROP_UPDATE_EVENTS, UI_PROP_CIRCULAR_MENU,   UI_PROP_TOUCH_ACTION_BEEP, UI_PROP_STATISTICS, UI_PROP_RESTRICTED, UI_PROP_CP_APP_MODE,   UI_PROP_SCROLL_COLOR, UI_PROP_INPUT_ERROR_BEEP, UI_DEVICE_WIDTH =1000, UI_DEVICE_HEIGHT,   UI_DEVICE_COLOR_DEPTH, UI_DEVICE_SUPPORTS_TOUCH , UI_DEVICE_SUPPORTS_AUDIO, UI_DEVICE_SUPPORTS_VIDEO,   UI_DEVICE_SUPPORTS_SIGCAP, UI_DEVICE_SUPPORTS_COLOR_DISPLAY, UI_DEVICE_HAS_CAP_TOUCH_KEYPAD }
enum	UIPropertyString {   UI_PROP_DECIMAL_SEPARATOR =2000, UI_PROP_THOUSANDS_SEPARATOR, UI_PROP_DEFAULT_FONT, UI_PROP_RESOURCE_PATH,   UI_PROP_FILE_PREFIX, UI_PROP_KEYMAP, UI_PROP_CSS, UI_PROP_RESOURCE_DEFAULT_PATH,   UI_PROP_GUI_EXTENSIONS, UI_PROP_HTTP_HEADER_FIELDS, UI_PROP_CP_APP_DIR, UI_PROP_LANGUAGE,   UI_PROP_JS_ROOT, UI_PROP_PRINT_ROOT, UI_PROP_PRINT_CSS, UI_DEVICE_MODEL =3000 }

Functions
DllSpec const char *	gui_GetSvcVersion (int display)
DllSpec const char *	gui_GetVersion ()
DllSpec int	uiConfigLEDs (UILEDShape shape, int width, int height, unsigned off_rgba, unsigned on0_rgba, unsigned on1_rgba, unsigned on2_rgba, unsigned on3_rgba)
DllSpec int	uiConfigLEDs (const char *filename)
DllSpec int	uiConfirm (int display, int region_id, const std::string &templateName, const std::string &text, uiCallback cb=0, void *cbdata=0)
DllSpec int	uiConfirmAsync (int display, int region_id, const std::string &templateName, const std::string &text, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiConfirmWait (int txn_id, int timeout_msec=-1)
DllSpec std::string	uiCurrentRegionPath (int display)
DllSpec int	uiDisplay (int display, int region_id, const std::string &templateName, const std::string &text)
DllSpec int	uiDisplay (int display, int region_id, const std::string &text)
DllSpec int	uiDisplayAsync (int display, int region_id, const std::string &text, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiDisplayAsync (int display, int region_id, const std::string &templateName, const std::string &text, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiDisplayCount ()
DllSpec int	uiDisplayWait (int txn_id, int timeout_msec=-1)
DllSpec int	uiEnterRegion (int display, int region_id)
DllSpec const std::vector< UIErrorEntry > &	uiErrorList ()
DllSpec int	uiGetBacklightConfig (int display, std::vector< UIBacklight > &levels)
DllSpec int	uiGetBacklightLevel (int display, int &level)
DllSpec std::string	uiGetCatalog (int display)
DllSpec int	uiGetHtml (int display, const std::map< std::string, std::string > &value, const std::string &text, std::string &html)
DllSpec int	uiGetHtmlURL (int display, const std::map< std::string, std::string > &value, const std::string &url, std::string &html)
DllSpec int	uiGetIdleTime (int display=0)
DllSpec int	uiGetLayout (int display, std::vector< UIRegion > &region)
DllSpec bool	uiGetLocalProperties ()
DllSpec unsigned	uiGetLogMask (void)
DllSpec int	uiGetPropertyInt (int display, enum UIPropertyInt property, int *value)
DllSpec int	uiGetPropertyString (int display, enum UIPropertyString property, char *value, int len)
DllSpec int	uiGetPropertyString (int display, enum UIPropertyString property, std::string &value)
DllSpec std::string	uiGetTerminalResourceDir (int display, const std::string &www_path)
DllSpec std::string	uiGetText (int display, const std::string &name, const std::string &deflt="")
DllSpec std::string	uiGetURLPath (int display, const std::string &url)
DllSpec int	uiHideLEDArea ()
DllSpec int	uiHTML2PNG (const char *filename, int width, int height, const std::map< std::string, std::string > &value, const std::string &text)
DllSpec int	uiHTML2PNGData (std::vector< unsigned char > &data, int width, int height, const std::map< std::string, std::string > &value, const std::string &text)
DllSpec int	uiInput (int display, int region_id, const std::string &templateName, std::vector< std::string > &value, const std::string &text, uiCallback cb=0, void *cbdata=0)
DllSpec int	uiInputAsync (int display, int region_id, const std::string &templateName, const std::vector< std::string > &value, const std::string &text, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiInputPINCheck (int display, int region_id, const std::string &templateName, const std::string &referencePIN, const std::string &text, uiCallback cb=0, void *cbdata=0)
DllSpec int	uiInputPINCheckAsync (int display, int region_id, const std::string &templateName, const std::string &referencePIN, const std::string &text, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiInputPINCheckWait (int txn_id, int timeout_msec=-1)
DllSpec int	uiInputWait (int txn_id, std::vector< std::string > &value, int timeout_msec=-1)
DllSpec int	uiInvoke (int display, int region_id, stringmap &value, const std::string &text, uiCallback cb=0, void *cbdata=0)
DllSpec int	uiInvokeAsync (int display, int region_id, const stringmap &value, const std::string &text, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiInvokeCancel (int txn_id, std::map< std::string, std::string > &value)
int	uiInvokeCancel (int txn_id)
DllSpec int	uiInvokeCancelAsync (int txn_id)
DllSpec int	uiInvokeTemplate (int display, int region_id, stringmap &value, const std::string &template_name, const std::string &text, uiCallback cb=0, void *cbdata=0)
DllSpec int	uiInvokeTemplateAsync (int display, int region_id, const stringmap &value, const std::string &template_name, const std::string &text, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiInvokeURL (int display, int region_id, stringmap &value, const char *url, uiCallback cb=0, void *cbdata=0)
DllSpec int	uiInvokeURL (int display, int region_id, stringmap &value, const std::string &url, uiCallback cb=0, void *cbdata=0)
DllSpec int	uiInvokeURLAsync (int display, int region_id, const stringmap &value, const char *url, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiInvokeURLAsync (int display, int region_id, const stringmap &value, const std::string &url, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiInvokeURLDetached (int display, int region_id, const char *url)
DllSpec int	uiInvokeWait (int txn_id, std::map< std::string, std::string > &value, int timeout_msec=-1)
int	uiInvokeWait (int txn_id, int timeout_msec=-1)
DllSpec int	uiLayout (int display, const UIRegion *region, int regcnt, const UIRegion *oldreg, int oldregcnt)
DllSpec int	uiLayout (int display, const UIRegion *region, int regcnt)
DllSpec int	uiLayout (const UIRegion *region, int regcnt)
int	uiLayout (int display, const std::vector< UIRegion > &reg)
int	uiLayout (int display, const std::vector< UIRegion > &reg, const std::vector< UIRegion > &oldreg)
DllSpec int	uiLayout (int display, const char *name)
DllSpec int	uiLeaveRegion (int display)
DllSpec const char *	uiLibVersion ()
DllSpec int	uiMenu (int display, int region_id, const std::string &templateName, const std::string &text, const struct UIMenuEntry menu[], int menusize, int preselect, uiCallback cb=0, void *cbdata=0)
DllSpec int	uiMenuAsync (int display, int region_id, const std::string &templateName, const std::string &text, const struct UIMenuEntry menu[], int menusize, int preselect, uiAsyncCallback cb=0, void *data=0)
DllSpec int	uiMenuWait (int txn_id, int timeout_msec=-1)
DllSpec std::string	uiPrint (const char *format,...)
DllSpec std::string	uiPrintV (const char *format, va_list va)
DllSpec void	uiReadConfig (int display)
DllSpec int	uiScreenshotPNG (int display, const char *filename)
DllSpec int	uiScreenshotPNGData (int display, std::vector< unsigned char > &data)
DllSpec std::string	uiScriptError ()
DllSpec int	uiSetBacklightConfig (int display, const std::vector< UIBacklight > &levels)
DllSpec int	uiSetBacklightLevel (int display, int level)
DllSpec int	uiSetCatalog (int display, const std::string &filename)
DllSpec int	uiSetCurrentRegionPath (int display, const std::string &path)
DllSpec int	uiSetLED (unsigned led, bool state)
DllSpec void	uiSetLocalProperties (bool local)
DllSpec void	uiSetLogMask (unsigned mask)
DllSpec int	uiSetPropertyInt (int display, enum UIPropertyInt property, int value)
DllSpec int	uiSetPropertyString (int display, enum UIPropertyString property, const char *value)
int	uiSetPropertyString (int display, enum UIPropertyString property, const std::string &value)
DllSpec int	uiSetTransition (int display, int region_id, unsigned transtype, int duration_ms)
DllSpec int	uiShowLEDArea (UIEdge edge, int width, int height, unsigned bg_rgba)
DllSpec const UIStatistics &	uiStatistics ()
DllSpec int	uiURL2PNG (const char *filename, int width, int height, const std::map< std::string, std::string > &value, const std::string &url)
DllSpec int	uiURL2PNGData (std::vector< unsigned char > &data, int width, int height, const std::map< std::string, std::string > &value, const std::string &url)

Detailed Description

---

Data Structure Documentation

UIBacklight

struct UIBacklight

backlight brightness level

Data Fields
unsigned	brightness	brightness level (0..100)
unsigned	timeout	timeout in milliseconds after which to switch to the next level (if there is another one

UIMenuEntry

struct UIMenuEntry

structure for menu entries

Data Fields
unsigned	options	options, see vfigui::UIMenuOptions
string	text	text to be displayed
int	value	return value

UIRegion

struct UIRegion

structure describing the position and size of an output region

Data Fields
int	bottom	bottom position in pixels (+=height if negative)
int	flags	flags: UI_REGION_FLAG_HIDDEN
int	id	region ID, 0 is the default region
int	left	left position in pixels (+=width if negative)
int	right	right position in pixels (+=width if negative)
int	top	top position in pixels (+=height if negative)

UIStatistics

struct UIStatistics

Statistics information

Data Fields
TimeStamp	css	css loading and parsing has finished
TimeStamp	draw	sending drawing commands to gfx system has finished (initial drawing of the HTML page)
TimeStamp	html	html loading, parsing and layout has finished
TimeStamp	start	starting time

Typedef Documentation

uiAsyncCallback

typedef void(* uiAsyncCallback) (void *data, UICBType type, UICBData &uidata)

callback function that is called when a dialog has returned some data. In case of dialog sequences (e.g. a dialog uses the load-URL action) the callback is invoked after each step of the sequence.

Parameters

[in]	data	data pointer provided by the application
[in]	type	type / reason why the callback was invoked
[in]	uidata	object to access data of the current transaction

Note

The callback will be run within a different thread context, so make sure to use appropriate locking if required. All callback functions share the same thread. Therefore, do not use functions that block for a long time, in particular uiInvokeWait() must not be called.

uiCallback

typedef bool(* uiCallback) (void *data)

Parameter Overloading

Most functions take a display and region_id parameter. For convenience these functions are overloaded so that these parameters may be omitted when using the default display and region:

• When the default display is to be used, display may be omitted
• When the default region on the default display is to be used display and region_id may be omitted.

If the key-value map is not required for a specific purpose, an overloaded version is provided so that the key-value map can be omitted. callback function that is called at regular intervals while the dialog is displayed. If the callback returns false, the dialog is cancelled;

Parameters

[in]

data

data pointer provided by the application

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
UI_REGION_DEFAULT	default region ID

anonymous enum

anonymous enum

Enumerator
UI_REGION_FLAG_HIDDEN	do not show region: Hiding a region does not terminate the contained dialog

anonymous enum

anonymous enum

bit mask constants for describing the transition

Enumerator
UI_TRANS_UP	movement direction: up, depending on the transition type horizontal an vertical movement may be combined.
UI_TRANS_RIGHT	movement direction: right, depending on the transition type horizontal an vertical movement may be combined.
UI_TRANS_DOWN	movement direction: down, depending on the transition type horizontal an vertical movement may be combined.
UI_TRANS_LEFT	movement direction: left, depending on the transition type horizontal an vertical movement may be combined.
UI_TRANS_DIRECTION_MASK	mask containing the movement direction bits
UI_TRANS_EASE_IN	transition accelerates after the start
UI_TRANS_EASE_OUT	transition decelerates before the end
UI_TRANS_EASE_INOUT	combination of UI_TRANS_EASE_IN and UI_TRANS_EASE_OUT
UI_TRANS_EASE_MASK	mask containing the acceleration bits
UI_TRANS_NONE	No transition
UI_TRANS_SLIDE	The dialog slides to the screen shifting out the old one
UI_TRANS_SLIDEON	The dialog slides to the screen covering the old one
UI_TRANS_SWAP	The new dialog starts behind the old one. Then both slide to opposite sides and then back, this time with the new dialog in front.
UI_TRANS_CROSSFADE	Crossfade between old and new dialog. The movement direction flags are ignored.
UI_TRANS_TYPE_MASK	mask containing the transition type bits

UICBType

enum UICBType

Reason why the callback was invoked

Enumerator
UI_CB_RESULT	callback was invoked due to receiving the result
UI_CB_UPDATE	callback was invoked due to receiving an update event
UI_CB_LOAD	callback was invoked due to switching to a new dialog
UI_CB_ERROR_LIST	callback was invoked due to receiving error data
UI_CB_STATISTICS	callback was invoked due to receiving statistics data

UIEdge

enum UIEdge

Display edge selection

Enumerator
UI_EDGE_TOP	top edge of display
UI_EDGE_RIGHT	right edge of display
UI_EDGE_BOTTOM	bottom edge of display
UI_EDGE_LEFT	left edge of display

UIError

enum UIError

Verifone GUI namespace error codes returned by the functions

Enumerator
UI_ERR_OK	no error
UI_ERR_ABORT	abort by user
UI_ERR_BACK	user selected back button
UI_ERR_TIMEOUT	dialog timeout
UI_ERR_PROPERTY	the property does not exist
UI_ERR_WRONG_PIN	wrong PIN was entered
UI_ERR_PARAMETER	parameter error
UI_ERR_PERMISSION	insufficient permissions
UI_ERR_CANCELLED	the dialog has been cancelled by callback or by displaying another dialog
UI_ERR_REGION	the region is not known
UI_ERR_FAIL	generic error
UI_ERR_UNSUPPORTED	the function requested is not supported on the current platform/device/...
UI_ERR_INVALID	an invalid transaction ID was provided
UI_ERR_WAIT_TIMEOUT	timeout while waiting for the result of an async function
UI_ERR_CONNECTION_LOST	lost connection to browser
UI_ERR_PROTOCOL	data received violated the protocol
UI_ERR_SCRIPT	error occurred during script processing, check uiScriptError() for more information about the error
UI_ERR_FILE_READ	the file was not found or could not be read
UI_ERR_RESTRICTED	the dialog was not shown due to security restrictions, e.g. using more than 3 buttons
UI_ERR_MODIFIED	the old layout does not match
UI_ERR_ACTION	invalid action provided
UI_ERR_DISPLAY	invalid display
UI_ERR_PIN_ENTRY_DENIED	requesting too many PIN sessions in a short period of time.

UILEDShape

enum UILEDShape

LED shape

Enumerator
UI_SHAPE_RECTANGLE	rectangular shape
UI_SHAPE_ELLIPSE	elliptic shape

UIMenuOptions

enum UIMenuOptions

Verifone GUI namespace menu options

Enumerator
UI_MENU_DISABLED	show the menu entry as disabled or leave it out (depending on device)

UIPropertyInt

enum UIPropertyInt

Int properties for configuring global GUI options

Enumerator
UI_PROP_TIMEOUT	Idle timeout in milliseconds, set to -1 to deactivate
UI_PROP_PASSWORD_CHAR	Password masking character
UI_PROP_DEFAULT_FONT_SIZE	Default font size
UI_PROP_PIN_AUTO_ENTER	Automatically terminate the PIN entry when the maximum number of digits has been reached
UI_PROP_PIN_CLEAR_ALL	The clear key deletes all entered digits instead of only the last one
UI_PROP_PIN_BYPASS_KEY	Key code that is used for PIN bypass. Setting it to 0 disables PIN bypass. Supported bypass keys are: 13 (enter/confirm key), 8 (clear/backspace key) Add 1000 to disable bypass as soon as a digit has been entered, e.g. using 1013 will use the enter key as bypass key but only if no digit has been entered in between.
UI_PROP_PIN_ALGORITHM	value used for iPS_SelectPINAlgo(), e.g. EMV_PIN, see "Verix eVo Volume I: Operating System" or "MX 900 Series Programmers Guide"
UI_PROP_PIN_INTERCHAR_TIMEOUT	if >0: inter character timeout for PIN entry in milliseconds
UI_PROP_PASSWORD_SHOW_CHAR	Time (in ms) to show last entered password character before masking it (ignored for PIN entry)
UI_PROP_KEEP_DISPLAY	Determines whether the display is cleared (0) or whether the display keeps displaying the old content (1) when updating the layout using uiLayout. Keeping the display on layout updates does not work on all platforms, therefore, default is to clear.
UI_PROP_UPDATE_EVENTS	if not 0 send update events each time the content of an input field changes or if the URL changes due to a load action (default: 0)
UI_PROP_CIRCULAR_MENU	if not 0 the actions "up" and "down" actions of the menu will not stop at the start/end of the menu but jump to the last/first element instead. (default: 0)
UI_PROP_TOUCH_ACTION_BEEP	if set (1) beep when an action was triggered from the touch screen. (default: 0)
UI_PROP_STATISTICS	if not 0 update statistics information that can be read using uiStatistics. (default: 0)
UI_PROP_RESTRICTED	if set (1) only up to three digit keys may be entered in a row. (default: 0)
UI_PROP_CP_APP_MODE	if set (1) activate CP app specific restrictions, (default: 0)
UI_PROP_SCROLL_COLOR	RGBA color value used for the scrollbar overlays, the value is an unsigned cast to an int (default: 0x00000060)
UI_PROP_INPUT_ERROR_BEEP	if set (1) beep when an input character cannot be inserted into an input field (input field full or invalid character) (default: 0)
UI_DEVICE_WIDTH	width of the display in pixels
UI_DEVICE_HEIGHT	height of the display in pixels
UI_DEVICE_COLOR_DEPTH	color depth in bits
UI_DEVICE_SUPPORTS_TOUCH	1 if the device supports touch, else 0
UI_DEVICE_SUPPORTS_AUDIO	1 if the device supports audio output, else 0
UI_DEVICE_SUPPORTS_VIDEO	1 if the device supports video output, else 0
UI_DEVICE_SUPPORTS_SIGCAP	1 if the device supports signature capture, else 0
UI_DEVICE_SUPPORTS_COLOR_DISPLAY	1 if the device supports color display, else 0 (B/W display)
UI_DEVICE_HAS_CAP_TOUCH_KEYPAD	1 if the device has a capacitive touch keypad, else 0

UIPropertyString

enum UIPropertyString

String properties for configuring global GUI options

Enumerator
UI_PROP_DECIMAL_SEPARATOR	Decimal separator
UI_PROP_THOUSANDS_SEPARATOR	Thousands separator
UI_PROP_DEFAULT_FONT	Default font name
UI_PROP_RESOURCE_PATH	Resource path, default is www/<platform> (or resource/<platform>)
UI_PROP_FILE_PREFIX	prefix that is added in front of the URL in uiInvokeURL and to the template names, e.g. using "en/" would access the files in the subdirectory "en".
UI_PROP_KEYMAP	Keymap string of the format: "&lt;key>=&lt;char>&lt;char>...&lt;char>\n&lt;key>=&lt;char>..."
UI_PROP_CSS	name of a CSS file
UI_PROP_RESOURCE_DEFAULT_PATH	Resource default path, default is www/default (or resource/default)
UI_PROP_GUI_EXTENSIONS	comma separated list of extension names, default: "adkgui.js" (WebGUI only)
UI_PROP_HTTP_HEADER_FIELDS	newline separated list of header fields of the form "key: value" (WebGUI only)
UI_PROP_CP_APP_DIR	CP app directory, if set only dialogs from the app dir can be shown. It should point to the base app directory without platform, e.g. /home/sys14/www/<app-id> on V/OS
UI_PROP_LANGUAGE	ISO 639-1 language code. Setting the language loads catalog file <language>.ctlg. It is searched in the resource folder (e.g. www/VX820) and in the default resource folder (www/default)
UI_PROP_JS_ROOT	Setting this path activates the JavaScript filesystem module. I/O is restricted to happen inside this path. Use "$APPDIR" to refer to this path from within JavaScript. Images and videos may also use "$APPDIR" to refer to files in this path.
UI_PROP_PRINT_ROOT	Setting this path activates JavaScript printing support. Receipts to be printed are looked up relative to this path. Note JavaScript printing may not be available for some platforms.
UI_PROP_PRINT_CSS	Name of the CSS file used for JavaScript printing. Default is "print.css"
UI_DEVICE_MODEL	Terminal model name, e.g. "Razor" or "VX820"

Function Documentation

gui_GetSvcVersion()

DllSpec const char* gui_GetSvcVersion

(

int

display

)

returns a zero-terminated string with version and build information of guiserver/guiprtserver in ADK version string format: <major>.<minor>.<patch>-<build>, e.g. "1.2.3-4"

Parameters

[in]

display

display

Returns

version string

gui_GetVersion()

DllSpec const char* gui_GetVersion

(

)

returns a zero-terminated string with version and build information of libvfiguiprt in ADK version string format: <major>.<minor>.<patch>-<build>, e.g. "1.2.3-4"

Returns

version string

uiConfigLEDs() [1/2]

DllSpec int uiConfigLEDs	(	UILEDShape	shape,
		int	width,
		int	height,
		unsigned	off_rgba,
		unsigned	on0_rgba,
		unsigned	on1_rgba,
		unsigned	on2_rgba,
		unsigned	on3_rgba
	)

set LED configuration. If present the LED area is cleared with the background color and the LEDs are drawn in off-state.

Parameters

[in]	shape	LED shape
[in]	width	width of a single LED
[in]	height	height of a single LED
[in]	off_rgba	color of the LED when switched off
[in]	on0_rgba	color of LED 0 when switched on
[in]	on1_rgba	color of LED 1 when switched on
[in]	on2_rgba	color of LED 2 when switched on
[in]	on3_rgba	color of LED 3 when switched on

Returns

error code (see UIError)

uiConfigLEDs() [2/2]

DllSpec int uiConfigLEDs

(

const char *

filename

)

set LED configuration from PNG file. The PNG file has to contain 5 LEDs next to each other. The first LED shows the off state, the remaining 4 LEDs show the on state of the 4 LEDs on screen. The alpha channel is supported to display non-rectangular LEDs. If present the LED area is cleared with the background color and the LEDs are drawn in off-state.

Parameters

[in]

filename

file name of the PNG image

Returns

error code (see UIError)

uiConfirm()

DllSpec int uiConfirm	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::string &	text,
		uiCallback	cb = 0,
		void *	cbdata = 0
	)

Display an HTML confirmation dialog on screen using a template file.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	cb	optional callback function
[in]	cbdata	data pointer passed on to the callback function

Returns

error code (see UIError) or return value specified in the template

Note

display and region_id are optional, see Parameter Overloading

uiConfirmAsync()

DllSpec int uiConfirmAsync	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::string &	text,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously display an HTML confirmation dialog on screen using a template file.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

transaction ID or error code (see UIError)

Note

display and region_id are optional, see Parameter Overloading

use uiConfirmWait() to wait for the dialog to finish or use uiInvokeCancel() to cancel the dialog

uiConfirmWait()

DllSpec int uiConfirmWait	(	int	txn_id,
		int	timeout_msec = -1
	)

Wait for the confirm dialog to finish

Parameters

[in]	txn_id	transaction id as returned by uiConfirmAsync()
[in]	timeout_msec	timeout in milliseconds. In case of a negative timeout wait forever.

Returns

error code (see UIError) or return value specified in the HTML fragment. In case of a timeout UI_ERR_WAIT_TIMEOUT is returned and uiConfirmWait() may be called again.

uiCurrentRegionPath()

DllSpec std::string uiCurrentRegionPath

(

int

display

)

Return the current region path that was constructed using uiEnterRegion(). The region path contains the regions passed on to successive calls of uiEnterRegion() separated by '/', e.g calling the sequence uiEnterRegion(1); uiEnterRegion(2); uiEnterRegion(3); the region path would be "1/2/3". If no region path is used, the empty string is returned.

Parameters

[in]

display

display

Returns

current region path

Note

display is optional, see Parameter Overloading

uiDisplay() [1/2]

DllSpec int uiDisplay	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::string &	text
	)

Display an HTML document on screen using a template file.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).

Returns

error code (see UIError)

Note

display and region_id are optional, see Parameter Overloading

uiDisplay() [2/2]

DllSpec int uiDisplay	(	int	display,
		int	region_id,
		const std::string &	text
	)

Display an HTML document on screen

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).

Returns

error code (see UIError)

Note

display and region_id are optional, see Parameter Overloading

uiDisplayAsync() [1/2]

DllSpec int uiDisplayAsync	(	int	display,
		int	region_id,
		const std::string &	text,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously display an HTML document on screen

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

transaction ID or error code (see UIError)

Note

display and region_id are optional, see Parameter Overloading

use uiDisplayWait() to wait for the dialog to finish or use uiInvokeCancel() to cancel the dialog

uiDisplayAsync() [2/2]

DllSpec int uiDisplayAsync	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::string &	text,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously display an HTML document on screen using a template file.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

transaction ID or error code (see UIError)

Note

display and region_id are optional, see Parameter Overloading

use uiDisplayWait() to wait for the dialog to finish or use uiInvokeCancl() to cancel the dialog

uiDisplayCount()

DllSpec int uiDisplayCount

(

)

determine the number of displays

Returns

number of displays

uiDisplayWait()

DllSpec int uiDisplayWait	(	int	txn_id,
		int	timeout_msec = -1
	)

Wait for the result of the display

Parameters

[in]	txn_id	transaction id as returned by uiDisplayAsync()
[in]	timeout_msec	timeout in milliseconds. In case of a negative timeout wait forever.

Returns

error code (see UIError) or return value specified in the HTML fragment. In case of a timeout UI_ERR_WAIT_TIMEOUT is returned and uiDisplayWait() may be called again.

uiEnterRegion()

DllSpec int uiEnterRegion	(	int	display,
		int	region_id
	)

Enter region region_id making it the parent region for all successive uiLayout() and uiGetLayout() commands. This is used to create a tree of regions.

Parameters

[in]	display	display
[in]	region_id	region ID

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

a new default region is created if required.

uiErrorList()

DllSpec const std::vector<UIErrorEntry>& uiErrorList

(

)

obtain list of non-fatal errors that happened while displaying a dialog. In case of synchronous dialogs the error list is reset as part of displaying the dialog. In case of asynchronous dialogs this list is reset when displaying the dialog using one of the ui*Async functions and when calling uiInvokeWait (or one of the other ui*Wait functions)

Returns

reference to the error list of the last dialog shown in this thread.

uiGetBacklightConfig()

DllSpec int uiGetBacklightConfig	(	int	display,
		std::vector< UIBacklight > &	levels
	)

read backlight parameters

Parameters

[in]	display	display
[out]	levels	backlight brightness levels and timeouts

Returns

error code (see UIError)

uiGetBacklightLevel()

DllSpec int uiGetBacklightLevel	(	int	display,
		int &	level
	)

get backlight level

Parameters

[in]	display	display
[out]	level	current level in the range 0..levels.size()-1

Returns

error code (see UIError)

uiGetCatalog()

DllSpec std::string uiGetCatalog

(

int

display

)

Parameters

[in]

display

display

Returns

file name of the current catalog file or empty string in case none has been loaded

Note

display is optional, see Parameter Overloading

uiGetHtml()

DllSpec int uiGetHtml	(	int	display,
		const std::map< std::string, std::string > &	value,
		const std::string &	text,
		std::string &	html
	)

preprocess HTML code and return the resulting string

Parameters

[in]	display	display whose settings should be used (e.g. text catalog, css file, etc.)
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[out]	html	resulting HTML code

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiGetHtmlURL()

DllSpec int uiGetHtmlURL	(	int	display,
		const std::map< std::string, std::string > &	value,
		const std::string &	url,
		std::string &	html
	)

preprocess HTML code and return the resulting string

Parameters

[in]	display	display whose settings should be used (e.g. text catalog, css file, etc.)
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX) unless an absolute path was provided.
[out]	html	resulting HTML code

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiGetIdleTime()

DllSpec int uiGetIdleTime

(

int

display = 0

)

Determine the amount of time passed since the last user interaction.

Returns

Idle time in milliseconds (>=0) or error code (<0).

uiGetLayout()

DllSpec int uiGetLayout	(	int	display,
		std::vector< UIRegion > &	region
	)

read the current layout setting

Parameters

[in]	display	display
[out]	region	returned region layout

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiGetLocalProperties()

DllSpec bool uiGetLocalProperties

(

)

Returns

true if thread local properties are used, else return false

uiGetLogMask()

DllSpec unsigned uiGetLogMask

(

void

)

Get log mask

Returns

current log mask

uiGetPropertyInt()

DllSpec int uiGetPropertyInt	(	int	display,
		enum UIPropertyInt	property,
		int *	value
	)

get int property

Parameters

[in]	display	display
[in]	property	property to be set
[out]	value	current value

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiGetPropertyString() [1/2]

DllSpec int uiGetPropertyString	(	int	display,
		enum UIPropertyString	property,
		char *	value,
		int	len
	)

get string property

Parameters

[in]	display	display
[in]	property	property to be set
[out]	value	current value
[in]	len	size ouf output buffer value in bytes

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiGetPropertyString() [2/2]

DllSpec int uiGetPropertyString	(	int	display,
		enum UIPropertyString	property,
		std::string &	value
	)

get string property

Parameters

[in]	display	display
[in]	property	property to be set
[out]	value	current value

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiGetTerminalResourceDir()

DllSpec std::string uiGetTerminalResourceDir	(	int	display,
		const std::string &	www_path
	)

determine the HW dependent terminal specific subdirectory inside the 'www' directory

Parameters

[in]	display	display
[in]	www_path	path of the www directory containing the resource files

Returns

path to the terminal specific subdirectory

Note

display is optional, see Parameter Overloading

The environment variable GUIPRT_APPNAME is not considered.

uiGetText()

DllSpec std::string uiGetText	(	int	display,
		const std::string &	name,
		const std::string &	deflt = ""
	)

lookup a text from current loaded catalog by key name. If text is not found in catalog or no catalog is loaded the function returns value in in parameter default.

Parameters

[in]	display	display
[in]	name	of key used to lookup the text in calalog
[in]	deflt	text that is returned, if text is not found in calalog

Returns

text from catalog for success, else value in parameter default

Note

display is optional, see Parameter Overloading

uiGetURLPath()

DllSpec std::string uiGetURLPath	(	int	display,
		const std::string &	url
	)

determine the full path of an url taking into account all settings and rules for looking up files

Parameters

[in]	display	display whose settings should be used (e.g. text catalog, css file, etc.)
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX) unless an absolute path was provided.

Returns

full path of the HTML file or empty string if not found.

Note

display is optional, see Parameter Overloading

uiHideLEDArea()

DllSpec int uiHideLEDArea

(

)

Decrement the LED area reference counter and hide the LED area if the counter reaches 0.

Returns

error code (see UIError)

uiHTML2PNG()

DllSpec int uiHTML2PNG	(	const char *	filename,
		int	width,
		int	height,
		const std::map< std::string, std::string > &	value,
		const std::string &	text
	)

convert a dialog to a PNG image

Parameters

[in]	filename	file name of the PNG file
[in]	width	width of the image
[in]	height	height of the image
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	text	HTML code

Returns

error code (see UIError)

uiHTML2PNGData()

DllSpec int uiHTML2PNGData	(	std::vector< unsigned char > &	data,
		int	width,
		int	height,
		const std::map< std::string, std::string > &	value,
		const std::string &	text
	)

convert a dialog to a PNG image

Parameters

[out]	data	data of PNG file
[in]	width	width of the image
[in]	height	height of the image
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	text	HTML code

Returns

error code (see UIError)

uiInput()

DllSpec int uiInput	(	int	display,
		int	region_id,
		const std::string &	templateName,
		std::vector< std::string > &	value,
		const std::string &	text,
		uiCallback	cb = 0,
		void *	cbdata = 0
	)

Display an HTML input dialog on screen using a template file.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in,out]	value	initial value and returned value of the input fields. The first value refers to the first input field, the second to the second, etc.
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>). The input fields have to be specified as HTML input fields (e.g. <input type='text' ...>). The following input types are supported: text: text input password: password input checkbox: checkbox number: numeric input (HTML extension) mask: masked input (HTML extension) pin: PIN input The following attributes are supported: allowed_chars: list of allowed characters mask: input mask (HTML extension): '*' is used as place holder for filling in characters maxlengh: maximum input length name: name of the input field precision: number of decimal places size: size of the input field in characters for display on screen
[in]	cb	optional callback function
[in]	cbdata	data pointer passed on to the callback function

Returns

error code (see UIError) or return value specified in the template

Note

display and region_id are optional, see Parameter Overloading

PIN input cannot be combined with other input types since the keyboard is exclusively locked by the PIN entry function. In case of PIN entry the value returned in value is the number of digits entered or "error" in case of an error, "cancel" if the user pressed CANCEL, "clear" if the user pressed CLEAR, "bypass" in case of PIN bypass and "timeout" in case of timeout.

Radio buttons will not behave as expected since these use more than one input element to represent a single input value.

uiInputAsync()

DllSpec int uiInputAsync	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::vector< std::string > &	value,
		const std::string &	text,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously display an HTML input dialog on screen using a template file.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	value	initial value of the input fields. The first value refers to the first input field, the second to the second, etc.
[in]	text	string containing an HTML fragment
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

transaction ID or error code (see UIError)

Note

display and region_id are optional, see Parameter Overloading

see also uiInput()

use uiInputWait() to wait for the dialog to finish or use uiInvokeCancel() to cancel the dialog

uiInputPINCheck()

DllSpec int uiInputPINCheck	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::string &	referencePIN,
		const std::string &	text,
		uiCallback	cb = 0,
		void *	cbdata = 0
	)

Display a PIN check dialog: The entered PIN is checkec against a known PIN

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	referencePIN	reference PIN
[in]	text	string containing an HTML fragment
[in]	cb	optional callback function
[in]	cbdata	data pointer passed on to the callback function

Returns

error code (see UIError) (UI_ERR_WRON_PIN in case of a wrong PIN, UI_ERR_OK in case the PIN was OK)

Note

display and region_id are optional, see Parameter Overloading

uiInputPINCheckAsync()

DllSpec int uiInputPINCheckAsync	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::string &	referencePIN,
		const std::string &	text,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously display a PIN check dialog: The entered PIN is checkec against a known PIN

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	text	string containing an HTML fragment
[in]	referencePIN	reference PIN
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

transaction ID or error code (see UIError)

Note

display and region_id are optional, see Parameter Overloading

use uiInputPINCheckWait() to wait for the dialog to finish or use uiInvokeCancel() to cancel the dialog

uiInputPINCheckWait()

DllSpec int uiInputPINCheckWait	(	int	txn_id,
		int	timeout_msec = -1
	)

Wait for the PIN check dialog to finish

Parameters

[in]	txn_id	transaction id as returned by uiInputPINCheckAsync()
[in]	timeout_msec	timeout in milliseconds. In case of a negative timeout wait forever.

Returns

error code (see UIError) or return value specified in the HTML fragment. In case of a timeout UI_ERR_WAIT_TIMEOUT is returned and uiInputPINCheckWait() may be called again.

Note

update events are currently not supported for uiInputPINCheckWait().

uiInputWait()

DllSpec int uiInputWait	(	int	txn_id,
		std::vector< std::string > &	value,
		int	timeout_msec = -1
	)

Wait for the input dialog to finish

Parameters

[in]	txn_id	transaction id as returned by uiInputAsync()
[in]	value	returned value of the input fields. The first value refers to the first input field, the second to the second, etc.
[in]	timeout_msec	timeout in milliseconds. In case of a negative timeout wait forever.

Returns

error code (see UIError) or return value specified in the HTML fragment. In case of a timeout UI_ERR_WAIT_TIMEOUT is returned and uiInputWait() may be called again.

uiInvoke()

DllSpec int uiInvoke	(	int	display,
		int	region_id,
		stringmap &	value,
		const std::string &	text,
		uiCallback	cb = 0,
		void *	cbdata = 0
	)

Invoke an HTML dialog.

Parameters

[in]	display	display
[in]	region_id	region ID
[in,out]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing. On return value contains the updated input values.
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	cb	optional callback function
[in]	cbdata	data pointer passed on to the callback function

Returns

error code (see UIError) or return value specified in the HTML fragment

Note

display, region_id and value are optional, see Parameter Overloading

uiInvokeAsync()

DllSpec int uiInvokeAsync	(	int	display,
		int	region_id,
		const stringmap &	value,
		const std::string &	text,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously invoke an HTML dialog.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

error code (see UIError) or transaction ID. The transaction ID is required for obtaining the dialog result using uiInvokeWait()

Note

display, region_id and value are optional, see Parameter Overloading

If no callback was provided, uiInvokeWait() must be called to obtain the result and release allocated memory or uiInvokeCancel() needs to be called to cancel the dialog. If a callback was provided uiInvokeWait() cannot be used and will return UI_ERR_INVALID.

uiInvokeCancel() [1/2]

DllSpec int uiInvokeCancel	(	int	txn_id,
		std::map< std::string, std::string > &	value
	)

Cancel dialog. This may be called whenever uiInvokeWait() can be called and cancels the dialog.

Parameters

[in]	txn_id	Request ID of the dialog
[out]	value	entered values are added to this map

Returns

error code (see UIError). For asynchronous calls with callback function the return value cannot be obtained since it is delivered to the callback function. In this case always UI_ERR_OK is returned. Normally the error code will be UI_ERR_CANCELLED, however, the returncode reflects the true result of the dialog, i.e. if the user terminated the dialog just before cancelling it, the returncode will contain the result of the dialog.

uiInvokeCancel() [2/2]

int uiInvokeCancel ( int  txn_id )

inline

the same as uiInvokeCancel(int txn_id, std::map<std::string,std::string> &value) but discards returned input values

uiInvokeCancelAsync()

DllSpec int uiInvokeCancelAsync

(

int

txn_id

)

Cancel dialog without reading the result, i.e. uiInvokeWait() will have to be called afterwards.

Parameters

[in]

txn_id

Request ID of the dialog

Returns

error code

uiInvokeTemplate()

DllSpec int uiInvokeTemplate	(	int	display,
		int	region_id,
		stringmap &	value,
		const std::string &	template_name,
		const std::string &	text,
		uiCallback	cb = 0,
		void *	cbdata = 0
	)

Invoke an HTML dialog with template: The provided text is inserted into the template file and then displayed.

Parameters

[in]	display	display
[in]	region_id	region ID
[in,out]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing. On return value contains the updated input values.
[in]	template_name	file name of template into which text is inserted
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	cb	optional callback function
[in]	cbdata	data pointer passed on to the callback function

Returns

error code (see UIError) or return value specified in the HTML fragment

Note

display, region_id and value are optional, see Parameter Overloading

uiInvokeTemplateAsync()

DllSpec int uiInvokeTemplateAsync	(	int	display,
		int	region_id,
		const stringmap &	value,
		const std::string &	template_name,
		const std::string &	text,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously invoke an HTML dialog. The provided text is inserted into the template file and then the dialog is displayed

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	template_name	template file
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

error code (see UIError) or transaction ID. The transaction ID is required for obtaining the dialog result using uiInvokeWait()

Note

display, region_id and value are optional, see Parameter Overloading

If no callback was provided, uiInvokeWait() must be called to obtain the result and release allocated memory or uiInvokeCancel() needs to be called to cancel the dialog. If a callback was provided uiInvokeWait() cannot be used and will return UI_ERR_INVALID.

uiInvokeURL() [1/2]

DllSpec int uiInvokeURL	(	int	display,
		int	region_id,
		stringmap &	value,
		const char *	url,
		uiCallback	cb = 0,
		void *	cbdata = 0
	)

display a dialog

Parameters

[in]	display	display
[in]	region_id	region ID
[in,out]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing. On return value contains the updated input values.
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX)
[in]	cb	optional callback function
[in]	cbdata	data pointer passed on to the callback function

Returns

error code (see UIError) or return value specified in the HTML fragment

Note

display, region_id and value are optional, see Parameter Overloading

uiInvokeURL() [2/2]

DllSpec int uiInvokeURL	(	int	display,
		int	region_id,
		stringmap &	value,
		const std::string &	url,
		uiCallback	cb = 0,
		void *	cbdata = 0
	)

display a dialog

Parameters

[in]	display	display
[in]	region_id	region ID
[in,out]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing. On return value contains the updated input values.
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX)
[in]	cb	optional callback function
[in]	cbdata	data pointer passed on to the callback function

Returns

error code (see UIError) or return value specified in the HTML fragment

Note

display, region_id and value are optional, see Parameter Overloading

uiInvokeURLAsync() [1/2]

DllSpec int uiInvokeURLAsync	(	int	display,
		int	region_id,
		const stringmap &	value,
		const char *	url,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously invoke an HTML dialog

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX)
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

error code (see UIError) or transaction ID. The transaction ID is required for obtaining the dialog result using uiInvokeWait()

Note

display, region_id and value are optional, see Parameter Overloading

If no callback was provided, uiInvokeWait() must be called to obtain the result and release allocated memory or uiInvokeCancel() needs to be called to cancel the dialog. If a callback was provided uiInvokeWait() cannot be used and will return UI_ERR_INVALID.

uiInvokeURLAsync() [2/2]

DllSpec int uiInvokeURLAsync	(	int	display,
		int	region_id,
		const stringmap &	value,
		const std::string &	url,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously invoke an HTML dialog

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX)
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

error code (see UIError) or transaction ID. The transaction ID is required for obtaining the dialog result using uiInvokeWait()

Note

display, region_id and value are optional, see Parameter Overloading

If no callback was provided, uiInvokeWait() must be called to obtain the result and release allocated memory or uiInvokeCancel() needs to be called to cancel the dialog. If a callback was provided uiInvokeWait() cannot be used and will return UI_ERR_INVALID.

uiInvokeURLDetached()

DllSpec int uiInvokeURLDetached	(	int	display,
		int	region_id,
		const char *	url
	)

Create a new thread and display a dialog from within this thread. The thread terminates when the dialog terminates. Dialog return values are discarded.

Parameters

[in]	display	display
[in]	region_id	region id
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX)

Returns

error code (see UIError) (but no result from dialog)

Note

display and region_id are optional, see Parameter Overloading

This function is useful for example for displaying some kind of virtual keyboard.

uiInvokeWait() [1/2]

DllSpec int uiInvokeWait	(	int	txn_id,
		std::map< std::string, std::string > &	value,
		int	timeout_msec = -1
	)

Wait for a dialog to finish

Parameters

[in]	txn_id	Request ID of the dialog
[out]	value	entered values are added to this map
[in]	timeout_msec	timeout in milliseconds. In case of a negative timeout wait forever.

Returns

error code (see UIError) or return value specified in the HTML fragment. In case of a timeout UI_ERR_WAIT_TIMEOUT is returned and uiInvokeWait() has to be called again or memory may be leaked. As an alternative uiInvokeCancel() may be called to cancel the dialog.

Note

uiInvokeWait cannot be called if a callback function has been provided when invoking the dialog.

When displaying dialog sequences (e.g. using load url in an action) uiInvokeWait() handles the switching to the next dialog in the sequence.

uiInvokeWait() [2/2]

int uiInvokeWait ( int  txn_id, int  timeout_msec = -1  )

inline

the same as uiInvokeWait(int txn_id, std::map<std::string,std::string> &value, int timeout_msec=-1) but discards returned input values

uiLayout() [1/6]

DllSpec int uiLayout	(	int	display,
		const UIRegion *	region,
		int	regcnt,
		const UIRegion *	oldreg,
		int	oldregcnt
	)

define output regions on the display. Region with id==0 is the default region. For incremental layout updates the previous layout may be provided to be checked before applying the new layout. If the previous layout does not match the current layout in guiserver, UI_ERR_MODIFIED is returned. This feature can be used to detect and prevent race conditions if several processes concurrently try to update a layout.

Parameters

[in]	display	display
[in]	region	array containing the regions, at least one region must be provided
[in]	regcnt	number of entries in region
[in]	oldreg	optional: if not NULL array containing the previous set of regions
[in]	oldregcnt	optional: number of entries in oldreg

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

If a region is removed that still contains a dialog this dialog is cancelled.

uiLayout() [2/6]

DllSpec int uiLayout	(	int	display,
		const UIRegion *	region,
		int	regcnt
	)

shortcut for uiLayout(display, region,regcnt,0,0);

uiLayout() [3/6]

DllSpec int uiLayout	(	const UIRegion *	region,
		int	regcnt
	)

shortcut for uiLayout(0,region,regcnt,0,0);

uiLayout() [4/6]

int uiLayout ( int  display, const std::vector< UIRegion > &  reg  )

inline

define output regions on the display. Region with id==0 is the default region.

Parameters

[in]	display	display
[in]	reg	vector containing the regions, at least one region must be provided

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

If a region is removed that still contains a dialog this dialog is cancelled.

uiLayout() [5/6]

int uiLayout ( int  display, const std::vector< UIRegion > &  reg, const std::vector< UIRegion > &  oldreg  )

inline

define output regions on the display. Region with id==0 is the default region. The old layout provided in oldreg must match the current layout in guiserver or the layout will not be updated and UI_ERR_MODIFIED will be returned.

Parameters

[in]	display	display
[in]	reg	vector containing the regions, at least one region must be provided
[in]	oldreg	vector containing the previous set of regions.

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

If a region is removed that still contains a dialog this dialog is cancelled.

uiLayout() [6/6]

DllSpec int uiLayout	(	int	display,
		const char *	name
	)

define output regions of the display. The layout definition is read from section name of gui.ini

Parameters

[in]	display	display
[in]	name	name of the layout section in gui.ini

Returns

error code (see UIError), in case the section is not found in gui.ini or it is does not contain a valid configuration, then UI_ERR_REGION is returned.

Note

display is optional, see Parameter Overloading

changing the layout may cancel all currently active dialogs

uiLeaveRegion()

DllSpec int uiLeaveRegion

(

int

display

)

Ascend one level in the tree of regions.

Returns

error code: UI_ERR_OK if region was left, UI_ERR_REGION if already at the highest level

Note

display is optional, see Parameter Overloading

uiLibVersion()

DllSpec const char* uiLibVersion

(

)

read library version

Returns

string containing the version

uiMenu()

DllSpec int uiMenu	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::string &	text,
		const struct UIMenuEntry	menu[],
		int	menusize,
		int	preselect,
		uiCallback	cb = 0,
		void *	cbdata = 0
	)

Display an HTML menu dialog on screen using a template file.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	text	string containing an HTML fragment (i.e. the part between <body> and lt;/body>).
[in]	menu	array containing menu entries
[in]	menusize	number of entries in the array
[in]	preselect	value of the menu entry to be preselected.
[in]	cb	optional callback function
[in]	cbdata	data pointer passed on to the callback function

Returns

error code (see UIError) or value of selected menu entry.

Note

display and region_id are optional, see Parameter Overloading

uiMenuAsync()

DllSpec int uiMenuAsync	(	int	display,
		int	region_id,
		const std::string &	templateName,
		const std::string &	text,
		const struct UIMenuEntry	menu[],
		int	menusize,
		int	preselect,
		uiAsyncCallback	cb = 0,
		void *	data = 0
	)

Asynchronously display an HTML menu dialog on screen using a template file.

Parameters

[in]	display	display
[in]	region_id	region ID
[in]	templateName	name of a template file. The HTML code found in text is inserted into the template
[in]	text	string containing an HTML fragment (i.e. the part between <body> and </body>).
[in]	menu	array containing menu entries
[in]	menusize	number of entries in the array
[in]	preselect	value of the menu entry to be preselected.
[in]	cb	optional callback function that is called when the dialog has returned
[in]	data	data pointer that is passed on to the callback function

Returns

transaction ID or error code (see UIError)

Note

display and region_id are optional, see Parameter Overloading

use uiMenuWait() to wait for the dialog to finish or use uiInvokeCancel() to cancel the dialog

uiMenuWait()

DllSpec int uiMenuWait	(	int	txn_id,
		int	timeout_msec = -1
	)

Wait for the menu dialog to finish

Parameters

[in]	txn_id	transaction id as returned by uiMenuAsync()
[in]	timeout_msec	timeout in milliseconds. In case of a negative timeout wait forever.

Returns

error code (see UIError) or value of selected menu entry. In case of a timeout UI_ERR_WAIT_TIMEOUT is returned and uiMenuWait() may be called again.

uiPrint()

DllSpec std::string uiPrint	(	const char *	format,
			...
	)

perform printf-like formatting.

Parameters

[in]

format

printf-like format string. It supports the commonly known format specifiers 's', 'i', 'd', 'u', 'o', 'x', 'X', 'p', 'c', 'f', 'e', 'g'. In addition the following format specifiers are supported: 'S': format as string and substitute the special HTML characters '&', '<', '>', '"' and '\'' by character references (e.g. '&amp;', '&lt;' ...). 'C': format as character and sustitute HTML characters

Returns

formatted string

uiPrintV()

DllSpec std::string uiPrintV	(	const char *	format,
		va_list	va
	)

perfom printf-like formatting. This is the same as uiPrint() just taking a va_list instead of a variable number of arguments

uiReadConfig()

DllSpec void uiReadConfig

(

int

display

)

re-read configuration from file gui.ini from within the resource directory associated with a display

Parameters

[in]

display

display

Note

display is optional, see Parameter Overloading

gui.ini is read automatically on startup. Invoking uiReadConfig() is required if gui.ini has been modified by the application or the resource path has been changed by updating UI_PROP_RESOURCE_PATH and re-reading of the file is required.

uiScreenshotPNG()

DllSpec int uiScreenshotPNG	(	int	display,
		const char *	filename
	)

take a screenshot and save as PNG file

Parameters

[in]	display	display
[in]	filename	file name

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

Only supported by DirectGUI

uiScreenshotPNGData()

DllSpec int uiScreenshotPNGData	(	int	display,
		std::vector< unsigned char > &	data
	)

take a screenshot and return PNG data in vector

Parameters

[in]	display	display
[out]	data	data of PNG file

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

Only supported by DirectGUI

uiScriptError()

DllSpec std::string uiScriptError

(

)

Obtain script error message

Returns

string containing information about errors that were reported during last script processing in this thread.

uiSetBacklightConfig()

DllSpec int uiSetBacklightConfig	(	int	display,
		const std::vector< UIBacklight > &	levels
	)

set up backlight parameters

Parameters

[in]	display	display
[in]	levels	backlight brightness levels and timeouts. The entries in the vectore are considered to represent decreasing brightness, i.e. levels[0] represents maximum brighness and levels[levels.size()-1] represents minimum brightness.

Returns

error code (see UIError)

Note

If more than one brightness level is configured, the first level is considered to be the on state. This level is activated as soon as there is some user interaction. The last level is considered to be the off state. In this state, the first touch or keypress is used to wake up the device and is otherwise dropped to not inadvertedly trigger an action.

uiSetBacklightLevel()

DllSpec int uiSetBacklightLevel	(	int	display,
		int	level
	)

set backlight level to one of the levels defined using uiSetBacklightParam

Parameters

[in]	display	display
[in]	level	new level in the range 0..levels.size()-1

Returns

error code (see UIError)

Note

The level is evaluated modulus the number of configured levels, i.e. setting it to -1 can be used to select the level with lowest brightness.

uiSetCatalog()

DllSpec int uiSetCatalog	(	int	display,
		const std::string &	filename
	)

load and set a catalog file containing name-value text pairs to be inserted with HTML placeholder <?text name?>. The current catalog is unloaded with filename=="" or by loading another catalog file.

Parameters

[in]	display	display
[in]	filename	of the catalog, empty string to unload the current dialog

Returns

UI_ERR_OK if file was successfully loaded, else error code (see UIError)

Note

display is optional, see Parameter Overloading

Setting the catalog file resets UI_PROP_LANGUAGE

uiSetCurrentRegionPath()

DllSpec int uiSetCurrentRegionPath	(	int	display,
		const std::string &	path
	)

set region path.

Parameters

[in]	display	display
[in]	path	absolute region path to be set

Returns

error code

Note

display is optional, see Parameter Overloading

uiSetLED()

DllSpec int uiSetLED	(	unsigned	led,
		bool	state
	)

switch led on/off

Parameters

[in]	led	led number (0..3)
[in]	state	on (true) or off (false)

Returns

error code (see UIError)

uiSetLocalProperties()

DllSpec void uiSetLocalProperties

(

bool

local

)

de-/activate thread local properties for the current thread. Activating thread local properties initially copies the global properties to the current thread.

Parameters

[in]

local

if true activate thread local properties, if false discard them

Note

Switching affects all displays.

uiSetLogMask()

DllSpec void uiSetLogMask

(

unsigned

mask

)

Set log mask

Parameters

[in]

mask

logging mask (see GUI_LOGMASK)

uiSetPropertyInt()

DllSpec int uiSetPropertyInt	(	int	display,
		enum UIPropertyInt	property,
		int	value
	)

set int property

Parameters

[in]	display	display
[in]	property	property to be set
[in]	value	new value

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiSetPropertyString() [1/2]

DllSpec int uiSetPropertyString	(	int	display,
		enum UIPropertyString	property,
		const char *	value
	)

set string property

Parameters

[in]	display	display
[in]	property	property to be set
[in]	value	new value

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiSetPropertyString() [2/2]

int uiSetPropertyString ( int  display, enum UIPropertyString  property, const std::string &  value  )

inline

set string property

Parameters

[in]	display	display
[in]	property	property to be set
[in]	value	new value

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

uiSetTransition()

DllSpec int uiSetTransition	(	int	display,
		int	region_id,
		unsigned	transtype,
		int	duration_ms
	)

set the transition type for a region

Parameters

[in]	display	display
[in]	region_id	region id;
[in]	transtype	transition type
[in]	duration_ms	duration for the transition in milliseconds, ignored for UI_TRANS_NONE which is the default transition type.

Returns

error code (see UIError)

Note

display is optional, see Parameter Overloading

Configured transitions are reset when changing the layout

uiShowLEDArea()

DllSpec int uiShowLEDArea	(	UIEdge	edge,
		int	width,
		int	height,
		unsigned	bg_rgba
	)

show virtual LEDs on the display and/or increment the LED area reference counter. The LED area is cleared with the background color and the LEDs are drawn in off-state.

Parameters

[in]	edge	selects edge of the display at which to reserve some room. UI_EDGE_OFF removes the LED area
[in]	width	width of the area
[in]	height	height of the area
[in]	bg_rgba	background color in RGBA format (alpha channel is ignored)

Returns

error code (see UIError)

Note

If uiShowLEDArea is called more than once, then the later calls do not update the parameters but only increase a reference counter. uiHideLEDArea() has to be called the same number of times to remove the area.

uiConfigLEDs should be called before calling uiShowLEDArea().

uiStatistics()

DllSpec const UIStatistics& uiStatistics

(

)

obtain statistics information for the last completed dialog. In case of synchronous dialogs the statistics information is reset as part of displaying the dialog. In case of asynchronous dialogs this information is reset as part of calling uiInvokeWait (or one of the other ui*Wait functions)

Returns

reference to statistics information of the last dialog shown in this thread.

uiURL2PNG()

DllSpec int uiURL2PNG	(	const char *	filename,
		int	width,
		int	height,
		const std::map< std::string, std::string > &	value,
		const std::string &	url
	)

convert a dialog to a PNG image

Parameters

[in]	filename	file name of the PNG file
[in]	width	width of the image
[in]	height	height of the image
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX) unless an absolute path was provided.

Returns

error code (see UIError)

uiURL2PNGData()

DllSpec int uiURL2PNGData	(	std::vector< unsigned char > &	data,
		int	width,
		int	height,
		const std::map< std::string, std::string > &	value,
		const std::string &	url
	)

convert a dialog to a PNG image

Parameters

[out]	data	data of PNG file
[in]	width	width of the image
[in]	height	height of the image
[in]	value	name value pairs that are used as initial value of input fields, checkboxes, etc. and that are used during script processing.
[in]	url	location of the dialog file. The location is prefixed by the resource path and by the optional prefix (see also UI_PROP_RESOURCE_PATH, UI_PROP_FILE_PREFIX) unless an absolute path was provided.

Returns

error code (see UIError)