Packages
 Comm
 DB
 Debug
 Extension
 Input
 Interface
 Module
 Token
 User

Objects
 bitmapwidget
 databasenode
 dragdata
 textbasecontrol
 textwidget
 tokeninstance
 widget
 widgetcontainer
 windowcontrol
 windowinstance

Controls
 buttoncontrol
 buttonfield
 categoryselectioncontrol
 chatentry
 chatwindow
 databasecontrol
 diecontrol
 diefield
 formattedtextcontrol
 formattedtextfield
 genericcontrol
 imagecontrol
 numbercontrol
 numberfield
 portraitselectioncontrol
 scrollbarcontrol
 scrollercontrol
 stringcontrol
 stringfield
 subwindow
 tokenbag
 tokencontrol
 tokenfield
 windowlist
 windowreferencecontrol
 windowreferencefield

Assets and Settings
 announcement
 categoryselectionsettings
 characterdbroot
 customdie
 description
 desktopframe
 die
 diebox
 distance
 font
 framedef
 hotkeybar
 icon
 imageupdatefolder
 imagesettings
 importinfo
 importruleset
 includefile
 panel
 pollbox
 portraitset
 properties
 replaces
 script
 string
 template
 textsettings
 tokenroot
 tooltip
 windowclass
addChildCategory
addHandler
addHolder
backup
convertCampaign
copyNode
createChild
createNode
deleteChild
deleteChildren
deleteNode
export
findNode
getCategory
getChild
getChildCategories
getChildCount
getChildren
getChildrenGlobal
getDefaultChildCategory
getHolders
getImportRulesetVersion
getImportVersion
getModule
getOwner
getParent
getPath
getRoot
getRulesetVersion
getText
getType
getValue
getVersion
import
isIntact
isOwner
isPublic
isReadOnly
isStatic
onAuxCharLoad
onImport
onIntegrityChange
removeAllHolders
removeChildCategory
removeHandler
removeHolder
revert
setCategory
setDefaultChildCategory
setOwner
setPublic
setStatic
setValue
updateChildCategory
updateVersion



This is a global built in package that provides global level interfaces to the program data base.

See databasenode for more information on data base nodes and their operation.



Interface


addChildCategory

function addChildCategory(nodeid, category)

Adds a child category for the specified data base node.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

category   (table (or string))   

New category information (or name)


addHandler

function addHandler(nodepath, event, callback)

Add an event handler callback function to a specified database event on any node matching the specified database path.

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

* [onAdd] parameters = (nodeAdded)

* [onCategoryChange] parameters = (nodeChanged)

* [onChildAdded] parameters = (nodeParent, nodeChildAdded)

* [onChildCategoriesChange] parameters = (nodeParent)

* [onChildDeleted] parameters = (nodeParent)

* [onChildUpdate] parameters = (nodeParent, nodeChildUpdated)

* [onDelete] parameters = (nodeToBeDeleted)

* [onIntegrityChange] parameters = (nodeChanged)

* [onUpdate] parameters = (nodeUpdated)

Parameters

nodepath   (string)   

A data base path identifier. The '*' character can be used as a wildcard for a path segment.

event   (string)   

The event to be captured (onUpdate, onAdd, onDelete, onObserverUpdate, onChildAdded, onChildUpdate, onChildDeleted, onIntegrityChange)

callback   (function)   

The function to be called when the event triggers


addHolder

function addHolder(sourcenode, username, owner)

This function adds the specified user as a holder for the specified database node and all child nodes. If the owner flag is set, the user will also be able to modify the contents of data nodes. In such a case, any existing ownership is revoked.

Warning
This function will only work if running as a host.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

username   (string)   

The username of the user gaining the status

owner   (boolean)   

If true, the user will also be flagged as the owner of the node.


backup

function backup()
Warning
Only available on host.

