Interface

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.

addImageFile

Saves the specified image file into the current campaign's images folder.

Parameters

imagefile   (string)   [optional]
The full path of the image file to save

addKeyedEventHandler

Add a keyed event handler callback function. If the key provided in the registration matches the key for the event, then the callback function will be called. If the empty key is provided in the registration (““), then the callback function will be called for all events of that type, regardless of key.

The handler function should have the following signature: [function name]([parameters]). The parameters will vary depending on the event the function is attached to, as follows.

• [onHotkeyActivated] parameters = (dragdata)

  • This event is fired then a hot key has been activated. The key will be the dragdata.getType() value.

• [onHotkeyDrop] parameters = (dragdata)

  • This event is fired then a hot key is being set. The key will be the dragdata.getType() value.

• [onLinkActivate] parameters = (sDisplayClass, sRecordPath)

  • This event is fired when a link is being activated. The key will be the sDisplayClass.

• [onWindowOpened] parameters = (windowinstance)

  • This event is fired when a window is opened. The key will be the window.getClass() value.

• [onWindowClosing] parameters = (windowinstance)

  • This event is fired when a window is just before a window is closed. The key will be the window.getClass() value.

• [onWindowClosed] parameters = (sDisplayClass, sRecordPath)

  • This event is fired after a window is closed. The key will be the sDisplayClass value of the window just closed.

Parameters

event   (string)   
The event to be captured (see function details)

key   (string)
The key to be used to determine whether to trigger event callback function.

callback   (function)   
The function to be called when the event triggers

clipboardGetText

Retrieves the current text value on the operating system clipboard.

Return values

(string)
The text from the clipboard

clipboardSetText

Sets the text parameter as the text value on the operating system clipboard.

Parameters

text   (string)   
The text to put on the clipboard

dialogFileClose

Cancel any file open or file save dialogs.

dialogFileOpen

Displays a standard file system dialog for opening files. Dialog functions are asynchronous cross-platform dialogs and require a callback function.

If a filter parameter is not defined or empty, then an XML file type will be added to the dialog filter.

Parameters

callback   (function)
The function to call when the dialog is accepted or cancelled.

filter   (table)   [optional]
Specifies filter values to use in the file open dialog as a table of key/value pairs where the extension type is the key and the description is the value.

directory   (string)   [optional]
Specifies the initial directory to display when opening this dialog, relative to the FG data directory.

multiselect   (boolean)   [optional]
Defines whether multi-select is enabled for the open file dialog.

Return values

(string (or table))
Returns the file (or files if multi-select enabled) that the user selects.

dialogFileSave

Displays a standard file system dialog for saving files. Dialog functions are asynchronous cross-platform dialogs and require a callback function.

If a filter parameter is not defined or empty, then an XML file type will be added to the dialog filter.

Parameters

callback   (function)
The function to call when the dialog is accepted or cancelled.

filter   (table)   [optional]
Specifies filter values to use in the file open dialog as a table of key/value pairs where the extension type is the key and the description is the value.

directory   (string)   [optional]
Specifies the initial directory to display when opening this dialog, relative to the FG data directory.

Return values

(string)
Returns the file that the user selects.

dialogMessage

Opens a simple operating system dialog to provide information to the user, or to request a simple positive/negative answer. Dialog functions are asynchronous cross-platform dialogs and require a callback function.

Parameters

callback   (function)
The function to call when the dialog is accepted or cancelled.

dialogtext   (string)   [optional]
The text to display in the dialog

title   (string)   [optional]
The text to display in the dialog title bar

type   (string)   [optional]
The type of dialog to display. Valid values are (nil, "okcancel", "yesno", "yesnocancel").

Return values

(string)
The button pressed in the dialog by the user. If nil, then the dialog was closed without selecting a button. Otherwise, valid values are ("ok", "cancel", "yes", "no").

dialogMessageClose

Cancel any message dialogs.

findWindow

Finds a top level window or panel 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)   
The name of the datasource to use, see windowinstance for details

Return values

(windowinstance)
A windowinstance to the window, or nil if the request failed or the window was not found.

getDice

Return a table with the names of all the registered die and customdie types.

Return values

(table)
Table of strings, which correspond to the die resources defined via the die and customdie tags.

getFonts

Returns a table of all the valid font resource names in the current ruleset.

Return values

(table)
Table of strings, which correspond to the font resources defined via the font tag.

getFrames

Returns a table of all the valid frame resource names in the current ruleset.

Return values

(table)
Table of strings, which correspond to the frame resources defined via the framedef tag.

getAssets

