Engine.uiWidget¶

Menus. A menu is a tree of widgets, each created from a ui_widget_definition tag. Widgets are returned as Widget objects, which are live views of the widget in memory.

Functions¶

Function	Returns	Description
`launchWidget(definition)`	`Widget` or `nil`	Opens a widget from a `ui_widget_definition` tag. When a menu is open it is launched from the active widget; otherwise it becomes the root widget.
`getActiveWidget()`	`Widget` or `nil`	The root widget of the open menu.
`closeWidget()`		Closes the active widget.
`replaceWidget(widget, definition)`	`Widget`	Replaces a widget with a new one made from another definition, in the same place.
`focusWidget(widget)`		Gives the input focus to a widget.
`unfocusWidget(widget)`		Takes the input focus away from a widget, if it has it.
`findWidgets(definition, baseWidget, firstMatch)`	`Widget[]`	Widgets made from `definition`, searched from `baseWidget` (the active widget when missing) through its children and following siblings. The search does not continue inside or past a widget that matches. With `firstMatch`, stops at the first one.
`disableWidget(widget)`		Disables a widget.
`enableWidget(widget)`		Enables a widget.
`getIndexForChildWidget(parent, child)`	`integer`	Position of `child` among the children of `parent`, counting from 0. `child` must be a child of `parent`.
`getNthChildWidget(parent, index)`	`Widget` or `nil`	Child number `index` of `parent`, counting from 0.
`getLastChildWidget(widget)`	`Widget` or `nil`	Last child of a widget.
`getTopmostParentWidget(widget)`	`Widget`	Root of the tree the widget is in.
`isListWidget(widget)`	`boolean`	Whether the widget is a list.
`textBoxWidgetIsFocused(widget)`	`boolean`	Whether a text box widget has the focus.

All functions are in the Engine.uiWidget table, such as Engine.uiWidget.launchWidget.

Example¶

-- Open a custom menu with a console command.
Balltze.registerCommand("menu", "Opens the plugin menu", nil, false, 0, 0, true, false, function()
    local definition = Engine.tag.lookupTag("ui\\my_plugin\\my_menu", "ui_widget_definition")
    if not definition then
        return false
    end
    Engine.uiWidget.launchWidget(definition)
    return true
end)

To react to what the player does in a menu, see the widget_loaded and widget_event_dispatch events.