Creates a backup of the current database, saved to a unique file name. (db.script.#.xml)


convertCampaign

function convertCampaign(ruleset)

Converts the current campaign to a different specified ruleset.

Parameters

ruleset   (string)   

Target ruleset for conversion


copyNode

function copyNode(sourcenodeid, destnodeid)

This function can be used to copy the contents of a data base node, using data node identifier paths. Either paths or objects can be used as parameters.

Warning
The source database node must exist, and the destination node if it exists already must be the same value type.
Warning
Copying of image database nodes is not supported. A new image node will be created as an empty drawing with no token, pointer, mask, or drawing data.

Parameters

sourcenodeid   (string (or databasenode))   

The data node identifier path (or a databasenode object) for the source node

destnodeid   (string (or databasenode))   

A data node identifier path (or a databasenode object) for the destination node

Return values

(databasenode)
A databasenode object representing the destination node, or nil if the node was unable to be created for any reason.

createChild

function createChild(sourcenode, [name], [type])

Create, or if it already exists fetch, the specified child node under the specified node.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

name   (string)   [optional]

A relative node identifier specifying the child node to find. If this parameter is omitted, a new unique node name will be generated.

type   (string)   [optional]

The type of node to create. If this parameter is omitted, an intermediate node will be created. Leaf nodes can be of types "number", "string", "formattedtext", "image", "dice" or "windowreference".

Return values

(databasenode)
If the node already exists, the return value is a reference to that node. If it was created, a reference to the created node is returned. If there was an error, returns nil.

createNode

function createNode(nodeid, [type])

This function creates a new top level data base node of the given type.

Parameters

nodeid   (string)   

A data base node identifier

type   (string)   [optional]

The type of node to create. If this parameter is omitted, an intermediate node will be created. Leaf nodes can be of types "number", "string", "formattedtext", "image", "dice" or "windowreference".

Return values

(databasenode)
A databasenode object representing the created node, or nil if the operation failed

deleteChild

function deleteChild(sourcenode, name)

Deletes the specified child node under the specified node. (if it exists)

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

name   (string)   

A relative node identifier specifying the child node to delete


deleteChildren

function deleteChildren(sourcenode)

Deletes all children under the specified node. (if it exists)

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node


deleteNode

function deleteNode(nodeid)

This function deletes a data base node.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)


export

function export(filename, targetnode, [rewrite], [listexport])

This function exports an XML data file to the host's hard drive containing the contents of the specified database node.

A root node to contain the exported contents is always created in the XML data file.

The export will follow these criteria depending on the rewrite and listexport parameters:

If rewrite and listexport not defined, then the data file root node will contain an export of all the children of the specified node.

If rewrite is defined but listexport is missing or false, then the data file root node will contain a tag set using the value of the rewrite parameter which will contain an export of all the children of the specified node. (Ex: To export a single character from a ruleset, DB.export("output.xml", "charsheet.id-00001", "character"))

If rewrite is defined and listexport is true, then the exporter will assume that the node to export is a list node. The data file root node will contain a tag set for each child record of the target database using the value of the rewrite parameter instead of the child node ID which will contain an export of all the children of the matching child node. (Ex: To export all characters from a ruleset, DB.export("output.xml", "charsheet", "character", true))

Warning
This function will only work if running as a host.

Parameters

filename   (string)   

The name of the file to be imported.

targetnode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

rewrite   (string)   [optional]

See function description.

listexport   (boolean)   [optional]

See function description.


findNode

function findNode(nodeid)

This function can be used to find a data base node in a global scope based on a global database node identifier.

Parameters

nodeid   (string)   

A global data base node identifier

Return values

(databasenode)
A databasenode object representing the given identifier, or nil if the node was not found

getCategory

function getCategory(nodeid)

Gets the category information for the specified data base node.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

Return values

(table)
Category information for specified node, including the following fields (name, mergeid, base, decal). The name field is the name of the category. The merge ID field is a value that can be specified for each module to allow multiple modules to be listed in a single category. The base field is a number defining the index of the background tab to use when displaying the category. The decal field is a number defining the index of the decal to use when displaying the category. The combination of all four entries defines a unique category.

getChild

function getChild(sourcenode, name)

Fetches the specified child node under the specified node.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

name   (string)   

A relative node identifier specifying the child node to find

Return values

(databasenode)
A databasenode object representing the node, or nil if the node could not be found or the specified node identifier does not exist.

getChildCategories

function getChildCategories(nodeid)

Gets the child categories for the specified data base node.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

Return values

