Packages
Comm
DB
Debug
Input
Interface
Module
Token
User

Objects
bitmapwidget
databasenode
dragdata
textwidget
tokeninstance
widget
widgetcontainer

Elements
buttoncontrol
categoryselectioncontrol
chatentry
chatwindow
databasecontrol
diecontrol
diefield
formattedtextcontrol
formattedtextfield
genericcontrol
imagecontrol
numbercontrol
numberfield
portraitselectioncontrol
script
scrollbarcontrol
scrollercontrol
stringcontrol
stringfield
subwindow
textbasecontrol
tokenbag
tokencontrol
tokenfield
windowclass
windowcontrol
windowinstance
windowlist
windowreferencecontrol
windowreferencefield

Components
categoryselectionsettings
customdie
desktopframe
die
distance
font
framedef
hotkeybar
icon
imageupdatefolder
importinfo
includefile
panel
portraitset
properties
replaces
template
tokenroot
tooltip
bringToFront
close
createControl
getClass
getDatabaseNode
getFrame
getLockState
getPosition
getSize
getViewers
isMinimized
isShared
notifyUpdate
onClose
onDrop
onHover
onHoverUpdate
onInit
onLockChanged
onMenuSelection
onMove
onShare
onSizeChanged
onSubwindowInstantiated
onViewersChanged
registerMenuItem
resetMenuItems
setBackColor
setFrame
setLockState
setPosition
setSize
share



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

bringToFront

function bringToFront( )

This function brings the windowinstance to the top of the Fantasy Grounds window stack.


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.

Note: Developers should prefer the getValue function for the individual controls when possible, in order to minimize memory usage for database script objects.

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.

getLockState

function getLockState( )

Returns the current positional lock state of the window instance. Only applies to windowinstance objects defined within panel tags.

Return values

(boolean)
Lock state of the panel windowinstance. If windowinstance is not embedded within a panel, then false.

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.

isMinimized

function isMinimized( )

This function can be used to check if the window is minimized.

Return values

(boolean)
true if the window is minimized, false otherwise.

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.


onDrop

event function onDrop( x, y, dragdata )

This function is called when a drag and drop operation finishes on the control. The dragdata parameter should be used to access the dragged information.

To transfer information back to the control where the drag originated, the same dragdata object is passed to the onDragEnd function in that control.

Parameters

x(number)
The X coordinate relative to the top left corner of the control
y(number)
The Y coordinate relative to the top left corner of the control
dragdata(dragdata)
A dragdata object containing the state of values connected to the mouse cursor as part of a drag and drop operation.

onHover

event function onHover( state )

This function is called when the mouse enters or leaves the area of the window.

Parameters

state(boolean)
true if the mouse is entering the area, false if leaving

onHoverUpdate

event function onHoverUpdate( x, y )

This function is called when the mouse cursor is moved while over the window.

Parameters

x(number)
The X coordinate of the mouse pointer in pixels relative to the top left corner of the window
y(number)
The Y coordinate of the mouse pointer in pixels relative to the top left corner of the window

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.


onLockChanged

event function onLockChanged( window )

This function is called when the position lock state of a windowinstance changes. Only applies to windowinstance objects defined within panel tags.

Parameters

window(windowinstance)
Object triggering the event

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)
The windowinstance causing the event.

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)
The windowinstance causing the event.

onSubwindowInstantiated

event function onSubwindowInstantiated( )

If present, this function is called if the window instance is contained in a subwindow. This will be called after onInit


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.


setBackColor

function setBackColor( color )

Set the color to be used to fill the background of the window before drawing the contents. If no backcolor specified (i.e. nil), then no fill will be done (i.e. transparent).

Parameters

color(string)
The color specified as a HTML compatible string representing an RGB color with an alpha (transparency) value. The format of the string is 'aarrggbb', and each component is presented as a hexadecimal value from 00 to FF. If alpha is zero or not defined, FF is assumed.

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.

setLockState

function setLockState( lock )

Sets the positional lock state of the window instance. Only applies to windowinstance objects defined within panel tags.

Parameters

lock(boolean)
Desired lock state for panel windowinstance.

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 users to receive the window.


'Fantasy Grounds' is a trademark of SmiteWorks Ltd. All other trademarks are the property of their respective owners.
2004-2010 SmiteWorks Ltd. ALL RIGHTS RESERVED.
Privacy policy