GUI

WORK IN PROGRESS

local gui = require('__RaiLuaLib__.lualib.gui')

The GUI module greatly eases the process of creating and managing complex GUIs. Easily build large GUI structures using GUI templates, and automatically register handlers to specific elements.

Click to view usage examples

Functions

build(parent, templates)

Creates a GUI from the given templates.

Parameters

• parent :: LuaGuiElement: Element that the GUI will be placed in.
• templates :: array of GuiTemplate

Returns

• output :: table: The output table as defined by the templates.
• gui_filters :: GuiFiltersTable

templates:extend(data)

Extends the GUI templates table.

Parameters

• data :: GuiTemplateLibrary

handlers:extend(data)

Extends the GUI handlers table.

Parameters

• data :: GuiHandlerLibrary

Concepts

GuiTemplate

A GUI template consists of a tree of nested tables. Each table takes on the format of the LuaGuiElement you are creating, and must have all of the required fields for that element:

{type='sprite-button', style='tool_button', sprite='utility/trash'}

This code would be a valid template as-is. However, just adding a single sprite button to the root GUI is... not very useful. Thus, the children table:

{type='frame', style='dialog_frame', children={
  {type='sprite-button', style='tool_button', sprite='utility/trash'}
}}

The GUI module will add all templates contained in the children table as children of that element. Each child can have a children table of its own, and tables are recursively navigated in order to build the GUI:

{type='frame', style='dialog_frame', save_as='window', children={
  {type='flow', style={vertical_align='center'}, direction='horizontal', children={
    {type='label', style='frame_title', caption='Settings},
    {type='empty-widget', style={horizontally_stretchable=true}},
    {template='close_button', handlers='close_button', save_as=true}
  }},
  {type='frame', style='window_content_frame_packed', children={
    {type='scroll-pane', style='scroll_pane_under_subheader', children={
      {type='table', save_as='content_table'}
    }}
  }}
}}

template

The template parameter is a string with a path to a template in the GuiTemplateLibrary table. The contents of the template will be used as a base, onto which the other parameters for that element are applied. This allows one to store oft-used elements in the templates library, avoiding redundant code and making it easy to modify.

gui.templates:extend{
  pushers = {
    both = {type='empty-widget', style_mods={horizontally_stretchable=true, vertically_stretchable=true}},
    horizontal = {type='empty-widget', style_mods={horizontally_stretchable=true}},
    vertical = {type='empty-widget', style_mods={vertically_stretchable=true}},
  }
}

gui.build(frame, {
  {type='label', style='frame_title', caption='Foo'},
  {template='pushers.horizontal'}
  {type='sprite-button', style='close_button', sprite='utility/close_white'}
})

style_mods

style_mods allows you to perform runtime style modifications inside the template. This is simply a table of key=value.

{type='flow', style_mods={horizontally_stretchable=true, height=24}}

mods

This parameter lets you perform runtime modifications to the element itself. Anything contained in LuaGuiElement is accessible and modifiable.

{type='button', caption='Hello!', mods={enabled=false}}

handlers

The handlers parameter is a string with a path to a group of handlers in the GuiHandlerLibrary table. These handlers will be registered to this element, and this element's ID will be added to the GuiFiltersTable output for later reference.

handlers_prefix

This parameter will act as a prefix to any handlers parameters in children of that element. The prefixes will stack. This avoids the need to have a giant handlers string taking up tons of space on a single element.

gui.build(parent, {
  {type='frame', style='dialog_frame', direction='vertical', handlers_prefix='dialog.', children={
    {type='flow', handlers_prefix='titlebar.', children={
      {type='label', style='frame_title', caption='Foo'},
      {template='pushers.horizontal'}
      -- actual handlers path string is 'dialog.titlebar.close_button':
      {type='sprite-button', style='close_button', sprite='utility/close_white', handlers='close_button'}
    }
  }
})

save_as

The return value of gui.build is an output table. This table starts empty, but is added to by using the save_as parameter. This parameter is a string that contains the path where you would like the element to be saved.

{template='close_button', save_as='titlebar.close_button'}

GuiFiltersTable

Dictionary string -> Event::GuiFilterTable. Each key is the name of a conditional event, to which the filters were applied. This allows one to keep track of which GUI filters belong to certain copies of the same GUI.

GuiTemplateLibrary

This is a table with a custom structure. It contains element templates that can be accessed using the template parameter when defining an element.

GuiHandlerLibrary