TextBox
The TextBox control allows users to enter a string. It supports highlighting, copy/paste, selection with mouse and keyboard, and CTRL key for performing operations on entire words.
Code Example: Creating a TextBox
The following code creates a TextBox.
Typing
TextBox supports reading characters from the keyboard. It supports:
Regular character typing - inserts a character the the caret position (
CaretIndex
)Backspace - removes a character at the index before the caret
Delete - removes a character at the caret index
Enter (if multi-line) - inserts the newline character (
'\n'
)Keyboard repeat rate - if a key is held, the repeat rate applies according to the OS settings
CTRL X, C, and V for cut, copy, and paste
The TextBox respects the OS-level repat rate. For example, the following animation shows the TextBox responding to the Windows Key repeat rate.
PreviewTextInput
The PreviewTextInput
event is raised whenever text is added to a text box. This includes regular typing and also pasting. This method can be used to react to text before it has been added to the TextBox.
The event includes arguments with a Handled
property. Setting this to true prevents the Text from being added to the TextBox
. The argument's Text
property contains the newly-added text. Keep in mind this can be a longer string if the user has pasted text, so you may need to check all letters rather than only the first.
For example, the following code shows how to only allow numbers in a TextBox:
IsReadOnly
If IsReadOnly
is set to true, then the user cannot modify a TextBox
's Text
. Setting IsReadOnly
to true results in the following TextBox behavior:
Text cannot be changed by typing, pasting, cutting, or deleting text with the keyboard
Text can be selected with the mouse or with key combinations (shift + arrow key)
Text can be copied
The TextBox can receive focus
The Caret is optionally visible depending on whether
IsCaretVisibleWhenReadOnly
is set to true. By defaultIsCaretVisibleWhenReadOnly
is false.
The following code shows how to create a read-only TextBox:
Selection
Selection can be performed programmatically or by the user using the cursor.
The SelectionLength
property can be used to determine if any text is selected. The following code shows how to output the selected characters:
The SelectionStart
and SelectionLength
properties can be modified to change the visual selection. For example, the following selects the first 5 letters:
The entire text can be selected as shown in the following code:
Selection can also be performed by the user. Double-clicking the text box selects all text. Also, pressing CTRL+A selects all text.
A push+drag with the mouse selects the text between the start and the current location of the drag.
Holding down the shift key and pressing the arrow keys adjusts the selection.
CaretIndex
CaretIndex
returns the index of the caret where 0 is before the first letter. This value is updated automatically when letters are typed, the caret is moved with arrow/home/end, and when the cursor is clicked and the cursor is moved.
The user can modify the CaretIndex
using the following actions:
Clicking in the text box places the caret at the nearest index to the click point
Typing text moves the caret to the right by one character
Pasting text moves the caret to the end of the pasted text
Left arrow and right arrow on the keyboard moves the caret to the left or right by one index
CTRL + left arrow and CTRL + right arrow move the caret to the left or right by one word
Home key moves the caret to the beginning of the line
End key moves the caret to the end of the line
CaretIndex
can be explicitly set in code to move the caret position.
When CaretIndex
changes the CaretIndexChanged
event is raised.
The following code shows how to display the CaretIndex in a label:
TextWrapping
The TextWrapping
property can be used to set whether the TextBox wraps text. By default this value is set to TextWrapping.NoWrap
which means the text does not wrap, but instead extends horizontally.
If TextWrapping
is set to TextWrapping.Wrap
, then text wraps to multiple lines. Note that usually this is combined with a taller text box so that multiple lines display properly.
Extended Character Sets and Keyboards
Characters must be available in the current font to support being written in TextBoxes. If you would like to support more characters, you can explicitly create a font (.fnt) including the desired characters, or change the default character set in Gum.
Last updated
Was this helpful?