gui module

GUI structuring tools and event handling.

See also

Usage

local gui = require("__flib__.gui")

Functions

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.

Concepts

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.

Functions

# hook_events(callback)

Provide a callback to be run for GUI events.

Parameters: See also: Usage:
gui.hook_events(function(e)
  local msg = gui.read_action(e)
  if msg then
    -- read the action to determine what to do
  end
end)
# read_action(event_data)

Retrieve the action message from a GUI element's tags.

Parameters:
  • event_data : (EventData)
Returns:
  • (any or nil) The element's action for this GUI event.
Usage:
event.on_gui_click(function(e)
  local action = gui.read_action(e)
  if action then
    -- do stuff
  end
end)
# build(parent, structures)

Build a GUI based on the given structure(s).

Parameters: Returns:
# add(parent, structure)

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.

Parameters: Returns:
  • A reference to the element that was created.
# update(elem, updates)

Update an existing GUI based on a given structure.

Parameters:
# get_tags(elem)

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: Returns:
# set_tags(elem, tags)

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_tags(elem)

Delete a GUI element's tags.

These tags are automatically written to and read from a subtable keyed by mod name, preventing conflicts.

Parameters:
# update_tags(elem, updates)

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_action(elem, event_name, msg)

Set (overwrite) the specified action message for this GUI element.

Parameters:
  • elem : (LuaGuiElement)
  • event_name : (string) The GUI event name for this action, with the _gui portion omitted (i.e. on_click).
  • msg : (any or nil) The action message, or nil to clear the action.
# get_action(elem, event_name)

Retrieve the specified action message for this GUI element.

Parameters:
  • elem : (LuaGuiElement)
  • event_name : (string) The GUI event name to get the action message for, with the _gui portion omitted (i.e. on_click).
Returns:
  • (any or nil) msg The action message, if there is one.

Concepts

# GuiBuildStructure

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:

  • style_mods : (table) A key -> value dictionary defining modifications to make to the element's style. Available properties are listed in LuaStyle. (optional)
  • elem_mods : (table) A key -> value dictionary defining modifications to make to the element. Available properties are listed in LuaGuiElement. (optional)
  • actions : (GuiElementActions) Actions to take on certain GUI events. (optional)
  • ref : (string[]) A nested table path in which to place a reference to this LuaGuiElement in the output of gui.build. (optional)
  • children : (GuiBuildStructure[]) GuiBuildStructures to add as children of this LuaGuiElement. Children may alternatively be defined in the array portion of the parent structure to remove a level of nesting. (optional)
  • tabs : (TabAndContent[]) TabAndContents to add as tabs of this LuaGuiElement. Tabs may alternatively be defined int he array portion of the parent structure to remove a level of nesting. (optional)
Usage:
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}}
        }
      }
    }
  }
})
# GuiUpdateStructure

A series of nested tables used to update a GUI.

  • cb : (function) A callback to run on this GUI element. The callback will be passed a LuaGuiElement as its first parameter. (optional)
  • style : (string) The new style that the element should use. (optional)
  • style_mods : (table) A key -> value dictionary defining modifications to make to the element's style. Available properties are listed in LuaStyle. (optional)
  • elem_mods : (table) A key –> value dictionary defining modifications to make to the element. Available properties are listed in LuaGuiElement. (optional)
  • tags : (table) Tags that should be added to the element. This is identical to calling gui.update_tags on the element.
  • actions : (table) Actions that should be added to the element. The format is identical to actions in a GuiBuildStructure. This is identical to calling set_action for each action on this element.
  • children : (GuiUpdateStructure[]) GuiUpdateStructures to apply to the children of this LuaGuiElement. This may alternatively be defined in the array portion of the parent structure to improve readability. (optional)
  • tabs : (TabAndContent[]) TabAndContents to apply to the tabs of this LuaGuiElement. This may alternatively be defined in the array portion of the parent structure to improve readability. (optional)
Usage:
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 = {...}}
     }
    }
  }
)
# GuiElementActions

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"}
    }
  }
})
# TabAndContent

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.