API reference
Class TextField
Namespace: MicroEngine.UI
Assembly: MicroEngine.UI.dll
Guide: UI widgets
One line of editable text: a name, a seed, a chat message. While it has the focus it turns the input system’s text channel on (the on-screen keyboard on a phone, the input method’s candidates next to the caret), inserts what is typed at the caret, shows what an input method is still composing, and takes the keyboard from gameplay: Backspace, Delete, the arrows, Home and End edit, Enter submits, Escape leaves the field, Tab and the up and down keys move the focus. Shift with the arrows, Home or End selects, as does dragging the pointer across the text; Ctrl (Command on macOS) with A selects everything, and with C, X and V copies, cuts and pastes through the root’s Clipboard. A gamepad edits nothing but moves the caret with left and right and submits with confirm.
public sealed class TextField : WidgetInheritance
Inherited Members
Widget.Measure(UiContext), Widget.Arrange(RectF, UiContext), Widget.Draw(IRenderer, UiContext), Widget.Bounds, Widget.Visible, Widget.Enabled, Widget.Width, Widget.Height, Widget.Offset, Widget.Opacity, Widget.BlocksPointer, Widget.Parent, Widget.Root, Widget.Children, Widget.Focusable, Widget.ClipsChildren, Widget.IsFocused, Widget.IsHovered, Widget.IsPressed, Widget.IsEnabledInTree, Widget.IsVisibleInTree, object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()
Constructors
TextField()
public TextField()Properties
Caret
Where new text goes, as an index into Text; setting it ends any selection.
public int Caret { get; set; }Property Value
Columns
The width, in layout units, the field measures when Width is not set (96 by default).
public float Columns { get; set; }Property Value
Composition
The text an input method is composing and has not committed yet (empty when none); drawn underlined at the caret.
public string Composition { get; }Property Value
Focusable
Whether the widget can take the focus (false by default; buttons and text fields can).
public override bool Focusable { get; }Property Value
HasSelection
Whether any text is selected.
public bool HasSelection { get; }Property Value
MaxLength
The most characters (UTF-16 code units) the text may have (64 by default).
public int MaxLength { get; set; }Property Value
Exceptions
The value is not positive.
Placeholder
Shown in the muted colour while the field is empty and does not have the focus.
public string Placeholder { get; set; }Property Value
SelectedText
The selected text, or “” when none is.
public string SelectedText { get; }Property Value
SelectionLength
How many characters (UTF-16 code units) are selected; 0 when none are.
public int SelectionLength { get; }Property Value
SelectionStart
Where the selection starts, as an index into Text: the end opposite the caret.
public int SelectionStart { get; }Property Value
Text
The text; setting it cuts it to MaxLength, puts the caret at its end and ends any selection.
public string Text { get; set; }Property Value
Methods
Copy()
Puts the selected text on the root’s clipboard; false when nothing is selected or there is no clipboard.
public bool Copy()Returns
Cut()
Puts the selected text on the root’s clipboard and deletes it; false (and nothing deleted) when it could not copy.
public bool Cut()Returns
DrawContent(IRenderer, UiContext)
Draws the widget in Bounds, and its children.
protected override void DrawContent(IRenderer renderer, UiContext context)Parameters
renderer IRenderer
context UiContext
HashState(StateHasher)
Adds the widget’s state that decides what happens next (a text field’s text) to the scene’s state hash; nothing by default.
protected override void HashState(StateHasher hash)Parameters
hash StateHasher
Insert(string)
Inserts text at the caret, in place of the selection when there is one, as far as
MaxLength allows, and moves the caret after it.
public void Insert(string text)Parameters
text string
MeasureContent(UiContext)
The size the widget’s content needs, in UI units.
protected override Vector2 MeasureContent(UiContext context)Parameters
context UiContext
Returns
OnAction(UiAction)
Called for an action while the widget has the focus; return true when it acted, which consumes the action.
protected override bool OnAction(UiAction action)Parameters
action UiAction
Returns
OnFocusChanged(bool)
Called when the widget gains (true) or loses (false) the focus.
protected override void OnFocusChanged(bool focused)Parameters
focused bool
OnPointerCancel()
Called when a press the widget holds is cancelled (the system took the touch, the widget left the tree, a container took it as a drag); no release or click follows.
protected override void OnPointerCancel()OnPointerDown(Vector2)
Called when a pointer press starts on the widget (the focusable widget under the pointer, or its nearest focusable
container). position is in UI units, like Bounds. The widget then holds the press:
it receives the press’s moves and its release wherever the pointer goes.
protected override void OnPointerDown(Vector2 position)Parameters
position Vector2
OnPointerMove(Vector2)
Called when the pointer of a press the widget holds moves, inside the widget or not (dragging a slider’s handle); position is in UI units.
protected override void OnPointerMove(Vector2 position)Parameters
position Vector2
OnPointerUp(Vector2)
Called when a press the widget holds is released, inside the widget or not; position is in UI units. A release on the widget then also calls OnClick.
protected override void OnPointerUp(Vector2 position)Parameters
position Vector2
Paste()
Inserts the root’s clipboard text at the caret, in place of the selection, as one line (line breaks and tabs become spaces) cut to MaxLength; false when there is no clipboard or it holds no text.
public bool Paste()Returns
Select(int, int)
Selects the text between anchor and caret (indices into Text,
clamped to it); the caret goes to caret, so the selection grows from there.
public void Select(int anchor, int caret)Parameters
anchor int
caret int
SelectAll()
Selects the whole text, with the caret at its end.
public void SelectAll()Update(float)
Called once per update of the root, before actions are read.
protected override void Update(float dt)Parameters
dt float
Changed
Raised with the new text whenever it changes.
public event Action<string>? ChangedEvent Type
Submitted
Raised with the text when Enter or confirm submits it.
public event Action<string>? Submitted