BoundColumn, DisplayValue

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.

BoundColumn, DisplayValue

These properties relate to multi-column list boxes and combo boxes. BoundColumn determines which column is used to fill the Value property and the ControlSource. DisplayValue contains the value of the first column of the current item or the row number of the current item, or, in a drop-down combo, the text typed in by the user.

These properties, although a little tricky to understand, are among those that make lists and combos much easier to manipulate in Visual FoxPro than they were in FoxPro 2.x.

Usage

oObject.BoundColumn = nColumn
nColumn = oObject.BoundColumn
oObject.DisplayValue = cFirstColumnValue | cNewValue | nRow
nRow = oObject.DisplayValue
cFirstColumnValue = oObject.DisplayValue
cNewValue = oObject.DisplayValue

In Visual FoxPro, unlike FoxPro 2.x, you can have true multi-column list and combo boxes. With many of the options for populating these controls (see RowSourceType for the list), it’s as simple as setting ColumnCount to something other than 1.

Once you have multiple columns, the question is “which column do we return?” In FoxPro 2.x, you had to write code for this—either parsing the item or looking up the return value in an array or table. In Visual FoxPro, just set BoundColumn to the desired column. If you have a list box containing, say, an employee’s name and ID, in that order, set BoundColumn to 2 and the list box’s Value contains the ID of the currently selected employee.

You can even bind the combo's or list's value to a column that isn't displayed. Just set ColumnWidths so the column in question has a width of 0, and set BoundColumn to that column. Using this approach, you can, for example, display the employee name and department, but return the employee ID from the list or combo.

With some RowSourceTypes, you can even bind to a column that isn't specified as part of the list or combo. For example, with 2-Alias, you can bind to columns beyond ColumnCount. Same thing for arrays.

DisplayValue, though tricky, is the key to making drop-down combos useful. Like a combo or list’s Value, it can be either numeric or character, but unlike Value, you’ll rarely want to make DisplayValue numeric. If it’s numeric, it references a row of the list or combo. If it’s character, it contains the contents of the first column of the currently selected row. On the whole, we recommend you stay away from the numeric version, except when BoundTo is set to .T. In fact, DisplayValue is always character by default—you have to go out of your way to make it numeric.

For the moment, let’s look at character DisplayValues. In this case, whatever item is highlighted in the combo or list, DisplayValue holds the contents of the first column for that item. In a combo box, this is the part of the value that you see when the combo isn’t dropped down—in other words, it’s the value that’s displayed. (Hey, DisplayValue—the value that’s displayed.)

More importantly, when a user of a drop-down combo (Style = 0) types in a string that isn’t in the list, that string is stored in DisplayValue and not in Value. You can tell whether the user has typed something in by either comparing DisplayValue to Value (if BoundColumn is 1) or by checking whether Value is empty, in the combo’s Valid. If so, you need to do something with DisplayValue. The user’s entry is not automatically added to the combo’s list. You can do so with code (for appropriate RowSourceTypes)—see the example.

As for numeric DisplayValues, you get them only when you set DisplayValue to a number in the first place. If BoundTo is .F. (the default), DisplayValue contains the number of the row that’s currently highlighted. If BoundTo is .T., DisplayValue contains the first column of the highlighted row whether or not it’s numeric, but if that column is numeric, DisplayValue contains the value as a number in this case. (If you leave DisplayValue alone, it contains the value as a string.)

In a multi-select list box, both DisplayValue and Value reflect the last item selected. (Interestingly, this is true even when that selection actually de-selects the item.)

Example

* If you have a drop-down combo with RowSourceType = 0
* you might do this in Valid
IF EMPTY(This.Value)
   * The user typed in a new item. Add it
   This.AddItem(This.DisplayValue)
   This.ListIndex = This.NewIndex
ENDIF