Textbox events and functions¶
Contents
Textbox functions are called as follows:
func_id(event_code, box_id [ , subscript, row])
The subscript is applicable to textboxes whose linked field is dimensioned. It indicates the element of the field which is displayed in the textbox. This may exceed the row number.
The row is applicable to textboxes with a rows = clause and|or a height = clause. It indicates the row which has focus, with the top box being 1. The textbox row number always wraps and so can never exceed the number of rows specified in the rows = clause. The row and subscript are often the same number.
Event function¶
event = func_id
The name of the function to be called when an event occurs for the textbox.
The events which cause the function to be called are:
EV_CREATE |
The textbox has just been created. |
EV_DESTROY |
The textbox has just been destroyed. |
EV_GAIN_FOCUS |
The textbox has gained focus. |
EV_LOSE_FOCUS |
The textbox has lost focus. |
The user has moved the mouse over the textbox during a dialog. |
|
The user has clicked down or released the right mouse button over the textbox. If EV_RIGHT_MOUSE_UP is not trapped, releasing the right mouse button over a textbox causes the Windows default menu to appear, with options to Undo, Cut, Copy, Paste, Delete and Select All. |
|
A keystroke is typed while the textbox has focus. |
|
EV_CHANGE 1 |
The data in the textbox has changed. The event is generated each time the user types a character into the textbox. The value of sys.InputBuf is updated before the event is sent. Pressing a cursor movement key does not generate EV_CHANGE. |
- 1(1,2,3,4,5)
These events are not generated by default; they must always be specifically requested for the textbox by means of the event_enable = clause, e.g.
event_enable = EV_DEFAULT | EV_RIGHT_MOUSE
New events may be added in the future. See Event functions.
Help function¶
help = func_id
The textbox help function. The function is called as follows
func_id(EV_HELP, box_id [ , subscript, row])
See Help functions.
Validation function¶
validate = func_id
Specifies the name of a function to be called when the user changes the contents of the textbox by means of the input or dialog commands. This enables more complex and sophisticated validation than is possible by the use of a field validation list. Automatic validation is always performed before the function is called. See Data validation.
If the Sculptor system variable sys.AutoValidate is ON, the input and dialog commands call the validate function when the textbox loses focus, whether the contents of the box have changed or not. The default is for sys.AutoValidate to be OFF.
The validate function is called before the general event function is called with event code EV_LOSE_FOCUS.
The function is called as follows:
func_id(EV_VALIDATE, box_id [ , subscript, row])
Validation functions may return one of several values, as follows:
OKAY |
Data valid - continue normally. |
ERROR |
Data invalid - the textbox is locked in focus. The data must be re-entered. |
CLOSE_DIALOG |
Terminate input, or close the dialog. |
CANCEL_DIALOG |
Abort input, or cancel the dialog. |
control_id |
The name of the control to receive focus next. The control must be in the dialog window or input list. |
See input and dialog for full details of the way in which validation functions and return values work with these two commands.
Default: No function.
See Event functions.
EXAMPLE
validate = ValData
Event enable function¶
event_enable = flags
This clause is used to select the event codes which are to be enabled for the textbox.
Default: The standard set of events listed under the event = clause above.
RELATED TOPICS |