Value, Text

Value is a wonderfully overloaded property that, in one way or another, tells you the current value of a control. The type and interpretation of the value changes, depending on the control involved. Text is a handy corollary to Value, giving you a textual version of the value, in case it’s not character. Text applies only to the controls that allow textual input.

Usage

oObject.Value = uControlValue
uControlValue = oObject.Value
cValueText = oObject.Text

You can change the Value of a control and see your changes reflected in the display. In some cases, changing the Value can have profound effects. In at least one, it can cause ugly behavior.

The simplest cases are text boxes, edit boxes and spinners. In that case, what you see is what you get. Value contains the actual value displayed.

Except for a couple of things. If an edit box has MaxLength set so you can only see part of the data, Value still contains the entire string. Watch out, though: as soon as you start fiddling with the data in the edit box, the data is truncated to MaxLength characters. If the edit box is bound to a field, the data in the field changes, too.

Value’s type for these controls is determined by the control’s ControlSource, if there is one. If not, Value is character for text and edit boxes and numeric for spinners.

These controls plus combo boxes are the ones that have the Text property. Most of the time, Text contains what you’d get if you applied TRANSFORM() to Value; that is, a character string that looks like the value. However, some of the Format options change that. For example, when Format includes “R”, Text includes the extra formatting characters, while Value does not. When Format includes “E” (for British dates), Text contains the date in the DD/MM/YY format rather than the current date format.

On to buttons. Command buttons don’t have a Value. Only CommandGroups do. The value can be either numeric or character. If it’s numeric, it contains the position in the group of the button last chosen. (Position is based on the buttons’ order in the Buttons collection.) If Value is character, it contains the Caption of the last chosen button.

OptionGroups work the same way, allowing either numeric or character Values. However, individual option buttons also have a Value property. It’s 1 if that button is chosen and 0 if it isn’t.

You can set the Value of more than one option button in an option group to 1, so that multiple options appear to be chosen. You can also set them all to 0, so that no buttons are chosen. Individual option buttons shouldn't even have a Value property, but since they do, it ought to work right.

Check boxes are pretty simple, too. Their Value can be numeric or logical, with 0 = .F. = unchecked and 1 = .T. = checked. There’s one complication: A check box can also show a null value. Set Value to 2 or .NULL. and the check box turns gray. Watch out. Just because it’s gray doesn’t mean it can’t be clicked—it can. Use Enabled to make it unclickable.

For combo and list boxes, things get interesting. Value can be either character or numeric. If it’s character, it contains the actual text of the chosen item—as a character string. Even if the RowSource data is something other than character, when it’s placed in a list or combo, it’s converted to character there. If Value is numeric, it’s the Index in the list or combo of the chosen item. In VFP 5 and later, you can put a numeric data item in Value (as a character string, of course) by setting the list or combo’s BoundTo property to .T. This lets you show a description in the list while saving a numeric ID for the Value. In VFP 3, there’s no way to use numeric data for the Value of a list or combo.

For multi-column lists and combos, Value (when character) contains the contents of BoundColumn for the chosen item. DisplayValue, however, always contains the contents of the first column, unless you make it numeric.

Finally, the one that surprised the heck out of us: Grids have Values. The Value is available only when the grid has focus, but then it contains the value of the cell with focus. The type of Value changes to match the current column. When the grid doesn’t have focus, its Value is 0.

Don't change a grid's Value—doing so unlinks the connection between the grid contents and the Value property. Once you do it, Value is no longer updated by moving in the grid.

Beware. When a control has a ControlSource, the new Value doesn’t reach the ControlSource until just before the control’s Valid. If you check the value of the ControlSource in InteractiveChange, you won’t see the new value. That is, in InteractiveChange, Value shows one thing and the value of the ControlSource shows something else. Yet another reason to always refer to Value, not the actual ControlSource to which the control is bound.

Example

* Initialize a list to a particular item.
This.Value = cCurrentChoice

See Also

BoundColumn, BoundTo, Buttons, Caption, ControlSource, DisplayValue, Enabled, Format, InteractiveChange