Text Gadgets

Software Customisation Guide

Gadget Set : Text Gadgets

A text gadget is a box that can display a value and into which the user may type a value, or edit an existing value.

To type into a text gadget on a form it must have the keyboard focus to receive the keystrokes typed by the user. The user can move the focus to another text gadget by selecting it with the mouse or stepping from one gadget to the next using the TAB key.

text .number AT . . . width 10 is REAL

text .name 'Name:' callback '!!MyFunction' width 10 scroll 100 is STRING 

text .active 'Active:' callback '!!MyFunction' width 10 is BOOLEAN

text .bore 'Bore:' width 10  is BORE  format !!FormatBore

text .password 'Password:' AT . . . width 10 NOECHO is STRING

The user must:

•

Specify the WIDTH, which determines the maximum number of character spaces visible. Optionally the user may specify a larger SCROLL width, which is the maximum number of characters that the gadget can hold, and scroll through. The default scroll-width is 132 characters. The maximum is 256 characters.

•

Specify a data type using IS which determines how a value assigned to the gadget will be displayed and how a value typed by the user will be interpreted by their PML code. The user may also supply a FORMAT object which specifies in detail how a value is to be displayed or interpreted (see below).

The user may optionally

•

Specify a tag name to be displayed to the left of the gadget.

•

Specify a callback command.

•

Specify a position on the form.

•

Specify a NOECHO keyword that indicates any characters typed should be displayed as stars: a typical use would be a gadget for the user to enter a password.

•

Give the text gadget an initial value, which will be the value accessed by their PML code if it is not modified by the user. To set an initial value for a text input gadget, use its .val member:

This.name.val = 'PIPE-1'

•

Specify whether the text displayed is editable interactively or is read only.

‘Tabbing’ to a text field highlights the contents for immediate over-typing. Once the user has focus and types into the field it becomes 'modified'. Once modified, the field's contents is 'actioned', whenever it loses focus. This happens when the user ‘Tab’ away, or click another gadget or form, or press the 'ENTER' key.

When a field is actioned its content is read and validated according to the field’s type (see Validating Input to Text Fields). If an error is detected, then the field’s background colour changes to gold to indicate an error and focus is returned to it so that the user can correct the error. If no error was detected, the SELECT event is fired for the text field and the field's callback (if any) is executed.

An attempt to dismiss the form with error highlights, will cause an alert followed by returning the focus to an erroneous field.

To get the current value of a text input gadget:

!Value = !This.name.val

The data type of the variable !Value will be the same as the type of the text gadget. To get the textual value use:

!string = !Value.String()

To set the keyboard focus so that keystrokes come to this gadget:

!This.name.SetFocus()