Class: UI

UI

Provides access to extended user interface properties and methods.


Example
var ui = $wat.load('ui')[0];

Members


autoWaitCursor :bool

Gets/sets whether the 'wait' cursor will be automatically shown when loading pages. If enabled, the spinning 'wait' cursor will appear in the middle of the screen during a page load, including in frames.

Type:
  • bool
Since:
  • 1.0
Default Value:
  • true

backlight :number

Gets/sets the backlight level. Range is [0-255].

WARNING The backlight level is persisted across reboots, so if it is turned completely off, it will remain off after the device has rebooted, which would leave the user with no way to turn the backlight back on from the screen. Any application that turns off the backlight for any reason should also check the backlight level when starting, and correct it if it is off.

Type:
  • number
Since:
  • 1.0

<readonly> dialogs :ui.UIDialogs

Gets an object that can be used to show built-in dialogs.

Type:
Since:
  • 1.0

<readonly> ip :wat.IPAddress

Gets the IP address of the system.

Type:
Since:
  • 1.0
Deprecated:

keyBeepEnabled :bool

Gets/sets whether the buzzer (if available) beeps when native buttons (e.g. in the soft keyboard) are pressed.

Buzzers are provided by the I/O board, if there is no buzzer available, this has no effect.

Type:
  • bool
Since:
  • 1.0
Default Value:
  • true

logFileFix :Array.<Object>

Gets/sets the expressions used to modify file names that are forwarded to syslog.

