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
addUnderlay
clearTargets
delete
getContainerNode
getContainerScale
getId
getImageSize
getName
getOrientation
getPosition
getPrototype
getScale
getTargetingIdentities
getTargets
isActivable
isActive
isModifiable
isTargetable
isTargeted
isTargetedBy
isTargetedByIdentity
isVisible
onActivation
onClickDown
onClickRelease
onContainerChanged
onContainerChanging
onDelete
onDoubleClick
onDrag
onDragEnd
onDragStart
onDrop
onHover
onHoverUpdate
onMenuSelection
onMove
onScaleChanged
onTargetUpdate
onTargetedUpdate
onWheel
registerMenuItem
removeAllUnderlays
resetMenuItems
setActivable
setActive
setContainerScale
setModifiable
setName
setOrientation
setOrientationMode
setPosition
setScale
setTarget
setTargetable
setVisible



This object represents a token instance placed in a token container. Token instances are based on token prototypes that define the bitmap used for the token. A token container can contain several instances of one prototype.

By default, token instances can be manipulated by the host and all clients. The token container may be locked, in which case vectors may be drawn out from the token by the clients to indicate movement requests. Tokens can also be toggled non-modifiable which disallows client interaction altogether.

Tokens flagged targetable can be clicked by players to indicate they are targeting the corresponding token. Several clients can target one token.

Token instances do not have direct scripting function definitions, but use a handler based notification scheme. Care should be taken to unregister handlers whenever the objects containing the handler script are destroyed.



Interface


addUnderlay

function addUnderlay(size, color, [mode])

Add an underlay to the token. Underlays are colored areas drawn based on the grid squares below the token. The size of underlays is given in squares and is measured as a radius from the token centre to the grid square centres. Thus, an equal value as the underlay size will result in a different sized overlay area based on whether the token is situated at a grid square centre or a grid line intersection.

Only scripts running on the session host can set this property.

Parameters

size   (number)   

The size of the underlay in grid squares

color   (string)   

The color of the underlay, in the form '#aarrggbb' where 'aa' represents the transparency (alpha) of the desired color. If alpha is zero or not defined, FF is assumed.

mode   (string)   [optional]

If this string contains the substring "gmonly", this overlay will be displayed on the host only. If the string contains the substring "hover", the overlay will only be drawn when the mouse cursor is hovering over the token. The flags can be combined.


clearTargets

function clearTargets()

Clears the targets for this token.


delete

function delete()

Destroy the token instance, removing it from the token container.


getContainerNode

function getContainerNode()

Returns a reference to a databasenode object representing the data for the image containing the token instance. The node name and the token id number (see getId) can be used together to identify the specific token in a saved session.

Return values

(databasenode)
The databasenode representing the image containing the token

getContainerScale

function getContainerScale()

Returns the global relative scaling between this token and the image control containing this token instance as a pixel to pixel ratio.

Any token specific scaling is applied in addition to any global token scaling value in the image control.

Return values

(number)
The size scale factor used for rendering the token

getId

function getId()

Returns the id number of the token in the image database node representing the image containing the token instance. See getContainerNode for more information.

Return values

(number)
The identifier number for this token instance

getImageSize

function getImageSize()

Returns the size of the bitmap used for this token instance.

Return values

(number)
The width on the image.
(number)
The height on the image.

getName

function getName()

Return a string containing the name of the token instance, as displayed in the tool tip drawn when the mouse cursor hovers over the token.

Return values

(string)
The name of the token instance

getOrientation

function getOrientation()

Returns the orientation value of the token.

Return values

(number)
Returns the current orientation

getPosition

function getPosition()

Return the coordinates the token is located at, relative to the origin of the token container.

Return values

(number)
The horizontal position of the token
(number)
The vertical position of the token

getPrototype

function getPrototype()

Gets the string identifying the token prototype used for this token instance.

Return values

(string)
Returns the string representing the prototype

getScale

function getScale()

Return the size scaling value used for rendering the token in the image control. Any token specific scaling is applied in addition to any global token scaling value in the image control.

Return values

(number)
The size scale factor used for rendering the token

getTargetingIdentities

function getTargetingIdentities()
Warning
Deprecated.

Targeting is now token to token targeting, instead of identity to token targeting.


getTargets

function getTargets()

Gets the set of targets for this token.

Return values

