About List Operations for List Boxes and Pop-Up Lists (DCL)

Lists in a dialog box require you to follow a specific sequence to populate them with items.

A dialog box list operation always begins with a start_list function call. The function syntax is as follows:

(start_list key [operation [index]])

The key argument is a string that identifies the dialog box tile. The key argument is case-sensitive. The operation argument is an integer value that indicates whether you are creating a new list, changing a list, or appending to a list. The following are valid operation arguments:

Operation codes for start_list
Value	Description
1	Change selected list contents
2	Append new list entry
3	Delete old list and create new list (the default)

The index argument is only used in change operations. The index indicates the list item to change by a subsequent add_list call. The first item in a list is index 0. If you do not specify operation, it defaults to 3 (create a new list). If you do not specify an index, the index value defaults to 0.

You implement the list operations as follows:

Creating a New List (3)

After the start_list call, call add_list repeatedly to add new items to the list. End list handling by calling end_list.

Changing an Item in a List (1)

After calling start_list, call add_list once to replace the item whose index was specified in the start_list call. (If you call add_list more than once, it replaces the same item again.) End list handling by calling end_list.

Appending an Item to a List (2)

After calling start_list, call add_list to append an item to the end of the list. If you continue to call add_list, more items are appended until you call end_list.

Regardless of which list operation you are doing, you must call the three functions in sequence: start_list, then add_list (possibly more than once), and then end_list.

The mapcar function is useful for turning a “raw” AutoLISP list into a list box display. In the following example, the appnames list contains strings that you want to appear in a list box called selections. You can use this code fragment to set up the list and display it as follows:

(start_list "selections")    ;Specify the name of the list box.
(mapcar ' add_list appnames) ;Specify the AutoLISP list.
(end_list)

Because list creation (3) is the default, this example does not specify it.

The value of a list_box tile is the index of the selected item (or the indexes of selected items, if multiple selections are allowed). If your program needs to know the actual text associated with an index, it must save the original list. It must also track changes to the list.

Appending list items is similar to creating a new list. If, for example, appnames has 12 items in it, and you want to append another list, called newnames, you could use the following code:

(start_list "selections" 2)
(mapcar 'add_list newnames)
(end_list)

Changing a single item requires only one add_list call. In this case, you specify the index of the item to change:

(start_list "selections" 1 5) ;Change the sixth item in the list.
(add_list "SURPRISE!")        ;Remember that the first index is 0.
(end_list)

You cannot delete a list item or insert an item without rebuilding the list from scratch.