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
addToken
clearSelectedTokens
deleteDrawing
enableGridPlacement
getCursorMode
getDrawingTool
getGridHexElementDimensions
getGridOffset
getGridSize
getGridSnap
getGridType
getImageSize
getMaskTool
getSelectedTokens
getTokenLockState
getTokenOrientationCount
getTokenScale
getTokens
getViewpoint
hasDrawing
hasGrid
hasMask
hasTokens
isTokenSelected
onCursorModeChanged
onDrawStateChanged
onDrawingSizeChanged
onGridStateChanged
onMaskingStateChanged
onMeasurePointer
onMeasureVector
onPointerSnap
onTargetSelect
onTokenAdded
onTokenSnap
preload
resetPointers
selectToken
setCursorMode
setDrawingSize
setDrawingTool
setGridOffset
setGridSize
setGridSnap
setGridToolType
setGridType
setMaskEnabled
setMaskTool
setTokenLockState
setTokenOrientationCount
setTokenOrientationMode
setTokenScale
setViewpoint
setViewpointCenter
snapToGrid



Inherits windowcontrol databasecontrol
Context windowinstance

Image controls are used to display large images stored in the database. Image controls support tokens and pointers as well as a toggleable grid with variable dimensions.

The control internally supports the "token" and "shortcut" dragdata types, with the former creating new token instances on the control, and the latter creating shortcut icons.

Distances will be automatically calculated for pointers and token paths based on the values specified in the distance tag, unless onMeasurePointer or onMeasureVector are defined (respectively).

Tokens and pointers will automatically be snapped to a grid point when grid snap is enabled, unless onTokenSnap or onPointerSnap are defined (respectively).

The grid snap status for an image is undefined until set using the defaultsnap tag or via the radial menu.



Definition

<imagecontrol name="..." >
<indicators > This section contains names for bitmaps used to indicate image control state
<availability > ... </availability> The name of the icon resource used to notify the host user that all clients have downloaded the image being displayed
<locked > ... </locked> The name of the icon resource used to notify that the drawing layer is locked
<zoom > ... </zoom> The name of the icon resource used to notify that the active zoom level is different from 100%
<shortcuts > ... </shortcuts> The name of the icon resource used to notify the host user that the shortcuts are being displayed and can be manipulated
<loading > ... </loading> The name of the icon resource used for client users to draw a notification in the middle of the control when the image is being downloaded
</indicators>
<shortcut > Information about the image used to represent shortcuts
<icon > ... </icon> The name of the icon resource used to draw the shortcut
<hotspot > ... </hotspot> The offset on the bitmap representing the location to pinpoint shortcut, as two comma separated numbers
</shortcut>
<default > Specify default settings for the control
<gridtype > ... </gridtype> The type of grid to set by default (hexrow, hexcolumn, square). The default value is square, if not defined.
<gridsize > ... </gridsize> The size in pixels of the grid units (square or hex). The default value is zero (which means no grid).
<gridoffset > ... </gridoffset> The X and Y coordinates to offset the first grid square from the upper left corner of the map. The default value is (0,0).
<snap > ... </snap> Defines whether tokens and pointers are automatically snapped to grid. Valid values are "on" and "off". If the underlying image database value already has a snap setting (specified by GM or imagecontrol), then this value is ignored on load.
<snapsquare > ... </snapsquare> Defines the grid snap style when using a rectangular grid. Valid values are ("center", "vertexandcenter"). The default style is "vertexandcenter".
<snaphex > ... </snaphex> Defines the grid snap style when using a hex grid. Valid values are ("center", "vertexandcenter"). The default style is "center".
<drawingsize > ... </drawingsize> The size used for the initial imagecontrol drawing, if the image record is a pure drawing (i.e. created by GM, not by image in the campaign images directory)
</default>
</imagecontrol>


Interface

addToken

function addToken( prototypename, x, y )

This function creates a new token instance in the control. The name of the prototype should be treated as an identifier obtained from another location (such as a tokencontrol or another imagecontrol) and not be directly edited by the calling script.

Parameters

prototypename(string)
The string identifying the token prototype to use for creating the token instance
x(number)
The X coordinate the token should be created at
y(number)
The Y coordinate the token should be created at

Return values

(tokeninstance)
A reference to a tokeninstance object representing the newly created token or nil in case of error.

clearSelectedTokens

function clearSelectedTokens( )

Clears any actively selected tokens.


deleteDrawing

function deleteDrawing( )

Deletes the entire drawing layer.


enableGridPlacement

function enableGridPlacement( )

Enables grid placement mode, using the currently set grid placement tool.


getCursorMode

function getCursorMode( )

Get the currently active cursor mode for this control. Valid values are (nil, "mask", "unmask", "draw", "erase", "setgrid", "select", "target").

Return values

(string)
The current cursor mode

