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
createLocalIdentity
getActiveUsers
getAllActiveIdentities
getCampaignName
getCurrentIdentity
getCurrentIdentityColors
getIdentityColor
getIdentityLabel
getIdentityOwner
getLocalIdentities
getLocalIdentityPortrait
getOwnedIdentities
getPortraitDirectoryList
getPortraitFileList
getRemoteIdentities
getRulesetName
getUsername
isHost
isLocal
isOwnedIdentity
kick
onIdentityActivation
onIdentityStateChange
onLogin
onUserStateChange
releaseIdentity
requestIdentity
ringBell
setCurrentIdentity
setCurrentIdentityColors
setLocalIdentityPortrait
setPortrait



This is a global built in package that provides information about and methods for handling the data for the currently active identities and users. The package also provides handlers for user and identity activation and state monitoring.



Interface

createLocalIdentity

function createLocalIdentity( )

Creates a new entry into the local character list. The return value is a databasenode object containing the root node of the new character's data.

Return values

(databasenode)
A databasenode object identifying the new character and containing the character's data

getActiveUsers

function getActiveUsers( )

Get the list of users names for all connected clients.

Return values

(table)
An integer indexed table containing string values representing the connected users

getAllActiveIdentities

function getAllActiveIdentities( )

Get the list of identity names in use by all connected clients.

Return values

(table)
An integer indexed table containing string values representing the identities in use

getCampaignName

function getCampaignName( )

Returns the name of the currently active campaign.

Return values

(string)
The name of the active campaign

getCurrentIdentity

function getCurrentIdentity( [username] )

This function returns the identity identifier of the currently active identity. By default, the identity is queried for the active user. If running as the host, the parameter may be specified to indicate a username of a connected client whose current identity selection will be returned.

Parameters

username(string)[optional]
The username of the client whose current identity is being queried

Return values

(string)
The identity identifier of the currently active identity

getCurrentIdentityColors

function getCurrentIdentityColors( )

This function returns the colors used for the current identity. The function returns the color used for the die base and the pointers painted when this identity is active, and whether black or white text is used on the dice.

Return values

(string)
A string containing the color for the die base and pointers, in the format "RRGGBB" where the color components are hexadecimal digits representing color channel values in the range 0 .. 255
(boolean)
A value of true will render dice text as black, a value of false will use white color

getIdentityColor

function getIdentityColor( identity )

This function returns the currently active color selection for the specified identity. The color will be given as a string value in the format "AARRGGBB" where the components are hexadecimal digits representing the values (in the range 0 .. 255) for alpha (transparency), red, green and blue color channels, respectively.

Parameters

identity(string)
The identifier of the identity whose color is being queried

Return values

(string)
The color for the queried identity in the form "AARRGGBB"

getIdentityLabel

function getIdentityLabel( [identityname] )

Fetch the string used as the label for the specified identity. If the identity name is not specified, the label for the current identity will be retrieved.

Parameters

identityname(string)[optional]
The identity identifier for the identity whose label is being queried

Return values

(string)
The label of the identity, or nil if no identity is active or running as the host

getIdentityOwner

function getIdentityOwner( identityname )

Fetch the name of the user that owns the specified identity.

Parameters

identityname(string)
The name of the identity for which the owner is being queried

Return values

(string)
The name of the user who owns the identity, or nil if the identity is not owned by any user

getLocalIdentities

function getLocalIdentities( )

Lists the currently available locally saved characters that can be used as identities in the running connected session, or in the active local mode session.

If the application is running in local mode, and a cached campaign has been selected, this list also includes characters used in the remote session. These characters' data cannot be modified. When connected to a running session, these identities are not included.

Each local mode character entry consists of a table with two or three values. The dbnode value contains a databasenode object reference identifying the database node containing the information for the character. The session value contains a string identifying the session the character is associated with, and is empty for characters that aren't used in remote campaigns. The id value is the identifier of the identity, and is only present for characters used in remote campaigns.

Return values

(table)
An integer indexed table containing entries with information about locally available characters.

getLocalIdentityPortrait

function getLocalIdentityPortrait( identityroot )

This function fetches the portrait set for a local character. The character is identified by a databasenode reference obtained from User.getLocalIdentities.

Parameters

identityroot(databasenode)

Return values

(string)
A string identifying the currently set portrait. This value should only be used to pass to other portrait elements using functions such as portraitselectioncontrol.setFile

getOwnedIdentities

function getOwnedIdentities( )

Get the list of identity names owned by this client.

Return values

(table)
An integer indexed table containing string values representing the identities in use

getPortraitDirectoryList

function getPortraitDirectoryList( )

This function fetches a list of the directories in the portraits subfolder found in the current campaign directory. If a relative path is defined, then the relative path will be appended to the campaign portraits directory path before retrieveing directories. The contents of the returned list should not be used directly, but rather can be used to populate controls in a portrait selection window.

Return values

(table)
An integer indexed list of strings containing the directories found

getPortraitFileList

function getPortraitFileList( )

This function fetches a list of the portrait files found in the locally installed portrait folder. The contents of the returned list should not be used directly, but rather can be used to populate controls in a portrait selection window.

Return values

(table)
An integer indexed list of strings containing the filenames of the portrait images found

getRemoteIdentities

function getRemoteIdentities( node, labelnode, resultcallback )

Lists the identities available for the current user on the remote host. The list will include unowned identities and identities owned by the user with the current username.

The identity list is populated using the session data base, and will include all the child nodes of the node identified by the node parameter. The labelnode parameter will be used to fetch a child node of the identity node, and will contain the text used as the label for the identity.

Parameters

