Text versus Value Properties of a Field Object A form in Alpha Five is bound to either a table or set. Opening a form automatically opens an instance of the table or set that the form is based upon, and the user is shown a view of the table's data. I like to explain a form as a 'window' that you view a table's data through. This 'window' can change your view of the data, but it never changes the actual data. For example, if you are looking through a tinted window in a home, a bright day might appear dark and gloomy. Such is the nature of a form. It can change the appearance of your data, but the data remains unaffected.

The field objects (controls) on a form are not the table fields. Field objects on a form are software objects that are bound to the table fields. A field object displays the table field in the manner you define. An easy way to see this is to set a field object's format properties. If you are dealing with a numerical field, one of the formatting options available is to display the field with a dollar sign "$". If you are dealing with a character field, you can set the formatting properties to display the field's characters in upper case. Setting these field object property values will change the way the actual data is displayed within a given form, but it does not in any way change the actual data in the underlying table field. Contrast this with a table field rule where a field's format is set to upper case. The field rule changes any lower case letters, entered into the field, to upper case when the record is saved.

When accessing data via a form, we are accessing the field control, not the field itself. While this may appear to be a moot point, as you will see, it is very important to understand the difference. The first issue this brings up is one of names. Assume that you have a character field named "FirstName". By default, when you place this field on a form, Alpha Five gives the field object the same name as the underlying field. So the field object on the form is also named "FirstName". If a second instance of the field is placed on the same form, Alpha Five can not give the second field object the same name as the first, so Alpha Five gives the second field object (bound to the same underlying table field) the name "FirstName0". In design mode, right clicking on a field object and choosing properties will bring the field objects properties sheet. In the first tab, Settings, you will find the name of the field object and the underlying table field it is bound to. Again, be aware that the names do not always match. When accessing a field object with Xbasic, you use the field objects name, not the physical table field name.

** insert graphic - show a fields properties sheet


A field object on a form has certain properties and methods. An object's properties are built-in variables, holding data about the object, while an object's methods are built-in functions that primarily work upon the object. If you open a form in design mode, right clicking on a field object and selecting actions will open the Action Scripting editor. Here you will have access to the Xbasic Explorer which will allow you to view a field objects methods and properties.



When using Xbasic to reference data via a form, we are actually referencing a field objects properties. The two field object properties that we will be concerned with are the value and text properties. It is important to understand the differences between these two properties. A field object's value property mirrors the actual data in the underlying table field. If the field object is bound to a numerical field, this means that the value property will be numerical. If the field object is bound to a text field, the value property will be a text value. The text property of a field object will always be a text value, regardless of whether it is bound to a numerical, date, logical, or character field. However, the value property will reflect the type of the underlying field.

The text property is how this data is displayed to the user. As pointed out above, these two values can be entirely different. (Radio, list, and check box field objects are somewhat different in that these type of field objects have additional properties to control the user display.)



Assuming a form is open and a button on the form is pushed to play an Xbasic script. The form has a field object bound to a numerical field. Assume the name of the field object is NumberField. The following line of Xbasic would place the value of the field in a variable named 'vNumValue'.

vNumValue = parentform:NumberField.value

(Parentform is an alias that references the parent form of the button. It is better to use an alias rather than the actual name of the form as there could be several instances of the same form opened. If this is the case, Alpha Five gives each instance of the form a distinct name which will be the name of the form followed by a number that is incremented for each instance of the form, i.e.: FormName, FormName0, FormName1, FormName1, etc.)

In the above line of Xbasic, Alpha Five creates the variable, vNumValue, as numerical in type because the NumberField's value property is numerical. Consider the following line of Xbasic:

vTextValue = parentform:NumberField.text

In this case vTextValue is created as a text variable and will contain a textual representation of the numerical value in the field. It is important to understand the distinctions between a field objects text and value properties. In your work with Xbasic you will often need to manipulate both text and numerical values, but, of course, you can not mix types. 5 x "102 East Main" will get you nowhere.
[PRINTER FRIENDLY VERSION]