Window lists are controls containing a number of windowinstance objects as entries in list format.
Typically, a window list is bound to a database node and displays and keeps track of all objects in that node. The list may also contain
header or title entries, or other entries based on the context of the list.
A reference to the window list object is available from the environments of all the contained window instances through the
windowlist variable.
Definition
|
<windowlist name="..."
>
|
|
|
<class
>
...
</class>
|
The name of the windowclass that is used by default to generate the list entries |
|
<datasource
>
...
</datasource>
|
A relative (to the window data source) identifier to a database node acting as the list parent |
|
<allowcreate
/>
|
If given, users can use the radial menu to create new entries in the list |
|
<allowdelete
/>
|
If given, users can delete entries from the list using the radial menu |
|
<noscroll
/>
|
If given, the list can't be scrolled; This is useful when the list is used as a dynamically sized control element |
|
<skipempty
/>
|
If given, the empty entry is not created in lists without a data source. |
|
<createonempty
/>
|
If given, an empty entry is created in lists with a data source. If the last record in the list data source is deleted, a new empty record will be created. |
|
<useallmodules
/>
|
If given, the list will pull data from all matching data paths in modules as well as the source node. |
|
<acceptdrop
>
|
Specify that a "shortcut" drag with the specified windowclass will create a new entry in the list. The definition can contain
multiple instances of this element.
|
|
<class
>
...
</class>
|
The name of the windowclass in the dragdata object containing the dragged shortcut |
|
<field
>
...
</field>
|
A series of "fields" tags specifying the fields copied to the created window's data source. If the field value is set to "*", then all child database values will be copied. |
|
</acceptdrop>
|
|
|
<footer
>
...
</footer>
|
The name of an icon resource to be used as a footer image, i.e. drawn in the control following all entries |
|
<columns
>
|
Indicates the list should be drawn in columns with the specified width |
|
<width
>
...
</width>
|
Specifies the width of a column, in pixels |
|
<filldown
/>
|
Renders the list so that columns are completed before moving to the next column, as opposed to the default case where the number of entries
in columns is equalized.
|
|
<fillwidth
/>
|
Enters the entries in the list filling rows from left to right before continuing with the next row.
|
|
</columns>
|
|
|
<ownedonly
/>
|
If acting as a client, only renders the entries whose data sources are owned by the currently active user |
|
<child
>
|
Specify attributes that apply to child windows within the list. If more than one child tag specified, then the attributes will apply in order to the child windows within the list. If there are more windows than child tags, then the attributes will then be applied in order starting from the first child tag. |
|
<frame
>
|
Defines the graphical frame used as the background for the child window |
|
<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>
|
|
|
<backcolor
>
...
</backcolor>
|
The color to be used to fill the background of the child window 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. |
|
</child>
|
|
|
<sortby desc="..." case="..."
>
|
Specify the control (or data source node via a relative path) within the child windowinstance (or child window data source) to sort by. Only string or number values can be used for sorting. If desc attribute is set, then the windows are sorted in descending order by this sort value. If the case attribute is set and this sort value is a string, then the sorting is case-sensitive; otherwise, string value sorting is case-insensitive. Multiple sortby tags can be defined, and additional tags will be applied in order as long as previous sort values are equal. If all sort values are equal, the child windows will be sorted by child data source node name (if available). |
|
<control
>
...
</control>
|
Name of the control within the child windowinstance to use for the sort value |
|
<field
>
...
</field>
|
Data path (relative to childwindow data source) to use for the sort value |
|
</sortby>
|
|
|
<filter
>
|
Specify the control (or data source node via a relative path) within the parent windowinstance (or parent window data source) to use for filtering the list. Only string or number values can be used for filtering. The list will perform a substring match when filtering on strings. |
|
<control
>
...
</control>
|
Name of the control within the parent windowinstance to use for the filter value |
|
<field
>
...
</field>
|
Data path (relative to parent window data source) to use for the filter value |
|
<casesensitive
>
...
</casesensitive>
|
Specifies that string filtering should be case sensitive. If not specified, string filtering is case insensitive. |
|
</filter>
|
|
|
<filteron
>
|
Specify the control (or data source node via a relative path) within the child windowinstance (or child window data source) to use for filtering the list. Only string or number values can be used for filtering. The list will perform a substring match when filtering on strings. |
|
<control
>
...
</control>
|
Name of the control within the child windowinstance to use for the filter value |
|
<field
>
...
</field>
|
Data path (relative to child window data source) to use for the filter value |
|
</filteron>
|
|
|
<empty
>
|
Specifies text to be shown in the list control area when the list is empty. The text will be horizontally and vertically centered. |
|
<text
>
...
</text>
|
The text to display |
|
<gmtext
>
...
</gmtext>
|
The text to display when hosting |
|
<pctext
>
...
</pctext>
|
The text to display when not hosting |
|
<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>
|
|
|
</windowlist>
|
|
Interface
applyFilter
function applyFilter([immediate])
Filter the list, using onFilter to select entries for display.
Parameters
immediate (boolean) [optional]
If true, the contents are sorted immediately. Specifying this option might degrade performance, but
be necessary in cases where succeeding script commands require the results of the operation.
applySort
function applySort([immediate])
Sort the contents of the list, using onSortCompare to place the entries in the desired order.
Parameters
immediate (boolean) [optional]
If true, the contents are sorted immediately. Specifying this option might degrade performance, but
be necessary in cases where succeeding script commands require the results of the operation.
closeAll
function closeAll()
This function closes all the windows in the window list.
createWindow
function createWindow(dbnode, [focus])
Creates a new entry in the list, represented by the returned windowinstance. The list is filtered and sorted automatically after the
addition of the new entry.
This form of the function creates a window instance with the window class specified in the definition of the list control, with the data source specified.
If the data source is nil, then a data record will automatically be created if the list is data bound.
Parameters
dbnode (string (or databasenode))
The data node identifier path (or a databasenode object) to use as the data source for the child window.
focus (boolean) [optional]
Specifies whether the keyboard focus should be set to this window. (if a focus field is available)
Return values
(windowinstance)
A
windowinstance representing the created entry, or nil in case of errors.
createWindowWithClass
function createWindowWithClass(class, dbnode, [focus])
Creates a new entry in the list, represented by the returned windowinstance. The list is filtered and sorted automatically after the
addition of the new entry.
This form of the function creates a window instance with the window class specified as a parameter and the data source specified.
If the data source is nil, then a child window will be created which is not bound to the database, regardless of whether the list is data bound.
Parameters
class (string)
The window class to use for the new child window instance.
dbnode (string (or databasenode) (or true))
The data node identifier path (or a databasenode object) to use as the data source for the child window. If set to true instead, a new child node under the windowlist database node will be created instead.
focus (boolean) [optional]
Specifies whether the keyboard focus should be set to this window. (if a focus field is available)
Return values
(windowinstance)
A
windowinstance representing the created entry, or nil in case of errors.
getColumnWidth
function getColumnWidth()
Retrieves column width for the windowlist. The width will be zero for lists which are single column.
Return values
(number)
The column width of the list
getNextWindow
function getNextWindow(source)
Retrieve the window instance entry in the list control following the one given as a parameter.
Parameters
source (windowinstance)
The window instance from which the next window is to be determined.
Return values
(windowinstance)
A
windowinstance representing the entry following the given entry. If the entry given as the parameter
is the last one in the list, the return value will be
nil.
getPrevWindow
function getPrevWindow(source)
Retrieve the window instance entry in the list control preceding the one given as a parameter.
Parameters
source (windowinstance)
The window instance from which the previous window is to be determined.
Return values
(windowinstance)
A
windowinstance representing the entry preceding the given entry. If the entry given as the parameter
is the first one in the list, the return value will be
nil.
getWindowAt
function getWindowAt(x, y)
Retrieve the window instance entry in the list control at the specified coordinates.
Parameters
x (number)
The horizontal position relative to the left edge of the control in its current scroll state, in pixels
y (number)
The vertical position relative to the top edge of the control in its current scroll state, in pixels
Return values
(windowinstance)
A
windowinstance representing the entry at the given position. If no entry was found at the position,
the return value will be
nil.
getWindowCount
function getWindowCount([visibleonly])
Get the number of child windows belonging to this list.
Parameters
visibleonly (boolean) [optional]
If true, only the windows which are currently visible will be counted.
Return values
(number)
The number of child windows
getWindows
function getWindows([visibleonly])
Get the selection of windowinstance objects forming the entries in the list.
Parameters
visibleonly (boolean) [optional]
If true, only the windows which are currently visible will be returned.
Return values
(table)
An integer indexed table containing references to the
windowinstance entries in the list
hasFocus
function hasFocus()
This function indicates whether the keyboard focus is on this control.
Return values
(boolean)
Returns true if the control has the keyboard focus, false otherwise.
onFilter
function onFilter(w)
If this function is defined, it is executed for each record in the window list each time the list is reordered or new entries are added.
Based on the return value, the corresponding record is only shown if it passes the filtering conditions.
Parameters
w (windowinstance)
A windowinstance representing the list entry being filtered
Return values
(boolean)
A return value of true indicates the entry passes the filter, a value of false hides
it from the currently displayed selection of entries
onGainFocus
function onGainFocus()
Is called when the control gains the keyboard focus.
onListChanged
function onListChanged()
If present, this function is called whenever the window list changes. (i.e. addition, deletion)
onListRearranged
function onListRearranged(listchanged)
If present, this function is called whenever the number or order of entries in the list changed.
Parameters
listchanged (boolean)
If the event causing the invocation of this event added or removed items from the list, the value will be true.
Otherwise, false indicating that only the order of items was changed.
onLoseFocus
function onLoseFocus()
Is called when the control loses the keyboard focus.
onSortCompare
function onSortCompare(w1, w2)
When the list is sorted, this function is executed to perform comparison operations between two entries in the list. All entries are not
necessarily compared against each other. The function should perform a greater than operation.
If this event handler is not defined or returns nil, then the windows will be sorted by the names of the data source nodes for the child windows (if the windowlist has a data source).
Parameters
w1 (windowinstance)
A reference to a windowinstance representing the first comparison operand
w2 (windowinstance)
A reference to a windowinstance representing the second comparison operand
Return values
(boolean)
A return value of true indicates the entry represented by w1 is greater than (should be located later in the list)
than the entry represented by w2. Otherwise, the function should return false.
scrollToWindow
function scrollToWindow(win, ctrl)
Scrolls the list to ensure that the given child window is visible. If a control within the child window is also specified, then the function will ensure that the field is visible.
Parameters
win (windowinstance)
A reference to a windowinstance object representing a child window within the window list.
ctrl (windowcontrol)
A reference to a windowcontrol object representing a control within the child window.
setColumnWidth
function setColumnWidth(width)
Sets the column width for the windowlist. If the column width is set to zero, then the list will be a single column; otherwise, the parameter value will be set as the column width for the list.
Parameters
width (number)
The column width to set
setDatabaseNode
function setDatabaseNode(dbnode)
Sets a new data source for the windowlist.
Parameters
dbnode (databasenode (or table of databasenode objects))
A reference to one or more databasenode objects representing the new data source(s) for the window list.
setFocus
function setFocus([state])
This function requests the framework to either set or reset the keyboard focus to this control.
Parameters
state (boolean) [optional]
A value of true sets the focus to this control, a false value resets the focus.
When the parameter is omitted (synonymous to passing a nil value), the value is treated as true.
