This is a base class for all elements that are contained in windows and panels. See windowclass and windowinstance for more information on the
general properties of windows.
Each window control, with a few exceptions, can have a name, a data source and a position in the window.
The name is a simple string specified as an attribute in the element definition or passed to windowinstance.createControl. By default, it is also the
name of the child node under the window instance data source that is used as the data source database node for the control itself. See databasecontrol for
details on how controls are bound to the database.
The position of the control can be specified as absolute coordinates relative to the window or relative coordinates that are relative to the other controls in the window.
Absolute positioning uses an X and Y coordinate that can be relative to any side of the window and a width/height or a bottom-right corner offset to define the position.
Relatively positioned controls are anchored to the sides of other controls in the window, using varying anchor combinations and offset values.
Definition
<windowcontrol
>
|
|
|
<bounds
>
|
Defines the placement of the control in the window. Do not use if <anchored> is defined. |
|
<rect
>
...
</rect>
|
Defines the position relative to the window. |
|
</bounds>
|
|
|
<anchored
>
|
Defines the position as anchored to other window elements. Do not use if <bounds> is defined. |
|
<to
>
...
</to>
|
The shorthand notation anchor control name |
|
<position
>
...
</position>
|
The shorthand notation position |
|
<offset
>
...
</offset>
|
The shorthand notation offset |
|
<left
>
|
|
|
<parent
>
...
</parent>
|
The name of the control being anchored to |
|
<relation
>
...
</relation>
|
"absolute" (default), "relative" or "current" |
|
<anchor
>
...
</anchor>
|
The edge used from the parent control. "left", "right", "right" or "bottom" |
|
<offset
>
...
</offset>
|
Two numbers separated by a comma, defining an offset to the calculated anchor position, in pixels |
|
</left>
|
|
|
<top
>
...
</top>
|
Contents similar to the <left> tag |
|
<right
>
...
</right>
|
Contents similar to the <left> tag |
|
<bottom
>
...
</bottom>
|
Contents similar to the <left> tag |
|
<size
>
|
Defines the size of controls anchored on only one side |
|
<width
>
...
</width>
|
The width of the control, in pixels |
|
<height
>
...
</height>
|
The height of the control, in pixels |
|
</size>
|
|
|
</anchored>
|
|
|
<frame
>
|
Defines the graphical frame used to render the control |
|
<name
>
...
</name>
|
The name of the <framedef> definition for the frame |
|
<offset
>
...
</offset>
|
A comma separated list of four numbers specifying the pixel margins applied to the frame when drawn |
|
</frame>
|
|
|
<droptypes
>
|
A list of drag types causing the drop target hilight frame to be displayed |
|
<type
>
...
</type>
|
Multiple "type" tags define all types hilighted |
|
</droptypes>
|
|
|
<stateframe
>
|
This section defines optional frames that will be used under special circumstances |
|
<hover
>
|
The mouse pointer is situated over this control |
|
<name
>
...
</name>
|
The name of the <framedef> definition for the frame |
|
<offset
>
...
</offset>
|
A comma separated list of four numbers specifying the pixel margins applied to the frame when drawn |
|
<nobaseframe
/>
|
If present, the normal base frame will not be drawn under the state frame |
|
</hover>
|
|
|
<drophilight
>
...
</drophilight>
|
The mouse pointer is carrying a drag and drop value that can be dropped in this control. Contents similar to the <hover> tag |
|
<drophover
>
...
</drophover>
|
The mouse pointer is carrying a drag and drop value that can be dropped in this control and is hovering over the control. Contents similar to the <hover> tag |
|
</stateframe>
|
|
|
<tabtarget
>
|
Defines the names of the target fields used when navigating using the tabulator key. |
|
<next
>
...
</next>
|
The next target field |
|
<prev
>
...
</prev>
|
The previous target field |
|
</tabtarget>
|
|
|
<tooltip
>
|
|
|
<text
>
...
</text>
|
Tooltip content text |
|
<anchor
>
...
</anchor>
|
The interface element the tooltip is drawn relative to. One of "control", "desktop" or"cursor" |
|
<align
>
...
</align>
|
The part of the tooltip placed at the location specified by the anchor and the position. One of the values "topleft", "top", "topright", "left", "center", "right", "bottomleft", "bottom" or "bottomright" |
|
<position
>
|
The offset from the defined anchor position |
|
<x
>
...
</x>
|
|
|
<y
>
...
</y>
|
|
|
</position>
|
|
|
</tooltip>
|
|
|
<invisible
/>
|
Indicates the control should be non-visible by default |
|
<disable
/>
|
Indicates the control should be disabled by default |
|
</windowcontrol>
|
|
Interface
bringToFront
function bringToFront(
)
Moves the control to the front in the processing order. It will be drawn last (on top) and will be the first to receive interface events
at its position.
Warning
Reordering the controls will affect layout order. Anchored controls may behave erratically if their parent is processed after them.
destroy
function destroy(
)
Destroys the control, removing it from the window.
getName
function getName(
)
This function returns the name of the control.
Return values
(string)
Returns the name of the control as a string. Unnamed controls return the empty string "".
getPosition
function getPosition(
)
Get the position of the top left corner of the control, relative to the parent window.
Return values
(number)
The horizontal position of the control, in pixels.
(number)
The vertical position of the control, in pixels.
getSize
function getSize(
)
Get the current size of the control. The size is calculated based on the anchoring of the control and the dimensions of the
containing window.
Return values
(number)
The width of the control, in pixels.
(number)
The height of the control, in pixels.
isEnabled
function isEnabled(
)
This function indicates whether the control is enabled.
Disabled controls do not receive interface events and can't be manipulated by the user. Enabled controls receive interface events but might not be visible (see setVisible).
Return values
(boolean)
Returns true if the control is enabled, false if it is hidden.
isVisible
function isVisible(
)
This function indicates whether the control is visible in the window.
Invisible controls are not drawn, have zero size in calculations involving
them as parents in relative control placement and do not receive interface events. Visible controls are drawn and affect relative control placement
calculations but might not receive interface events if they are disabled (see isEnabled).
Return values
(boolean)
Returns true if the control is visible, false if it is hidden.
onClickDown
event
function onClickDown(
button, x, y
)
This function is called when a mouse button is pressed down on the control. If this function is not defined or returns false, the onClickRelease function is not called.
Parameters
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 control
y (number)
The Y coordinate relative to the top left corner of the control
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
event
function onClickRelease(
button, x, y
)
This function is called when a mouse button is released, if the cursor was not moved after the button press. If the control did not process the button pressed event, this function is not called.
Parameters
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 control
y (number)
The Y coordinate relative to the top left corner of the control
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.
onClose
event
function onClose(
)
If present, this function is called when the control is destroyed, before the onClose event of the parent window is called.
onDoubleClick
event
function onDoubleClick(
x, y
)
This function is called when the left mouse button is pressed down twice in succession on the control. Note that if this function is present and returns nil, the onClickDown
function is called as well.
Parameters
x (number)
The X coordinate relative to the top left corner of the control
y (number)
The Y coordinate relative to the top left corner of the control
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
event
function onDrag(
button, x, y, dragdata
)
This function is called when the mouse is moved after having been pressed down on the control. The event is called repeatedly as the user adjusts the mouse position. The onDragEnd
function is called when the mouse button is released.
If a customized drag and drop transfer is done, the dragdata parameter should be used to make the required changes.
Parameters
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 control
y (number)
The Y coordinate relative to the top left corner of the control
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
event
function onDragEnd(
dragdata
)
This function is called when the mouse is released at the end of a drag operation that started on the control. 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
dragdata (dragdata)
A
dragdata object containing the state of values connected to the mouse cursor as part of a drag and drop operation.
onDrop
event
function onDrop(
button, x, y, dragdata
)
This function is called when a drag and drop operation finishes on the control. 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.
Parameters
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 control
y (number)
The Y coordinate relative to the top left corner of the control
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
event
function onHover(
state
)
This function is called when the mouse enters or leaves the area of the control.
Parameters
state (boolean)
true if the mouse is entering the area, false if leaving
onHoverUpdate
event
function onHoverUpdate(
x, y
)
This function is called when the mouse cursor is moved while over the control.
Parameters
x (number)
The X coordinate of the mouse pointer in pixels relative to the top left corner of the control
y (number)
The Y coordinate of the mouse pointer in pixels relative to the top left corner of the control
onInit
event
function onInit(
)
If present, this function is called when the control is created, after the window and child controls are initialized by the framework, before the onInit event of the parent window is called.
onMenuSelection
event
function onMenuSelection(
...
)
This function is called when a user defined item is selected in the control's radial menu.
Parameters
...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.
onWheel
event
function onWheel(
notches
)
This function is called when the mouse wheel is spun over the control.
Parameters
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 for the control radial menu. If the user selects the item, the script is notified
of this through the onMenuSelection event.
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.
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.
resetAnchor
function resetAnchor(
target
)
Resets (clears) an anchor point for one of the edges (left, top, right or bottom) of the control.
Anchored controls should either be anchored at opposite sides (left and right, or top and bottom) or have one anchor and a width or height directly
specified.
To set the anchor, see setAnchor.
Parameters
target (string)
The name of the anchor being reset. This string should be one of "left", "top", "right" or "bottom".
resetMenuItems
function resetMenuItems(
)
This function unregisters all user defined menu items. It does not affect menu entries defined by the application engine.
sendToBack
function sendToBack(
)
Moves the control to the back in the processing order. It will be drawn first (behind others) and will be the last to receive interface events
at its position.
Warning
Reordering the controls will affect layout order. Anchored controls may behave erratically if their parent is processed after them.
setAnchor
function setAnchor(
target, parent, parentanchor, [relation], [offset]
)
Sets an anchor point for one of the edges (left, top, right or bottom) of the control.
Anchored controls should either be anchored at opposite sides (left and right, or top and bottom) or have one anchor and a width or height directly
specified (see setAnchoredWidth and setAnchoredHeight). Controls can anchor to any edge on the target control, and specify an
offset in pixels that is applied to the point.
To clear the anchor, see resetAnchor.
Parameters
target (string)
The name of the anchor being set. This string should be one of "left", "top", "right" or "bottom".
parent (string)
The name of the control being anchored to. If this value is the empty string "", the control will be anchored to the window edges.
parentanchor (string)
Specifies the edge on the target control being anchored to. This string should be one of "left", "top", "right" or "bottom".
relation (string) [optional]
This string should be one of "absolute", "relative" or "current". The default value is "absolute". When using a relation other than absolute,
an anchor rectangle is internally tracked for the target control. Any "relative" controls anchoring to it will increase this rectangle to encompass that
control as well. Controls using "current" will anchor to the anchor rectangle, but will not adjust it. Relative positioning can be used to lay out arrays
of controls such as rows or columns.
offset (number) [optional]
This number is directly added to the calculated position after the positioning calculations have been completed. A positive value will shift the
control right or down, a negative value will shift it left or up.
setAnchoredHeight
function setAnchoredHeight(
height
)
Sets the height of the control relative to an anchored top or bottom edge. If the height is set, only one of the mentioned anchors should be used.
Parameters
height (string)
The height set for the control.
setAnchoredWidth
function setAnchoredWidth(
width
)
Sets the width of the control relative to an anchored left or right edge. If the width is set, only one of the mentioned anchors should be used.
Parameters
width (string)
The width set for the control.
setEnabled
function setEnabled(
state
)
This function can be used to toggle the control enabled and disabled.
Parameters
state (boolean)
A value of true marks the control enabled, false marks it disabled.
setFrame
function setFrame(
name, [leftmargin], [topmargin], [rightmargin], [bottommargin]
)
Set the bitmap frame drawn in the control area. The area used by the frame can be adjusted per edge by using the margin offset values. A negative value
shifts the bitmap frame edge towards the center of the control, and a positive value shifts it outward.
Parameters
name (string)
The name of the bitmap frame resource to be used for the frame.
leftmargin (number) [optional]
The margin offset for the left edge.
topmargin (number) [optional]
The margin offset for the top edge.
rightmargin (number) [optional]
The margin offset for the right edge.
bottommargin (number) [optional]
The margin offset for the bottom edge.
setHoverCursor
function setHoverCursor(
name
)
This function can be used to set a specific cursor to be used when the mouse hovers over the control. The available values for the
parameter are "arrow" and "hand".
Parameters
name (string)
A string naming the cursor to be used. See the description for value options.
setStateFrame
function setStateFrame(
state, name, [leftmargin], [topmargin], [rightmargin], [bottommargin]
)
Set the bitmap frame drawn in the control area for special states. The area used by the frame can be adjusted per edge by using the margin offset values. A negative value
shifts the bitmap frame edge towards the center of the control, and a positive value shifts it outward.
The state frame is drawn instead of the regular frame (set by setFrame) if the condition for the state is fulfilled and the frame for that state has been set.
When the user is performing a drag of a type that the control is registered to accept (see dragdata), the frame of type "drophilight" is used.
When the mouse is hovering over the control, the frame of type "hover" is used. This setting overrides the "drophilight" frame.
When the mouse is hovering over the control and the user is performing a drag of a type that the control is registered to accept, the frame of the type "drophover" is used.
This setting overrides both the "drophilight" and the "hover" frame.
Parameters
state (string)
A string identifying the state for which the frame is to be set. This value should be one of "hover", "drophilight" or "drophover".
name (string)
The name of the bitmap frame resource to be used for the frame.
leftmargin (number) [optional]
The margin offset for the left edge.
topmargin (number) [optional]
The margin offset for the top edge.
rightmargin (number) [optional]
The margin offset for the right edge.
bottommargin (number) [optional]
The margin offset for the bottom edge.
setStaticBounds
function setStaticBounds(
x, y, width, height
)
Set the position and size of the control relative to the parent window. This function corresponds to the "bounds/rect" setting in the xml definition.
If the X parameter is positive, the left side of the control is placed relative to the left side of the window. If it is negative, the left side is placed
relative to the right side of the window.
The Y parameter works similarly, relative to the top or bottom edge, respectively.
A positive width value directly dictates the width of the control. A negative value will place the right edge of the control directly relative to the
right edge of the window.
The height parameter works similar to the width parameter, but is relative to either the Y coordinate of the control or the bottom of the window.
Parameters
x (number)
The X coordinate of the control
y (number)
The Y coordinate of the control
width (number)
The width of the control
height (number)
The height of the control
setVisible
function setVisible(
state
)
This function can be used to toggle the control visible and invisible.
Parameters
state (boolean)
A value of true marks the control visible, false marks it hidden.
