ComboBox, ListBox

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

ComboBox, ListBox

These two controls let a user choose one item from a specified, generally scrollable, list. In addition, combo boxes can be configured to let the user enter a new item as well (hence the name combo—it’s a combination of a text box and a drop-down). List boxes, not to be outdone, optionally support multiple selection. Both controls have far more in common than different, though.

These are incredibly versatile, powerful controls. Some days, we might even argue that combos and lists are more powerful than grids.

Property	Value	Purpose
BoundTo	Logical	Determines whether a numeric Value indicates the row to highlight or the numeric data to highlight.
ColumnCount	Numeric	The number of columns displayed in a list or in the drop-down portion of a combo.
ColumnLines	Logical	Determines whether the lines between columns are visible.
ColumnWidths	Character	A comma-delimited list of the widths for the columns. Required with proportional fonts to make straight columns.
DisabledItemBackColor, DisabledItemForeColor	Numeric	The colors used to represent disabled items in the list or combo.
DisplayCount	Numeric	Combo only. Determines how many items are displayed when you drop the combo open.
DisplayValue	Character or Numeric	Determines which item in a combo is displayed when the combo is closed (and displays first on the list when it opens). Contains text typed by the user in a drop-down combo. For lists, indicates which item is highlighted.
FirstElement, NumberOfElements	Numeric	Determine which column of an array is displayed (one-column list or combo only) and which rows of the array are included.
IncrementalSearch	Logical	Determines whether the list or combo uses FoxPro's smart incremental search technique or Windows (3.1's) dumb one.
ItemBackColor, ItemForeColor	Numeric	The colors used for the items in the list or combo. For a combo, affects only the drop-down portion.
ItemData, ItemIdData	Array containing numeric	Can contain numeric data matched to the items in a list or combo.
List, ListItem	Array containing character	Contain the actual data from the list or combo.
ListCount	Numeric	The number of items in the list or combo.
ListIndex, ListItemId	Numeric	The position of the currently selected item in the list or combo.
MoverBars	Logical	List only. Determines whether the list has mover buttons that let the user reorganize the items.
MultiSelect	Logical	List only. Determines whether multiple items can be selected at the same time.
NewIndex, NewItemId	Numeric	The position of the most recently added item in the list or combo.
Picture	Array containing file names	Indicates, for each item, the icon to display next to it.
RowSource	Character	The data in the list or combo, or a pointer to it. RowSourceType determines the actual meaning.
RowSourceType	Numeric	The form of the data. Determines the interpretation of RowSource.
Selected, SelectedId	Array containing logical	Indicates, for each item, whether it's currently highlighted.
SelectedItemBackColor, SelectedItemForeColor	Numeric	The colors used for highlighted items.
SelLength, SelStart	Numeric	Combo only. The length and starting position of highlighted text in the text box portion of the combo.
SelText	Character	Combo only. The highlighted text in the text box portion of the combo.
Sorted	Logical	Determines whether the items in the list or combo are sorted alphabetically.
SpecialEffect	Numeric	Determines the appearance of the control.
Style	Numeric	Combo only. Specifies either combo box or drop-down list box.
TopIndex, TopItemId	Numeric	The position of the first item displayed in the list or combo.

Event	Purpose
DownClick	Supposed to fire when user clicks the down arrow on the scrollbar. Doesn't fire for lists, only for combos.
DropDown	Fires after user clicks down arrow to open combo, but before combo opens. (In early versions, fired late.)
InteractiveChange	Fires each time the user moves in the list. Also fires for each character the user types.
MouseEnter	Fires when the mouse moves into the area occupied by the control.
MouseLeave	Fires when the mouse leaves the area occupied by the control.
ProgrammaticChange	Fires when DisplayValue or Value is changed via code.
UpClick	Supposed to fire when user clicks the up arrow on the scrollbar. Doesn't fire for lists, only for combos.
Valid	In a combo, fires whenever the user closes the combo (except with ESC) or, in a drop-down list, when the user types enough to choose a value. In a list, fires when the user leaves.
When	In a combo, fires when focus is headed for the combo. In a list, fires whenever the list highlight moves.

Method	Purpose
AddItem, AddListItem	Add a new item to the list or combo.
Clear	Remove all items from the list or combo.
IndexToItemId, ItemIdToIndex	Convert between the two numbering schemes for items.
RemoveItem, RemoveListItem	Remove an item from the list or combo.
Requery	Refresh the list or combo to include the latest data from the RowSource.

You’ve probably noticed that many of the properties and methods come in pairs. This is because there are two ways to address each item in a list or combo. The “Index” properties address items by their current position in the list. The “ItemId” properties address the items by a unique, permanent ID number assigned when the item is added to the list. See ListIndex for more on this.

The behavior of lists and combos with numeric data confuses people. The key point is that, even when we think we're seeing numbers in a combo or list, we're actually seeing characters. Combos and lists cannot show numeric data. If you specify a RowSource that's numeric, FoxPro internally converts the data to character before displaying it.

The Value of a list or combo (and, therefore, the ControlSource it’s bound to) can be either character or numeric. If the Value is character, it contains the text of the currently highlighted item. If the Value is numeric, by default it contains the index of that item. Before VFP 5, there was no way to get numeric data out of a list or combo. The BoundTo property lets you tell VFP to convert a numeric character string to a number before sticking it into Value or DisplayValue.

In VFP 7, these controls (along with the others) acquired the MouseEnter and MouseLeave events, which let you react as the mouse passes over a control. Both also support the Hot Tracking value for SpecialEffect that lets them look flat until the mouse passes over. Note that a combo with SpecialEffect set to 2–Hot Tracking keeps its 3-D look as long as it’s dropped down, even if the mouse moves on.

Example

* This code creates a subclass of ListBox
* that is, by default, based on an array called aItems,
* which is a property of the list itself.
* The list is multi-select and displays
* a message whenever an item is highlighted.
DEFINE ArrayList AS ListBox

  DIMENSION aItems[1]

  RowSourceType = 5
  RowSource = "This.aItems"
  MultiSelect = .T.

  PROCEDURE InteractiveChange

  WAIT WINDOW "Got one!"

  ENDPROC
ENDDEFINE

ComboBox, ListBox

Example

See Also