Class GuiAPI

Index Home MAE > MAE Architecture > MAE Data Types > Class Index > Class GuiAPI

Summary
Public Methods
static bool prompt(device, question, prefillAnswer, queryType, cbapp, cbtag, cbdata, style)
static bool select(device, question, choices, cbtag, cbdata, defaultValue)
static bool textarea(device, question, origText, cbtag, cbdata, style, saveButtonLabel)
static bool checkbox(device, question, cbtag, cbdata, defaultValue, style)
static bool form(device, formName, formDefaults, cbtag, cbdata)
static bool run(device, appname, appparams)
static bool download(device, query, cbtag, cbdata, fileclass)
static bool registerMenu(device, menuname, menuoption, action)
static bool registerKey(device, keystroke, action)
static bool registerHotspot(device, region, action)
static bool redirectHotspot(device, region, otherapp)
static bool registerMouse(device, region, action)
static bool registerCommand(device, cmd, cmdparams)
static bool send(request, params)

#include <GuiAPI.h >

Summary

This class is used by other apps to send messages to the gui channel.

Use this interface instead of sending messages directly to ensure message keywords are spelled correctly, all parameters are specified, and error checked.

The receiving app defined this interface to ensure it receives the messages correctly.

Public Methods

static bool prompt(device, question, prefillAnswer, queryType, cbapp, cbtag, cbdata, style)

const UserDevice& device

the end-user's device

const string& question

the text prompt for the user; the user is answering this question

const string& prefillAnswer

(optional) the default input for the user

const string& queryType

the type of prompt for the user, e.g. text, int, YN, (dice)

const string& cbapp

(deprecated) the task where the user's response should be set.  Default: your app

const string& cbtag

when responding with the user's answer, this cbtag will be used (see handleInputResponse())

const XMLData& cbdata

when responding with the user's answer, this callback data will be provided

const string& style

(optional) the style to use when displaying this prompt

Default value: ""


Ask the user a question and provide instruction on where to send the answer.

Return value: true if sent successfully

static bool select(device, question, choices, cbtag, cbdata, defaultValue)

const UserDevice& device

the end-user's device

const string& question

the text prompt for the user; the user is answering this question

const HashArray& choices

key/value pairs of display text (key) and response text (value)

const string& cbtag

when responding with the user's answer, this cbtag will be used (see handleInputResponse())

const XMLData& cbdata

when responding with the user's answer, this callback data will be provided

const string& defaultValue

(optional) the default input for the user

Default value: ""


Provide the user with a question and a selection of choices. When the user selectrs a choice, send a response to the app.

Return value: true if sent successfully

static bool textarea(device, question, origText, cbtag, cbdata, style, saveButtonLabel)

const UserDevice& device

the end-user's device

const string& question

the text prompt for the user; the user is answering this question

string origText

prefill the text block with this text

const string& cbtag

when responding with the user's answer, this cbtag will be used (see handleInputResponse())

const XMLData& cbdata

when responding with the user's answer, this callback data will be provided

const string& style

(optional) the style to use when displaying this prompt

const string saveButtonLabel

(optional) the text for the button for the user to save the text


Setup an area where the user can type in a lot of text.  When the user saves the text, send a response to the app.

Return value: true if sent successfully

static bool checkbox(device, question, cbtag, cbdata, defaultValue, style)

const UserDevice& device

the end-user's device

const string& question

the text prompt for the user; the user is answering this question

const string& cbtag

when responding with the user's answer, this cbtag will be used (see handleInputResponse())

const XMLData& cbdata

when responding with the user's answer, this callback data will be provided

const bool defaultValue

(optional) the checked box when presented to user

Default value: ""

const string& style

Default value: ""


Provide the user with a set of checkboxes (radio buttons - select one at a time). When the user selects one, send a response to the app.

Return value: true if sent successfully

static bool form(device, formName, formDefaults, cbtag, cbdata)

const UserDevice& device

the end-user's device

const string& formName

