List boxes and Combo boxes are used when the user needs to select a value from a set of many values. They are similar to a set of Radio buttons except that List boxes and Combo boxes are scrollable and can contain more items than a set of Radio buttons which are limited by the screen display area. Also, unlike Radio buttons, the number of entries in a List box or Combo box can change at run-time.
The difference between a List box and a Combo box is that a List box is simply a list of items, while a Combo box is a combination of a List box and an Edit box. A List box allows the user to choose multiple selections from the list at one time, while a Combo box allows only a single selection, but a Combo box allows the user to edit the selected value while a List box only allows the user to choose from the given list.
A Drop-down list box looks like a Combo box since it has a drop-down arrow to display the list. Like a Combo box, only one selection can be made at a time in a Drop-down list box, but, like a List box, the selected value cannot be edited. A Drop-down list box serves the same function as a List box except for the disadvantage that the user can choose only a single selection, and the advantage that it takes up less dialog screen space.
Visual Fortran dialog routines do not support user-drawn List boxes or user-drawn Combo boxes. You must create List boxes and Combo boxes with the Resource Editor.
The following sections describe how to use List boxes and Combo boxes:
For both List boxes and Combo boxes, the control index DLG_NUMITEMS
determines how many items are in the box. Once this value is set, you set
the text of List box items by specifying a character string for each item
index. Indexes run from 1 to the total number of list items set with DLG_NUMITEMS.
For example:
LOGICAL retlog
retlog = DlgSet ( dlg, IDC_LISTBOX1, 3, DLG_NUMITEMS )
retlog = DlgSet ( dlg, IDC_LISTBOX1, "Moe", 1 )
retlog = DlgSet ( dlg, IDC_LISTBOX1, "Larry", 2 )
retlog = DlgSet ( dlg, IDC_LISTBOX1, "Curly", 3 )
These function calls to DLGSET put three items in the List box. The initial value of each List box entry is a blank string and the value becomes nonblank after it has been set.
You can change the list length and item values at any time, including from within callback routines. If the list is shortened, the set of entries is truncated. If the list is lengthened, blank entries are added. In the preceding example, you could extend the list length and define the new item with the following:
retlog = DLGSET ( dlg, IDC_LISTBOX1, 4)
retlog = DLGSET ( dlg, IDC_LISTBOX1, "Shemp", 4)
Since List boxes allow selection of multiple entries, you need a way to determine which entries are selected. When the user selects a List box item, it is assigned an integer index. You can test which list items are selected by reading the selection indexes in order until a zero value is read. For example, if in the previous List box the user selected Moe and Curly, the List box selection indexes would have the following values:
| Selection Index | Value |
|---|---|
| 1 | 1 (for Moe) |
| 2 | 3 (for Curly) |
| 3 | 0 (no more selections) |
If Larry alone had been selected, the List box selection index values would be:
| Selection Index | Value |
|---|---|
| 1 | 2 (for Larry) |
| 2 | 0 (no more selections) |
To determine the items selected, the List box values can be read with DLGGET until a zero is encountered. For example:
INTEGER j, num, test
INTEGER, ALLOCATABLE :: values(:)
LOGICAL retlog
retlog = DLGGET (dlg, IDC_LISTBOX1, num, DLG_NUMITEMS)
ALLOCATE (values(num))
j = 1
test = -1
DO WHILE (test .NE. 0)
retlog = DLGGET (dlg, IDC_LISTBOX1, values(j), j)
test = values(j)
j = j + 1
END DO
In this example, j is the selection index and values(j) holds the list numbers, of the items selected by the user, if any.
To read a single selection, or the first selected item in a set, you
can use DLG_STATE, since for a List Box DLG_STATE holds
the character string of the first selected item (if any). For example:
! Get the string for the first selected item.
retlog = DLGGET (dlg, IDC_LISTBOX1, str, DLG_STATE)
Alternatively, you can first retrieve the list number of the selected item, and then get the string associated with that item:
INTEGER value
CHARACTER(256) str
! Get the list number of the first selected item.
retlog = DLGGET (dlg, IDC_LISTBOX1, value, 1)
! Get the string for that item.
retlog = DLGGET (dlg, IDC_LISTBOX1, str, value)
In these examples, if no selection has been made by the user, str will be a blank string.
In the Properties/Styles box in the Resource Editor, List boxes can be specified as sorted or unsorted. The default is sorted, which causes List box items to be sorted alphabetically starting with A. If a List box is specified as sorted, the items in the list are sorted whenever they are updated on the screen. This occurs when the dialog box is first displayed and when the items are changed in a callback.
The alphabetical sorting follows the ASCII collating sequence, and uppercase letters come before lowercase letters. For example, if the List box in the example above with the list "Moe," "Larry," "Curly," and "Shemp" were sorted, before a callback or after DLGMODAL returned, index 1 would refer to "Curly," index 2 to "Larry," index 3 to "Moe," and index 4 to "Shemp." For this reason, when using sorted List boxes, indexes should not be counted on to be the same once the dialog is displayed and any change is made to the list items.
You can also call DLGSETCHAR with the DLG_ADDSTRING index to add items to a List box or Combo box. For example:
retlog = DlgSet(dlgtab, IDC_LIST, "Item 1", DLG_ADDSTRING)
When you use DLG_ADDSTRING, the DLG_NUMITEMS control index of the List or Combo box is automatically incremented.
When adding items to a sorted list or Combo box, using DLG_ADDSTRING can be much easier than the alternative (setting DLG_NUMITEMS and then setting items using an index value), because you need not worry about the list being sorted and the index values changing between calls.
A Combo box is a combination of a List box and an Edit box. The user can make a selection from the list that is then displayed in the Edit box part of the control, or enter text directly into the Edit box.
All dialog values a user enters are character strings, and your application must interpret these strings as the data they represent. For example, numbers entered by the user are returned to your application as character strings.
Because user input can be given in two ways, selection from the List
box portion or typing into the Edit box portion directly, you need to register
two callback types with DLGSETSUB for a Combo box. These
callback types are dlg_selchange
to handle a new list selection by the user, and dlg_update to
handle text entered by the user directly into the Edit box portion. For
example:
retlog = DlgSetSub( dlg, IDC_COMBO1, UpdateCombo, dlg_selchange )
retlog = DlgSetSub( dlg, IDC_COMBO1, UpdateCombo, dlg_update )
A Combo box list is created the same way a List box list is created, as described in the previous section, but the user can select only one item from a Combo box at a time. When the user selects an item from the list, Windows automatically puts the item into the Edit box portion of the Combo box. Thus, there is no need, and no mechanism, to retrieve the item list number of a selected item.
If the user is typing an entry directly into the Edit box part of the Combo box, again Windows automatically displays it and you do not need to. You can retrieve the character string of the selected item or Edit box entry with the following statement:
! Returns the character string of the selected item or Edit box entry as str.
retlog = DLGGET (dlg, IDC_COMBO1, str)
Like List boxes, Combo boxes can be specified as sorted or unsorted. The notes about sorted List boxes also apply to sorted Combo boxes.
You have three choices for Combo box Type in the Styles tab of Combo box Properties:
Simple and Drop-down are the same, except that a simple Combo box always displays the Combo box choices in a list, while a Drop-down list Combo box has a Drop-down button and displays the choices in a Drop-down list, conserving screen space. The Drop list type is halfway between a Combo box and a List box and is described below.
To create a Drop-down list box, choose a Combo box from the control toolbar and place it in your dialog. Double-click the left mouse button on the Combo box to open the Properties box. On the Styles Tab, choose Drop List as the control type.
A Drop-down list box has a drop-down arrow to display the list. Like a Combo box, only one selection can be made at a time in the list, but like a List Box, the selected value cannot be edited. A Drop-down list box serves the same function as a List box except for the disadvantage that the user can choose only a single selection, and the advantage that it takes up less dialog screen space.
A Drop-down list box has the same control indexes as a Combo box with the addition of another INTEGER index to set or return the list number of the item selected in the list. For example:
INTEGER num
! Returns index of the selected item.
retlog = DLGGET (dlg, IDC_DROPDOWN1, num, DLG_STATE)