Normally, for the sake of having complete information, the entire URL of the source file is sent to the log (e.g. http://mydomain.com/path/to/file.html). However, in order to keep the logs smaller, applications can choose to set regular expressions that are used to modify the files name (typically with the intent of reducing the size).

A single regular expression may be specified as a string. In this case, any matches will be replaced with an empty string. If something other than an empty string is desired, then this expression may be specified as an object with two properties: match, which is the regular expression pattern string, and replace, which is a string value to replace the match with.

Multiple expressions in either of the above formats may be specified by using an array. In this case the expressions will be processed in the given order. The result will be modified (if applicable) before processing the next expression.

The default value for this property is "^\w+://", which removes the protocol. The protocol is generally not useful, but if desired, this property can be set to an empty string to print the full URL.

Type:
  • Array.<Object>
Since:
  • 2.3
Examples
// replace the domain with a shorter string and eliminate the path
$ui.logFileFix = [{
  match: "^http://mydomain.com/",
  replace: "[md]"
}, "(\\w+/)+"];
// remove the root of this app
$ui.logFileFix = "^" + (new URL('.', location.href)).href;
// override the default and print everything
$ui.logFileFix = "";

popupLevel :number

Gets/sets the popup level. The popup level is the minimum trace level that will cause the trace log dialog to automatically appear. For example, to have the trace log appear on the screen whenever a critical log occurs, set popupLevel to TraceLevel.Critical.

Type:
  • number
Since:
  • 1.1
Default Value:
  • TraceLevel.None
See:
Example
// make the trace log appear if a critical error occurs
ui.popupLevel = ui.TraceLevel.Critical;

popupOnCritical :bool

Type:
  • bool
Since:
  • 1.0
Deprecated:
Default Value:
  • false

<readonly> serials :Array.<wat.SerialPort>

An array of the serial ports available on the main board.

NOTE: depending on the model used, there may be 1 or 2 serial ports available on the main board, and these ports may or may not be wired out to connectors on the outside of the box. Check the documentation for the model to determine what is available.

Type:
Since:
  • 1.3
Deprecated:

traceLevel :number

Gets/sets the current trace level. The trace level is the minimum trace level that will be stored in the trace log. For example, if traceLevel is set to TraceLevel.Warning, then only Warning, Error, and Critical logs will be stored in the trace log buffer.

Type:
  • number
Since:
  • 1.0
Default Value:
  • TraceLevel.Info
See:
Example
// only show Errors and Critical logs
ui.traceLevel = ui.TraceLevel.Error;

TraceLevel :object

Available trace levels.

Type:
  • object
Properties:
Name Type Description
Debug number

0

Verbose number

1

Info number

2

Warning number

3

Error number

4

Critical number

5

None number

6

Since:
  • 1.0
See:

<readonly> version :wat.Version

Gets the version of the UI plugins. Because UI currently is a built-in plugin, this version should match wat.WAT#version.

Type:
Since:
  • 1.0

waitCursor :bool

Gets/sets whether the wait cursor is currently being shown. The application can use this to force the wait cursor to show so that the user knows that processing is taking place.

Type:
  • bool
Since:
  • 1.0
Default Value:
  • false

Methods


clearAppCache()

Clears the application cache. This will clear ALL items in the application cache, including any that may have been saved by other applications.

Since:
  • 1.0
Deprecated:

critical(message)

Adds a critical message to the trace log. Same as trace(message, ui.TraceLevel.Critical).

Parameters:
Name Type Description
message string

The message to log

Since:
  • 1.0
See:

debug(message)

Adds a debug message to the trace log. Same as trace(message, ui.TraceLevel.Debug).

Parameters:
Name Type Description
message string

The message to log

Since:
  • 1.0
See:

error(message)

Adds an error message to the trace log. Same as trace(message, ui.TraceLevel.Error).

Parameters:
Name Type Description
message string

The message to log

Since:
  • 1.0
See:

info(message)

Adds an information message to the trace log. Same as trace(message, ui.TraceLevel.Info).

Parameters:
Name Type Description
message string

The message to log

Since:
  • 1.0
See:

keyBeep()

Beeps the buzzer (when available) briefly. The application could, for example, call keyBeep whenever a button is pressed to give feedback to the user.

Since:
  • 1.0

logger(category [, enableForLevel] [, oldLogger])

Wraps a logging object to apply the category defined rules.

The logging methods in the wrapped object will only be called if the method is enabled in the specified logging category. Other methods will always be passed through to the wrapped object.

If a logging object is not supplied, the console object will be used.

A method name can also be supplied, which will be the lowest priority method enabled by default. If not specified, this will be 'info'. This means that 'info', 'warn', and 'error' will print to the console and syslog, but 'debug' and 'log' will not print to either.

The category name can be any string, however it is typical to use dot separated names to define a category/sub-category. This makes it much easier to specify override rules in the web admin. For example, if the category is myApp.component.eip, then levels may be fine tuned using a rule similar to myApp.component.eip.debug=true, but may also be changed at a higher level using a rule similar to myApp.*.debug=true. It is generally a good idea to prefix all categories with the same ID (myApp.) and to keep that separate from built-in names (wat, qt).

Rules can be added to the web admin that override the initial setting for the category. All rules that match from the web admin will be applied in the order specified.

The rules on the web page are specified using a form like: <category>[.<type>] = true|false. <category> is the name of the category, potentially with * as a wildcard symbol as the first or last character (or at both positions). The optional <type> must be either debug, info, warning, or critical.

Note that the valid rule types do not exactly match the logger method names. E.g.: to enable the error logger method on myCat, set the rule myCat.critical = true.

Parameters:
Name Type Argument Default Description
category string

The category name

enableForLevel string <optional>
"info"

The lowest priority logging method to enable

oldLogger object <optional>
console

The logging object to wrap

Since:
  • 2.3
Returns:
Type
object
Example
var log = $ui.logger('myApp.component');
log.error('An error'); // prints
log.info('Something interesting'); // prints
log.debug('Only useful during debugging'); // does not print
var prefixedLogger = {
  error: function(first, ...others) { console.error('Prefix: ' + first, ...others); },
  info:  function(first, ...others) { console.info('Prefix: ' + first, ...others); }
};
var log2 = $ui.logger('myApp.quiet', 'warn', prefixedLogger);
log2.error('An error'); // prints 'Prefix: An error'
log2.info('Information'); // does not print

loggingCategory(catName [, enableLevel])

Creates an object that can be used to determine if a log level of a logging category is enabled.

Generally this function does not need to be called directly. Instead, use logger, which is more convenient.

The resulting object has one function isEnabled, which is passed the name of a logging function ('debug', 'log', 'info', 'warn', 'error') and returns whether that function is enabled for the logging category.

Parameters:
Name Type Argument Default Description
catName string

The category name to use

enableLevel string <optional>
"info"

The lowest priority method name to enable by default

Since:
  • 2.3
Returns:
Type
object

reboot()

Reboots the device.

Since:
  • 1.0
Deprecated:

refresh()

Refreshes the current page and bypasses the cache. The current URL remains unchanged during the refresh.

Alternately, this can be done in JavaScript using document.location.reload(), in which bypassing the cache can be specified as required.

Since:
  • 1.0

reload()

Reloads the application. This will re-direct back to the configured initial URL, which may not necessarily be the current URL. The pages may be read from the cache if they present. To force a load to bypass the cache, use refresh after reload.

Since:
  • 1.0

setInputFocus()

Sets the input focus to the current window. This is useful in a multi-screen situation where keyboard input should be directed to one screen without use of a mouse.

NOTE if the mouse (or touchscreen) is clicked, input focus will be switched to the screen that was clicked.

NOTE by default, the primary screen will receive input focus, so it would not be necessary to call this function to assign focus to the primary under most conditions.

Since:
  • 2.2

sizeHint(width, height)

Experimental feature

Tells WAT what the intended full size of the application is. WAT may then attempt to zoom the view to fit the actual screen resolution. Useful if an application was designed with a specific resolution in mind, but could be used on a display with a different resolution.

Note that a size smaller than the actual size of the application cannot be used. In this case, the minimum bounding box that shows everything in the application will be used (i.e. sizeHint cannot be used to cut out parts of the application). A size larger than the application is acceptable.

Parameters:
Name Type Description
width number

The intended width of the application

height number

THe intended height of the application

Since:
  • 1.3

toggleWaitCursor()

Toggles the wait cursor. Same as ui.waitCursor = !ui.watCursor.

Since:
  • 1.0
See:
  • ui.UI.waitCursor

trace(message [, level] [, addToConsole])

Adds a message to the trace log, if the level is greater than or equal to traceLevel. If addToConsole is true, than the message is also logged to the debug console if it is added to the trace log.

Parameters:
Name Type Argument Default Description
message string

The message to log

level number <optional>
TraceLevel.Info

The level of the message

addToConsole bool <optional>
true

Add the message to the debug console

Since:
  • 1.0
See:

verbose(message)

Adds a verbose message to the trace log. Same as trace(message, ui.TraceLevel.Verbose).

Parameters:
Name Type Description
message string

The message to log

Since:
  • 1.0
See:

warning(message)

Adds a warning message to the trace log. Same as trace(message, ui.TraceLevel.Warning).

Parameters:
Name Type Description
message string

The message to log

Since:
  • 1.0
See: