This is a global built-in package that provides interfaces for manipulating top level user interface objects, such as
top level windows and panels. Hot key bar event processing also happens through this interface.
Opening windows explicitly using the functions in this interface should be done carefully, in order to preserve the
integrity of the program data base on client instances. Generally, windows should only be opened once shared from the host,
or by using requestNewClientWindow to notify the host of the new window and its data.
Interface
findWindow
function findWindow(
windowclass, datasource
)
Finds a top level window by its windowclass and datasource. If the window is not found, it is not created.
Parameters
windowclass (string)
The windowclass of the window to find
datasource (string)
Return values
(windowinstance)
A
windowinstance to the window, or
nil if the request failed or the window was
not found.
onHotkeyActivated
handler
function onHotkeyActivated(
draginfo
)
The functions registered on this handler will be called whenever a hot key bar slot is activated. This allows the processing of custom
drag types and context specific special operation.
Parameters
draginfo (dragdata)
The
dragdata object representing the contents of the activated hot key bar slot
onWindowClosed
handler
function onWindowClosed(
window
)
The functions registered on this handler will be called whenever a top level window is about to be closed.
Parameters
window (windowinstance)
onWindowOpened
handler
function onWindowOpened(
window
)
The functions registered on this handler will be called whenever a new top level window is created.
Parameters
window (windowinstance)
openWindow
function openWindow(
windowclass, datasource
)
Creates a top level window by a windowclass and a datasource. If a matching window already exists, it is returned. Otherwise, a new
window is created.
See windowinstance for more information on the parameter values.
Parameters
windowclass (string)
The windowclass of the window to create
datasource (string)
Return values
(windowinstance)
requestNewClientWindow
function requestNewClientWindow(
windowclass, rootnode
)
Because client instances should not create windows with data bound to nonexistant database nodes, they need to ask the host to
create a new data base node to act as the window datasource whenever a new record is required. This function sends a request to
do this to the host asynchronously, with the host responding with an acknowledgement to create a new window instance if successful.
Due to the asynchronous nature of this function, it does not return a reference to the window, returning immediately. If any
further processing is required, other means to process the created window are required.
A new datasource node will be created for the window. The host will create a new unique node under the node passed as the second
parameter, i.e. the datasource node will be a child of the node specified in the root node parameter.
It is possible to create client windows with openWindow. This option should be reserved for special cases and should
not be used under normal circumstances.
Parameters
windowclass (string)
The windowclass of the window to create
rootnode (string)
The name of the parent node used to create the data source, see above and
windowinstance for details
setLighting
function setLighting(
systemcolor, windowcolor, controlcolor, contentcolor
)
This function can be used to change the ambient lighting of the user interface elements. The color change will take place on all
connected clients gradually over a couple of seconds.
All the color components are specified as strings in the form "RRGGBB", where the characters are hexadecimal digits specifying the
red, green and blue color channels in the range 0 .. 255. The colors will be modulated with the pixel values in the bitmaps defining
the interface.
The recommended operation is to only alter the windowcolor parameter, passing the value "FFFFFF" to the other color channels.
Parameters
systemcolor (string)
The color used to render system interface elements
windowcolor (string)
The color used to render window frame interface elements
controlcolor (string)
The color used to render control elements
contentcolor (string)
The color used to render user specified content interface elements. Please note that changing this value may affect
the usability of the respective content.
