LIST Gadget Page 1 of 5

Software Customisation Reference Manual

Summary of Objects, Members and Methods : Object Type Details : LIST Gadget

LIST Gadget
Members

Name Type Purpose

Val REAL Selected field-number of a

Get/Set single-choice list.

Val REAL Selected field numbers of a

ARRAY multiple-choice list.
Get/Set

DText STRING Set or get the entire list of

ARRAY display texts.
Get/Set

DText[n] STRING Get the display text of the n'th

Get Only field.

PickedField REAL Get Last picked list field number.

Only

RText STRING Set or get the list of replacement

ARRAY texts.
Get/Set

RText[n] STRING et Get the replacement text of the

Only n'th field.

Count REAL Get count of number of fields in

Get only the list

val REAL Selected field as integer. Zero

Get/Set implies no selection. Setting val
to zero will cause an error for
mandatory selection lists.

Methods

Name Result Purpose

Add(STRING NO Append an entry to the list, where Dtext is the text

Dtext) RESULT to display in the option list.

Add(STRING NO Append and entry to the list, where Dtext is the

Dtext, STRING RESULT text to display in the option list, and Rtext is the
Rtext)) replacement text for the new field. If Rtext isn’t

[Link] 09.09.2022
LIST Gadget Page 2 of 5

specified, it will be set to Dtext by default.

FullName() STRING Get the full name of the gadget, e.g..'!!

[Link]'

Name() STRING Get the gadget's name, e.g. 'gadget'

Owner() FORM Get owning form.

Select(STRING NO Select specified item in a list. text must be ‘Rtext’

text, STRING RESULT or ‘Dtext’. value is the RTEXT or DTEXT of the
value) item to be selected.

Select(STRING NO Select multiple choice list items. text must be

text, ARRAY of RESULT 'Rtext' or 'Dtext'. values contains the RTEXT or
STRING values) DTEXT values to be selected.

Selection( ) STRING Get selected RTEXT

ARRAY OF
Array of RTEXT for multi-choice list.
STRING

Selection(STRING STRING Get selected RTEXT or DTEXT

text) ARRAY OF
Array of texts for multi-choice list.
STRING
text must be 'Rtext' or 'Dtext'.

Clear() NO Clear list contents and selections.

RESULT

ClearSelection() NO Clear list selections.

RESULT

SetPopup(MENU NO Links menu with the gadget as a popup.

menu) RESULT

RemovePopup(MENU NO Removes popup menu from the gadget.

menu) RESULT

GetPickedPopup() MENU Returns the last picked popup menu for the
gadget.

Refresh() NO Refreshes the display of the gadget.

RESULT

Shown() BOOLEAN Get ‘shown’ status.

Type() STRING Get the gadget type as a STRING.

SetToolTip NO Allows a TOOLTIP to be edited.

(STRING) RESULT

SetFocus() NO Move keyboard focus to this gadget.

RESULT

SetHeadings(! NONE Specifies the number of columns and sets the list's
Dtexts is column headings. Dtexts contains a set of TAB

[Link] 09.09.2022
LIST Gadget Page 3 of 5

STRING) separated sub-strings.

SetHeadings(! NONE Specifies the number of columns and sets the list's
Dtexts is ARRAY) column headings. Dtexts is an array of strings.

Clear( !dtext ) NO Delete the field with the given DTEXT string.
RESULT

Clear( ! NO Delete the specified field number.

fieldNumber ) RESULT

SetRows(Array of NO This sets the display text for all the data fields of
(Array of RESULT the list gadget by row. If the list gadget is already
STRING)) populated then it replaces all the current rows by
the new ones. Array is an array of ‘row arrays’,
and its size determines the number of rows in the
list. Each entry is a row array of strings, which
supplies the displayed text for each column of the
row. The size of each row array must be less than
or equal to the number of columns of the list. The
columns are filled sequentially until the array is
exhausted.

SetColumns(Array NO This sets the display text for all the data fields of
of (Array of RESULT the list gadget by column. If the list gadget is
STRING)) already populated then it replaces all the current
rows by the new ones. Array is an array of
‘column arrays’, and its size must match the
number of columns of the list. The size of each all
column arrays must be the same and determines
the no of rows in the list.

Select(REAL NO This selects the first list row whose column

column, STRING RESULT column has the display text dtext. If the field is
dtext) not found then the list selection is unaltered. If the
list is a multi-choice list then repeated use of this
method will add selections to the list.

Background() STRING Get Background Colour Name.

Some gadgets do not support this property in all
circumstances, e.g. gadgets which are showing a
pixmap. Gadgets whose colour has not been set
explicitly, may not have a colour with a known
colourname. In this case an error is raised..

Column Headings
The number of columns is deduced from the List's data. If you specify a set of (1 or more) column headings
before the list is populated, then this will determine the number of columns. If no headings are pre-specified
then the number of columns is deduced from the display text (Dtext) of the List's first data field. This provides
upwards compatibility for existing Appware using single column lists.
A List gadget's headings can be replaced after the list has been populated. If the new headings specify the
same number of columns then the headings are replaced but the List's data fields and selection remain
unchanged. If the number of columns is different, then the list is replaced by an empty list with the new
headings.
Invoking the Clear() method will clear the list's data fields and rebuild the current headings.
There are two methods for defining a List's column headings:
The data fields can be set using the List's DTEXT member or its Add methods, where a row's Dtext string can

[Link] 09.09.2022
LIST Gadget Page 4 of 5

be a set of TAB separated column sub-strings for populating multiple columns. Alternatively you can use the
SetRows or SetColumns methods.

Single choice lists

Reselection of the Selected Field can be Disallowed

For Single choice lists there is a keyword NORESELECT which disables UnSelect and Select events when
the currently selected field is clicked with the mouse, for example:
list .l1 |List gadget| zeroSel noReselect width 15 length 5 tooltip 'single choice list'

De-selection of the selected field for ZeroSelection lists

For ZeroSelection lists it is possible to interactively deselect the selected field by clicking in unused rows or
after the last column.
The val member now allows programmatic de-selection of the current field.

Unselect Events
Single choice List gadgets support UNSELECT events. Typically when a field is selected, an UNSELECT
event is raised for the previously selected field (if any) and then a SELECT event is raised for the new field.
An UNSELECT event is raised whenever a selected field is interactively deselected.

Notes:
1. UNSELECT events are not notified to PML unless an open callback has been specified (so that SELECT
and UNSELECT events can be differentiated).
2. Typically the UNSELECT action allows Appware to manage consequences of deselection for any
dependent gadgets or forms.
3. We recommend that you do not change the List's selection programmatically in an UNSELECT event.

Command
The LIST command defines a single-choice or multiple-choice list gadget, and specifies its position, tag,
number of columns and callback text. Also defines the area (width and height) in which the displayed part of
the list will appear.
The arrays defining the display texts and replacement texts for the list options are usually set in the form's
default constructor method.

.-------<--------.
/ |
>- <flist> - LIST gname -+- <fgtagw> ------|
+- <fgpos> -------|
+- <fganch> ------|
+- CALLback text -|
+- TOOLTIP text --|
+- CORE ----------* Core managed gadget
|
+- MULTiple --------.
| .-------<-------. |
|/ | |
+- NORESELect ----| |
+- ZEROSELection -* |
‘-------------------‘- <vshap> +- TOOLTIP text -.
‘----------------‘->

Note: The TOOLTIP keyword can be given at two different places in the syntax.

A single choice, mandatory selection list.

Default:

[Link] 09.09.2022
LIST Gadget Page 5 of 5

1974 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved.

[Link] 09.09.2022