Using ListBoxes

A ListBox displays available choices. You can specify scroll bars for a ListBox if more choices exist than can be displayed in the ListBox at one time.

Smartphone platforms ListBoxes are converted to spinner controls when you deploy them to a Smartphone device or emulator. Extended and multiple selection properties for spinner controls are not supported. For more information about spinner controls, see Appendix D, “Designing Applications for Windows CE Platforms.”

Selecting an item and invoking actions

ListBoxes are an exception to the rule that a control should either invoke an action or be used for viewing and entering data. ListBoxes can do both. ListBoxes display data, but they can also invoke actions.

In Windows applications, clicking an item in the ListBox typically selects the item and triggers the SelectionChanged event. On Pocket PC devices, tapping an item in the ListBox has the same effect. Double-clicking an item (double-tapping the item on a Pocket PC) acts upon the item by triggering the DoubleClicked event.

PocketBuilder automatically highlights an item when a user selects the item at runtime. If you want something to happen when users double-click (or double-tap) an item, you can add a script to the control's DoubleClicked event. The SelectionChanged event is always triggered before the DoubleClicked event. The RButtonDown event on a ListBox control translates to a tap-and-hold action on a Windows CE device.

Populating the list of items

To add items to a ListBox, select the ListBox to display its properties in the Properties view, select the Items tab, and enter the values for the list. Press the Tab key to go to the next line.

In the Items tab page, you can work with rows as described in Table 11-3.

**Table 11-3: Working with rows in the Items page of the ListBox Properties view**
To do this	Do this
Select a row	Click the row button on the left, or with the cursor in the edit box, press Shift+Space
Delete a row	Select the row and press Delete
Move a row	Click the row button and drag the row where you want it, or press Shift+Space to select the row, then press Ctrl+Up Arrow or Ctrl+Down Arrow to move the row
Delete text	Click the text and select Delete from the pop-up menu

Changing the list during execution To change the items in the list at runtime, use the functions AddItem, DeleteItem, and InsertItem.

Setting tab stops

You can set tab stops for text in ListBoxes (and in MultiLineEdits) by setting the TabStop property on the General properties page. You can define up to 16 tab stops. The default is a tab stop every eight characters.

You can also define tab stops in a script. Here is an example that defines two tab stops and populates a ListBox control:

// lb_1 is the name of the ListBox.
string f1, f2, f3
f1 = "1"
f2 = "Emily"
f3 = "Foulkes"
// Define 1st tab stop at character 5.
lb_1.tabstop[1] = 5
// Define 2nd tab stop 10 characters after the 1st.
lb_1.tabstop[2] = 10
// Add an item, separated by tabs.
// Note that the ~t must have a space on either side
// and must be lowercase.
lb_1.AddItem(f1 + " ~t " + f2 + " ~t " + f3)
//Make sure a scroll bar displays for the list box

lb_1.HScrollBar=true

Note that this script will not work if it is in the window's Open event, because the controls have not yet been created. The best place to include this script is in a user event that is posted in the window's Open event using the PostEvent function.

Other properties

For ListBoxes, you can specify whether:

Items in the ListBox are displayed in sorted order
The ListBox allows the user to select multiple items
The ListBox displays scroll bars if needed

For more information, right-click in any tab page in the Properties view for a ListBox and select Help from the pop-up menu.