Allowing a user to select one or more items from a list is a common Web design pattern. A ListBox permits the programmer to display a number of items, allow the user to make a selection, and then proceed accordingly. ListBoxes are ideal controls for presenting a list of choices to the user---whether a few items or a large number.

In Curl, a ListBox is used to select multiple items. Each selection can be displayed as either text or graphics. The choices are displayed in single vertical column. Zero, one, or more of the choices can be selected by the user.


Notice that scrollbars will automatically appear if the ListBox height is greater than the specified height. If the height is not specified, the ListBox will display all selections. Also, the style of the displayed items has been set to checkbutton which provides a small box to show what is selected. When an item is selected, a "check" graphic will appear in the box. The style can also be set to standard, in which it looks and behaves like a traditional list control.

If the requirement is that a maximum of one item can be selected from the list, you can set ListBox.selection-policy to "single" instead of the default policy of "multiple". You may also want to consider using ComboBox, DropdownList or RadioButton classes.

Creating List Items from Accessed Data

It is common that the selectable items are dynamically retrieved at runtime from an external source such as a database. We can query the data and temporarily store it using an array, hashtable, recordset, or other method of storage. The append or insert methods are used to add new items to the ListBox.

Items appended to a ListBox appear in the order in which they were added. For our example, we will store our list data in an array and then append each item in the array to the ListBox.

Another method of gathering items from an array is to use splice. The splice macro returns the elements of the array as a list of arguments as shown below.

Tip: Sometimes list items need to be added after the actual control has been created. ListModelControl provides methods for manipulating items such as append, remove, clear, delete and find.

Getting Selected Values

Once the user has made their selections, you will need to gather the information for display or further processing. The user selected items in a ListBox are stored as an array in the value property. We can loop through the items of the array to obtain the selected values.

In our example below, the selected values are gathered and displayed in a VBox.

For more information regarding List Controls, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Graphical User Interface > List Controls

The next example takes input from a TextField and appends those values to a ListBox. The ListBox displays the current entries.

Notice that unset-value is used to clear the input value in the TextField when the user presses enter.

For more information regarding Text Controls, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Graphical User Interface > Text Controls