API reference
Class UiRoot
Namespace: MicroEngine.UI
Assembly: MicroEngine.UI.dll
Guide: UI widgets
Shows one widget tree in the UI view and drives it: lays Content out in UI units at
Anchor, keeps the focus, moves it with the engine’s direction actions, gives the focused widget confirm
and cancel, and, as the highest input layer (UI), takes pointer presses that land on
the content and, while a text field has the focus, the keyboard. What it takes never reaches gameplay: a press on a
button is not a press in the world, and the actions it acts on are consumed (Consume), so the
scene’s update, which runs after the root’s, does not see them. A scene has one in Scene.Widgets, which the engine
updates, draws and routes input to; a root can also be driven by hand (Update, Draw,
Handle).
public sealed class UiRoot : IInputLayer, IStateHashedInheritance
Implements
Constructors
UiRoot(InputMap, TextInput?)
A root reading actions from input and typed text from text (null: text fields cannot be typed in).
public UiRoot(InputMap input, TextInput? text = null)Parameters
input InputMap
text TextInput?
Properties
Actions
The actions the widgets answer to (Default: the input map’s names).
public UiActions Actions { get; set; }Property Value
AllWidgets
The visible widgets of the content in focus and drawing order (depth first).
public IEnumerable<Widget> AllWidgets { get; }Property Value
Anchor
The point of the UI view the content is placed at (Center by default).
public Anchor Anchor { get; set; }Property Value
AutoFocus
Whether the first focusable widget takes the focus when nothing has it, so a keyboard or a gamepad can use the UI at once (true by default).
public bool AutoFocus { get; set; }Property Value
Clipboard
The clipboard text fields copy, cut and paste through (Ctrl or Command with C, X and V); null: they cannot. A scene’s widgets get the platform’s (IClipboard).
public IClipboard? Clipboard { get; set; }Property Value
Content
The widget tree shown; setting it drops the focus, the hover and any press.
public Widget? Content { get; set; }Property Value
Exceptions
The widget already belongs to another widget or root.
Focused
The widget with the focus, or null.
public Widget? Focused { get; }Property Value
Font
The font widgets measure and draw text with. The engine sets the game’s font; it must be set before drawing.
public IFont? Font { get; set; }Property Value
Hovered
The widget under the pointer, or null.
public Widget? Hovered { get; }Property Value
Offset
Moves the content from its anchor, in UI units.
public Vector2 Offset { get; set; }Property Value
PointerToUi
Maps a pointer event’s position (virtual canvas pixels, Position) into UI units. The engine sets it to the game’s view mapping; the identity by default (UI units are canvas pixels).
public Func<Vector2, Vector2> PointerToUi { get; set; }Property Value
Pressed
The widget a held pointer press started on, or null.
public Widget? Pressed { get; }Property Value
Size
The size of the UI view in UI units: set by every Draw from the renderer’s size, and by the engine before each update.
public Vector2 Size { get; set; }Property Value
TextInput
The text channel text fields type through, or null.
public TextInput? TextInput { get; }Property Value
Theme
The colours (Default by default).
public UiTheme Theme { get; set; }Property Value
Time
Seconds the root has been updated.
public float Time { get; }Property Value
UiToCanvas
Maps a UI position into virtual canvas pixels, for the caret an input method shows its candidates by; the identity by default.
public Func<Vector2, Vector2> UiToCanvas { get; set; }Property Value
WrapFocus
Whether moving the focus past the last widget in a direction continues from the other side (true by default).
public bool WrapFocus { get; set; }Property Value
Methods
Contains(Vector2)
Whether uiPoint (UI units) lies on a widget of the content that takes the pointer (BlocksPointer): there the root takes presses and the wheel.
public bool Contains(Vector2 uiPoint)Parameters
uiPoint Vector2
Returns
Draw(IRenderer)
Lays the content out for ui’s size (UI units) and draws it there.
public void Draw(IRenderer ui)Parameters
ui IRenderer
Exceptions
Font is not set.
Focus(Widget?)
Gives widget the focus (null removes it); false when it cannot take it (not focusable, disabled, hidden or not in this root).
public bool Focus(Widget? widget)Parameters
widget Widget?
Returns
Handle(in InputEvent)
Takes an event as the UI’s input layer (see IInputLayer): a pointer press on the content, everything of a press it took, the wheel over the content, and keys while a text field has the focus. Taken events are applied at the next Update. Pointer moves are watched (for the hover) but left to gameplay, and text goes to the text channel.
public bool Handle(in InputEvent e)Parameters
Returns
HashState(StateHasher)
Adds the focus and the widgets’ state (in tree order) to the scene’s state hash.
public void HashState(StateHasher hash)Parameters
hash StateHasher
Layout()
Measures the content and places it in the UI view (Size) at Anchor.
public void Layout()Exceptions
Font is not set.
MoveFocus(UiAction)
Moves the focus to the nearest focusable widget in direction (up, down, left or right) by the
widgets’ last layout; past the last one it continues from the other side when WrapFocus is on.
Returns whether the focus moved.
public bool MoveFocus(UiAction direction)Parameters
direction UiAction
Returns
Update(float)
Advances the UI by one update: lays it out, applies the pointer events and keys it took since the last update, updates the widgets, then gives the actions to the focused widget and to focus navigation, consuming those it acts on. The engine calls it before the scene’s own update.
public void Update(float dt)Parameters
dt float
WidgetAt(Vector2)
The deepest visible widget under uiPoint, or null; the last one drawn where several overlap.
Children of a widget that clips them (ClipsChildren) count only inside its bounds.
public Widget? WidgetAt(Vector2 uiPoint)Parameters
uiPoint Vector2
Returns
Cancelled
Raised when cancel is pressed and no focused widget used it; the press is then consumed (for example to close a menu).
public event Action? CancelledEvent Type
FocusChanged
Raised whenever the focus moves, by the arrows, a press, Focus or the first focus AutoFocus gives (whose From is null): for a cursor sound, or a description that follows the focus.
public event Action<FocusChange>? FocusChanged