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

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

dialogFileOpen

function dialogFileOpen([multiselect], [filter], [directory])

Displays a standard file system dialog for opening files.

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

Parameters

multiselect (boolean) [optional]

Defines whether multi-select is enabled for the open file dialog.

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 (or table))

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

dialogFileSave

function dialogFileSave([filter], [directory])

Displays a standard file system dialog for saving files

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

Parameters

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

function dialogMessage([dialogtext], [title], [type])

Opens a simple operating system dialog to provide information to the user, or to request a simple positive/negative answer.

Parameters

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").

findWindow

function findWindow(windowclass, datasource)

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

function 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

function 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

function 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.

getIcons

function 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.

getString

function getString(id)

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

isFont

function isFont(fontname)

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

function isFrame(framename)

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.

isFullScreen

function isFullScreen()

Returns whether Fantasy Grounds is running in full screen (maximized) mode or not.

Return values

(boolean)

Whether Fantasy Grounds is running in full screen mode.

isIcon

function isIcon(iconname)

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

function isToken(tokenname)

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

function onDesktopClose()

The functions registered on this handler will be called just before the virtual table is closed.

onDesktopInit

function onDesktopInit()

The functions registered on this handler will be called after the virtual table is initialized.

onHotkeyActivated

function onHotkeyActivated(dragdata)

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

function onHotkeyDrop(dragdata)

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

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)

A windowinstance object identifying the closed window

onWindowOpened

function onWindowOpened(window)

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

function openCampaignFolder([relative])

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

function openDataFolder([relative])

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

function openRadialMenu()

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

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)

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.

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 "BBGGRR", 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.

All parameters other than windowcolor are ignored.

Warning

The parameter values expect color strings in a different format than all other FG API functions. (BBGGRR)

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.

setString

function setString(id, text)

Sets the text of a string resource.

Parameters

id (string)

String resource ID

text (string)

Text to store in the string resource

toggleWindow

function toggleWindow(windowclass, datasource)

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.