(table)
An integer-indexed table of category records. Each category record is a table with the following fields (name, mergeid, base, decal).

getChildCount

function getChildCount([source], sourcepath)

Get the number of child nodes belonging to the specified node.

Parameters

source   (databasenode)   [optional]

Optional source node to whic path is relative.

sourcepath   (string)   

Path to the database node.

Return values

(number)
The number of child nodes, or zero if database node does not exist.

getChildren

function getChildren([source], sourcepath)

Get all the child nodes of the specified node.

Parameters

source   (databasenode)   [optional]

Optional source node.

sourcepath   (string)   

Absolute path (if no database node parameter), or relative path from the database node parameter.

Return values

(table)
The child nodes are returned as databasenode objects in a table with keys corresponding to the names of the child nodes. If the database node does not exist, an empty table is returned.

getChildrenGlobal

function getChildrenGlobal([source], sourcepath)

Get all the child nodes of the specified path. The path to use in the child lookup will be calculated from the parameters, then any children of that path will be compiled across the campaign database as well as all loaded module databases.

Parameters

source   (databasenode)   [optional]

Optional source node.

sourcepath   (string)   

Absolute path (if no database node parameter), or relative path from the database node parameter.

Return values

(table)
The child nodes are returned as databasenode objects in a table with keys corresponding to the names of the child nodes. If the database node does not exist, an empty table is returned.

getDefaultChildCategory

function getDefaultChildCategory(nodeid, category)

Gets the default child category for the specified data base node. When new child nodes are created under this node, the default category is given to those child nodes.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

category   (string)   

Category to set as default (or category name)

Return values

(string)
The name of the default category assigned to child nodes under the specified node.

getHolders

function getHolders(sourcenode)

This function returns a list of all users registered as holders for the specified database node. Holders will be notified of changes to the node value. Users are automatically added to the holder list as a result of window sharing operations.

Warning
This function will only work if running as a host.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

Return values

(table)
Returns an integer indexed table containing the usernames of all registered holders for this node.

getImportRulesetVersion

function getImportRulesetVersion()

Returns the release number of the ruleset used to save the data currently being imported (or last imported if called after import event).

Return values

(number)
The major version number
(number)
The minor version number
(table)
A table containing the major version number of each ruleset layer, where the key is the name of the ruleset layer.
(table)
A table containing the minor version number of each ruleset layer, where the key is the name of the ruleset layer.

getImportVersion

function getImportVersion()

Returns the version number of the FG client used to save the data currently being imported (or last imported if called after import event).

Return values

(number)
The major version number
(number)
The minor version number

getModule

function getModule(sourcenode)

Retrieves the name of the module the data base node was loaded from.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

Return values

(string)
Returns the name of the module the node was loaded from, or nil if the node was not loaded from a module

getOwner

function getOwner(nodeid)
Warning
Only valid on host.

This function returns the username of the client acting as the current owner of the specified node. Only the GM or the node owner can alter the value of the database node contents.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

Return values

(string)
Returns the username of the user owning the node, or nil if no owner is registered.

getParent

function getParent(sourcenode)

Fetches the parent of the specified node.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

Return values

(databasenode)
A databasenode object representing the parent node, or nil if the current node is a root level node or the specified node identifier does not exist.

getPath

function getPath([node], [value])

Returns a database path comprised of the optional databasenode parameter and any path parameters provided. The module portion of the path returned will be inherited from the databasenode parameter. (if provided, and if the node is from a module)

Database paths are of the form: [node].(...).[node][@Module Name]

where there can be any number of valid XML tag names concatenated by periods to form the main path and the at symbol and module name is optional.

Parameters

node   (databasenode)   [optional]

A databasenode object to be used as the basis for the path returned.

value   (...)   [optional]

One or more strings to be appended to database path returned.

Return values

(string)
The string representation of the databasenode path

getRoot

function getRoot(dbname)

Returns the root node for the specified database. If parameter missing or empty string, then the root of the campaign database is returned. Otherwise, the string is assumed to be a module name.

Parameters

dbname   (string)   

Name of the database

Return values

(databasenode)
A databasenode object representing the root node, or nil if the module specified is not loaded or does not exist.

getRulesetVersion

function getRulesetVersion(sourcenode)