(table)
Table of token IDs (number) identifying the tokens targeted.

isActivable

function isActivable()

Indicates whether the token can be activated. See setActive for more information.

Only scripts running on the session host can set this property.

Return values

(boolean)
Returns true if the token is activable, false otherwise.

isActive

function isActive()

Determine if the token is currently active. See setActive for more information.

Return values

(boolean)
Returns true if the token is active, false otherwise.

isModifiable

function isModifiable()

Returns the modifiability flag status.

Return values

(boolean)
Returns true if the token can be interacted with by the clients, false otherwise

isTargetable

function isTargetable()

Returns the targetability flag status.

Return values

(boolean)
Returns true if the token is targetable, false otherwise

isTargeted

function isTargeted()

Determines if the token is targeted by one or more identities.

Return values

(boolean)
If true, at least one token is targeting this token. Otherwise, returns false.

isTargetedBy

function isTargetedBy(tokenid)

Determines if this token is targeted by the specified token.

Parameters

tokenid   (number (or tokeninstance))   

Token ID to check for targeting info. (or tokeninstance object)

Return values

(boolean)
If true, the specified token is targeting this token. Otherwise, returns false.

isTargetedByIdentity

function isTargetedByIdentity()
Warning
Deprecated.

Targeting is now token to token targeting, instead of identity to token targeting.


isVisible

function isVisible()

Get the visibility status of the token instance.

Return values

(boolean)
Returns true if the token is visible, false otherwise

onActivation

function onActivation(target)

This handler is called when the target token is activated.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event


onClickDown

function onClickDown(target, button, image)

This function is called when a mouse button is pressed down on the token. If this function is not defined or returns false, the onClickRelease function is not called.

Warning
The token interface for click events is different than other objects in that a handler must be registered to intercept click events.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

button   (number)   

Returns a numerical value indicating the button pressed (1 = left, 2 = middle, 4 = button 4, 5 = button 5). Right button is used for radial menus.

image   (imagecontrol)   

The imagecontrol object in which the token was clicked.

Return values

(boolean)
This function should return true if it handled the event and the processing of the event should be stopped. A value of false indicates that the default framework functionality for the this particular control should not be executed, but the processing should continue for the element below this control, if any. A return value of nil (or the absence of a return statement) indicates that the framework should continue handling the event normally.

onClickRelease

function onClickRelease(target, button, image)

This function is called when a mouse button is released, if the cursor was not moved after the click down event. If the control did not process the click down event, this function is not called.

Warning
The token interface for click events is different than other objects in that a handler must be registered to intercept click events.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

button   (number)   

Returns a numerical value indicating the button pressed (1 = left, 2 = middle, 4 = button 4, 5 = button 5). Right button is used for radial menus.

image   (imagecontrol)   

The imagecontrol object in which the token was clicked.

Return values

(boolean)
This function should return true if it handled the event and the processing of the event should be stopped. A value of false indicates that the default framework functionality for the this particular control should not be executed, but the processing should continue for the element below this control, if any. A return value of nil (or the absence of a return statement) indicates that the framework should continue handling the event normally.

onContainerChanged

function onContainerChanged(target)

This handler is called after the target token is added to a new token container after being removed from a its previous token container.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event


onContainerChanging

function onContainerChanging(target)

This handler is called just before the target token is removed from its token container and added to a new token container.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event


onDelete

function onDelete(target)

This handler is called when the target token is deleted.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event


onDoubleClick

function onDoubleClick(target, image)

This function is called when the left mouse button is pressed down twice in succession on the token. Note that if this function is present and returns nil, the onClickDown function is called as well.

Warning
The token interface for click events is different than other objects in that a handler must be registered to intercept click events.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

image   (imagecontrol)   

The imagecontrol object in which the token was clicked.

Return values

(boolean)
This function should return true if it handled the event and the processing of the event should be stopped. A value of false indicates that the default framework functionality for the this particular control should not be executed, but the processing should continue for the element below this control, if any. A return value of nil (or the absence of a return statement) indicates that the framework should continue handling the event normally.

onDrag

function onDrag(target, button, x, y, dragdata)

This function is called when the mouse is moved after having been pressed down on the token. The event is called repeatedly as the user adjusts the mouse position.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

button   (number)   

1 if the event was caused by the left mouse button, 2 if it was caused by the middle (wheel) button.

x   (number)   

