Module: GUI

Poly’s GUI module has three major features that simplify creating and managing GUIs:

1. Poly’s event handling is an easy-to-use registry for event handler functions, that are called to handle GUI events on GUI components and LuaGuiElements.

2. Poly’s GUI components are a convenient way to declaratively build GUIs. Although they are compatible with Factorio’s imperative style GUI API, they are most useful when the whole GUI is implemented using Poly.

3. Poly’s window manager helps to manage multiple windows, e.g., modal dialogs.

Although each part of Poly’s GUI API can be used in isolation, it is a good idea to let Poly handle all GUI related features in your mod. Feel free to contact me in case you have a scenario that Poly cannot handle fully and naturally.

See Full Example for an example GUI using all three features.

Note: Because Poly stores, e.g., class ids as part of event handlers in Factorio’s global table, it is necessary to update these values when the mod is updated. The simplest way to do this is to (by default) delete all Poly GUIs when your mod is updated.

Event Handling

Poly’s event handler for GUI events is an easy way to register function calls (and optionally their arguments) with an id string. This enables Poly to associate GUI events on LuaGuiElement with handler functions, as a LuaGuiElement can only store primitive type values in its tags.

The Poly EventHandler provides three basic functions:

• EventHandler:register(handler_table, function_name, ...)

  Registers a call to handler_table:function_name(..., event) and returns an id for it. handler_table can be either nil (if function_name is the name of a globally available function), a Poly class, or an instance of a Poly class. function_name is the name of the function to be called on handler_table as a string. All further arguments will be passed on to the handler function.

• EventHandler:call(event_handler_id, event)

  Calls the previously registered event handler with id event_handler_id. It passes as arguments the registered arguments followed by the passed in event.

• EventHandler:delete(event_handler)

  Deletes a previously registered event handler. event_handler can be either a single event handler id, an array of ids. Alternatively, a valid LuaGuiElement can be passed, deleting all event handlers referenced in its tags.

To associate a LuaGuiElement with an event handler, simply provide its event handler id in the elements tags in a table called Poly with the event’s name as its key, e.g.:

-- register call to globally defined function handle_button_click(5)
local id1 = EventHandler:register(nil, 'handle_button_click', 5)
-- register call to my_object:handle_button_click(10)
local my_object = MyHandlerClass:new()
local id2 = EventHandler:register(my_object, 'handle_button_click', 10)
-- register call to MyHandlerClass:handle_button_click(15)
local id3 = EventHandler:register(MyHandlerClass, 'handle_button_click', 15)

-- create a button on some previously defined frame
local button = frame.add {
    type = 'button', name = 'test_button',
    tags = {
        -- pass the registered event handlers to the LuaGuiElement by id
        -- you can either pass a single id or an array containing multiple ids
        Poly = { on_gui_click = { id1, id2, id3 } }
    }
}

This assumes that the various handler functions have been defined as follows:

-- require Poly's Class API
local Class = require('__poly__.Class')

-- require Poly's EventHandler
local EventHandler = require('__poly__.GUI.EventHandler')

-- define globally available handler function
function handle_button_click(value, event)
    print('called global handle_button_click(' .. value .. ')')
end

-- define event handler class
local MyHandlerClass = Class:new('examples.MyHandlerClass')
function MyHandlerClass:new()
    return {}
end
function MyHandlerClass:handle_button_click(value, event)
    print('called MyHandlerClass:handle_button_click(' .. value .. ')')
end

Make sure to delete all event handlers of a LuaGuiElement before it is destroyed, e.g., by calling EventHandler:delete(button), to prevent orphaned event handlers.

Using Poly’s components makes it even easier to handle events, because components automatically create a LuaGuiElement’s tags and take care of deleting event handlers before their LuaGuiElements are destroyed.

Components

Components are the basic building block for Poly GUIs. They can be simple, e.g., a label or textfield, or complex, e.g., a window containing a table and three buttons.