getDrawingTool

function getDrawingTool( )

Gets the currently selected drawing tool. Valid values are "paint" and "erase".

Return values

(string)
The current paint mode, or nil if paint mode is not active

getGridHexElementDimensions

function getGridHexElementDimensions( )

This utility function helps with the location of points on the hex grid. Hexes are drawn by treating the grid size as the number of pixels between opposing straight sides (vertical or horizontal depending on the type). The hexagonal shape is then calculated in an integer approximation by calculating a "half height" value (half of the grid size, rounded down) and a "quarter width" (grid size * tan(30 degrees) / 2, rounded down). The size of the hex is then considered to be twice the half height from straight side to straight side, and four times the quarter width along the longest axis.

Return values

(number)
The quarter width of the hex
(number)
The half height of the hex

getGridOffset

function getGridOffset( )

Returns the offset of the first grid square in the top left corner of the image. The offsets will be different from zero as a result of the grid not being perfectly aligned with the top left corner of the image itself. The values will vary from zero to -((grid size) - 1).

Return values

(number)
The horizontal offset of the grid
(number)
The vertical offset of the grid

getGridSize

function getGridSize( )

Get the size of the grid squares in pixels. The grid is rectangular, i.e. the height and width of the squares is the same.

Return values

(number)
The size of the grid squares in pixels. If the grid is disabled, returns 0.

getGridSnap

function getGridSnap( )

Returns whether grid snapping is enabled for this control.

Return values

(number)
Returns nil if the grid snap style is undefined; or 1 if a grid snap style is defined and enabled; or 0 if a grid snap style is defined and disabled.

getGridType

function getGridType( )

Returns the type of grid currently active. Valid types are "square", "hexcolumn" (hexes stacked vertically) and "hexrow" (hexes stacked horizontally).

Return values

(string)
The type of grid or nil if the grid is disabled

getImageSize

function getImageSize( )

Returns the size of the bitmap displayed in the image control.

Return values

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

getMaskTool

function getMaskTool( )

Get the currently active mask manipulation tool. Valid values are "maskselection" and "unmaskselection".

Return values

(string)
The current masking tool, or nil if mask draw mode is not active

getSelectedTokens

function getSelectedTokens( )

Retrieve a list of all tokens selected on the image shown in the control.

Return values

(table)
A table with integer index values containing references to tokeninstance objects contained in the control

getTokenLockState

function getTokenLockState( )

Returns whether token movement has been locked for clients.

Return values

(boolean)
The current lock state

getTokenOrientationCount

function getTokenOrientationCount( )

Returns the number of different token orientations available in this image, evenly spread out along a full revolution.

Return values

(number)
The number of orientations.

getTokenScale

function getTokenScale( )

Return the global relative scaling between tokens and the image displayed 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

getTokens

function getTokens( )

Retrieve a list of all tokens placed on the image shown in the control.

Return values

(table)
A table with integer index values containing references to tokeninstance objects contained in the control

getViewpoint

function getViewpoint( )

Returns data on the current viewpoint of the user. The viewpoint is determined by the center point of the portion of image being viewed in the control as well as the used zoom level.

Return values

(number)
The X coordinate on the image acting as the center point of the viewpoint
(number)
The Y coordinate on the image acting as the center point of the viewpoint
(number)
The zoom level being used (a value of 1.0 represents 100% zoom)

hasDrawing

function hasDrawing( )

Checks if the control has a drawing layer. (i.e. there is at least one line drawn)

Return values

(boolean)
Returns true if the layer is enabled, or false if it is disabled

hasGrid

function hasGrid( )

Checks if the control has the image grid enabled.

Return values

(boolean)
Returns true if the grid is on, or false if it is off

hasMask

function hasMask( )

Checks if the control has a mask layer.

Return values

(boolean)
Returns true if the layer is enabled, or false if it is disabled

hasTokens

function hasTokens( )

Returns whether any tokens have been placed on the image shown in the control.

Return values

(boolean)
Whether tokens exist on the image.

isTokenSelected

function isTokenSelected( tokenid )

Returns whether a given token is currently selected.

Parameters

tokenid(number (or tokeninstance))
The ID of the token (or a token instance object)

Return values

(boolean)
Whether the given token is currently selected

onCursorModeChanged

event function onCursorModeChanged( mode )

If present, this function is called when the cursor mode changes. Valid values are (nil, "mask", "unmask", "draw", "erase", "setgrid", "select", "target").

Parameters

mode(string)
Current cursor mode

onDrawStateChanged

event function onDrawStateChanged( tool )

If present, this function is called when the draw tool is changed.

Parameters

tool(string)
The selected draw tool, or nil if drawing mode was exited.

onDrawingSizeChanged

event function onDrawingSizeChanged( )

If present, this function is called when the drawing surface size is changed for drawing only imagecontrols.


