windowcontrol
Inherits | |
Inherited By | buttoncontrol, categoryselectioncontrol, chatwindow, chatentry, diecontrol, formattedtextcontrol, genericcontrol, imagecontrol, numbercontrol, portraitselectioncontrol, scrollbarcontrol, scrollercontrol, stringcontrol, subwindow, tokenbag, tokencontrol, windowlist, windowreferencecontrol |
Context | windowinstance |
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 > ... </bounds>
<anchored >
<to > ... </to>
<position > ... </position>
<offset > ... </offset>
<width > ... </width>
<height > ... </height>
<left >
<parent > ... </parent>
<relation > ... </relation>
<anchor > ... </anchor>
<offset > ... </offset>
<postoffset > ... </postoffset>
</left>
<top > ... </top>
<right > ... </right>
<bottom > ... </bottom>
<size >
<width > ... </width>
<height > ... </height>
</size>
<sizelimits >
<maximum >
<width > ... </width>
<height > ... </height>
</maximum>
<minimum >
<width > ... </width>
<height > ... </height>
</minimum>
</sizelimits>
</anchored>
<frame >
<name > ... </name>
<offset > ... </offset>
</frame>
<backcolor > ... </backcolor>
<droptypes >
<type > ... </type>
</droptypes>
<stateframe >
<keyedit >
<name > ... </name>
<offset > ... </offset>
<nobaseframe />
<hidereadonly />
</keyedit>
<pressed > ... </pressed>
<hover > ... </hover>
<drophilight > ... </drophilight>
<drophover > ... </drophover>
</stateframe>
<tabtarget >
<next > ... </next>
<prev > ... </prev>
</tabtarget>
<cursor >
<hover > ... </hover>
</cursor>
<tooltip >
<text > ... </text>
<textres > ... </textres>
<gmtext> ... </gmtext>
<gmtextres> ... </gmtextres>
<pctext> ... </pctext>
<pctextres> ... </pctextres>
</tooltip>
<invisible />
<gmvisibleonly />
<disabled />
<readonly />
<gmeditonly />
</windowcontrol><windowcontrol > |
|
<bounds > ... </bounds> | Defines the position of the control relative to the window. Do not use if <anchored> is defined. |
<anchored > | Defines the position as anchored to the window or other window controls. Do not use if <bounds> is defined. |
<to > ... </to> | Specify the control to use for all four anchors. If not defined, anchors are relative to the parent window. |
<position > ... </position> | The shorthand notation position (above, aboveleft, aboveright, below, belowleft, belowright, left, lefthigh, leftlow, right, righthigh, rightlow, insidetop, insidetopleft, insidetopright, insidebottom, insidebottomleft, insidebottomright, insideleft, insideright, over) |
<offset > ... </offset> | Two numbers separated by a comma, defining the horizontal and vertical offset based on the position attribute specified, in display units |
<width > ... </width> | Attribute only. The width of the control, in display units |
<height > ... </height> | Attribute only. The height of the control, in display units |
<left > |
|
<parent > ... </parent> | Specify the control for this anchor |
<relation > ... </relation> | "absolute" (default), "relative" or "current" |
<anchor > ... </anchor> | The anchor edge to use from the parent control. ("left", "top", "right", "bottom") If not defined, the opposite anchor on the parent will be used (if relation is “relative” or “current”) or the same anchor on the parent will be used (otherwise). |
<offset > ... </offset> | An offset to the calculated anchor position. If a percentage is specified, then a value will be calculated from the width/height of the parent control or window. If a number is specified, then a fixed distance in display units will be used (horizontal for left/right anchors and vertical for top/bottom anchors). |
<postoffset > ... </postoffset> | An offset to the relative anchor position, in display units (horizontal for left/right anchors and vertical for top/bottom anchors) after the control size is calculated. Only applies when relation=”relative”. |
</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 display units |
<height > ... </height> | The height of the control, in display units |
</size> |
|
<sizelimits > |
|
<maximum > | Defines the maximum dimensions of the control |
<width > ... </width> | The maximum width, in display units |
<height > ... </height> | The maximum height, in display units |
</maximum> |
|
<minimum > | Defines the minimum dimensions of the control |
<width > ... </width> | The minimum width, in display units |
<height > ... </height> | The minimum height, in display units |
</minimum> |
|
</sizelimits> |
|
</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 display unit margins applied to the frame when drawn |
</frame> |
|
<backcolor > ... </backcolor> | The color to be used to fill the background of the window control before drawing the contents. If no backcolor specified, then no fill will be done (i.e. transparent). The color should be in the form #AARRGGBB. If alpha is zero or not defined, FF is assumed. |
<droptypes > | A list of drag types causing the drop target highlight frame to be displayed |
<type > ... </type> | Multiple "type" tags define all types highlighted |
</droptypes> |
|
<stateframe > | This section defines optional frames that will be used under special circumstances |
<keyedit > | The keyboard focus is on this control |
<name > ... </name> | The name of the bitmap frame resource |
<offset > ... </offset> | A comma separated list of four numbers specifying the display unit margins applied to the frame when drawn |
<nobaseframe /> | If present, the normal base frame will not be drawn under the state frame |
<hidereadonly /> | If present, the frame will not be drawn regardless of state when the control is set to read only. |
</keyedit> |
|
<pressed > ... </pressed> | The mouse button was clicked down on this control, but has not been released yet. Contents similar to the <keyedit> tag. |
<hover > ... </hover> | The mouse pointer is situated over this control. Contents similar to the <keyedit> tag. |
<drophilight > ... </drophilight> | The mouse pointer is carrying a drag and drop value that can be dropped in this control. Contents similar to the <keyedit> 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 <keyedit> tag. |
</stateframe> |
|
<tabtarget > | Defines the names of the target fields used when navigating using the Tab key. |
<next > ... </next> | The next target field |
<prev > ... </prev> | The previous target field |
</tabtarget> |
|
<cursor > |
|
<hover > ... </hover> | The cursor type that FG should display when hovering over control. Valid values are ("hand", "arrow"). The default cursor type is "arrow". |
</cursor> |
|
<tooltip > |
|
<text > ... </text> | Tooltip text to display. |
<textres > ... </textres> | Tooltip string resource to be displayed. |
<gmtext>...</gmtext> | Tooltip text to display when hosting |
<gmtextres>...</gmtextres> |
|
<pctext>...</pctext> | Tooltip text to display when not hosting |
<pctextres>...</pctextres> |
|
</tooltip> |
|
<empty > | The text to display when the underlying value is empty (only windowlist and string controls currently). |
<text > ... </text> | Text to display when control is empty. |
<textres>...</textres> | String resource to display when control is empty. |
<gmtext>...</gmtext> | The text to display when hosting |
<gmtextres>...</gmtextres> |
|
<pctext>...</pctext> | The text to display when not hosting |
<pctextres>...</pctextres> |
|
<font >…</font> | The name of the font resource used to render the text. |
<color>…</color> | The color used to draw the text, in the form #AARRGGBB. If not present, the font default color is used. If alpha is zero or not defined, FF is assumed. |
</empty> |
|
<emptyreadonly>… | Same as empty tag except only applies when control is read only. |
<emptyedit>… | Same as empty tag except only applies when control is editable. |
<invisible /> | Indicates the control should not be visible when first created. |
<gmvisibleonly /> | If not running in host mode, the control will not be visible when initially created. |
<disabled /> | Indicates the control should be disabled by default |
<readonly /> | Disable all user interface based editing |
<gmeditonly /> | If not running in host mode, disable all user interface based editing |
</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.
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 "".
getEmptyText
function getEmptyText()Retrieve the possible text values to display in the control when the underlying data is empty.
Return values
(string)
The value of the empty text display string for this control, if the subsequent values are not defined or are empty.
(string)
The value to display when the control is set to read only and is empty.
(string)
The value to display when the control is set to editable and is empty.
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.
(number)
The vertical position of the control.
getScrollState
function getScrollState()Gets the scrolling properties of the control. Scroll properties include the total size of the control's scrollable area, the visible area, and the position in the scrollable area where the visible area is located. Support for horizontal scrolling is only present in some control types.
Return values
(number)
The width of the entire scrollable area.
(number)
The position of the left edge of the visible portion of the total area, relative to the left edge of the entire scrollable area.
(number)
The width of the visible area.
(number)
The height of the entire scrollable area.
(number)
The position of the top edge of the visible portion of the total area, relative to the top edge of the entire scrollable area.
(number)
The height of the visible area.
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.
(number)
The height of the control.
getTabTarget
function getTabTarget(direction)Checks if the control is flagged as read only.
Parameters
direction (boolean)
A value of true specifies the "next" tab target value to be returned, and a value of false indicates the "previous" tab target value to be returned.
Return values
(string)
Returns the name of the control that is currently set as the tab target for the specified direction. If the result is an empty string, then no tab target defined.
isEmpty
function isEmpty()Returns whether the control contains text or is empty.
Certain control types will always return false. (genericcontrol, imagecontrol, assetviewcontrol, chatwindow, scrollercontrol, scrollbarcontrol, portraitselectioncontrol)
Return values
(boolean)
Whether the control is empty
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.
isReadOnly
function isReadOnly()Checks if the control is flagged as read only.
Return values
(boolean)
Returns true if the control has the read only flag set, false otherwise
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
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)
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.
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
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)
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.
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
function onClose()If present, this function is called when the control is destroyed, before the onClose event of the parent window is called.
onDoubleClick
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
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. As of v2.8, the onDrag event will not be called for the initial drag event. See onDragStart to capture the initial drag event.
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
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.