UserGuide

Desktop Text Field

From Xojo Documentation

Text Field Library Icon

Text Fields display text in a single-line text entry field, such as the To: field in your Mail client. In contrast, the Text Area control is a multi-line field that displays text similarly to a text editor or word processor.

The Text Field supports the Edit menu’s Cut, Copy, and Paste menu items and keyboard shortcuts automatically. This functionality is built into the default Desktop Application project. If you rename or otherwise modify the Cut, Copy, and Paste menu items, you can disable automatic functionality.

Text Fields also have built-in support for textual drag and drop.

You can specify a mask for a Text Field which filters data entry on a character-by-character basis. For example, if you are using a Text Field for a telephone number entry area, you can specify that only numbers can be entered and you can restrict the entry to the correct number of characters.

Text Field Mac
Text Field Linux

Refer to TextField in Language Reference Guide details on all its events, properties and methods.

Text Field Windows

Below are the commonly used events, properties and methods.

Events

KeyDown - Called when a key is pressed while the Text Field has focus. The key that was typed is available as a parameter.

SelChange - Called when the selected text changes. Refer to UserGuide:Text Selection.

TextChange - Called when the text was changed, either by typing or through code (by setting the Value property).

ValidationError - Called when something is typed that does not match the ValidationMask property settings (if a ValidationMask is applied).

Properties

TextAlignment - Lets you specify if the text should be left, center or right aligned. Use with the TextAlignments enumeration to set and test the alignment.

Hint - Enables you to specify a prompt text string that suggests a data entry value. A user can enter the hint themselves or enter another value. It does not serve as a default value.

Format - Specifies the format string that is used to format the text when the TextField loses focus.

ValidationMask - Specifies a mask that can be used to validate user input. If the user types a character that does not match the mask, the ValidationFailed event handler is called. Refer to the Format method for a list of mask characters.

MaximumCharactersAllowed - Specifies the maximum number of characters that can be entered in the TextField.

Password - When set to True, the Text Field behaves as a password Field.

ReadOnly - Indicates if the Text Field is read-only. The user cannot type into a read-only Text Field, but copying the text works.

SelectionLength, SelectionStart, SelectedText - Used to specify and set selected text in the TextField. Refer to UserGuide:Text Selection.

Value - Used to get or set the value of the TextField.

Methods

CharacterPosition, InsertionPosition, LineNumber - These methods are used to determine character positions based on various values such as the line number or mouse coordinates.

Copy, Paste, SelectAll - Used to copy the text to the clipboard, paste text from the clipboard or select all text in the TextField.

Password Field

A Password Field is a subclass of TextField that has the Password property set to ON in the Inspector. For privacy, text typed in the field is replaced with bullet characters and Copy is disabled. Because Password Field is a subclass of Text Field it shares the same events, properties and methods.

Handling Focus

TextFields on any platform display the focus by showing a blinking insertion point and accepting text entry. The behavior of the TextField when the Tab key is pressed is controlled by the AllowTabs property. If this property is False, pressing the Tab causes the TextField to lose the focus and the next control in the entry order gains the focus. If AllowTabs is True, the TextField accepts the Tab character for data entry, just as any text character. The TextField keeps the focus. By default, AllowTabs is False.

Usage

To clear the text in a TextField set it's Text property to the empty string:

TextField1.Value = ""

You can apply a mask to the field to limit what the user can type into it by using the special characters described for the Format method. For example, this code restricts a TextField to only allow text entry up to 5 numbers:

TextField1.ValidationMask = "#####"

See Also

UserGuide:Text Selection, UserGuide:Desktop Text Area, UserGuide:Desktop Drag and Drop topics; TextField class