Xojo Documentation 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, InsertionPoint, 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 Text Field 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 AcceptTabs 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 AcceptTabs is True, the TextField accepts the Tab character for data entry, just as any text character. The TextField keeps the focus. By default, AcceptTabs 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