Logo

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

See Also

AddItem, AddListItem, BoundTo, Clear Method, ColumnCount, ColumnLines, ColumnWidths, DisabledItemBackColor, DisabledItemForeColor, DisplayCount, DisplayValue, DownClick, DropDown, FirstElement, IncrementalSearch, IndexToItemId, InteractiveChange, ItemBackColor, ItemData, ItemForeColor, ItemIdData, ItemIdToIndex, List Property, ListCount, ListIndex, ListItem, ListItemId, MouseEnter, MouseLeave, MoverBars, MultiSelect, NewIndex, NewItemId, NumberOfElements, Picture, RemoveItem, RemoveListItem, Requery, RowSource, RowSourceType, Selected, SelectedId, SelectedItemBackColor, SelectedItemForeColor, SelLength, SelStart, SelText, Sorted, SpecialEffect, Style, TopIndex, TopItemId, UpClick, Valid, When