The X coordinate relative to the top left corner of the token

y   (number)   

The Y coordinate relative to the top left corner of the token

dragdata   (dragdata)   

A dragdata object containing the state of values connected to the mouse cursor as part of a drag and drop operation.

Return values

(boolean)
This function should return true if it handled the event and the processing of the event should be stopped. A value of false indicates that the default framework functionality for the this particular control should not be executed, but the processing should continue for the element below this control, if any. A return value of nil (or the absence of a return statement) indicates that the framework should continue handling the event normally.

onDragEnd

function onDragEnd(target, dragdata)

This function is called when the mouse is released at the end of a drag operation that started on the token. The dragdata object is first passed to the onDrop handler in the receiving control, which can set properties in the dragdata object that notify this control of the events.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

dragdata   (dragdata)   

A dragdata object containing the state of values connected to the mouse cursor as part of a drag and drop operation.


onDragStart

function onDragStart(target, button, x, y, dragdata)

This function is called when the mouse is moved after having been pressed down on the token. The event is called once.

If a customized drag and drop transfer is done, the dragdata parameter should be used to make the required changes.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

button   (number)   

1 if the event was caused by the left mouse button, 2 if it was caused by the middle (wheel) button.

x   (number)   

The X coordinate relative to the top left corner of the token

y   (number)   

The Y coordinate relative to the top left corner of the token

dragdata   (dragdata)   

A dragdata object containing the state of values connected to the mouse cursor as part of a drag and drop operation.

Return values

(boolean)
This function should return true if it handled the event and the processing of the event should be stopped. A value of false indicates that the default framework functionality for the this particular control should not be executed, but the processing should continue for the element below this control, if any. A return value of nil (or the absence of a return statement) indicates that the framework should continue handling the event normally.

onDrop

function onDrop(target, dragdata)

This function is called when a drag and drop operation finishes on the token. The dragdata parameter should be used to access the dragged information.

To transfer information back to the control where the drag originated, the same dragdata object is passed to the onDragEnd function in that control.

Warning
The token interface for drop events is different than other objects in that a handler must be registered to intercept drop events.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

dragdata   (dragdata)   

A dragdata object containing the state of values connected to the mouse cursor as part of a drag and drop operation.

Return values

(boolean)
This function should return true if it handled the event and the processing of the event should be stopped. A value of false indicates that the default framework functionality for the this particular control should not be executed, but the processing should continue for the element below this control, if any. A return value of nil (or the absence of a return statement) indicates that the framework should continue handling the event normally.

onHover

function onHover(target, state)

This handler is called when the hover state of this token changes.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

state   (boolean)   

true if the mouse is entering the area, false if leaving


onHoverUpdate

function onHoverUpdate(target, x, y)

This handler is called when the mouse cursor is moved while over this token.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

x   (number)   

The X coordinate of the mouse pointer in pixels relative to the top left corner of the token

y   (number)   

The Y coordinate of the mouse pointer in pixels relative to the top left corner of the token


onMenuSelection

function onMenuSelection(target, ...)

This function is called when a user defined item is selected in the token's radial menu.

Warning
The token interface for menus is different than other objects in that a handler must be registered to intercept menu events.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

...

A variable amount of number parameters, depending on the menu hierarchy depth of the selected item. A first level menu item will contain one number, identifying the slot it occupies on the menu. A second level item will contain two numbers, with the first specifying the submenu position, and the second the position of the item in the submenu. See registerMenuItem for more information.


onMove

function onMove(target)

This handler is called when the target token is moved.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event


onScaleChanged

function onScaleChanged(target, scale)

This handler is called when the target token scaling is changed.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

scale   (number)   

The new scaling value for this token relative to the global scaling for the token container.


onTargetUpdate

function onTargetUpdate(source, target, status)

This handler is called when target information for this token changes.

Parameters

source   (tokeninstance)   

The tokeninstance triggering the event

target   (tokeninstance)   

The tokeninstance of the target token.

status   (boolean)   

Current target status. True if targeted; false if not.


onTargetedUpdate

function onTargetedUpdate(source, target, status)

This handler is called when this token is targeted or untargeted by another token.

Parameters

source   (tokeninstance)   

The tokeninstance of the source token.

target   (tokeninstance)   

The tokeninstance triggering the event

status   (boolean)   

Current target status. True if targeted; false if not.


onWheel