Returns the release number of the ruleset last used to save the data, as defined by the release attribute of the database definition root element.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

Return values

(number)
The major version number
(number)
The minor version number
(table)
A table containing the major version number of each ruleset layer, where the key is the name of the ruleset layer.
(table)
A table containing the minor version number of each ruleset layer, where the key is the name of the ruleset layer.

getText

function getText(sourcenode, [subpath], [default])

Returns a textual representation of the value contained in the specified database node. If the node type is not string, number or formattedtext, then the default values will be returned or nil if no default values specified.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

subpath   (string)   [optional]

If the first parameter has type databasenode, then this parameter specifies the relative data node identifier path from the specified node object.

default   (...)   [optional]

The value(s) to be returned if getText fails. (node does not exist; or not string, number or formattedtext value type)

Return values

(string)
Returns the string value of the database node value.

getType

function getType(nodeid)

Get the string identifying the type of the specified node. The possible values are "node" (representing an intermediate node), "number", "string", "formattedtext", "image", "dice" and "windowreference".

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

Return values

(string)
The type string

getValue

function getValue(sourcenode, [subpath], [default])

Returns the value contained in the specified database node. The return value(s) vary depending on the type of the node. If the node does not exist or if the node is a non-value type, then the default values passed in will be returned or nil if no default values are specified.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

subpath   (string)   [optional]

If the first parameter has type databasenode, then this parameter specifies the relative data node identifier path from the specified node object.

default   (...)   [optional]

The value(s) to be returned if getValue fails. (node does not exist; or non-value node)

Return values

(...)
Returns data contained in the database node

getVersion

function getVersion(sourcenode)

Returns the version number of the FG client last used to save the data, or since the last updateVersion call.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

Return values

(number)
The major version number
(number)
The minor version number

import

function import(filename, targetnode, [listchildname])

This function imports an XML data file from the host's hard drive as children of the specified database node.

The root node of the XML data file is always ignored.

If a list child name is specified, then the target node will be assumed to be a list node, and each XML record under the data file root node with the given list child name will instantiate a unique list record and copy the contents from the XML sub-record to the new unique list record. (Ex: To import all characters from an XML file, DB.import("output.xml", "charsheet", "character"))

Warning
This function will only work if running as a host.

Parameters

filename   (string)   

The name of the file to be imported.

targetnode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

listchildname   (string)   [optional]

See function description.


isIntact

function isIntact(sourcenode)

Database nodes loaded from modules are modifiable unless marked static. These modifications are local to a campaign, and the node may be reverted back to its original state. This function may be used to check if such a node has any changes applied.

Non-module campaign data base nodes always return false.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

Return values

(boolean)
Returns false if the node has been modified, true if it is identical to the module contents

isOwner

function isOwner(nodeid)

This function returns whether the current user can modify the specified node. Only the GM or the node owner can alter the value of the database node contents.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

Return values

(boolean)
Returns true if the user is the GM or owns the node, or false otherwise.

isPublic

function isPublic(nodeid)

Returns whether the specified node is public.

Public nodes are available for viewing by any user, whether GM or player. A node can still be shared with specific players without being made public.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

Return values

(string)
Returns true if the node is public, false if it is not

isReadOnly

function isReadOnly(sourcenode)

Determines whether the specified database node can be edited. Reasons for database nodes to be non-editable include: nodes marked as static, nodes from client or common modules, nodes not owned by client (host owns all nodes)

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

Return values

(boolean)
Returns true if the node is not editable, false otherwise

isStatic

function isStatic(sourcenode)

Database nodes may be flagged as static, disabling value editing completely. This flag is generally used for non-alterable reference data loaded from rules modules. This function can be used to check if a node is part of the static content.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

Return values

(boolean)
Returns true if the node is static, false otherwise

onAuxCharLoad

function onAuxCharLoad(source)

A handler function that will be called when a character tree is loaded into memory that exists outside the primary database. (campaign characters in local mode, local characters in client mode)

Parameters

source   (databasenode)   

A databasenode object reference identifying the node causing the event


onImport

function onImport(source)

A handler function that will be called when a database tree is imported into the primary database. (i.e. character import)

Parameters

source   (databasenode)   

