Module: ui

UI is a built-in module and is always available. UI is the object returned when the module is loaded. It provides useful UI related properties and functions.

The name of the module for loading is 'ui'. When loaded, a single ui.UI object is returned.

The Wait Cursor

The wait cursor is a graphical indeterminate progress indicator. It is typically used to indicate a process that is not yet completed. The wait cursor looks like: Wait Icon. The wait cursor is controlled using properties of UI, such as ui.UI#autoWaitCursor and ui.UI#waitCursor.

Key Beep

Provided you have hardware that can beep, by default, the device will generate a beep whenever you press a button in a built-in dialog. In order to make buttons (or other elements) in an HTML page also beep, ui.UI#keyBeep can be used.

Trace Logger

There are two methods of logging messages when using WAT. The first is to use the console object, which has functions such as 'log', 'warn', etc and the second is to use the UI function such as ui.UI#trace and variants. The messages generated by both methods will appear in both the debug console (if debugging is enabled) and the trace log (if the appropriate level has been configured). The two methods produce slightly different log entries from each other.

The primary focus of the console logging is developer debugging. To this end, data logged also contains the file name and line number that generated the log and allows JavaScript objects to be logged, which records the object state at that time in the debug console. Although the messages will be logged to the trace log as well, the primary destination is the debug console. Note that the detail of objects logged will be significantly reduced in the trace log compared to the debug console. See console for more details.

The UI functions, on the other hand, are more suitable for generating messages that can be used by a user of the application. The data logged does not contain file/line information and the logging function provide more trace levels, which can be useful for enabling extra information for advanced users. Although the messages will be logged to the debug console as well, the primary destination is the trace log.

The trace log can be configured to filter out messages below a specific level. This can help keep the information in the log relevant, so that important messages are not overlooked. This level can be set in ui.UI#traceLevel. The level also applies to messages logged using the console functions, but note that the lowest level available from the console is Info. The trace log, which is normally hidden, can be configured to 'pop-up' automatically if a message of a specific level or higher is logged. This can be used to ensure that undesirable conditions are more visible.

In summary:

console logging:

  • contains file/line information
  • provides more advanced developer logging
  • logs at levels Info, Warning, Error and Critical (for asserts)

UI logging:

  • does not contain file/line information
  • logs at levels Debug, Verbose, Info, Warning, Error, and Critical

Developers would typically want to start with console logging as it provides the most developer-friendly features.