ListBox

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

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 can also invoke actions. Typically in Windows applications, clicking an item in the ListBox selects the item. Double-clicking an item acts upon the item.

For example, in the PowerBuilder Open dialog box, clicking an object name in a ListBox selects the object. Double-clicking a name opens the object’s painter.

PowerBuilder automatically selects (highlights) an item when a user selects it at runtime. If you want something to happen when users double-click an item, you must code a script for the control's DoubleClicked event. The Clicked event is always triggered before the DoubleClicked event.

Populating the list

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 tab to go to the next line.

In the Items tab page, you can work with rows in this way:

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 and 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 at runtime 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 property 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:

// 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)

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 way to specify this 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.