: list_box

Display a vertical list of text, with optional scrollbar and title. DCL Active Tile

This active tile displays a list box. When the user selects an item, it is highlighted. A scroll bar appears automatically when there are more items than the list_box tile is able to display.

Creating and Modifying a List Box with LISP Functions

To create and modify the list displayed by the list_box tile, use these LISP functions:

(start_list "key" int1 int2)
The start_list function takes three arguments. The key argument identifies the name of the list_box tile. The int1 argument specifies the action to take:

int1	Meaning
1	Change one item in the list.
2	Add an item to the end of the list.
3	Create a new list; the default.

The int2 argument specifies the item # to change (the first item in the list is #0); int2 is only used when int1 is 1. For example:

(start_list "L1" 1 3 ; changes the fourth item in the list.

(add_list "string")
To make the change, use the add_list function. The string argument specifies the text to be added or replaced in the list:

(start_list "L1" 1 3 ; Changes the fourth item in the list.

(add_list "New item")

When start_list is in change mode (int1 = 1), each call to the add_list changes the same item. When start_list is in add mode (int1 = 2), each call to the add_list adds another item to the end of the list.

(end_list)
To end the list processing, call the end_list function as follows:

(start_list "L1" 1 3 ; changes the fourth item in the list.

(add_list "New item")

(end_list)

NOTE There are no LISP functions for inserting an item in the middle of the list nor for deleting an item from the list.

Valid Attributes

: list_box {

action = "(string)";

allow_accept = flag;

alignment = position;

fixed_height = flag;

fixed_width = flag;

height = number;

is_enabled = flag;

is_tab_stop = flag;

key = "string";

label = "string";

list = "string";

mnemonic = "char";

multiple_select = flag;

tabs = "string";

value = "string";

width = number;

}

Example

: list_box {

action = "(subdir)";

label = "Select a color:";

list = "Red\nGreen\nBlue";

value = "0";

}

NOTE

Use the \n (new-line) character within the list attribute to separate lines.
The label attribute displays the text above the list box.
The value attribute determines which items on the list are initially selected or highlighted. The attribute consists of a string of integers separated by spaces, as in the following:

value = "0 2 5";

The first item is #0. A null string "" means no items are highlighted. When the multiple_select attribute is false, the value attribute must contain a single integer.

Related DCL Tiles

Tell me about...

Programming Overview of DCL (Dialog Control Language)

About Predefined Attributes