onGridStateChanged

event function onGridStateChanged( type )

If present, this function is called whenever the attributes of the grid on an image changes. (i.e. grid type, grid size, grid offset, grin on/off)

Parameters

type(string)
One of the strings "square", "hexcolumn" or "hexrow", depending on the current grid type, or nil if the grid is disabled

onMaskingStateChanged

event function onMaskingStateChanged( tool )

If present, this function is called when the mask manipulation tool is changed.

Parameters

tool(string)
The selected mask manipulation tool, or nil if mask draw mode was exited.

onMeasurePointer

event function onMeasurePointer( pixellength, pointertype, startx, starty, endx, endy )

If present, this function is called to calculate a length label for a pointer in the control. This function allows for the use of customized length values that are based on a map scale or a grid value setup.

To turn off the label, return the empty string.

Warning
This calculation is performed as part of the screen rendering process. Very complicated calculations may adversely affect the performance of the application.

Parameters

pixellength(number)
The length of the pointer in pixels
pointertype(string)
The type of the pointer: "arrow", "circle", "cone", "rectangle"
startx(number)
The x coordinate of pointer origination point
starty(number)
The y coordinate of pointer origination point
endx(number)
The x coordinate of pointer termination point
endy(number)
The y coordinate of pointer termination point

Return values

(string)
The label applied to the pointer

onMeasureVector

event function onMeasureVector( token, vector )

If present, this function is called to calculate a length label for a movement vector at a locked token. This function allows for the use of customized length values that are based on a map scale or a grid value setup.

To turn off the label, return the empty string.

Warning
This calculation is performed as part of the screen rendering process. Very complicated calculations may adversely affect the performance of the application.

Parameters

token(tokeninstance)
A reference to a tokeninstance object representing the token the vector is drawn from. This reference can be used to retrieve information about the token.
vector(table)
A table with integer indices ranging from 1 to the number of path segments in the vector, representing the lengths of the segments. Each index contains a subtable with the indices "x" and "y" that contain the corresponding segment length components. For example, vector[1].x contains the length of the first path segment in the horizontal direction, and #vector indicates the number of path segments.

Return values

(string)
The label applied to the vector

onPointerSnap

event function onPointerSnap( startx, starty, endx, endy, type )

If present, this function is executed whenever pointers placed on this control are moved. The new coordinates of the pointer are given as parameters, and the returned values are used as replacements.

When snap is disabled, the function should return the original values. See hasGrid, getGridSize and getGridOffset for snapping based on the image grid.

Parameters

startx(number)
The X coordinate for the starting point of the pointer. For circles and rectangles, the center point.
starty(number)
The Y coordinate for the starting point of the pointer. For circles and rectangles, the center point.
endx(number)
The X coordinate of the ending point of the pointer. For circles and rectangles, this is the point on the shape closest to the mouse cursor when adjusting the pointer.
endy(number)
The Y coordinate of the ending point of the pointer. For circles and rectangles, this is the point on the shape closest to the mouse cursor when adjusting the pointer.
type(string)
The type of the pointer being adjusted. This string has one of the following values: "arrow", "circle", "cone" or "rectangle".

Return values

(number)
The desired snapped X coordinate of the pointer starting point.
(number)
The desired snapped Y coordinate of the pointer starting point.
(number)
The desired snapped X coordinate of the pointer end point.
(number)
The desired snapped Y coordinate of the pointer end point.

onTargetSelect

event function onTargetSelect( targets )

If present, this function is called when one or more tokens is selected using the "target" cursor mode or by CTRL-clicking on tokens.

Parameters

targets(table)
Table of tokeninstance objects

Return values

(boolean)
Whether the default FG handling should continue

onTokenAdded

event function onTokenAdded( token )

This function is executed when a new token instance is created in the control. As of v2.8, this function will be called when the imagecontrol is initialized for each existing token.

Parameters

token(tokeninstance)
A reference to the tokeninstance created

onTokenSnap

event function onTokenSnap( token, x, y )

If present, this function is executed whenever tokens placed on this control are moved. The new coordinates of the token are given as parameters, and the returned values are used as replacements.

When snap is disabled, the function should return the original values. See hasGrid, getGridSize and getGridOffset for snapping based on the image grid.

Parameters

token(tokeninstance)
A reference to the tokeninstance being snapped
x(number)
The X coordinate of the token instance
y(number)
The Y coordinate of the token instance

Return values

(number)
The snapped X coordinate for the token instance
(number)
The snapped Y coordinate for the token instance

preload

function preload( )

Sends the image to all connected clients without sharing the image, making the image instantly available when later shared.


resetPointers

function resetPointers( )

Forces all pointers to be recalculated and redrawn. Used primarily for rulesets where custom pointers are defined.


selectToken

function selectToken( tokenid, selected )

