WillChangeField Event

True DataControl 8.0 Reference> True DataControl Control> TData Control Events> WillChangeField Event

Occurs before a field value changes.

Syntax

TData_WillChangeField (ByVal cFields As Long, ByVal Fields As Variant, NewValues As Variant, adStatus As EventStatusEnum)

Remarks

Arguments: cFields is the number of fields that are about to change. In True DataControl version 8.0, this is always one, but we recommend you not make this assumption. It is better to write general code that can accommodate changing several fields at once.

Fields is an array of ADO Field objects, items of the Recordset.Fields collection. In True DataControl version 8.0, it always contains one element, Fields(0). Fields(0).Name is the name of the field that is about to change.

NewValues is an array of values that are about to be assigned to the fields. It has the same dimension as the Fields array, that is, in True DataControl version 8.0, it always has one element, NewValues(0). Your code in this event is allowed to not only validate, but also modify the values in NewValues, thus changing the value entered by the user (for example, convert it to uppercase).

adStatus is an ADO EventStatusEnum value, with two possible values: adStatusOK and adStatusCancel. You should set the adStatus argument to adStatusCancel to reject new field values.

The WillChangeField event occurs when a new value is assigned to a TData field as a result of code execution or end-user interaction with a bound control. You can use this event to impose complex field validation rules that cannot be specified as field constraint expressions, see Validation and Constraints. You can also use this event to modify the values entered by the user.

The event is similar to the standard ADO WillChangeField event, but it has an additional argument, NewValues. The standard ADO event is quite useless, because one always needs to know the values that are about to be assigned to fields.

When this event fires, adStatus is adStatusOK, indicating that the new field values are valid. Your event handler should examine the NewValues array to determine whether the new values meet your acceptance criteria. If they do not, you should take an appropriate action (such as displaying an error message) and set the adStatus argument to adStatusCancel. This prevents the field change. If you permit the change, you can also adjust the value, modify it according to some formatting or other rules, for example, convert it to uppercase.

For more information, see Validation and Constraints and Modifying Field Values Retrieving and Saving Them in the Data Source.