Component Lifecycle

Key to using Poly components is to understand their lifecycle:

• new: Creates a new instance of the component class (see Class Mechanism for details on classes). Note that the component’s LuaGuiElements are not yet created.

• create: Creates the LuaGuiElements visualizing the component. It is now in the Created state.

• refresh: Refreshes the created LuaGuiElements with the current values from the component’s instance.

• destroy: Destroys the component’s LuaGuiElements, moving it back to the Instantiated state. Again, just like after the new transition, the component no longer has any visible LuaGuiElements.

• delete: Deletes the component instance.

Component Interface

Every Poly component (including the ones you define yourself) has to be (indirectly) derived from the Component class. Component provides default implementations for all lifecycle transitions, as well as some other functionality that is shared by all components. Custom components can override the default implementations (typically the new method to create a customized instance of the base component) and extend them with their own implementations. It should almost never be necessary to override something other than new.

Component provides the following interface:

• Component:new(args):

  Initializes a component instance with an optional args.name. All values in args with numeric keys will be added as children to the component.

• Component:create(parent):

  Creates the component’s LuaGuiElements with parent as their parent LuaGuiElement (i.e. they are created using parent.add { ... }. The default implementation simply passes this call to all children.

• Component:refresh():

  Refreshes the component’s LuaGuiElements. The default implementation simply passes this call to all children.

• Component:destroy():

  Destroys the component’s LuaGuiElements. The default implementation simply passes this call to all children.

• Component:delete():

  Deletes the component instance. The default implementation simply passes this call to all children.

• Component:get_state():

  Returns component’s current lifecycle state (either Component.State.Instantiated` or ``Component.State.Created).

• Component:get_name():

  Returns component’s name.

• Component:add_child(child):

  Adds child to component’s children.

• Component:get_child(index_or_name):

  Returns component’s child with index or name index_or_name. Alternatively, children with a name can be directly accessed using <component_instance>.<child_name>, e.g., flow.my_button for accessing a button with name “my_button” that was added to flow.

• Component:get_children():

  Returns a read-only table containing all of component’s children.

• Component:remove_child(index_or_name):

  Removes and returns component’s child with index or name index_or_name. If the child component is currently in the Component.State.Created state, the child will be destroyed before it is returned.

• Component:delete_child(index_or_name):

  Same as Component:remove_child(index_or_name), but additionally also calls delete on the child.

• Component:clear_children():

  Deletes all of component’s children.

Note: The Component class provides implementations for adding children to a component, meaning all Poly components have that ability. This is similar to Factorio’s LuaGuiElement, where you can add children to, e.g., a label, as well. You can choose however to ignore those children in your custom component’s create implementation, if it does not make sense to add children to it.

Factorio Components

Poly provides pre-implemented components for all subtypes of LuaGuiElement. They are available under __poly__.GUI.Factorio and named after the subtype converted to camel case, e.g., component ChooseElemButton for subtype choose-elem-button.

The Factorio components have a straightforward interface, which makes them usable in a similar way to the built-in ones:

• Their new method takes all arguments that are listed under LuaGuiElement.add for the component’s subtype, e.g., flow’s direction: Flow:new { direction = 'horizontal' }. Additionally, you can also pass any other of subtype’s writeable attributes that are not listed, e.g., flow’s drag_target.

• They have a getter method called <ComponentClass>:get_<attribute> for each attribute of the component’s subtype, as well as a setter called <ComponentClass>:set_<attribute> for the writeable attributes.

• The setter for a components style attribute (and also new) accepts style names (like LuaGuiElements) as a string, as well as tables for modifying the styles directly, for example:

  -- sets label's style to the built-in 'caption_label':
  Label:new { style = 'caption_label' }
  -- keeps label's current style and sets style.width = 120
  Label:new { style = { width = 120 } }
  -- sets label's style to the built-in 'caption_label' and additionally sets label's style.width = 120
  Label:new { style = { 'caption_label', width = 120 } }
  

• For Poly to be able to keep track of a component’s tags, <ComponentClass>:get_tags() returns a read-only of the tags. To modify them, use methods <ComponentClass>:set_tags(tags), <ComponentClass>:update_tags(tags), and <ComponentClass>:delete_tags(tags).

• Most methods listed for LuaGuiElement can be called on components: <ComponentClass>:<method_name>(...). Note that the component has to be in Component.State.Created` state to be able to call ``LuaGuiElement’s methods.

• Factorio components seamlessly integrate with Poly’s event handling. Simply pass one or multiple event handler ids to a component’s new function with the event name as key, e.g., Button:new { on_gui_click = EventHandler:register(...) }. By default, the component takes ownership of the event handler and deletes it when the component gets deleted. You can prevent that by passing delete_event_handler = false to new as well.

  Outside of new, on or multiple event handlers can be added to a component via ComponentClass:add_<event_name>(event_handler), e.g., my_button:add_on_gui_click(EventHandler:register(...)).

Creating Components

Custom components are derived from Component or any other previously defined component, e.g., Flow. Typically, a custom component overrides the base components new function to create a customized instance of the base component, and adds getters and setters to interact with the custom component.

The following simple example illustrates how to create custom components by implementing a simple spinner textfield. It is a numeric textfield with two buttons for decreasing and increasing the textfield’s value:

-- require Poly's Class API
local Class = require('__poly__.Class')

-- require Poly's pre-implemented components for flow, textfield, and button
local Flow = require('__poly__.GUI.Factorio.Flow')
local Textfield = require('__poly__.GUI.Factorio.Textfield')
local Button = require('__poly__.GUI.Factorio.Button')

-- require Poly's EventHandler API
local EventHandler = require('__poly__.GUI.EventHandler')


-- define a new custom component called "SpinnerTextfield", derived from Flow
local SpinnerTextfield = Class:new('examples.SpinnerTextfield', Flow)

-- override Flow's `new` to create a custom flow containing the SpinnerTextfield's buttons and textfield
function SpinnerTextfield:new(args)
    -- create the SpinnerTextfield as a flow containing two buttons and a textfield
    local spinner_textfield = Flow:new {
        name = args.name,
        direction = 'horizontal',

        -- add button for decreasing the spinner value
        Button:new { name = 'decrease', caption = '-', style = { width = 36 } },
        -- add numeric textfield with optional initial value that can be passed as
        -- a parameter to SpinnerTextfield's `new` for displaying the spinner value
        Textfield:new { name = 'spinner_value', numeric = true, text = args.initial_value, style = { width = 48 } },
        -- add button for increasing the spinner value
        Button:new { name = 'increase', caption = '+', style = { width = 36 } }
    }
    -- setup event handling
    spinner_textfield.decrease:add_on_gui_click(EventHandler:register(spinner_textfield, 'on_gui_click_inc_dec', -1))
    spinner_textfield.increase:add_on_gui_click(EventHandler:register(spinner_textfield, 'on_gui_click_inc_dec', 1))

    return spinner_textfield
end

-- add event handler function for updating the SpinnerTextfield's value
function SpinnerTextfield:on_gui_click_inc_dec(delta, event)
    if event.shift then
        -- multiply delta by 10, if the shift key was pressed during click
        delta = delta * 10
    end
    -- get current value and modify by delta
    local value = tonumber(self.spinner_value:get_text()) or 0
    self.spinner_value:set_text(tostring(value + delta))
end


-- make SpinnerTextfield usable as Lua module
return SpinnerTextfield

Window Manager

The window manager keeps track of the windows opened by your mod. It establishes a hierarchy (more precisely a stack) of windows per GUI available under player.gui, e.g., screen, which allows easily implementing modal dialogs, for example.

WindowManager provides the following interface:

• WindowManager:open(anchor, window_or_class, ...)

  Creates the window_or_class if it is an instance of Poly’s Window or any derived class. Instantiates and then creates it, if window_or_class is Poly’s Window or any derived class itself. All further arguments are passed to the classes new function. Anchor is one of the values of enum WindowManager.Anchor, e.g., WindowManager.Anchor.screen(player) for creating windows in player.gui.screen. All windows below the new window in the stack will have their ignored_by_interaction attribute set to true, allowing input only to the topmost window.

• WindowManager:close(window_or_anchor, delete, delete_in_front)

  Destroys window_or_anchor. If window_or_anchor is a window, it and all windows on top of it in the stack will be destroyed. If window_or_anchor is an anchor, all windows in the anchor’s stack will be destroyed. When the optional parameter delete is omitted or set to true, the window will also be deleted (i.e. its delete function will be called). When the optional parameter delete_in_front is omitted or set to true, the windows on top of window_or_anchor will also be deleted.

The following listing illustrates the usage of WindowManager and Window. It creates a simple test window every time the command /open_window is executed in Factorio’s console. When multiple windows are opened, only the top one can be moved around and closed. Executing command /close_all_windows closes all previously opened windows.

-- require Poly's Class API
local Class = require('__poly__.Class')

-- require Poly's WindowManager & Window
local WindowManager = require('__poly__.GUI.WindowManager')
local Window = require('__poly__.GUI.Window')

-- require Poly's pre-implemented component for label
local Label = require('__poly__.GUI.Factorio.Label')

-- add command that opens a new window in player.gui.screen
commands.add_command('open_window', '', function(command)
    local player = game.players[command.player_index]

    -- initialize a new window
    local window = Window:new {
        -- configure window's titlebar
        titlebar = {
            -- set window's title (append number of currently open windows)
            title = 'Test window ' .. tostring(#player.gui.screen.children)
        },

        -- add components to the window (3 labels for this example)
        Label:new { caption = 'This window can be dragged' },
        Label:new { caption = 'by clicking and dragging' },
        Label:new { caption = 'its titlebar or title' }
    }

    -- open window in player.gui.screen
    WindowManager:open(WindowManager.Anchor.screen(player), window)
end)

-- add command that closes all windows in player.gui.screen
commands.add_command('close_all_windows', '', function(command)
    local player = game.players[command.player_index]

    -- close all windows in player.gui.screen
    WindowManager:close(WindowManager.Anchor.screen(player))
end)

Full Example

This section provides a full example using all three major features of Poly’s GUI module: custom components, event handling, and managing multiple windows. The example will implement a simple, manual counter GUI, where the player can enter a caption and update a number. For this, we implement a custom SpinnerLabel component that is a numeric label with two buttons for increasing and decreasing its value. We will use the window manager to display the counter GUI and show a modal dialog for entering the counter’s caption.

Each listing in this section has a filename shown as its caption at the top. You can test this example by copying the listings into files with these names.

Let’s start with the SpinnerLabel:

SpinnerLabel.lua

-- require Poly's Class API
local Class = require('__poly__.Class')

-- require Poly's pre-implemented components for flow, label, and button
local Flow = require('__poly__.GUI.Factorio.Flow')
local Label = require('__poly__.GUI.Factorio.Label')
local Button = require('__poly__.GUI.Factorio.Button')

-- require Poly's EventHandler API
local EventHandler = require('__poly__.GUI.EventHandler')


-- define a new custom component called "SpinnerLabel", derived from Flow
local SpinnerLabel = Class:new('examples.SpinnerLabel', Flow)

-- override Flow's `new` to create a custom flow containing the SpinnerLabel's buttons and label
function SpinnerLabel:new(args)
    -- create the SpinnerLabel as a flow containing two buttons and a label
    local spinner_label = Flow:new {
        name = args.name,
        direction = 'horizontal',

        -- add button for decreasing the spinner value
        Button:new { name = 'decrease', caption = '-', style = { width = 36 } },
        -- add a label with optional initial value that can be passed as
        -- a parameter to SpinnerLabel's `new` for displaying the spinner value
        Label:new { name = 'spinner_value', numeric = true, caption = args.initial_value,
                    style = { width = 48, horizontal_align = 'center', vertical_align = 'center' } },
        -- add button for increasing the spinner value
        Button:new { name = 'increase', caption = '+', style = { width = 36 } }
    }
    -- setup event handling
    spinner_label.decrease:add_on_gui_click(EventHandler:register(spinner_label, 'on_gui_click_inc_dec', -1))
    spinner_label.increase:add_on_gui_click(EventHandler:register(spinner_label, 'on_gui_click_inc_dec', 1))

    return spinner_label
end

-- add event handler function for updating the SpinnerLabel's value
function SpinnerLabel:on_gui_click_inc_dec(delta, event)
    if event.shift then
        -- multiply delta by 10, if the shift key was pressed during click
        delta = delta * 10
    end
    -- get current value and modify by delta
    local value = tonumber(self.spinner_value:get_caption()) or 0
    self.spinner_value:set_caption(tostring(value + delta))
end


-- make SpinnerLabel usable as Lua module
return SpinnerLabel

Additionally, we create a custom dialog to enter a caption for the counter:

CaptionDialog.lua

-- require Poly's Class API
local Class = require('__poly__.Class')

-- require Poly's pre-implemented components for frame, flow, empty-widget, label, textfield, and button
local Frame = require('__poly__.GUI.Factorio.Frame')
local Flow = require('__poly__.GUI.Factorio.Flow')
local EmptyWidget = require('__poly__.GUI.Factorio.EmptyWidget')
local Label = require('__poly__.GUI.Factorio.Label')
local Textfield = require('__poly__.GUI.Factorio.Textfield')
local Button = require('__poly__.GUI.Factorio.Button')

-- require Poly's WindowManager & Window component
local WindowManager = require('__poly__.GUI.WindowManager')
local Window = require('__poly__.GUI.Window')

-- require Poly's EventHandler API
local EventHandler = require('__poly__.GUI.EventHandler')


-- define a new custom component called "CaptionDialog", derived from Window
local CaptionDialog = Class:new('examples.CaptionDialog', Window)

-- override Window's `new` to create a custom window
function CaptionDialog:new()
    local caption_dialog = Window:new {
        -- configure dialog's titlebar (don't add a close button, as Factorio dialogs have a back button on the bottom)
        titlebar = { title = 'Enter counter\'s caption', add_close_button = false },

        -- add a frame for dialog's content (a label and textfield)
        Frame:new {
            name = 'content',
            direction = 'horizontal',
            style = { 'inside_shallow_frame_with_padding' },

            Flow:new {
                name = 'input',
                style = 'player_input_horizontal_flow',

                Label:new { caption = 'Counter caption:' },
                Textfield:new { name = 'counter_caption' }
            }
        },
        -- add a flow for dialog's buttons (Back and Confirm)
        Flow:new {
            name = 'buttons',
            direction = 'horizontal',

            Button:new { name = 'back', caption = 'Back', style = 'back_button' },
            EmptyWidget:new { style = { horizontally_stretchable = true } },
            Button:new { name = 'confirm', caption = 'Confirm', style = 'confirm_button' }
        }
    }
    -- setup event handling
    caption_dialog.buttons.back:add_on_gui_click(EventHandler:register(caption_dialog, 'on_gui_click_back'))
    caption_dialog.buttons.confirm:add_on_gui_click(EventHandler:register(caption_dialog, 'on_gui_click_confirm'))

    return caption_dialog
end

-- add event handler functions for clicking on buttons
function CaptionDialog:on_gui_click_back()
    -- close this dialog
    WindowManager:close(self)
end
function CaptionDialog:on_gui_click_confirm(event)
    -- apply the new caption to the counter GUI's label
    global.counter_guis[event.player_index].content.counter.counter_caption:set_caption(
            self.content.input.counter_caption:get_text())
    -- close this dialog
    WindowManager:close(self)
end

-- make CaptionDialog usable as Lua module
return CaptionDialog

We can now create the counter GUI using these components in control.lua:

control.lua

-- require Factorio's mod GUI for adding a mod button
local mod_gui = require('mod-gui')

-- require Poly's WindowManager & Window component
local WindowManager = require('__poly__.GUI.WindowManager')
local Window = require('__poly__.GUI.Window')

-- require Poly's Component API
local Component = require('__poly__.GUI.Component')

-- require Poly's pre-implemented components for frame, flow, button, sprite-button, empty-widget and label
local Frame = require('__poly__.GUI.Factorio.Frame')
local Flow = require('__poly__.GUI.Factorio.Flow')
local Button = require('__poly__.GUI.Factorio.Button')
local SpriteButton = require('__poly__.GUI.Factorio.SpriteButton')
local EmptyWidget = require('__poly__.GUI.Factorio.EmptyWidget')
local Label = require('__poly__.GUI.Factorio.Label')

-- require Poly's EventHandler API
local EventHandler = require('__poly__.GUI.EventHandler')

-- require custom SpinnerLabel component
local SpinnerLabel = require('SpinnerLabel')

-- require custom CaptionDialog
local CaptionDialog = require('CaptionDialog')


-- function for initializing a mod button and counter GUI for the given player
-- this will be called when the mod is initialized or a new player joins
local function create_counter_gui(player)
    -- initialize player's counter GUI and store it in global
    global.counter_guis[player.index] = Window:new {
        -- configure window's titlebar (don't delete window when closing, because we want to keep it in global)
        titlebar = { title = 'Counter', delete_on_close = false },

        -- add content to the window
        Frame:new {
            name = 'content',
            direction = 'horizontal',
            style = { 'inside_shallow_frame_with_padding' },

            Flow:new {
                name = 'counter',
                style = 'player_input_horizontal_flow',

                Label:new { name = 'counter_caption', caption = 'My Counter' },
                -- add button for opening CaptionDialog (its event handler directly calls WindowManager:open)
                SpriteButton:new { style = 'tool_button', sprite = 'utility/rename_icon_normal',
                                   on_gui_click = EventHandler:register(WindowManager, 'open',
                                   -- WindowManager:open's arguments:
                                           WindowManager.Anchor.screen(player), CaptionDialog) },
                EmptyWidget:new { style = { width = 12 } },
                SpinnerLabel:new { name = 'counter_value', initial_value = 0 }
            }
        }
    }

    -- create player's mod button for opening/closing the counter GUI
    local mod_button = Button:new {
        caption = 'C',
        style = mod_gui.button_style,
        on_gui_click = EventHandler:register(nil, 'toggle_counter_gui', global.counter_guis[player.index])
    }
    mod_button:create(mod_gui.get_button_flow(player))
end

-- create global event handler for toggling counter GUI
function toggle_counter_gui(counter_window, event)
    local player = game.get_player(event.player_index)
    -- depending on counter GUIs state, either open or close it
    if counter_window:get_state() == Component.State.Created then
        -- close counter GUI, but don't delete it
        WindowManager:close(counter_window, false)
    else
        -- open counter GUI
        WindowManager:open(WindowManager.Anchor.screen(player), counter_window)
    end
end

-- create counter GUI for all players when the mod is initialized
script.on_init(function(event)
    global.counter_guis = {}
    for _, player in pairs(game.players) do
        create_counter_gui(player)
    end
end)
-- create counter GUI for newly joined players
script.on_event(defines.events.on_player_created, function(event)
    local player = game.get_player(event.player_index)
    create_counter_gui(player)
end)