Objects of type windowinstance are individual representations of windows created based on a windowclass.
Window instances contain controls, as defined in the sheetdata section of the windowclass definition, or dynamically constructed
using the createControl function.
Window contents, i.e. the data present in the data field controls, is determined by the instance's association with the database tree.
A window instance can be tied to a particular database tree node or it can be unbound (in which case getDatabaseNode returns
nil). The node the window is bound to is called the window data source. The controls in the window will get
their data from a node under the data source (see databasecontrol for details). The controls in an unbound window are unbound by default.
A window instance is identified by two parameters: the window class name and the data source node. These parameters identify a window instance
uniquely, i.e. a second window with the same parameters cannot exist. Thus, only one unbound instance of a particular window class can ever exist
at one time.
Interface
close
function close(
[closeclients]
)
Closes the window.
Parameters
closeclients (boolean) [optional]
If true and running as the host, the corresponding window will be closed for all clients that have it open as well.
createControl
function createControl(
type, name
)
Creates a new control into the window dynamically at run time. The created control will use default settings. It is possible to use this command to create
controls defined by a template.
The onInit function of the control is executed when it is created.
Parameters
type (string)
The type is defined as the name of a control as specified in the window class XML definition (e.g. "numbercontrol") or as the name of a template
to be used for the creation of this control.
name (string)
The name of the control. If the control is a
databasecontrol and the window has a data source, it will be bound to the
corresponding node in the database.
getClass
function getClass(
)
Returns the name of the windowclass resource used to construct the window.
Return values
(string)
The name of the
windowclass this window instance represents.
getDatabaseNode
function getDatabaseNode(
)
This function will return a reference to a databasenode object representing the data source database node for this window.
Return values
(databasenode)
A reference to the root data source node for this window. If the window is unbound, returns nil.
getFrame
function getFrame(
)
Returns the name of the bitmap frame used to render the background area of the window.
Return values
(string)
The name of the frame resource.
getPosition
function getPosition(
)
Returns the position of the window on the screen calculated from the top left corner of the application window.
Warning
Calling this function on a dynamically sized window used as a subwindow or list item may have unpredictable results.
Return values
(number)
The X coordinate of the window, distance from the left edge in pixels.
(number)
The Y coordinate of the window, distance from the top edge in pixels.
getSize
function getSize(
)
Returns the current size of the window in pixels, as calculated from the outer edge of the window frame.
Return values
(number)
The width of the window in pixels.
(number)
The height of the window in pixels.
getViewers
function getViewers(
)
Returns an integer indexed list of string values containing the usernames of the connected clients that
currently have the window open.
Return values
(table)
An integer indexed table of string values containing the usernames.
isShared
function isShared(
)
This function can be used to check if the window has been shared since it was opened, or if it was opened as a result of a remote sharing operation.
Return values
(boolean)
true if the window has been shared, false otherwise.
notifyUpdate
function notifyUpdate(
)
Notifies the window that some of its contents have been changed and a minimized window should be hilighted.
Most built-in controls call this method automatically, but this may be useful for some custom control types and data handling schemes.
onClose
event
function onClose(
)
If present, this function will be called when the window is closing, after the onClose functions of child controls have been called.
onInit
event
function onInit(
)
If present, this function is called when the window instance is created, after the onInit functions of child controls have been called,
but before the window is first displayed.
onMenuSelection
event
function onMenuSelection(
...
)
This function is called when a user defined item is selected in the window's radial menu.
Parameters
...A variable amount of number parameters, depending on the menu hierarchy depth of the selected item. A first level menu item
will contain one number, identifying the slot it occupies on the menu. A second level item will contain two numbers, with the first specifying
the submenu position, and the second the position of the item in the submenu. See
registerMenuItem for more information.
onMove
handler
function onMove(
source
)
This handler is triggered whenever the position of the window is changed.
Parameters
source (windowinstance)
onShare
handler
function onShare(
)
If present, this function is called when the window is shared between session participants. This occurs when the host elects to share
a window with clients, a subset of all clients or when a client shares a player sharable window.
onSizeChanged
handler
function onSizeChanged(
source
)
This handler is triggered whenever the size of a window is changed. It can be used to implement specific content positioning based on
window size.
Warning
Repositioning controls may trigger a new layout pass for the entire window. Using this function carelessly may cause significant
performance hits.
Parameters
source (windowinstance)
onViewersChanged
handler
function onViewersChanged(
)
This handler is triggered whenever the viewer list for the window is updated. See getViewers for more information.
registerMenuItem
function registerMenuItem(
label, icon,
...
)
This function registers a new user defined menu item for the window radial menu. If the user selects the item, the script is notified
of this through the onMenuSelection event.
The menu item is defined by specifying the bitmap and label to use, as well as the position of the item on the menu. The position is
given as a number value. To define entries in submenus, use multiple number values, with the first being the position value of the outermost
submenu, and the last being the position of the actual menu item in the innermost submenu.
Trying to redefine an existing menu item will fail.
Parameters
label (string)
A string to be used as the label of the menu item
icon (string)
The name of an icon resource to use as the bitmap for the menu item
...A list of numbers specifying the menu item position as a number between 1 and 8, with one being the top slot, and the
progression of numbers proceeding in a clockwise direction.
resetMenuItems
function resetMenuItems(
)
This function unregisters all user defined menu items. It does not affect menu entries defined by the application engine.
setFrame
function setFrame(
name
)
Sets the window background to the bitmap frame resource identified by the given name.
Parameters
name (string)
The name of the bitmap frame resource used as the new window frame.
setPosition
event
function setPosition(
x, y
)
Adjusts the position of a window on the screen.
Warning
A window moved out of the application window area may be unrecoverable by the user. Keep in mind that the
application window size may vary by user.
Warning
Calling this function on a dynamically sized window used as a subwindow or list item may have unpredictable results.
Parameters
x (number)
The new X coordinate position of the window.
y (number)
The new Y coordinate position of the window.
setSize
function setSize(
width, height
)
Resizes the window to the given dimensions. All controls will be laid out according to the new size. This function will override the operation
of an automatic resize performed for shared windows whose size is controlled by the host.
Warning
Calling this function on a dynamically sized window used as a subwindow or list item may have unpredictable results.
Parameters
width (number)
The new width of the window in pixels.
height (number)
The new height of the window in pixels.
share
function share(
...
)
Share the window. If called as a host, parameters can be used to control the recipient list. As a client, shares the window to all, provided the window
has the player control flag set.
Parameters
...
If called as a host, one or more strings can be passed as parameters to specify the list of recipients. The string should be the user name of the
recipient as returned by
User.getConnectedUsernames.
