imagecontrol
- Derek Batting
- John Gregory
Inherits | |
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 is defined (respectively).
The grid snap status for an image is undefined until set using the defaultsnap tag or via the radial menu.
If no pointer types are defined, then the arrow, cone, circle and ssquare pointer types will be automatically added.
Definition
<imagecontrol name="..." >
<indicators >
<availability > ... </availability>
<locked > ... </locked>
<zoom > ... </zoom>
<shortcuts > ... </shortcuts>
<loading > ... </loading>
</indicators>
<shortcut >
<icon > ... </icon>
<hotspot > ... </hotspot>
</shortcut>
<default >
<gridtype > ... </gridtype>
<gridsize > ... </gridsize>
<gridoffset > ... </gridoffset>
<snap > ... </snap>
<snapsquare > ... </snapsquare>
<snaphex > ... </snaphex>
<drawingsize > ... </drawingsize>
</default>
<pointertypes >
<arrow >
<icon > ... </icon>
<label > ... </label>
</arrow>
<circle >
<icon > ... </icon>
<label > ... </label>
</circle>
<rectangle >
<icon > ... </icon>
<label > ... </label>
</rectangle>
<cone >
<icon > ... </icon>
<label > ... </label>
<angle > ... </angle>
</cone>
<custom >
<name > ... </name>
<icon > ... </icon>
<label > ... </label>
</custom>
</pointertypes>
</imagecontrol><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 of the grid (square or hex). |
<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> |
|
<pointertypes > |
|
<arrow > | Optional. Enable arrow pointer. |
<icon > ... </icon> | Radial menu icon. |
<label > ... </label> | Radial menu text. |
</arrow> |
|
<circle > | Optional. Enable circle pointer. |
<icon > ... </icon> | Radial menu icon. |
<label > ... </label> | Radial menu text. |
</circle> |
|
<rectangle > | Optional. Enable square pointer. |
<icon > ... </icon> | Radial menu icon. |
<label > ... </label> | Radial menu text. |
</rectangle> |
|
<cone > | Optional. Enable cone pointer. |
<icon > ... </icon> | Radial menu icon. |
<label > ... </label> | Radial menu text. |
<angle > ... </angle> | Angle of cone pointers on this image. Default value is 90. Valid values are 180, 120, 90, 60, 45, 30 and 5E. |
</cone> |
|
<custom > | Optional. Allows multiple. Enable custom pointer. |
<name > ... </name> | Custom pointer name. |
<icon > ... </icon> | Radial menu icon. |
<label > ... </label> | Radial menu text. |
</custom> |
|
</pointertypes> |
|
</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.
enableGridPlacement
Enables grid placement mode, using the currently set grid placement tool.
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
getDistanceBetween
Returns the distance (in game system units) between two tokens (or points) on the control. If the either parameter specifies a token not on the current control, then zero will be returned.
Parameters
token (tokeninstance)
A tokeninstance object on the current image control.
tokenid (number)
The ID value for a tokeninstance on the current image control
point (table)
A Lua table of the form { 1 = #, 2 = # } or { x = #, y = # } indicating a point on the current image control
Return values
(number)
The distance between the two specified tokens or points in game system units
getGridHexElementDimensions
This utility function helps with the location of points on the hex grid. Hexes are drawn by treating the grid size as a number 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
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
Returns the size of the grid squares. 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.
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
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
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
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
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
Returns whether token movement has been locked for clients.
Return values
(boolean)
The current lock state
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.
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
getTokensWithinDistance
Returns a list of all tokens within the given game system unit distance from the specified token or point. If the first parameter specifies a token not on the current control, then an empty list will be returned.
Parameters
token (tokeninstance)
A tokeninstance object on the current image control.
tokenid (number)
The ID value for a tokeninstance on the current image control
point (table)
A Lua table of the form { 1 = #, 2 = # } or { x = #, y = # } indicating a point on the current image control
distance (number)
The range in game system units that should be considered for distance calculations
Return values
(table)
A table with integer index values containing references to tokeninstance objects contained in the control
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)
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
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
Returns whether any tokens have been placed on the image shown in the control.
Return values
(boolean)
Whether tokens exist on the image.
isTokenSelected
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
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
onGridStateChanged
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
onMeasurePointer
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
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 poin
tendy (number)
The y coordinate of pointer termination point
Return values
(string)
The label applied to the pointer
onStateChanged
If present, this function is called whenever the state of the image control changes.
Parameters
type (string)
One of the strings "tokenlock" (token lock state), "shortcut" (shortcut visibility state) or "preview" (player view state)
onTargetSelect
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
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
selectToken
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
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
setGridOffset
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
Set the size of the image grid. Setting this value to 0 will disable the grid.
Parameters
size (number)
The size of the grid
setGridSnap
Sets whether grid snapping is enabled for this control.
Parameters
snapenable (number)
If 0 then disable grid snapping; otherwise, enable grid snapping.
setGridToolType
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
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
Enables or disables the image mask.
Parameters
state (boolean)
The desired mask state
setMaskTool
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
Sets whether clients can move tokens.
Only scripts running on the session host can set this property.
Parameters
state (boolean)
The desired lock state
setTokenOrientationCount
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
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).
setViewpoint
Sets the active viewpoint of the user. 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
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 snapy (number)
The Y coordinate to snap
Return values
(number)
The snapped X coordinate(number)
The snapped Y coordinate