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.
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>
|
|
|
<drawing
>
|
|
|
<defaultsize
>
...
</defaultsize>
|
The size used for the initial image control contents if the image contains no bitmap image, i.e. is a pure drawing |
|
</drawing>
|
|
|
</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.
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.
getTokens
function getTokens(
)
Retrieve a list of all tokens 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)
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
onMeasurePointer
event
function onMeasurePointer(
pixellength
)
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
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.
(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.
onTokenAdded
event
function onTokenAdded(
token
)
This function is executed when a new token instance is created in the control.
Parameters
token (tokeninstance)
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)
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
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
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 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)
The zoom level as a decimal number, with 1.0 being 100% zoom
