SELECTION-LIST phrase

Describes the selection-list representation of a field or variable. A selection-list is a scrollable list of values. The SELECTION-LIST phrase is an option of the VIEW-AS phrase.

Note:

Does not apply to SpeedScript programming.

Syntax 

 

SELECTION-LIST [ SINGLE | MULTIPLE ] [ NO-DRAG ] { LIST-ITEMS item-list | LIST-ITEM-PAIRS item-pair-list } [ SCROLLBAR-HORIZONTAL ] [ SCROLLBAR-VERTICAL ] { size-phrase | { INNER-CHARS cols INNER-LINES rows } } [ SORT ] [ TOOLTIP tooltip ]

SINGLE

Specifies that on input the user can select only a single item from the list. This is the default. The value of the selection-list is set to the character-string item the user selects.

MULTIPLE

Specifies that on input the user can select one or more items from the item list. The value of the selection-list is set to a comma-separated list of character-string items that the user selects.

NO-DRAG

Specifies that the user cannot select items by simultaneously holding down the mouse select button and dragging the mouse through the list.

If you specify NO-DRAG then the DRAG-ENABLED attribute is set to FALSE. You can set the DRAG-ENABLED attribute only before the selection-list is realized. The default is TRUE.

In Windows, DRAG-ENABLED is always TRUE and the NO-DRAG option is ignored.

LIST-ITEMS item-list

Specifies the items to appear in the list. item-list represents a comma-separated list of character-string constants.

LIST-ITEM-PAIRS item-pair-list

Specifies a list of label-value pairs. Each pair represents a label and value of the associated field or variable. When the selection-list appears, it displays each pair’s label. Then, if the user selects a label, the AVM assigns the corresponding value to the field or variable. The syntax for item-pair-list is as follows:

 

Syntax 

label , value [ , label , value ] ...

label

A character string representing the label of the field or variable.

value

A valid value for the field or variable.

SCROLLBAR-VERTICAL

Specifies that a scroll bar is displayed along side the selection-list. The user can browse through a long selection-list by manipulating the slider.

SCROLLBAR-HORIZONTAL

Specifies that a scroll bar is displayed along the bottom of the selection-list. The user can view long list items by manipulating the slider.

size-phrase

Specifies the outside dimensions of the selection-list widget. Following is the syntax for the size-phrase:

 

Syntax 

{ SIZE | SIZE-CHARS | SIZE-PIXELS } width BY height

For more information, see the SIZE phrase reference entry.

INNER-CHARS cols INNER-LINES rows

Specifies the number of character positions visible in each line of the selection-list and the number of lines visible in the selection-list. Both cols and rows must be integer constants.

Note that the values you supply for INNER-CHARS and INNER-LINES specify only the size of the list, not the overall size of the selection-list widget. The overall size is determined by the size of the list plus the sizes of the margin and border heights and widths.

SORT

Specifies that list items are sorted prior to display.

TOOLTIP tooltip

Allows you to define a help text message for a text field or text variable. The AVM automatically displays this text when the user pauses the mouse button over a text field or text variable for which a tooltip is defined.

You can add or change the TOOLTIP option at any time. If TOOLTIP is set to "" or the Unknown value (?), then the tooltip is removed. No tooltip is the default. The TOOLTIP option is supported in Windows only.

Example 

The r-select.p procedure prompts the user for a directory name and then populates a selection-list with the contents of the specified directory. After the user selects an item from the selection-list, the procedure echoes back the selection.

The procedure uses the INPUT FROM statement to read the contents of the user-specified directory and creates a comma-separated list of all the file and directory names in the directory. It then assigns the comma-separated list to the LIST-ITEMS attribute of the selection-list. Because an assignment to an attribute depends on the widget being located in a frame, the DEFINE FRAME statement is used to locate the selection-list.

 

r-select.p

DEFINE VARIABLE f-name        AS CHARACTER NO-UNDO FORMAT "x(14)". DEFINE VARIABLE choice        AS CHARACTER NO-UNDO FORMAT "x(50)"   LABEL "You have selected". DEFINE VARIABLE list_contents AS CHARACTER NO-UNDO FORMAT "x(200)". DEFINE VARIABLE dir           AS CHARACTER NO-UNDO FORMAT "x(40)"   LABEL "Please enter a directory pathname ". DEFINE VARIABLE sl            AS CHARACTER NO-UNDO   VIEW-AS SELECTION-LIST INNER-CHARS 15 INNER-LINES 10 SORT.   DEFINE FRAME b sl. DEFINE FRAME c choice.   DEFINE STREAM dirlist.   ENABLE dir WITH FRAME d WITH SIDE-LABELS. ON RETURN OF dir IN FRAME d DO: ASSIGN FRAME d dir. INPUT STREAM dirlist FROM OS-DIR (dir). IMPORT STREAM dirlist f-name. list_contents = f-name. REPEAT: IMPORT STREAM dirlist f-name. list_contents = list_contents + "," + f-name. END. INPUT CLOSE.   sl:LIST-ITEMS IN FRAME b = list_contents. ENABLE sl WITH FRAME b NO-LABELS TITLE "Please Select a File" WIDTH 50. END.   ON VALUE-CHANGED OF sl IN FRAME b DO:   choice = sl:SCREEN-VALUE.   DISPLAY choice WITH FRAME c SIDE-LABELS. END.   WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

Notes 

When the selection-list appears, if it contains the value of the associated field or variable, that value is initially highlighted. Otherwise, no value in the selection-list is initially highlighted.

The LIST-ITEMS option of the SELECTION-LIST phrase requires a list of quoted items ("a", "b", "c"), whereas the LIST-ITEMS attribute of a selection-list requires a quoted list of items ("a, b, c"). Similarly, the LIST-ITEM-PAIRS option of the SELECTION-LIST phrase requires a list of quoted items ("a", "1", "b", "2", "c", "3"); whereas the LIST-ITEM-PAIRS attribute of a selection-list requires a quoted list of items ("a, 1, b, 2, c, 3").

If you specify the SORT option for a selection-list, then any items you add with ADD-FIRST, ADD-LAST, or INSERT methods are added in sorted order rather than the order you specify.

In Windows, you can use a mnemonic to transfer focus to the selection-list.

See also 

SIZE phrase, VIEW-AS phrase