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
const char *	gui_GetSvcVersion (int display)

const char *	gui_GetVersion ()

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

int	uiConfigLEDs (const char *filename)

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

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

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

std::string	uiCurrentRegionPath (int display)

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

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

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

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

int	uiDisplayCount ()

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

int	uiEnterRegion (int display, int region_id)

const std::vector< UIErrorEntry > &	uiErrorList ()

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

int	uiGetBacklightLevel (int display, int &level)

std::string	uiGetCatalog (int display)

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

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

int	uiGetIdleTime (int display=0)

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

bool	uiGetLocalProperties ()

unsigned	uiGetLogMask (void)

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

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

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

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

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

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

int	uiHideLEDArea ()

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

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

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)

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)

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)

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)

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

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

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

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

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

int	uiInvokeCancel (int txn_id)

int	uiInvokeCancelAsync (int txn_id)

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

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)

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

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

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

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

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

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)

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

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

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)

int	uiLayout (int display, const char *name)

int	uiLeaveRegion (int display)

const char *	uiLibVersion ()

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)

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)

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

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

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

void	uiReadConfig (int display)

int	uiScreenshotPNG (int display, const char *filename)

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

std::string	uiScriptError ()

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

int	uiSetBacklightLevel (int display, int level)

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

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

int	uiSetLED (unsigned led, bool state)

void	uiSetLocalProperties (bool local)

void	uiSetLogMask (unsigned mask)

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

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

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

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

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

const UIStatistics &	uiStatistics ()

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

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: "<key>=<char><char>...<char>\n<key>=<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()

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()

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]

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]

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()

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()

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()

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()

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]

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]

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]

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]

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()

int uiDisplayCount ( )

determine the number of displays

Returns: number of displays

§ uiDisplayWait()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

bool uiGetLocalProperties ( )

Returns: true if thread local properties are used, else return false

§ uiGetLogMask()

unsigned uiGetLogMask ( void )

Get log mask

Returns: current log mask

§ uiGetPropertyInt()

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]

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]

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()

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()

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()

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()

int uiHideLEDArea ( )

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

Returns: error code (see UIError)

§ uiHTML2PNG()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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]

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()

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()

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()

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]

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]

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]

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]

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()

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]

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]

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]

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

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

§ uiLayout() [3/6]

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]

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()

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()

const char* uiLibVersion ( )

read library version

Returns: string containing the version

§ uiMenu()

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()

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()

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()

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. '&', '<' ...).
'C': format as character and sustitute HTML characters

Returns: formatted string

§ uiPrintV()

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()

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()

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()

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()

std::string uiScriptError ( )

Obtain script error message

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

§ uiSetBacklightConfig()

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()

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()

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()

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()

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()

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()

void uiSetLogMask ( unsigned mask )

Set log mask

Parameters

[in] mask logging mask (see GUI_LOGMASK)

§ uiSetPropertyInt()

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]

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()

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()

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()

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()

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()

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)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

§ UIBacklight

§ UIMenuEntry

§ UIRegion

§ UIStatistics

Typedef Documentation

§ uiAsyncCallback

§ uiCallback

Parameter Overloading

Enumeration Type Documentation

§ anonymous enum

§ anonymous enum

§ anonymous enum

§ UICBType

§ UIEdge

§ UIError

§ UILEDShape

§ UIMenuOptions

§ UIPropertyInt

§ UIPropertyString

Function Documentation

§ gui_GetSvcVersion()

§ gui_GetVersion()

§ uiConfigLEDs() [1/2]

§ uiConfigLEDs() [2/2]

§ uiConfirm()

§ uiConfirmAsync()

§ uiConfirmWait()

§ uiCurrentRegionPath()

§ uiDisplay() [1/2]

§ uiDisplay() [2/2]

§ uiDisplayAsync() [1/2]

§ uiDisplayAsync() [2/2]

§ uiDisplayCount()

§ uiDisplayWait()

§ uiEnterRegion()

§ uiErrorList()

§ uiGetBacklightConfig()

§ uiGetBacklightLevel()

§ uiGetCatalog()

§ uiGetHtml()

§ uiGetHtmlURL()

§ uiGetIdleTime()

§ uiGetLayout()

§ uiGetLocalProperties()

§ uiGetLogMask()

§ uiGetPropertyInt()

§ uiGetPropertyString() [1/2]

§ uiGetPropertyString() [2/2]

§ uiGetTerminalResourceDir()

§ uiGetText()

§ uiGetURLPath()

§ uiHideLEDArea()

§ uiHTML2PNG()

§ uiHTML2PNGData()

§ uiInput()

§ uiInputAsync()

§ uiInputPINCheck()

§ uiInputPINCheckAsync()

§ uiInputPINCheckWait()

§ uiInputWait()

§ uiInvoke()

§ uiInvokeAsync()

§ uiInvokeCancel() [1/2]

§ uiInvokeCancel() [2/2]

§ uiInvokeCancelAsync()

§ uiInvokeTemplate()

§ uiInvokeTemplateAsync()

§ uiInvokeURL() [1/2]

§ uiInvokeURL() [2/2]

§ uiInvokeURLAsync() [1/2]

§ uiInvokeURLAsync() [2/2]

§ uiInvokeURLDetached()

§ uiInvokeWait() [1/2]

§ uiInvokeWait() [2/2]