GUIBaseContext :: doValidateControl - Handler for validate control event
The handler handles the GEV_Validate GUI event. The event is fired for a control when receiving the focus ( GEV_FocusOut ). In this case, the event is also generated for all parent controls in the control hierarchy. The event is also generated, when filling a control with data (together with the DEV_Filled event) or when changing data in a control ( DEV_Stored ).
When changing data in a control, the handler is also called for its parent control, which allows changing control states in a form depending on value settings in subordinated controls.
The handler is typically used for enablind and disabling or hiding and showing controls depending on the content read into the control. Data is already available and can be provided by calling the currentProperty() or property() function.
The handler should return one of the following return codes:
- -1 (not handled) - the event handler will be removed from the handler list and is not called anymore.
- 1 (error) - Returning an error has no effect for the event.
- 0 (ok) - Event handler terminated successfully.
Since the handler is called frequently, one should try to optimize the handler function, e.g. by setting states that allow to decide, whether the handler has to do something or not. The handler may also be called when data source is not yet opened. In order to avoid exceptions, one should call hasData() before calling property() .