function onWheel(target, notches)

This function is called when the mouse wheel is spun over the token.

Warning
The token interface for wheel events is different than other objects in that a handler must be registered to intercept click events.

Parameters

target   (tokeninstance)   

The tokeninstance triggering the event

notches   (number)   

This number specifies the number of notches the wheel was spun. Typically one notch corresponds to one adjustment step on the wheel.

Return values

(boolean)
This function should return true if it handled the event and the processing of the event should be stopped. A value of false indicates that the default framework functionality for the this particular control should not be executed, but the processing should continue for the element below this control, if any. A return value of nil (or the absence of a return statement) indicates that the framework should continue handling the event normally.

registerMenuItem

function registerMenuItem(label, icon, ...)

This function registers a new user defined menu item. If the user selects the item, the script is notified of this through the onMenuSelection handler, if registered.

The menu item is defined by specifying the bitmap and label to use, as well as the position of the item on the menu. The position is given as a number value. To define entries in submenus, use multiple number values, with the first being the position value of the outermost submenu, and the last being the position of the actual menu item in the innermost submenu.

Trying to redefine an existing menu item will fail.

Warning
The token interface for menus is different than other objects in that a handler must be registered to intercept menu events.

Parameters

label   (string)   

A string to be used as the label of the menu item

icon   (string)   

The name of an icon resource to use as the bitmap for the menu item

...

A list of numbers specifying the menu item position as a number between 1 and 8, with one being the top slot, and the progression of numbers proceeding in a clockwise direction.


removeAllUnderlays

function removeAllUnderlays()

Removes all underlays from the token.


resetMenuItems

function resetMenuItems()

This function unregisters all user defined menu items. It does not affect menu entries defined by the application engine.


setActivable

function setActivable(state)

Determine whether the token can be activated. See setActive for more information.

Parameters

state   (boolean)   

A value of true to enable activation, false to disable it


setActive

function setActive(state)

Determines whether the token is currently marked active. Active markers can be used by the host to indicate a single token in a container, e.g. to represent it is currently active in a turn sequence.

Parameters

state   (boolean)   

Returns true if this token is presently marked active, false otherwise.


setContainerScale

function setContainerScale(scale)

Sets the global relative scaling between this token and the image control containing this token instance as a pixel to pixel ratio.

Any token specific scaling is applied in addition to any global token scaling value in the image control.

Parameters

scale   (number)   

The requested non-negative scaling factor


setModifiable

function setModifiable(state)

Flags the token modifiability status. Non-modifiable tokens can't be interacted with by the clients.

Only scripts running on the session host can set this property.

Parameters

state   (boolean)   

A value of false to disable client interactions with the token, or true to allow them.


setName

function setName(name)

Sets the name string used as the tooltip for the token.

Parameters

name   (string)   

A string containing the value to use as the token name and tooltip


setOrientation

function setOrientation(orientation)

Sets the orientation, i.e. rotation state, of the token.

Parameters

orientation   (number)   

The desired new rotation value


setOrientationMode

function setOrientationMode(mode)
Warning
Available on host only.

Sets token rotation mode for this token, which overrides imagecontrol setting. (physical token rotation or facing arrows)

Parameters

mode   (string)   

Desired orientation mode (rotation or facing).


setPosition

function setPosition(x, y)

Sets the coordinates the token is located at in the token container.

Parameters

x   (number)   

The horizontal position the token is placed at

y   (number)   

The vertical position the token is placed at


setScale

function setScale(scale)

Sets the size scaling factor used in rendering the token instance in the image control. A token specific scaling value is applied in addition to any global token scaling used in the image control.

Parameters

scale   (number)   

The requested non-negative scaling factor


setTarget

function setTarget(state, targeter)

Sets the target state of this token as a target of the specified token.

Parameters

state   (boolean)   

A value of true to set the target, or false to reset it.

targeter   (string)   

Token ID to check for targeting info. (or tokeninstance object)


setTargetable

function setTargetable(state)

Sets the targetablility flag for the token.

Only scripts running on the session host can set this property.

Parameters

state   (boolean)   

The value true to enable targeting, false otherwise


setVisible

function setVisible(state)

Set the client visibility for the token. A hidden token will not be displayed to the clients, and will be drawn with 50% transparency on the host.

Parameters

state   (boolean)   

Set to true to show the token, false to hide it



'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