Using the List Box Control

See Also

A list box control displays a list of items from which the user can select one or more.

Figure 7.32   The list box control

List boxes present a list of choices to the user. By default, the choices are displayed vertically in a single column, although you can set up multiple columns as well. If the number of items exceeds what can be displayed in the list box, scroll bars automatically appear on the control. The user can then scroll up and down, or left to right through the list. Figure 7.33 shows a single-column list box.

Figure 7.33   Single-column list box

Data-Bound Features

Visual Basic includes both standard and data-bound versions of the list box control. While both versions of the list box control allow you to display, edit, and update information from most standard types of databases, the DataList provides more advanced data access features. The DataList control also supports a different set of properties and methods than the standard list box control.

For More Information   See "Using the DataCombo and DataList Controls" for more information on the data-bound version of the list box control.

The Click and Double-Click Events

A recommended practice for list box events, especially when the list box appears as part of a dialog box, is to add a command button to use with the list box. The Click event procedure for this button should make use of the list-box selection, carrying out whatever action is appropriate for your application.

Double-clicking an item in the list should have the same effect as selecting the item and then clicking the command button. To do this, have the DblClick procedure for the list box call the Click procedure for the command button:

Private Sub List1_DblClick ()
   Command1_Click
End Sub

Or, set the value of the command button's Value property to True, which will automatically invoke the event procedure:

Private Sub List1_DblClick ()
   Command1.Value = True
End Sub

This provides mouse users with a shortcut, yet does not prevent keyboard users from performing the same action. Note that there is no keyboard equivalent for the DblClick event.

Adding Items to a List

To add items to a list box, use the AddItem method, which has the following syntax:

box.AddItem item[, index]

While list items are commonly added in the Form_Load event procedure, you can use the AddItem method at any time. This gives you the ability to add items to the list dynamically (in response to user actions).

The following code places "Germany," "India," "France," and "USA" into a list box named List1:

Private Sub Form_Load ()
   List1.AddItem "Germany"
   List1.AddItem "India"
   List1.AddItem "France"
   List1.AddItem "USA"
End Sub

Whenever the form is loaded at run time, the list appears as shown in Figure 7.34.

Figure 7.34   "Countries" list box

Adding an Item at a Specified Position

To add an item to a list at a specific position, specify an index value for the new item. For example, the next line of code inserts "Japan" into the first position, adjusting the position of the other items downward:

List1.AddItem "Japan", 0

Notice that it is 0, not 1, that specifies the first item in a list (see Figure 7.35).

Figure 7.35   Adding an item to a list

Adding Items at Design Time

You can also enter items into the list at design time by setting the List property in the Properties window of the list box control. When you select the List property option and then click the down arrow, you can type list items and then press the CTRL+ENTER key combination to start a new line.

You can only add items to the end of the list. So, if you want to alphabetize the list, set the Sorted property to True. See "Sorting a List" below for more information.

Sorting a List

You can specify that items be added to a list in alphabetical order by setting the Sorted property to True and omitting the index. The sort is not case-sensitive; thus, the words "japan" and "Japan" are treated the same.

When the Sorted property is set to True, using the AddItem method with the index argument can lead to unpredictable, unsorted results.

Removing Items from a List

You can use the RemoveItem method to delete items from a list box. RemoveItem has one argument, index, which specifies the item to remove:

box.RemoveItem index

The box and index arguments are the same as for AddItem.

For example, to remove the first entry in a list, you would add the following line of code:

List1.RemoveItem 0

To remove all list entries in bound or standard versions of the list and combo boxes, use the Clear method:

List1.Clear

Getting List Contents with the Text Property

Usually, the easiest way to get the value of the currently selected item is to use the Text property. The Text property always corresponds to a list item a user selects at run time.

For example, the following code displays information about the population of Canada if a user selects "Canada" from a list box:

Private Sub List1_Click ()
   If List1.Text = "Canada" Then
      Text1.Text = "Canada has 24 million people."
   End If
End Sub

The Text property contains the currently selected item in the List1 list box. The code checks to see if "Canada" has been selected and, if so, displays the information in the Text box.

Accessing List Items with the List Property

The List property provides access to all items in the list. This property contains an array in which each item in the list is an element of the array. Each item is represented in string form. To refer to an item in the list, use this syntax:

box.List(index)

The box argument is a reference to a list box, and index is the position of the item. The top item has an index of 0, the next has an index of 1, and so on. For example, the following statement displays the third item (index = 2) in a list in a text box:

Text1.Text = List1.List(2)

Determining Position with the ListIndex Property

If you want to know the position of the selected item in a list, use the ListIndex property. This property sets or returns the index of the currently selected item in the control and is available only at run time. Setting the ListIndex property for a list box also generates a Click event for the control.

The value of this property is 0 if the first (top) item is selected, 1 if the next item down is selected, and so on. ListIndex is – 1 if no item is selected.

Note   The NewIndex property allows you to keep track of the index of the last item added to the list. This can be useful when inserting an item into a sorted list.

Returning the Number of Items with the ListCount Property

To return the number of items in a list box, use the ListCount property. For example, the following statement uses the ListCount property to determine the number of entries in a list box:

Text1.Text = "You have " & List1.ListCount & " _
entries listed"

Creating Multiple-Column and Multiple-Selection List Boxes

The Columns property allows you to specify the number of columns in a list box. This property can have the following values:

Visual Basic takes care of wrapping list items to the next line and adding a horizontal scroll bar to the list if needed; if the list fills a single column, no scroll bar is added. Wrapping to the next column also occurs automatically as needed. Note that if a list box entry is wider than the width of a column, the text is truncated.

You can allow users to select multiple items from a list. Multiple selection in standard list boxes is handled by setting the MultiSelect property, which can have the following values.

For More Information   See "List Box Control Scenario 2: Creating Multiple-Column List Boxes" later in this chapter for more information on the Columns and MultiSelect properties.