Sets whether the given token should be added or removed from the set of selected tokens.

Parameters

tokenid(number (or tokeninstance))
The ID of the token (or a token instance object)
selected(boolean)
Whether the token should be added or removed from the selection

setCursorMode

function setCursorMode( mode )

Sets the cursor mode for this control. Valid values are (nil, "mask", "unmask", "draw", "erase", "setgrid", "select", "target").

Parameters

mode(string)
The desired cursor mode

setDrawingSize

function setDrawingSize( width, height, offsetx, offsety )

Sets the available canvas for drawing on non-bitmap image spaces.

Warning
This function can only be called from the host. Also, this function will only work if the image control does not contain a bitmap image (i.e. a pure drawing).

Parameters

width(number)
The desired canvas width
height(number)
The desired canvas height
offsetx(number)
The horizontal offset of the current canvas space within the new canvas dimensions
offsety(number)
The vertical offset of the current canvas space within the new canvas dimensions

setDrawingTool

function setDrawingTool( type )

Sets the drawing tool, enabling or disabling painting mode accordingly. Valid values are "paint" and "erase", other values will cause drawing mode to be exited.

Parameters

type(string)
The desired draw mode

setGridOffset

function setGridOffset( offsetx, offsety )

Sets the offset of the first grid square in the top left corner of the image. The valid values for the offsets range from zero to -((grid size) - 1), any values not in this range will be converted to fit the interval.

Parameters

offsetx(number)
The horizontal grid offset
offsety(number)
The vertical grid offset

setGridSize

function setGridSize( size )

Set the size of the image grid. Setting this value to 0 will disable the grid.

Parameters

size(number)
The size of the grid in pixels

setGridSnap

function setGridSnap( snapenable )

Sets whether grid snapping is enabled for this control.

Parameters

snapenable(number)
If 0 then disable grid snapping; otherwise, enable grid snapping.

setGridToolType

function setGridToolType( type )

Sets the type of the grid placement tool used. The possible values are "square" and "hex". The hex tool places a hex grid whose type is determined by the direction of mouse movement while placing the grid.

Parameters

type(string)
The desired tool type

setGridType

function setGridType( type )

Sets the type of grid currently active. Valid types are "square", "hexcolumn" (hexes stacked vertically) and "hexrow" (hexes stacked horizontally).

The token orientation will be automatically set to 8 (square) or 12 (hex), based on the new grid type.

Parameters

type(string)
The desired type for the grid

setMaskEnabled

function setMaskEnabled( state )

Enables or disables the image mask.

Parameters

state(boolean)
The desired mask state

setMaskTool

function setMaskTool( type )

Sets the mask manipulation tool, enabling or disabling mask drawing mode accordingly. Valid values are "maskselection" and "unmaskelection", other values will cause mask draw mode to be exited. If there is no active mask on the image, will have no effect.

Parameters

type(string)
The desired mask draw mode

setTokenLockState

function setTokenLockState( count )

Sets whether clients can move tokens.

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

Parameters

count(number)
The desired lock state

setTokenOrientationCount

function setTokenOrientationCount( count )

Sets the number of different token orientations available in this image, evenly spread out along a full revolution.

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

Parameters

count(number)
The desired number of orientations

setTokenOrientationMode

function setTokenOrientationMode( mode )
Warning
Available on host only.

Sets default token rotation mode for tokens on map (physical token rotation or facing arrows).

Parameters

mode(string)
Desired orientation mode (rotation or facing).

setTokenScale

function setTokenScale( scale )

Sets the global relative scaling between tokens and the image displayed 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

setViewpoint

function setViewpoint( viewx, viewy, [zoom] )

Sets the active viewpoint of the user. The image viewpoint is repositioned so that the given coordinates on the image are in the upper left in the control with the specified zoom level active.

Parameters

viewx(number)
The desired horizontal view point center coordinate
viewy(number)
The desired vertical view point center coordinate
zoom(number)[optional]
The zoom level as a decimal number, with 1.0 being 100% zoom

setViewpointCenter

function setViewpointCenter( viewx, viewy, [zoom] )

Sets the active viewpoint of the user to center on the . The image viewpoint is repositioned so that the given coordinates on the image are centered in the control with the specified zoom level active.

Parameters

viewx(number)
The desired horizontal view point center coordinate
viewy(number)
The desired vertical view point center coordinate
zoom(number)[optional]
The zoom level as a decimal number, with 1.0 being 100% zoom

snapToGrid

function snapToGrid( x, y )

Snaps the specified X and Y coordinate point to the nearest snap point on the imagecontrol, either vertex or center.

If a grid is not defined, then no adjustments are made to the X and Y coordinates.

Parameters

x(number)
The X coordinate to snap
y(number)
The Y coordinate to snap

Return values

(number)
The snapped X coordinate
(number)
The snapped Y coordinate


'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