GUI structuring tools and event handling.
local gui = require("__flib__.gui")
hook_events(callback) | Provide a callback to be run for GUI events. |
read_action(event_data) | Retrieve the action message from a GUI element's tags. |
build(parent, structures) | Build a GUI based on the given structure(s). |
add(parent, structure) | Build a single element based on a GuiStructure. |
update(elem, updates) | Update an existing GUI based on a given structure. |
get_tags(elem) | Retrieve a GUI element's tags. |
set_tags(elem, tags) | Set (override) a GUI element's tags. |
delete_tags(elem) | Delete a GUI element's tags. |
update_tags(elem, updates) | Perform a shallow merge on a GUI element's tags. |
set_action(elem, event_name, msg) | Set (overwrite) the specified action message for this GUI element. |
get_action(elem, event_name) | Retrieve the specified action message for this GUI element. |
GuiBuildStructure | A series of nested tables used to build a GUI. |
GuiUpdateStructure | A series of nested tables used to update a GUI. |
GuiElementActions | A mapping of GUI event name -> action message. |
TabAndContent | A table representing a tab <-> content pair. |
Provide a callback to be run for GUI events.
Parameters:
gui.hook_events(function(e)
local msg = gui.read_action(e)
if msg then
-- read the action to determine what to do
end
end)
Retrieve the action message from a GUI element's tags.
Parameters:
event.on_gui_click(function(e)
local action = gui.read_action(e)
if action then
-- do stuff
end
end)
Build a GUI based on the given structure(s).
Parameters:
ref
throughout the
GuiBuildStructure.
Build a single element based on a GuiStructure.
This is to allow use of style_mods
, actions
and tags
without needing to use gui.build()
for a single element.
Unlike gui.build()
, the element will be automatically returned from the function without needing to use ref
. If
you need to obtain references to children of this element, use gui.build()
instead.
Update an existing GUI based on a given structure.
Parameters:
Retrieve a GUI element's tags.
These tags are automatically written to and read from a subtable keyed by mod name, preventing conflicts.
If no tags exist, this function will return an empty table.
Parameters:Set (override) a GUI element's tags.
These tags are automatically written to and read from a subtable keyed by mod name, preventing conflicts.
Parameters:Delete a GUI element's tags.
These tags are automatically written to and read from a subtable keyed by mod name, preventing conflicts.
Parameters:Perform a shallow merge on a GUI element's tags.
These tags are automatically written to and read from a subtable keyed by mod name, preventing conflicts.
Only the top level will be updated. If deep updating is needed, use gui.get_tags and table.deep_merge, then gui.set_tags.
Parameters:Set (overwrite) the specified action message for this GUI element.
Parameters:
_gui
portion omitted (i.e. on_click
).
nil
to clear the action.
Retrieve the specified action message for this GUI element.
Parameters:
_gui
portion omitted (i.e.
on_click
).
A series of nested tables used to build a GUI.
This is an extension of LuaGuiElement, providing new features and options.
This inherits all required properties from its base LuaGuiElement, i.e. if the type
field is
sprite-button
, the GuiBuildStructure must contain all the fields that a sprite-button
LuaGuiElement
requires.
There are a number of new fields that can be applied to a GuiBuildStructure depending on the type:
gui.build(player.gui.screen, {
{
type = "frame",
direction = "vertical",
ref = {"window"},
actions = {
on_closed = {gui = "demo", action = "close"}
},
-- Titlebar
{type = "flow", ref = {"titlebar", "flow"},
{type = "label", style = "frame_title", caption = "Menu", ignored_by_interaction = true},
{type = "empty-widget", style = "flib_titlebar_drag_handle", ignored_by_interaction = true},
{
type = "sprite-button",
style = "frame_action_button",
sprite = "utility/close_white",
hovered_sprite = "utility/close_black",
clicked_sprite = "utility/close_black",
ref = {"titlebar", "close_button"},
actions = {
on_click = {gui = "demo", action = "close"}
}
}
},
-- Content
{type = "frame", style = "inside_deep_frame_for_tabs",
{type = "tabbed-pane",
{
tab = {type = "tab", caption = "1"},
content = {type = "table", style = "slot_table", column_count = 10, ref = {"tables", 1}}
},
{
tab = {type = "tab", caption = "2"},
content = {type = "table", style = "slot_table", column_count = 10, ref = {"tables", 2}}
}
}
}
}
})
A series of nested tables used to update a GUI.
actions
in a
GuiBuildStructure. This is identical to calling set_action
for each action on this element.
gui.update(
my_frame,
{
elem_mods = {caption = "Hello there!"},
tags = {subject = "General Kenobi"},
actions = {on_click = "everybody_say_hey"},
{
{
{tab = {elem_mods = {badge_text = "69"}}, content = {...}},
{content = {...}}
}
}
}
)
A mapping of GUI event name -> action message.
Each key is a GUI event name (on_gui_click
, on_gui_elem_changed
, etc.) with the _gui
part removed. For example,
on_gui_click
will become on_click
.
Each value is a custom set of data that gui.read_action will return when that GUI event is fired and passes this GUI element. This data may be of any type, as long as it is truthy.
Actions are kept under a flib
subtable in the element's mod-specific tags subtable, retrievable with
gui.get_tags. Because of this, there is no chance of accidental mod action overlaps, so feel free to use
generic actions such as "close" or "open".
A common format for a mod with multiple GUIs might be to give each GUI a name, and write the actions as shown below.
Usage:gui.build(player.gui.screen, {
{
type = "frame",
caption = "My frame",
actions = {
on_click = {gui = "my_gui", action = "handle_click"},
on_closed = {gui = "my_gui", action = "close"}
}
}
})
A table representing a tab <-> content pair.
When used in gui.build, both fields are required. When used in gui.update, both fields are optional.
tab
.