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
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.
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
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
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
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(
)
Returns a list of all the identities that are targeting this token.
Return values
(table)
An integer indexed table containing a list of all the identity names targeting this token
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, one or more identities are targeting this token. If no identity is targeting
this token, returns false.
isTargetedByIdentity
function isTargetedByIdentity(
[targetedby]
)
Determines if the token is targeted by the specified identity.
Parameters
targetedby (string) [optional]
The name of the identity whose target flag is to be set. If this parameter is omitted, the users currently
active identity is used.
Return values
(boolean)
If true, the specified ideneity is targeting this token, false
otherwise.
isVisible
function isVisible(
)
Get the visibility status of the token instance.
Return values
(boolean)
Returns true if the token is visible, false otherwise
onActivation
handler
function onActivation(
target
)
This handler is called when the target token is activated.
Parameters
target (tokeninstance)
onClickDown
handler
function onClickDown(
target, button
)
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)
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.
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
handler
function onClickRelease(
target, button
)
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)
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.
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
handler
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)
onContainerChanging
handler
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)
onDelete
handler
function onDelete(
target
)
This handler is called when the target token is deleted.
Parameters
target (tokeninstance)
onDoubleClick
handler
function onDoubleClick(
target
)
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)
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
handler
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)
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
handler
function onHover(
target, state
)
This handler is called when the hover state of this token changes.
Parameters
target (tokeninstance)
state (boolean)
true if the mouse is entering the area, false if leaving
onHoverUpdate
handler
function onHoverUpdate(
target, x, y
)
This handler is called when the mouse cursor is moved while over this token.
Parameters
target (tokeninstance)
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
handler
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)
...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
handler
function onMove(
target
)
This handler is called when the target token is moved.
Parameters
target (tokeninstance)
onScaleChanged
handler
function onScaleChanged(
target, scale
)
This handler is called when the target token scaling is changed.
Parameters
target (tokeninstance)
scale (number)
The new scaling value for this token relative to the global scaling for the token container.
onTargetUpdate
handler
function onTargetUpdate(
target
)
This handler is called when the targeting information for the target token is changed.
Parameters
target (tokeninstance)
onWheel
handler
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)
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.
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
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, [targetedby]
)
Sets a target flag on the token. Targeting flags are identity specific, i.e. each token may be targeted by more than one
identity.
Parameters
state (boolean)
The state of the targeting flag. A value of true to set the target for the specified identity
or false to reset it.
targetedby (string) [optional]
The name of the identity whose target flag is to be set. If this parameter is omitted, the users currently
active identity is used.
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
