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

You must:

• Specify the WIDTH, which determines the maximum number of character spaces visible. Optionally you 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 your PML code. You may also supply a FORMAT object which specifies in detail how a value is to be displayed or interpreted (see below).

You 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 your 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.

  When you type into a text gadget its background color changes from white to beige to indicate that has been modified. Its content is actioned when you press Enter while the text gadget has focus, or if you press a button on the form.

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 then the text gadget’s callback (if any) is executed

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()