List Gadgets

PML Customisation User Guide

Gadget Set : List Gadgets

A list gadget allows you to make single or multiple selections from many alternatives. The list of choices is scrollable if the list is too long to be displayed all at once.

A LIST gadget is thus appropriate if you have a long list of choices, or if you are constructing the list dynamically (at run time), especially if you cannot predict how many choices there will be.

You must specify whether the gadget is a single or multiple-choice list, and give the width and height of the displayed portion.

The length defines the number of choices that will be visible within the gadget. You may optionally specify a text tag to be displayed at the top-left above the gadget, the position on the form and a callback command.

Typically you enter text values into the list using an array of strings and assigning to its Dtext member.

list .List 'Select some of these' MULTIPLE width 15 height 8

 !Elements[1]= 'Element 1'

 !Elements[2]= 'Element 2'

 !Elements[3]= 'Element 3'

 !Elements[4]= 'Element 4'

 !Elements[5]= 'Element 5'

 !Elements[6]= 'Element 6'

 !This.List.Dtext= !Elements

More examples:

list .Components SINGLE  width 10 height 15

list .Components 'Colour:' AT . . .  MULTIPLE width 10 height 15

list .Elements 'Elements to be deleted' callback '!this.Delete' MULTIPLE  width 10 length 15

As with the option gadget, the list gadget actually contains two parallel lists, of the same length, one containing display values (Dtext) and the other containing replacement values (Rtext).

The Dtext values must be supplied, but the replacement values are optional.

If you do not supply the Rtext values you will default to the Dtext values. The Rtext values are often used to assign callback strings to each field of the list.

Resetting a list gadget's display-texts automatically deletes the existing display and replacement-texts and clears any current selections. For example, the contents of gadget List of Figure 21:2.: The tabbed pages of a complex form could be replaced by:

!Choices[ 1 ] = 'Tea'

!Choices[ 2 ] = 'Coffee'

!Choices[ 3 ] = 'Chocolate'

!This.List.Dtext = !Choices

You can replace the list’s Rtext with a new array of the same length without disturbing the current Dtexts:

!newRtext[1] = ‘drink6’

!newRtext[2] = ‘drink4’

!newRtext[3] = ‘drink12’

!This.List.Rtext = !newRtext

You can use the new Add methods to add a single new entry to be appended to LIST and SELECTOR gadgets:

Add( !Dtext is STRING ) 

Add( !Dtext is STRING, !Rtext is STRING )

Where Dtext is the text to be displayed in the option list, and Rtext is the replacement text for the new field.

If Rtext is not specified, it will be set to the Dtext string by default.