API reference

Namespace MicroEngine.UI

Widgets: labels, buttons, panels, stacks, text fields, dialogue boxes, menus, typewriter text, toasts, themes, focus and the UI input layer.

Guide: UI widgets

Classes

Button

A button: confirm while it has the focus, or a click (a press and release of the pointer on it), raises Clicked. It takes the focus.

Grid

Children in rows of Columns equal cells, left to right then top to bottom: an inventory, a level select, a character roster, a keyboard on screen. Every cell is as large as the largest child; hidden children take no cell. Focus moves between cells by direction, as it does anywhere in the tree.

Label

Text that does nothing: a heading, a value, a hint, a line of dialogue. Lines are separated by \n; with Wrap and a fixed Width the text also breaks between words to fit. Set VisibleCharacters to reveal it a little at a time: the lines stay where the whole text puts them.

Layer

The whole UI view, with each child placed on its own: against an edge or a corner (a banner in a corner, a HUD block), or at a point (a speech bubble over a character, a damage number, a marker that follows something in the world). Children keep the size they measure; later children draw over earlier ones. Where no child is, the pointer passes through to gameplay. Use it as a root’s Content.

Panel

A box behind one child, with padding around it: the frame of a menu, a dialog or a HUD block.

PromptGlyphStyle

Colours of prompt glyphs (PromptText): key caps, gamepad buttons and touch controls.

PromptText

Draws text with action prompts as glyphs: “Press {attack} to swing” shows a key cap with Z on a keyboard, a green A on an Xbox pad, a × button on a PlayStation pad and the touch button’s label in a ring on a phone. Text that does not name an action is drawn as with Draw. Glyphs are as tall as a line of the font.

ScrollView

A window onto content longer than the space it has: a long menu, a list of saves, an achievement list, the credits. Give it a fixed Height (or Width when Orientation is horizontal); its content keeps the size it measures and is cut at the view’s edges. It scrolls to show a widget inside it when that widget takes the focus, with the wheel over it, and with a drag, also one that starts on a button inside it (a finger on a phone). A thin bar on its edge shows where the window is.

Stack

Children placed one after another, top to bottom or left to right, with a space between them: menus, rows of buttons, forms.

TextField

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.

UiActions

The actions engine widgets answer to. A member left null (the default) is the input map’s own name for it (Names), read at every update: a game that renames confirm with ActionNames keeps working widgets, and a gameplay action that happens to be called confirm never presses a button. Set a member to give the widgets an action of the game’s own.

UiRoot

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).

UiTheme

Visual theme for the shared widgets so each game can keep its own identity.

Widget

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.