node(string)
A global database identifier identifying the node in the session database from where the list of identities should be retrieved
labelnode(string)
The name of a child node under the identity node containing the string value to use as a label for the identity
resultcallback(function)
A callback function that will be called for each matching result delivered by the host. The function will receive two string value parameters representing the identity identifier and the label for the identity, respectively.

getRulesetName

function getRulesetName( )

Returns the name of the currently active ruleset.

Return values

(string)
The name of the active ruleset

getUsername

function getUsername( )

Returns the local user's network username.

Return values

(string)
The username string

isHost

function isHost( )

Check if the currently running application instance is acting as a session host.

Return values

(boolean)
Returns true if running as the host and false if running as a client. Always returns false in local mode.

isLocal

function isLocal( )

Check if the currently running application instance is running in local mode.

Return values

(boolean)
Returns true if running in local mode and false otherwise

isOwnedIdentity

function isOwnedIdentity( identityname, [username] )

This function can be used to check if an identity is owned by the current user (on the client) or held by a specific user (on the host).

Parameters

identityname(string)
The identity whose status is being queried
username(string)[optional]
The username whose ownership is being queried. Only used when calling from the host machine.

Return values

(boolean)
If true, the user owns the identity, otherwise false.

kick

function kick( username )

Kicks the specified user from the session, and release all their identities.

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

Parameters

username(string)
The user name to kick

onIdentityActivation

handler function onIdentityActivation( username, identityname, activated )

Registered functions on this handler are called when a user activates or deactivates an identity.

Parameters

username(string)
The username of the user triggering the event
identityname(string)
The identifier of the identity being activated or deactivated
activated(boolean)
A value of true if the identity is being activated, or false otherwise

onIdentityStateChange

handler function onIdentityStateChange( identityname, username, statename, state )

Registered functions on this handler are called when the state of an activated identity changes.

If the value of the statename parameter is "current", the event indicates that the user has changed his currently active identity. The event is triggered once for each of the users activated identities, the state parameter being true for the newly activated identity and false otherwise.

If the value of the statename parameter is "label", the event indicates that the specified identity's label string has been changed. In this case, the state parameter is a string containing the value of the new label string.

If the value of the statename parameter is "color", the identity's color has changed. The state parameter should be ignored, and the getIdentityColor function used to update the color setting's display.

Parameters

identityname(string)
The identifier of the identity that is the target of the operation triggering the event
username(string)
The username of the user triggering the event
statename(string)
A string representing the identity state flag whose value is changing. See above for details.
state(any)
The new value for the user state flag. See above for details.

onLogin

handler function onLogin( username, activated )

Registered functions on this handler are called whenever a user logs in to or out of the running session.

Parameters

username(string)
The username of the connecting/disconnecting client
activated(boolean)
This value is true if the user is logging on, or false if the user is logging off

onUserStateChange

handler function onUserStateChange( username, statename, state )

Registered functions on this handler are called when the state of a connected user changes.

Currently, this event notifies the user interface of changes in the user's input activity. The possible values for the statename paramter are "active", "typing" and "idle". For these events, the state variable is always true.

Parameters

username(string)
The username of the client triggering the event
statename(string)
A string representing the user state flag whose value is changing. See above for details.
state(boolean)
The new value for the user state flag. See above for details.

releaseIdentity

function releaseIdentity( identityname )

Release the specified identity, deactivating it from current use.

Parameters

identityname(string)
The name of the identity to release

requestIdentity

function requestIdentity( name, local, resultcallback )

Send a request to activate the given identity to the host. The request may fail if the identity is already in use or owned by another user.

Parameters

name(string)
The identity identifier of the identity requested
local(boolean)
This value should be true if the identity being activated is a local character.
resultcallback(function)
A function that will be called when the request is complete. The function will receive three parameters. The first parameter is a boolean value indicating whether the request was successful (true) or not (false). The second parameter is a string containing the identifier of the requested identity. The third parameter is a boolean value containing the value given as the local parameter to the requestIdentity call.

ringBell

function ringBell( username )

Rings a bell on the client computer, specified by user name parameter. If no parameter is supplied, then the bell will be rung on all clients.

Parameters

username(string)
Optional. The user name of the client where the bell is to be rung.

setCurrentIdentity

function setCurrentIdentity( identityname )

This function changes the active identity for the current client. If the identity is used by another client or not owned by the current user, the function will fail.

Parameters

identityname(string)
The identity identifier of the identity to activate

setCurrentIdentityColors

function setCurrentIdentityColors( color, blacktext )

This function sets the colors used for the current identity. The function sets the color used for the die base and the pointers painted when this identity is active, and determines whether to use black or white text on the dice.

Parameters

color(string)
A string containing the color for the die base and pointers, in the format "RRGGBB" where the color components are hexadecimal digits representing color channel values in the range 0 .. 255. If alpha is zero or not defined, FF is assumed.
blacktext(boolean)
A value of true will render dice text as black, a value of false will use white color

setLocalIdentityPortrait

function setLocalIdentityPortrait( identityroot )

This function sets the portrait for a local character. The character is identified by a databasenode reference obtained from User.getLocalIdentities or User.createLocalIdentity.

Parameters

identityroot(databasenode)

Return values

(string)
A string identifying the currently set portrait. This value should only be used to pass to other portrait elements using functions such as portraitselectioncontrol.setFile

setPortrait

function setPortrait( identity, portraitfile )

This function changes the portrait of the specified identity to the one represented by the given portrait file. If used in local mode (i.e. Manage Characters), then only a databasenode may be used for the first parameter.

Parameters

identity(string (or databasenode))
The node name (not full path) of the character identity whose portrait is being changed, or a databasenode object representing the target identity.
portraitfile(string)
The file identifying the portrait to use


'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