the form (in ../html/form) to use with questions for the user

const HashArray& formDefaults

key/value pairs for form question ids (key) and filled in answers (value)

const string& cbtag

when responding with the user's answer, this cbtag will be used (see handleInputResponse())

const XMLData& cbdata

when responding with the user's answer, this callback data will be provided


Present the user with a form (see file in ../html/form).

Note that all the formDefault values will be merged into the cbdata hash array.  Don't use the same keys!

The cbtag & cbdata here is delivered to userInputFormValid() in guibroker:cmd.cpp for form validation.

The cbtag & cbdata here is delivered to messageResponse() in guibroker:cmd.cpp.

Return value: true if sent successfully

static bool run(device, appname, appparams)

const UserDevice& device

the end-user's device

const string& appname

the name of the MAE app

const XMLData& appparams

app-specific parameters for the MAE app


Run another app inside MAE.  The user's attention will be forced to the new app.  App-specific parameters may be provided.

Return value: true if sent successfully

static bool download(device, query, cbtag, cbdata, fileclass)

const UserDevice& device

the end-user's device

const string& query

the text prompt for the user; the user is answering this question

const string& cbtag

when responding with the user's answer, this cbtag will be used (see handleInputResponse())

const XMLData& cbdata

when responding with the user's answer, this callback data will be provided

const StringSet& fileclass

a comma separated list of types of file expected, e.g. html, svg, jpg, etc.


Request the user to send the app a file.

Return value: true if sent successfully

static bool registerMenu(device, menuname, menuoption, action)

const UserDevice& device

the end-user's device (only AppMode is used)

const string& menuname

the name for a group of options

const string& menuoption

the text presented to the user as the menu option

const string& action

the message keyword to send to the app when the user selects this menu option


Register a menu selection, which will automatically be provided with the user starts the UI for this application. Menu options are grouped under a menu name.

Return value: true if sent successfully

static bool registerKey(device, keystroke, action)

const UserDevice& device

the end-user's device (only AppMode is used)

const string& keystroke

the key to register, which may be a special key such as ctrl-s, F2, alt-a

const string& action

the message keyword to send to the app when the user selects this menu option


Register a keystroke, so when the user presses that key the provided action will be sent as a message to the app.

Return value: true if sent successfully

static bool registerHotspot(device, region, action)

const UserDevice& device

the end-user's device (only AppMode is used)

const string& region

this can be a specific region name or it may contain one or more wildcards, e.g. tile_*

const string& action

the message keyword to send to the app when the user clicks on the hotspot


Register a hotspot or group of hotspots, so when the user clicks on it the specified action is sent as a message to the app.

Return value: true if sent successfully

static bool redirectHotspot(device, region, otherapp)

const UserDevice& device

the end-user's device (only AppMode is used)

const string& region

this can be a specific region name or it may contain one or more wildcards, e.g. tile_*

const string& otherapp

the task id of the other app that will handle this click


Redirect a hotspot or group of hotspots, so when the user clicks on it the specified action is sent as a message to the app.

Return value: true if sent successfully

static bool registerMouse(device, region, action)

const UserDevice& device

the end-user's device (only AppMode is used)

const string& region

this can be a specific region name or it may contain one or more wildcards, e.g. tile_*

const string& action

the message keyword to send to the app when the user clicks on the region


Register a mouse callback (with x,y inside region as well as mouse direction) for a region or group of regions, so when the user clicks on it the specified action is sent as a message to the app as a mouise response.

Return value: true if sent successfully

static bool registerCommand(device, cmd, cmdparams)

const UserDevice& device

the end-user's device (only AppMode is used)

const string& cmd

they keyword

const XMLData& cmdparams

the parameters/callback data to be sent with the command


Register a command so when that command is triggered through the UI, the command provided parameters will also be sent with it.

Return value: true if sent successfully

static bool send(request, params)

const string& request

the request keyword

const XMLData& params

the data (parameter payload)

Default value: XMLData("")


Send an API message to channel gui.