TextBox Class

A text box control, sometimes called an edit field or edit control, can display information entered in the JADE development environment, entered by the user, or assigned to the control by logic at run time.

As the TextBox class is a subclass of the Control class, it inherits all of the properties and methods defined in the Control and Window classes. The TextBox class provides the WebHTML subclass.

The TextBox class validates the setting and entry of text based on the dataType property value, using the current locale of the client with regional overrides on both the presentation client and the application server when the EnhancedLocaleSupport parameter in the [JadeEnvironment] section of the JADE initialization file is set to true.

By setting appropriate property values, the text box control can:

Be a single-line data entry text box
Be a multiple-line data entry text box
Allow the word wrap feature (implied when the scrollHorizontal property is set to false)
Allow scrolling of the text both horizontally and vertically

For details about the support of mouse wheel requests to scroll up, down, or across a text box control, see "Window Class", earlier in this document.
Align the text left, right, or centrally
Be a password entry text box, where the characters entered are displayed as asterisk (*) characters
Be declared as a numeric text box, preventing the entry of invalid characters or non-numeric characters
Automatically convert the case of the entered characters
Be a read-only display text box
Offset the left and right margins, to improve the appearance of the displayed text

Use the firstChange event to move logic from other key events when that logic is relevant only to the first time the text changes. (This reduces the number of events that must be sent and processed for each key that is pressed.)

The text box is always created as a multiple line text box, unless the passwordField property is set to true. In a text box, CrLf and Lf are recognized as end-of-line sequences.

The text box functions as a single-line text box when:

The height of the text box leaves room only for one line of text to be displayed and the scrollVertical property is set to false
The dataType property is set to that of a numeric text box

Control the functionality of the text box as a multiple-line control by setting the scrollHorizontal, scrollVertical, and scrollBars properties. If the scrollHorizontal property is set to true, word wrapping does not occur, and each line must be terminated by the Enter key. If the scrollVertical property is set to false, the entry of text is limited to the number of visible text lines.

The text box does not receive tab characters from Windows unless the text box is the only enabled visible control that has the tabStop property set, as the tab functions is interpreted by Windows as a skip to the next text box. If there is no other text box to tab to, the character is passed to the text box. Use Ctrl+Tab to enter a tab when the tab is interpreted as a control skip.

By default, the text box does not respond to the Enter key if an enabled and visible default button is defined on the same form. Use the TextBox class wantReturn property to make the text box respond to the Enter key.

If the text box is defined as numeric data type, the text cannot be set to a value that is an invalid numeric (according to the dataType, decimals, and maxLength properties). Additionally, as each character is entered, the character is rejected with a beep if the resulting text would result in an invalid number (including the deletion of a character).

If the case property is set to Case_UpperFirst (3) or Case_LowerFirst (4), the text box control accepts only an alphabetic character as the first character entered in the text box and automatically changes the case of the entered character to the required type, if applicable. If the case property is set to any value other than the default value of Case_None (0), the dataType property is set to the default value of DataType_AlphaNumeric (0) and the decimals property is set to zero (0); that is, no exception is raised.

You can specify hint text and colors for a text box; for example, text that can be displayed when the text property is empty, to advise the user what data is required. The TextBox control provides the properties listed in the following table.

Property	Value	Default	Description
hintText	String	An empty string	Text that is displayed in an empty text box as a hint
hintBackColor	Integer	#80000000	Background color of hint text
hintForeColor	Integer	#80000000	Color of the hint text

If the value of the hintText property is:

Empty, these properties have no impact on the text box display
Not empty, the specified hint text is displayed in the text box when the value of the text property is empty

When the value of the hintText property is displayed, the:

text and selText properties return an empty string
Text cannot be selected or deleted, and the cursor is always positioned at the beginning of the text

As soon as text is entered or pasted into the text box, the hint text is removed and replaced with the specified or pasted text. If the entire text is removed, the hint text is displayed again.

When hint text is displayed, the:

Back ground of the text box is drawn using the value of the hintBackColor property except when it is #80000000, in which case the TextBox control backColor property value is used.
Text of the text box is drawn using the value of the hintForeColor property except when it is #80000000, in which case the TextBox control foreColor property value is used.

The values of the dataType, case, and selectionStyle properties are ignored when the hint text is displayed; for example, hint text can be displayed for a numeric field. The hint text, which is always displayed in the case of its defined string, can never be selected. In addition, for a password text box, the hint text is displayed as clear text (that is, it is not displayed using asterisk (*) characters).

When the value of the hintBackColor or hintForeColor property is #80000000, the value of the respective hintBackColor or hintForeColor property in the JADE Painter Properties dialog is displayed as Use backColor Value or Use foreColor Value, with an image at the left of the text displaying the current value of the respective backColor or foreColor property. The combo box drop‑down list of colors includes an entry for Use backColor Value or Use foreColor Value that sets the property value to the default.

If the values of the hintBackColor and hintForeColor properties are both zero (0), the default values of #80000000 (that is, transparent) are used instead.

A text box automatically handles the clipboard copy, cut, and paste key sequences (that is, Ctrl+Insert, Ctrl+C, Ctrl+Delete, Ctrl+X, and Shift+Insert).

If text is pasted into or cut from a text box and the resulting text is no longer valid according to the automatic validation rules, the text in the text box is cleared; for example, when pasting non‑numeric text into a numeric text box. This ensures that JADE logic can always assume the resulting text complies with the validation rules. This situation occurs only with paste or cut operations that involve numeric text boxes and when the first character must be alphabetic (case property). When data is entered from the keyboard, the validation rules are applied, and the entered character is ignored (with a beep) if the resulting text would be invalid.

When text with trailing carriage return and line feed characters (the CrLf end-of-line sequence) is pasted after the current text of a text box, the CrLf characters are removed if the:

Resulting text would be invalid (for example, pasting '1234' followed by a CrLf character into a numeric text box results in '1234' only being pasted)
Text box has the scrollVertical property set to false and the CrLf characters would cause the number of lines of text to exceed the height of the available area in the text box (for example, pasting 'No' followed by a CrLf character into a single-line text box with the scrollVertical property set to false results in 'No' being pasted)

To implement the handling of a TextBox control to achieve the same functionality as the default Table class InputType_TextBox value, only the following is required.

In the change event for the text box:
```
table1.text := textbox1.text
```
In the cellInputReady event for the table:
```
textbox1.text := table1.text
```

You can use the Windows key + period (.) function keys combination to paste a selected emoji or selection of emojis from the emoji selection window into TextBox controls in a Unicode JADE system. For details, see "Unicode Surrogate Pair Characters, including Emojis", in Chapter 1 of the JADE Developer's Reference.

Pastes a selected emoji or selection of emojis from the emoji selection window into TextBox controls or the editor pane in a Unicode JADE system. For more details, see "Unicode Surrogate Pair Characters, including Emojis", in Chapter 1 of the JADE Developer's Reference.

For more details, see the Table class inputType and cellControl properties. See also the Control class automaticCellControl property and "Value Round Trips through TextBox Controls", elsewhere in this document. For a summary of the constants, properties, methods, and events defined in the TextBox class, see "TextBox Class Constants", "TextBox Properties", "TextBox Methods", and "TextBox Events", in the following subsections.