Skip to content

Search

Documentation

ui module

Immediate-mode UI redrawn from a script's draw_ui every frame: panels, layout containers and widgets. HUD elements in the scene tree are the widget…

На тази страница

Immediate-mode UI redrawn from a script's draw_ui every frame: panels, layout containers and widgets. HUD elements in the scene tree are the widget component.

73 functions, 68 constants. Scripts reach it as ui::.

Functions

Argument kinds are the script values a call passes: node is a node handle, any a table or value of any kind, fn a callback.

function acts on what it does
activate_focused() — Activate the focused widget, exactly as a click on it would.
add_space(float) — Insert blank space along the current layout, in design pixels.
align_right(fn) — Lay the callback's widgets out against the right edge, still declared left to right.
available_height() -> float — The height left in the current container, in design pixels.
available_width() -> float — The width left in the current container, in design pixels.
bottom_panel(string, any?, fn) -> float — Dock a strip across the bottom of the window and draw the callback inside it; height is in design pixels. Answers the height it ended up with.
button(string, any?) -> bool — Draw a button, or a row with its caption at the start when text_align = "start"; true on the frame it was clicked. enabled = false greys it out and swallows the click. menu hangs a right-click menu off it, menu_click one that opens on a left click.
button_rect() -> any — Where the last button was drawn, as #{ x, y, width, height } in design pixels; empty before one has. An immediate control has no node widget_rect can be asked about, so a caller that wants to point at one reads it back here, straight after the call that drew it.
central_panel(any?, fn) — Draw the callback into whatever room the docked panels left over.
central_rect() -> float, float, float, float — The x, y, width and height of the surface being drawn into, in design pixels.
circle_button(string, any?) -> bool — Draw a round button holding one glyph, diameter design pixels across; true on the frame it was clicked. enabled = false greys it out and swallows the click.
click(node, any?) -> bool — Click a widget node as the pointer would, at the next tick and with no window needed: what a test harness drives the game with. False for a node a pointer could not click, hidden, disabled or not a widget; #{ hidden: true } clicks a hidden one anyway, as a test emitting its signal would.
code_editor(string, string, any?) -> string, bool, int?, any — Draw an editable, highlighted buffer with a gutter; returns the text, whether it changed, any line clicked, and the caret as #{ x, y, index }.
code_line(string, any, any?) — Draw one read-only code row from a list of { text, color, strong } spans, with a gutter label on the left.
color_picker(any?) -> [float], bool — Draw a color picker over value, an [r, g, b, a] of unit floats; returns the colour and whether it changed.
column(fn) — Lay the callback's widgets out in a column.
complete_theme(any) -> any — The theme document with every colour and size it leaves out derived from its sources, and dark stated.
contrast(string, string) -> any — The WCAG contrast ratio between two #rrggbb colours, 1 to 21. Body text wants 4.5, large or bold text 3.
contrast_pairs(any, string) -> any — Every ink a widget_theme document's roles draw on the fill each draws it on, as { role, ink, fill, ratio, need }. A role with no fill is read on the ground token; need is 3 for large or bold text and 4.5 otherwise.
dialog(string, any?, fn) -> bool — Draw the callback in a centered dialog over a dimming scrim; true on the frame the scrim was clicked. width, height and top size and place it, fill, stroke and scrim colour it; height follows the content when it is not given.
dot(string, float) — Draw a filled circle in a #rrggbb colour, diameter design pixels across.
dropdown(string, string, any, any?) -> string, bool — Draw a pill-shaped select over a list of strings; returns the selection and whether it changed this frame.
edit(node, any) -> bool — Change a widget node's value as the reader would, at the next tick, so it announces change: a number for a slider or a number field, a colour for a swatch, a boolean for a fold, text for a field, a dropdown's pick, a list's row or a tab. False for a disabled widget or a value its kind does not take.
fill_rows(string, any, any, bool) -> bool — fill_strip for a form: each row table is a label, its controls and an optional draw hatch, laid beside label_width, or above the controls when stacked. full spans both columns; height, tooltip, label_role and slot_role dress it.
fill_strip(string, any) -> bool — Put one widget node per control table under the node at host, made, reused and hidden as the list changes; a node is written only when its table changed. A control's on hears the reader's edit and on_submit hears Enter as they happen, so a strip that did not change need not be filled again, and a control carrying controls is a row holding them. True when a control's table differed from the last one written to it.
finish_loading() — Say the load is through, which lets a held splash go once splash_seconds has also passed. The editor calls it once its shell has settled.
focus_next() — Move focus to the next widget in scene order, wrapping past the last.
focus_previous() — Move focus to the previous widget in scene order, wrapping past the first.
focused_widget() -> any — The widget node focus is on, or nil.
frame(any?, fn) — Wrap the callback in a box with optional fill, stroke, corner_radius and padding, in design pixels. tooltip, menu and menu_click make the whole box answer the pointer, the way a button does, and a hover table is what it wears while the pointer is over it.
height_class() -> string — How much height this screen has, as ui::SHORT or ui::TALL.
image(string, any?) — Draw a PNG from the project, sized by width/height in design pixels and cached by path. region ([x, y, w, h] in the image's own pixels) draws one part of it, which is how an atlas is shown a tile at a time.
image_button(string, any?) -> bool — The same picture, answering a click: returns whether it was clicked this frame. Takes every image option plus selected, which draws the stroke border a chosen tile needs, and the menu/menu_click callbacks a pill takes.
label(string, any?) — Draw a line of text; font_size, font_family, text_color, font_weight, wrap and truncate style it.
layout_y() -> float — How far down the current panel the next widget will land, in design pixels: the same origin rect_stroke measures from.
left_panel(string, any?, fn) -> float — Dock a column down the left of the window and draw the callback inside it; width is in design pixels. Answers the width it ended up with.
list(string, any?, int, fn) — A scroll area of count rows of one height, calling the callback only for the rows on screen. row_height is the row, in design pixels.
menu_item(string, any?) -> bool — Draw a row inside a menu, width design pixels across and with trailing set against its right edge; true on the frame it was clicked, which also closes the menu unless keep_open says otherwise.
number_field(float, any?) -> float, bool — Draw a number dragged sideways to change it; returns the value and whether this frame changed it.
overlay(string, any?, fn) — Draw the callback in a foreground area at x/y design pixels, above the panels and the widget layer. width/height fix its size, and fill, stroke, corner_radius and padding make it a sheet. interactive = false for one that is only read, which hands its clicks to what is behind it.
pasted_text() -> string — The text pasted this frame, empty otherwise: the platform clipboard is not readable on demand.
progress_bar(float, any?) — Draw how far along something is: a track with part of it filled in fill, width by height design pixels, cornered by corner_radius. part is 0 to 1, and one outside that is held at the nearest end.
rect_stroke(float, float, float, float, any?) — Outline a rectangle at x/y/w/h design pixels from the current panel's corner, dashed when asked.
request_repaint(any?) — Run the UI pass this frame even when lazy, and the frame itself under [window] low_processor; call it every frame something on screen moves without input, such as while the scene plays. #{ after: seconds } asks for one that far ahead instead.
right_panel(string, any?, fn) -> float — Dock a column down the right of the window and draw the callback inside it; width is in design pixels. Answers the width it ended up with.
row(any?, fn) — Lay the callback's widgets out in a row; width, height and tight size it, in design pixels.
scale() -> float — The global UI scale: how many screen pixels a design pixel is drawn at, on top of the display's own.
scroll(string, any?, fn) — Put the callback in a scroll area. axis is vertical (the default), horizontal or both; max_height and max_width cap it, stick_to_end follows new content, and scroll_offset scrolls it to that many design pixels along, one number along axis or [across, down], below zero leaving an axis where it is.
separator(string?) — Draw a one-pixel rule across the container, in the given #rrggbb colour when one is passed.
set_clipboard(string) — Copy text to the system clipboard.
set_field_text(string, string) — Overwrite what the field with this id is editing, leaving the seed its value option last wrote alone.
set_focus(node) — Put focus on a widget node. A node focus cannot activate is refused at the next draw.
set_keyboard_navigation(bool) — Let the arrows, Tab, Enter and Space move and activate the focused widget. Off unless asked for, so a game that moves with the arrows does not click its own HUD; standard_app turns it on for a project declaring the ui_* actions.
set_lazy(bool) — Run the UI pass only when something asks for it (input, request_repaint, a log line, an asset reload, an egui animation, or the idle tick every 250 ms, which waits out a drag the UI is no part of) and re-present the last pass in between. Off by default: a HUD that reads live state each frame should leave it off. Ignored offscreen.
set_load_progress(float, string?) — Report how far a load is, zero to one. This is what holds [application] splash past its seconds, and what draws the bar under it.
set_scale(float) — Set the global UI scale, clamped to between 0.25 and 3.0. It is egui's zoom factor, so it grows every control and every font; screen_size already answers in the design pixels it leaves.
set_theme(any) — Dress every ui::* call from a theme document, the shape a widget_theme file holds: source colours under colors, sizes under sizes, and a roles table of named looks a call takes with role. What the document leaves out is derived from its sources.
set_widget_layer(bool, float?, float?, float?, float?) — Turn drawing of the scene's widget nodes on or off, and confine it to an x/y/w/h rect in design pixels.
set_widget_surface(string, bool, float?, float?, float?, float?) — The same for one named surface: roots whose layer is this name draw here instead. A name nothing has set takes the default surface.
shortcut(string) -> bool — Whether this chord was pressed this frame, consuming it: modifiers and a key joined by +, as in "cmd+shift+s" or "f5". cmd is the platform's command key, Command on a Mac and Control everywhere else.
slider(float, float, float, any?) -> float, bool — Draw a horizontal slider between min and max; returns the value after this frame and whether it moved.
spacing(float, float) — Set the gap between the current container's widgets, in design pixels.
switch(bool, any?) -> bool, bool — Draw an on/off switch; returns the state after this frame and whether it was clicked.
tab_rect(node) -> any — Where a tabs page's own button in the strip was last drawn, as #{ x, y, width, height } in design pixels; empty before the strip has drawn. widget_rect on the same node answers with the page body.
takes_pointer_at(float, float) -> bool — Whether the UI would take a press at this point, in design pixels, by the same layers as wants_pointer: what an editor asks of a point it is about to act on.
text_field(string, string?, any?) -> string, bool, bool — Draw a single-line text box keyed by id; returns its text, whether it changed, and whether Enter was pressed.
top_panel(string, any?, fn) -> float — Dock a strip across the top of the window and draw the callback inside it; height is in design pixels. Answers the height it ended up with.
wants_keyboard() -> bool — Whether a UI widget holds keyboard focus, so the game should leave this frame's key presses alone.
wants_pointer() -> bool — Whether the UI has the pointer or finger, so the game should leave it alone: what stops a tap on a HUD button also firing the shot behind it. A press is routed once, from the top: an open dialog, then a popup or window, then a widget that is not interactive = false or a seam between boxes, and the world last; it keeps that answer until the button comes up. Answers outside draw_ui too; false without a window.
widget_rect(node) -> any — Where a widget node was last drawn, as #{ x, y, width, height } in design pixels; empty until it has drawn once.
width_class() -> string — How much width this screen has, as ui::NARROW, ui::MEDIUM or ui::WIDE. Read every frame: a rotation changes it. A run with no window answers ui::WIDE.
window(string, any?, fn) -> bool — Draw the callback in a floating window the user drags and resizes; false once its close button is used. resizable, movable and closable are on unless turned off, collapsible and constrain off unless turned on; header = false drops the title bar, default_open = false starts it folded, and min_width, min_height, max_width and max_height bound its size, as the window widget's keys of those names do.
window_size() -> float, float — The window's width and height, in design pixels; a headless run answers the [window] size the project states.

Constants

name value
ALIGN_BASELINE baseline
ALIGN_CENTER center
ALIGN_END end
ALIGN_START start
ALIGN_STRETCH stretch
ANCHOR_BOTTOM_LEFT bottom_left
ANCHOR_BOTTOM_RIGHT bottom_right
ANCHOR_CENTER center
ANCHOR_CENTER_BOTTOM center_bottom
ANCHOR_CENTER_LEFT center_left
ANCHOR_CENTER_RIGHT center_right
ANCHOR_CENTER_TOP center_top
ANCHOR_FILL fill
ANCHOR_FILL_ACROSS fill_across
ANCHOR_FILL_BOTTOM fill_bottom
ANCHOR_FILL_DOWN fill_down
ANCHOR_FILL_LEFT fill_left
ANCHOR_FILL_RIGHT fill_right
ANCHOR_FILL_TOP fill_top
ANCHOR_TOP_LEFT top_left
ANCHOR_TOP_RIGHT top_right
FONT_HEADING heading
FONT_MONO mono
FONT_STYLE_ITALIC italic
FONT_STYLE_NORMAL normal
FONT_STYLE_OBLIQUE oblique
HEIGHT_SHORT short
HEIGHT_TALL tall
INPUT_POINTER pointer
INPUT_TOUCH touch
MODIFIER_ALT alt
MODIFIER_CMD cmd
MODIFIER_CTRL ctrl
MODIFIER_SHIFT shift
WIDGET_BUTTON button
WIDGET_CHECKBOX checkbox
WIDGET_CODE code
WIDGET_COLOR_PICKER color_picker
WIDGET_COLUMN column
WIDGET_DIALOG dialog
WIDGET_DRAW draw
WIDGET_DROPDOWN dropdown
WIDGET_FLOW flow
WIDGET_FOLD fold
WIDGET_GRID grid
WIDGET_IMAGE image
WIDGET_LABEL label
WIDGET_LIST list
WIDGET_MENU menu
WIDGET_NUMBER_FIELD number_field
WIDGET_PANEL panel
WIDGET_PROGRESS_BAR progress_bar
WIDGET_ROW row
WIDGET_SCROLL scroll
WIDGET_SEPARATOR separator
WIDGET_SLIDER slider
WIDGET_STACK stack
WIDGET_SWITCH switch
WIDGET_TABLE table
WIDGET_TABS tabs
WIDGET_TEXT_AREA text_area
WIDGET_TEXT_FIELD text_field
WIDGET_TOAST toast
WIDGET_TREE tree
WIDGET_WINDOW window
WIDTH_MEDIUM medium
WIDTH_NARROW narrow
WIDTH_WIDE wide