windowlist

Owned by Derek Batting
Last updated: May 02, 2022 by John Gregory
10 min read

Inherits

windowcontrol, databasecontrol

Context

windowinstance

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> <datasource > ... </datasource> <allowcreate /> <allowdelete /> <noscroll /> <useallmodules /> <acceptdrop > <class > ... </class> <field > ... </field> </acceptdrop> <footer > ... </footer> <columns > <width > ... </width> <filldown /> <fillwidth /> </columns> <ownedonly /> <child > <frame > <name > ... </name> <offset > ... </offset> </frame> <backcolor > ... </backcolor> </child> <sortby desc="..." case="..." > <control > ... </control> <field > ... </field> </sortby> <filter > <control > ... </control> <field > ... </field> <casesensitive > ... </casesensitive> </filter> <filteron > <control > ... </control> <field > ... </field> </filteron> <empty > <text > ... </text> <gmtext > ... </gmtext> <pctext > ... </pctext> <font > ... </font> <color > ... </color> </empty> </windowlist>

<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

<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

This function closes all the windows in the window list.

createWindow

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

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

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

getEmptyText

Retrieve the text to display in the control when the underlying data is an empty list.

Return values

(string)
The value of the empty text display string for this control.

getNextWindow

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

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

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

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

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

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

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

Is called when the control gains the keyboard focus.

onListChanged

If present, this function is called whenever the window list changes. (i.e. addition, deletion)

onListRearranged

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

Is called when the control loses the keyboard focus.

onSortCompare

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

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

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

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.

setEmptyText

Set the text to display in the control when the underlying data is an empty list.

Parameters

value   (string)   

The new value for the empty text display string

setFocus

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.

Â