Interface
- Derek Batting
- John Gregory
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
function addImageFile([imagefile])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
clipboardGetText
function clipboardGetText()Retrieves the current text value on the operating system clipboard.
Return values
(string)
The text from the clipboard
clipboardSetText
function clipboardSetText(text)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.
onDesktopClose
The functions registered on this handler will be called just before the virtual table is closed.
onDesktopInit
The functions registered on this handler will be called after the virtual table is initialized.
onHotkeyActivated
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
dragdata (dragdata)
The dragdata object representing the contents of the activated hot key bar slot.
onHotkeyDrop
The functions registered on this handler will be called whenever an object is dropped on the hot key bar.
Parameters
dragdata (dragdata)
A dragdata object containing the state of values connected to the mouse cursor as part of a drag and drop operation.
onWindowClosed
The functions registered on this handler will be called whenever a top level window is about to be closed.
Parameters
window (windowinstance)
A windowinstance object identifying the closed window
onWindowOpened
The functions registered on this handler will be called whenever a new top level window is created.
Parameters
window (windowinstance)
A windowinstance object identifying the opened window
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.
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.