API reference
Class Widget
Namespace: MicroEngine.UI
Assembly: MicroEngine.UI.dll
Guide: UI widgets
One element of a user interface, laid out in UI units in the UI view (window pixels divided by the presentation’s UI scale) by its UiRoot: it says how large it wants to be (Measure), is given its Bounds (Arrange) and draws itself there (Draw). Focusable widgets take the focus, act on the engine’s actions while they have it and on the pointer. Derive from it for a widget of a game’s own.
public abstract class WidgetInheritance
Derived
Button, Grid, Label, Layer, Panel, ScrollView, Stack, TextField
Constructors
Widget()
protected Widget()Properties
BlocksPointer
Whether a press on the widget itself, where no child is, belongs to the UI (true by default). A Layer says false: its empty areas let the pointer through to gameplay.
public virtual bool BlocksPointer { get; }Property Value
Bounds
Where the widget was placed by the last layout, in UI units.
public RectF Bounds { get; }Property Value
Children
The widgets this one contains, in focus and drawing order.
public virtual IReadOnlyList<Widget> Children { get; }Property Value
ClipsChildren
Whether the widget restricts its children to its Bounds (false by default): what they draw outside is cut, and the pointer outside reaches them neither. A scrolling container does.
public virtual bool ClipsChildren { get; }Property Value
Enabled
Whether the widget and its children accept the focus, the pointer and actions (true by default); disabled widgets draw muted.
public bool Enabled { get; set; }Property Value
Focusable
Whether the widget can take the focus (false by default; buttons and text fields can).
public virtual bool Focusable { get; }Property Value
Height
A fixed height in UI units; null (the default) is the height the widget measures.
public float? Height { get; set; }Property Value
InterceptsDrag
Whether the widget takes a press that started on one of its children once the pointer moves further than a few units (false by default). The child’s press is then cancelled and the widget receives OnPointerDown at the press’s start and the moves that follow: a scrolling container dragged by a finger that landed on a button. A press on the widget itself, where no child takes it, is the widget’s from the start.
protected virtual bool InterceptsDrag { get; }Property Value
IsEnabledInTree
Whether this widget and every widget containing it are enabled.
public bool IsEnabledInTree { get; }Property Value
IsFocused
Whether the widget has its root’s focus.
public bool IsFocused { get; }Property Value
IsHovered
Whether the pointer is over the widget.
public bool IsHovered { get; }Property Value
IsPressed
Whether a pointer press that started on the widget is held.
public bool IsPressed { get; }Property Value
IsVisibleInTree
Whether this widget and every widget containing it are visible.
public bool IsVisibleInTree { get; }Property Value
Offset
A shift from where the layout places the widget, in UI units (zero by default). The widget and everything in it move, for drawing and for the pointer; the space it takes in its container does not. Animate it to slide a widget in.
public Vector2 Offset { get; set; }Property Value
Opacity
How opaque the widget and everything in it draw, 0..1 (1 by default); it multiplies the opacity of the widgets around it. Animate it to fade a widget. A transparent widget is still laid out and reached by the pointer.
public float Opacity { get; set; }Property Value
Parent
The widget that contains this one, or null for a root’s content or a widget not placed yet.
public Widget? Parent { get; }Property Value
Root
The root the widget is shown by, or null while it is not part of one.
public UiRoot? Root { get; }Property Value
Visible
Whether the widget and its children are drawn, laid out and reachable (true by default).
public bool Visible { get; set; }Property Value
Width
A fixed width in UI units; null (the default) is the width the widget measures.
public float? Width { get; set; }Property Value
Methods
Adopt(Widget)
Makes child a child of this widget (containers call it when a child is added).
protected void Adopt(Widget child)Parameters
child Widget
Exceptions
The child already belongs to another widget or root.
Arrange(RectF, UiContext)
Places the widget at bounds (UI units) and its children within it.
public void Arrange(RectF bounds, UiContext context)Parameters
bounds RectF
context UiContext
ArrangeContent(RectF, UiContext)
Places the children within bounds; nothing by default.
protected virtual void ArrangeContent(RectF bounds, UiContext context)Parameters
bounds RectF
context UiContext
Draw(IRenderer, UiContext)
Draws the widget in its Bounds; nothing while invisible.
public void Draw(IRenderer renderer, UiContext context)Parameters
renderer IRenderer
context UiContext
DrawContent(IRenderer, UiContext)
Draws the widget in Bounds, and its children.
protected abstract 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 virtual void HashState(StateHasher hash)Parameters
hash StateHasher
Measure(UiContext)
The size the widget wants, in UI units: Width and Height when set, else what it measures; zero while invisible.
public Vector2 Measure(UiContext context)Parameters
context UiContext
Returns
MeasureContent(UiContext)
The size the widget’s content needs, in UI units.
protected abstract 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 virtual bool OnAction(UiAction action)Parameters
action UiAction
Returns
OnClick()
Called when a pointer press that started on the widget is released on it, after OnPointerUp.
protected virtual void OnClick()OnFocusChanged(bool)
Called when the widget gains (true) or loses (false) the focus.
protected virtual 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 virtual 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 virtual 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 virtual 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 virtual void OnPointerUp(Vector2 position)Parameters
position Vector2
OnWheel(Vector2)
Called for the wheel over the widget (delta in notches: y positive away from the player, x positive
to the right). Return true when the widget used it; otherwise its container is asked, up to the root.
protected virtual bool OnWheel(Vector2 delta)Parameters
delta Vector2
Returns
Release(Widget)
Detaches child from this widget (containers call it when a child is removed).
protected void Release(Widget child)Parameters
child Widget
Update(float)
Called once per update of the root, before actions are read.
protected virtual void Update(float dt)Parameters
dt float