Returns a table of all the valid graphic assets (portraits, tokens, images) in the current session.

Return values

(table)
Table of strings, which correspond to the asset resources currently available.

getAssetSize

Returns the size of the specified graphic asset (or 0,0 if not a valid asset key).

Parameters

assetkey   (string)   
The name/key of the asset that you want to determine the size of

Return values

(number)
The width of the asset (or 0 if not a valid asset)

(number)
The height of the asset (or 0 if not a valid asset)

getIcons

Returns a table of all the valid icon resource names in the current ruleset.

Return values

(table)
Table of strings, which correspond to the icon resources defined via the icon tag.

getIconSize

Returns the size of the specified icon (or 0,0 if not a valid asset key).

Parameters

iconname   (string)   
The name of the icon that you want to determine the size of

Return values

(number)
The width of the icon (or 0 if not a valid icon)

(number)
The height of the icon (or 0 if not a valid icon)

getRulesetInfo

This function can be used to retrieve information about a particular extension. The returned table contains information in the following fields:

• name = [lookup name]

• major = [major version number]

• minor = [major version number]

Parameters

lookupname   (string)   
The “internal” name of the ruleset being targeted by the operation. (Same as file/folder name)

Return values

(table)
A table containing information about the ruleset, see above for details

(table)

A table with numerical indexes with each imported ruleset as an entry in the same format as the first return value

getString

Return the text of the string resource identified by the parameter

Parameters

id   (string)   
String resource ID

Return values

(string)
The text stored in the string resource

getWindows

Return a table of all the currently open top-level windows (including panels), based on the optional classname parameter. If the classname parameter is not provided or nil or empty string, then all open top-level windows are returned.

Parameters

classname   (string)   [optional]
The class name of windows desired to be returned.

Return values

(table)
Table of windowinstance objects, which correspond to the top-level windows currently open.

isFont

Returns true or false based on whether font name belongs to a valid font resource in the current ruleset.

Parameters

fontname   (string)   
The name of the font resource to check

Return values

(boolean)
Whether the font resource exists.

isFrame

Returns true or false based on whether frame name belongs to a valid frame resource in the current ruleset.

Parameters

framename   (string)   
The name of the frame resource to check

Return values

(boolean)
Whether the frame resource exists.

isIcon

Returns true or false based on whether icon name belongs to a valid icon resource in the current ruleset.

Parameters

iconname   (string)   
The name of the icon resource to check

Return values

(boolean)
Whether the icon resource exists.

isToken

Returns true or false based on whether token name belongs to a valid token resource in the current ruleset.

Parameters

tokenname   (string)   
The name of the token resource to check

Return values

(boolean)
Whether the token resource exists.

openCampaignFolder

Opens an operating system file explorer instance to view the current campaign folder. If relative path parameter is defined, then open there instead.

Parameters

relative   (string)   [optional]
Relative path within current campaign folder

openDataFolder

Opens an operating system file explorer instance to view the FG data folder. If relative path parameter is defined, then open there instead.

Parameters

relative   (string)   [optional]
Relative path within FG data folder

openRadialMenu

Opens the radial menu at the current mouse position. The radial menu is normally activated when right-clicking with the mouse.

openWindow

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)   
The name of the datasource to use, see windowinstance for details

Return values

(windowinstance)
A windowinstance to the window, or nil if the request failed.

openURL

Opens a URL in the background. If a callback function is defined, then the callback function will be called once the URL request completes successfully with the response from the URL returned as a parameter.

Parameters

url   (string)
The URL to request in the background

callback   (function)
If defined, the function called when the URL request completes successfully with the response as the only parameter.

removeKeyedEventHandler

Remove a keyed event handler callback function.

Parameters should be the same as the event handler registration performed by addKeyedEventHandler API.

Parameters

event   (string)   
The event to be removed (see addKeyedEventHandler API)

key   (string)
The key to be removed

callback   (function)
The event handling function to be removed

requestNewClientWindow

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

setString

Sets the text of a string resource.

Parameters

id   (string)   
String resource ID

text   (string)   
Text to store in the string resource

toggleWindow

If a top level window with the specified windowclass and datasource exist, it is brought to the top of the window Z-order. If it was already at the top of the Z-order, it will be closed. If it does not exist, then a new window will be created with the specified windowclass and datasource.

See windowinstance for more information on the parameter values.

Parameters

windowclass   (string)   
The windowclass of the window to toggle

datasource   (string)   
The name of the datasource to use, see windowinstance for details

Return values

(windowinstance)
A windowinstance to the window, or nil if the request failed or the window was closed.