A databasenode object reference identifying the node causing the event


onIntegrityChange

function onIntegrityChange(source)

A handler function that will be called when a node loaded from a module is either reverted back to its original state or receives a user modification.

Parameters

source   (databasenode)   

A databasenode object reference identifying the node causing the event


removeAllHolders

function removeAllHolders(sourcenode)

This function removes all users from the holder list for the specified database node and all child nodes. The data is deleted from any client instance and any windows having a deleted node as their data source will be closed.

Warning
This function will only work if running as a host.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node


removeChildCategory

function removeChildCategory(nodeid, category)

Removes a child category for the specified data base node. Any child nodes in this category will be given an empty category.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

category   (table (or string))   

Category to remove by name (either "name" element or string)


removeHandler

function removeHandler(nodepath, event, callback)

Remove an event handler callback function previously specified using addHandler function.

Parameters

nodepath   (string)   

A data base path identifier. The '*' character can be used as a wildcard for a path segment.

event   (string)   

The event to be captured (onUpdate, onAdd, onDelete, onObserverUpdate, onChildAdded, onChildUpdate, onChildDeleted, onIntegrityChange)

callback   (function)   

The callback function to be removed


removeHolder

function removeHolder(sourcenode, username)

This function removes the specified user from the holder list for the specified database node and all child nodes. The data is deleted from the client instance and any windows having a deleted node as their data source will be closed.

Warning
This function will only work if running as a host.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

username   (string)   

The username of the user losing the holder status


revert

function revert(sourcenode)

Return a node loaded from a module back to the state it was when loaded. If the target node was not loaded from a module, or if it does not have any changes, this operation has no effect.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node


setCategory

function setCategory(nodeid, category)

Sets the category for the specified data base node. The category parameter can also be a table with a "name" element.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

category   (table (or string))   

Category information for specified node, including the following fields (name, mergeid, base, decal). If a string is specified, it will be used as a new table with the string as the name element.


setDefaultChildCategory

function setDefaultChildCategory(nodeid, category)

Sets the default child category for the specified data base node. When new child nodes are created under this node, the default category is given to those child nodes.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

category   (table (or string))   

Category name to set as default (either "name" element or string)


setOwner

function setOwner(nodeid, owner)
Warning
Only valid on host.

This function sets the owner of the specified node to the specified player name. Only the GM or the node owner can alter the value of the database node contents.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

owner   (string)   

The name of the player to gain ownership of the data base node


setPublic

function setPublic(nodeid, value)

Sets whether the specified node is public. While public, all addHolder, removeHolder and removeAllHolders function calls will be ignored.

Public nodes are available for viewing by any user, whether GM or player. A node can still be shared with specific players without being made public.

Warning
Rulesets with compatibility less than v3.0 that call this function will generate a script error.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

value   (boolean)   

If set to true, then the node will be set to the public state; otherwise, the node will be set to the non-public (unshared) state.


setStatic

function setStatic(sourcenode, state)

Sets the static flag of a database node. The values of static nodes are not modifiable.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

state   (boolean)   

A value of true to set the node static, or false to remove the static state.


setValue

function setValue(sourcenode, [subpath], type, value)

Sets the data in the specified database node path. If the node exists already, the type value must match the existing database node type. If the node does not exist, a new node will be created with the specified type. The format of the value parameter(s) depends on the type of the node.

Parameters

sourcenode   (string (or databasenode))   

A data node identifier path (or a databasenode object) representing the target node

subpath   (string)   [optional]

If the first parameter has type databasenode, then this parameter specifies the relative data node identifier path from the specified node object.

type   (string)   

Identifier for the data type of the new or existing node.

value   (...)   

Data to be placed in the database node


updateChildCategory

function updateChildCategory(nodeid, source_category, target_category)

Updates the child category information for the specified data base node. The source category with the given name will be replaced wih tht target category, and the category information for all child nodes will be updated.

Parameters

nodeid   (string (or databasenode))   

Data node identifier path (or databasenode object)

source_category   (table (or string))   

Original category information (or name)

target_category   (table (or string))   

Desired category information (or name)


updateVersion

function updateVersion()

Sets the version number value of the campaign database to the current FG and ruleset versions.



'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