Progress
Language Tutorial
for Windows


Working with Selection Lists

A selection-list widget presents the user with a list of choices in a rectangle. The user can make single or multiple selections by manipulating a highlight bar. The selection list can contain more values than the rectangle can hold. In this case, Progress provides scrolling behaviors. Figure 7–7 shows the parts of a selection list.

Figure 7–7: Parts of a Selection List

You can use the selection list widget with a CHARACTER field or variable. The choices in a list are always CHARACTER strings and the values returned to the procedure from the widget are CHARACTER strings. (You can effectively create a selection list of a different data type by using the data conversion functions on the returned CHARACTER string.)

Selection lists are valuable for restricting values to a predefined set. Selection lists are also valuable for creating indexes to data sets. For example, suppose you needed to search through several records. As you search, each record displays-that’s a lot of work on the computer’s part. Instead, you could create a selection list that contains a key field in a record, such as Name in the Customer table. You can then search more quickly through the selection list and use the result to display the whole record. This technique of creating a run-time selection list from a data set is called populating a selection list.

The selection list is an extremely flexible widget, as you can see by the options of the VIEW-AS syntax.

SYNTAX
VIEW-AS SELECTION-LIST
  [ SINGLE | MULTIPLE ]
  LIST-ITEMS item-list
  [ DELIMITER character ]
  [ SCROLLBAR-HORIZONTAL ]
  [ SCROLLBAR-VERTICAL ]
  { size-phrase | INNER-CHARS cols INNER-LINES rows }
  [ SORT ]
  [TOOLTIP tooltip ] 

Table 7–7 explains some of the elements of the selection list syntax:

Table 7–7: Selection List Syntax
Element
Description
SINGLE
MULTIPLE
The SINGLE and MULTIPLE options allow you to specify whether the user can select a single value from the list or multiple values. Normally, selection lists have single selection and that is the default. For more information about MULTIPLE lists, see the Progress Programming Handbook .
item-list
After the keyword LIST-ITEMS, include a comma-separated list of strings. The strings are both the values that appear in the widget and the values the widget returns to your procedure.
DELIMITER
After the keyword DELIMITER, you can specify a character other than the comma to use as the separator in the item list. This option is necessary when your data could contain commas.
SCROLLBAR-HORIZONTAL
SCROLLBAR-VERTICAL
If the selection list has more items than the confining rectangle can show, then the selection list automatically scrolls the values as the user accesses the top and bottom values in the selection rectangle. Despite this behavior, specifying a vertical scrollbar with the SCROLLBAR-VERTICAL option makes it explicit to your users that the selection list contains more items than they can see.
Specify a horizontal scrollbar with the SCROLLBAR-HORIZONTAL option when the selection list items are longer than the confining rectangle.
Scrollbars only appear if Progress cannot fit all the items in the display rectangle.
size-phrase
Although available, you’ll find the INNER-CHARS and INNER-LINES syntax more useful than the size phrase for setting up selection lists.
INNER-CHARS
After the keyword INNER-CHARS, specify the number of characters of the list items you want to appear in the selection list rectangle. Typically, this value should equal the length of the longest list item plus one. Progress can then determine the width of the widget.
INNER-LINES
After the keyword INNER-LINES, specify the number of list items you want to appear in the rectangle of the selection list. Progress will then determine the height of the widget.
SORT
This option sorts and displays the list items in alphabetical order. This option is especially valuable when populating selection lists at run time.
TOOLTIP tooltip
You can optionally define a text message string that automatically displays when the mouse pointer pauses over the selection list.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095