LIST Gadget
- Last UpdatedNov 07, 2024
- 5 minute read
Members
|
Name |
Type |
Purpose |
|---|---|---|
|
Val |
REAL Get/Set |
Selected field-number of a single-choice list. |
|
Val |
REAL ARRAY Get/Set |
Selected field numbers of a multiple-choice list. |
|
DText |
STRING ARRAY Get/Set |
Set or get the entire list of display texts. |
|
DText[n] |
STRING Get Only |
Get the display text of the n'th field. |
|
PickedField |
REAL Get Only |
Last picked list field number. |
|
RText |
STRING ARRAY Get/Set |
Set or get the list of replacement texts. |
|
RText[n] |
STRING Get Only |
Get the replacement text of the n'th field. |
|
Count |
REAL Get only |
Get count of number of fields in the list. |
|
val |
REAL Get/Set |
Selected field as integer. Zero implies no selection. Setting 'val' to zero will cause an error for mandatory selection lists. |
Methods
|
Name |
Result |
Purpose |
|---|---|---|
|
Add(STRING Dtext) |
NO RESULT |
Append an entry to the list, where Dtext is the text to display in the option list. |
|
Add(STRING Dtext, STRING Rtext)) |
NO RESULT |
Append and entry to the list, where Dtext is the text to display in the option list, and Rtext is the replacement text for the new field. If Rtext isn’t specified, it will be set to Dtext by default. |
|
FullName() |
STRING |
Get the full name of the gadget, for example, '!!Form.gadget'. |
|
Name() |
STRING |
Get the gadget's name, for example, 'gadget'. |
|
Owner() |
FORM |
Get owning form. |
|
Select(STRING text, STRING value) |
NO RESULT |
Select specified item in a list. text must be ‘Rtext’ or ‘Dtext’. value is the RTEXT or DTEXT of the item to be selected. |
|
Select(STRING text, ARRAY of STRING values) |
NO RESULT |
Select multiple choice list items. text must be 'Rtext' or 'Dtext'. values contains the RTEXT or DTEXT values to be selected. |
|
Selection( ) |
STRING ARRAY OF STRING |
Get selected RTEXT. Array of RTEXT for multi-choice list. |
|
Selection(STRING text) |
STRING ARRAY OF STRING |
Get selected RTEXT or DTEXT. Array of texts for multi-choice list. text must be 'Rtext' or 'Dtext'. |
|
Clear() |
NO RESULT |
Clear list contents and selections. |
|
ClearSelection() |
NO RESULT |
Clear list selections. |
|
SetPopup(MENU menu) |
NO RESULT |
Links menu with the gadget as a pop-up. |
|
RemovePopup(MENU menu) |
NO RESULT |
Removes pop-up menu from the gadget. |
|
GetPickedPopup() |
MENU |
Returns the last picked pop-up menu for the gadget. |
|
Refresh() |
NO RESULT |
Refreshes the display of the gadget. |
|
Shown() |
BOOLEAN |
Get ‘shown’ status. |
|
Type() |
STRING |
Get the gadget type as a STRING. |
|
SetToolTip(STRING) |
NO RESULT |
Allows a TOOLTIP to be edited. |
|
SetFocus() |
NO RESULT |
Move keyboard focus to this gadget. |
|
SetHeadings(!Dtexts is STRING) |
NONE |
Specifies the number of columns and sets the list's column headings. Dtexts contains a set of TAB separated sub-strings. |
|
SetHeadings(!Dtexts is ARRAY) |
NONE |
Specifies the number of columns and sets the list's column headings. Dtexts is an array of strings. |
|
Clear( !dtext ) |
NO RESULT |
Delete the field with the given DTEXT string. |
|
Clear( !fieldNumber ) |
NO RESULT |
Delete the specified field number. |
|
SetRows(Array of (Array of STRING)) |
NO RESULT |
This sets the display text for all the data fields of the list gadget by row. If the list gadget is already 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 of (Array of STRING)) |
NO RESULT |
This sets the display text for all the data fields of the list gadget by column. If the list gadget is 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 column, STRING dtext) |
NO RESULT |
This selects the first list row whose column column has the display text dtext. If the field is 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 Color Name. Some gadgets do not support this property in all circumstances, for example, gadgets which are showing a pixmap. Gadgets whose color has not been set explicitly, may not have a color with a known colorname. 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 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:
-
UNSELECT events are not notified to PML unless an open callback has been specified (so that SELECT and UNSELECT events can be differentiated).
-
Typically the UNSELECT action allows Appware to manage consequences of deselection for any dependent gadgets or forms.
-
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.
|
Default: |
A single choice, mandatory selection list. |