Textbox events and functions

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.

EV_MOUSE_OVER 1

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.

EV_KEYSTROKE 1

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.

See The event_enable clause.


RELATED TOPICS

Textboxes

Event functions