aperx/factorio-scenario-ExpCluster
1
0
Fork 0
mirror of https://github.com/PHIDIAS0303/ExpCluster.git synced 2025-12-27 11:35:22 +09:00
Code Issues Packages Projects Releases Wiki Activity

Refactor some of the Guis from the legacy plugin (#399)

Browse Source 
* Fix bugs in core and add default args to Gui defs

* Refactor production Gui

* Refactor landfill blueprint button

* Fix more bugs in core

* Consistent naming of new guis

* Refactor module inserter gui

* Refactor surveillance gui

* Add shorthand for data from arguments

* Make element names consistent

* Add types

* Change how table rows work

* Refactor player stats gui

* Refactor quick actions gui

* Refactor research milestones gui

* Refactor player bonus gui

* Refactor science production gui

* Refactor autofill gui

* Cleanup use of aligned flow

* Rename "Gui.element" to "Gui.define"

* Rename Gui types

* Rename property_from_arg

* Add guide for making guis

* Add full reference document

* Add condensed reference

* Apply style guide to refactored guis

* Bug fixes
This commit is contained in:
Cooldude2606
2025-08-29 14:30:30 +01:00
committed by GitHub
parent e2a7ab7b8b
commit 7ab721b4b6
72 changed files with 6736 additions and 4105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
exp_gui/docs/motivation.md Normal file
View File

@@ -0,0 +1,203 @@
# Design motivation
This document outlines why I created this framework, and the reasoning behind some of the opinionated decisions that shaped its design.
The motivation came from my experience with existing libraries, which often enforced a strict separation between element definitions, event handling, and GUI-related data.
In many cases, these libraries focused solely on element creation, leaving developers to manually manage event filtering and data scoping themselves.
I found that approach cumbersome and unintuitive.
I believed there was a better way, one that embraced a different kind of encapsulation, making the conceptual model easier to understand and work with.
And so I created a framework with four distinct and independent parts that all come together with a sense of locality not seen in our libraries.
Additionally, the guide places greater emphasis on naming conventions and calling patterns, rather than just listing what each function does.
These conventions are key to how the framework is expected to be used and are intended to make development feel more cohesive and intuitive.
At the heart of the framework are four core concepts that bring everything together:
## ExpElement
ExpElement serves as the prototype for all element definitions.
It's intentionally designed as a wrapper around LuaGuiElement.add and associated event handlers.
It takes in definition tables and functions, and returns a function that can be used to create a LuaGuiElement.
This focused purpose makes it easier to reason about.
It also reduces boilerplate, allowing you to concentrate on functionality rather than repetitive setup.
You can optionally add methods to the definition, such as `add_row` or `refresh`.
While these could technically be local functions, including them directly in the definition makes it immediately clear which data they interact with or modify.
This enhances both readability and maintainability.
For example, the following two snippets are conceptually equivalent:
```lua
Elements.my_label = Gui.define("my_label")
:draw{
type = "label",
caption = "Hello, World!",
}
:style{
font_color = { r = 1, g = 0, b = 0 },
width = Gui.from_argument(1),
}
:element_data{
foo = "bar"
}
:on_click(function(def, player, element, event)
element.caption = "Clicked!"
end)
function Elements.my_label.reset(my_label)
my_label.caption = "Hello, World!"
end
```
```lua
local my_label_data = GuiData.create("my_label")
function Elements.my_label(parent, width)
-- :draw
local element = parent.add{
type = "label",
caption = "Hello, World!",
}
-- :style
local style = element.style
style.font_color = { r = 1, g = 0, b = 0 }
style.width = width
-- :element_data
my_label_data[element] = {
foo = "bar"
}
-- event handlers
local tags = element.tags or {}
local event_tags = tags.event_tags or {}
event_tags[#event_tags + 1] = "my_label"
element.tags = tags
return element
end
local function my_label_reset(my_label)
my_label.caption = "Hello, World!"
end
local function on_gui_click(event)
local element = event.element
if is_my_label(element) then -- pseudo function to check event_tags
element.caption = "Clicked!"
end
end
```
In the example, I use table-style definitions, which are the most common approach for simple elements and are encouraged wherever possible.
Internally, these tables are converted into draw functions, which can also be passed directly if needed.
You could, of course, write everything into a single "create" function, or even place all logic inside a `:draw` method, but maintaining a separation between these responsibilities serves as a form of clear signposting.
This improves readability and makes the structure of your code easier to follow at a glance.
```lua
Elements.my_label = Gui.define("my_label")
:draw(function(def, parent, width)
return parent.add{
type = "label",
caption = "Hello, World!",
}
end)
:style(function(def, element, parent, width)
return {
font_color = { r = 1, g = 0, b = 0 },
width = width,
}
end)
:element_data(function(def, element, parent, width)
return {
foo = "bar"
}
end)
:on_click(function()
print("Clicked!")
end)
```
## GuiData
Building on the goal of keeping GUI data close to where it’s used and displayed, I introduced `GuiData`, which is integrated as `ExpElement.data`.
Like the other components, its purpose is focused and singular, and it can even be used standalone if it's the only part of the framework you find useful.
In simple terms, GuiData creates a table in `storage` with a custom `__index` metamethod that enables automatic scoping of data.
It also cleans up data when the associated key is destroyed, helping to reduce unnecessary memory usage.
One common use case, explained earlier in this guide, is storing references to other elements.
This approach removes the tight coupling between event handlers and the GUI structure by giving handlers direct access to what they need.
Additionally, it encourages you to make assumptions explicit by requiring references as arguments.
While this pattern can take some getting used to, it makes dependencies much easier to identify and reason about.
While this example exposes some of the internal mechanics, it should help you understand the convenience and clarity that scoped data access provides.
```lua
local data = GuiData.create("my_data")
-- data[element] = "foo"
storage.gui_data.scopes["my_data"].element_data[element.player_index][element.index] = "foo"
-- data[player] = "bar"
storage.gui_data.scopes["my_data"].player_data[player.index] = "bar"
-- data[force] = "baz"
storage.gui_data.scopes["my_data"].force_data[force.index] = "baz"
```
## GuiIter
With scoped data easily accessible, it became straightforward to track elements belonging to a specific player, especially for updates or state changes.
However, this pattern became so common (and often cluttered `GuiData`) that I created a dedicated iterator: `GuiIter`.
As with the other modules, GuiIter can be used independently if you like what it offers, or through its integration with ExpElement.
Whenever an element is created, or at any point, really, it can be registered with the iterator for future access.
Retrieval is then handled by applying a filter across all tracked elements, returning them one by one.
Don’t worry, the underlying data structure is designed for efficient lookup and automatic cleanup.
This can be incredibly powerful.
It gives you direct access to GUI elements without having to manually navigate from `player.gui`, and the filtering makes it simple to, for example, target only elements belonging to online players in a specific force.
Below is an example of how GuiIter can be used as a standalone utility:
```lua
local function teammate_counter(player)
local frame = player.gui.left.add{ type = "frame" }
local label = frame.add{ type = "label", caption = tostring(#player.force.players) }
GuiIter.add_element("teammate_counter", label)
end
local function on_player_changed_force(event)
local old_force = event.old_force
local old_force_count = tostring(#old_force.players)
for player, label in GuiIter.get_online_elements("teammate_counter", old_force) do
label.caption = caption
end
local new_force = game.get_player(event.player_index).force
local new_force_count = tostring(#new_force.players)
for player, label in GuiIter.get_online_elements("teammate_counter", new_force) do
label.caption = caption
end
end
```
## Toolbar
While ExpElement ties individual components together into self-contained units, the Toolbar acts as a singleton that manages them all.
From an implementation standpoint, it’s split into two parts: one that handles drawing elements when a player joins, and an optional settings menu named "Toolbox".
The element-drawing functionality is the final piece of the puzzle for eliminating boilerplate and letting you focus on functionality.
You simply register an element at a given location, and it gets drawn automatically on player join, it really is that straightforward.
The optional settings menu provides a standardised way to manage button behaviour, while also giving players control over which buttons are visible.
This was born out of necessity: as the number of GUI modules grew, having all of them visible by default became overwhelming.
The settings menu solves that by letting players hide modules they don’t need.
![toolbox](./docs/toolbox.png)

457
exp_gui/docs/reference.md Normal file
View File

@@ -0,0 +1,457 @@
# ExpGui API Reference
This is a streamlined version of the API reference, highlighting the methods you're most likely to use day-to-day.
It includes extra detail and practical examples to help you get up and running quickly.
If you haven’t already, we recommend starting with the [framework guide](../readme.md).
It lays the groundwork and gives you the context you’ll need to understand how these methods work together.
A [full reference](./reference_full.md) is also available.
But if you plan to rely on it, we strongly suggest reviewing and familiarizing yourself with the underlying implementation of the functions.
## Utility Functions
These helper methods are designed to simplify common tasks when working with GUI elements, like toggling states or safely destroying elements.
### `Gui.get_player`
Retrieves the player associated with a given context. This can be:
- A LuaGuiElement
- An event containing `event.player_index`
- An event containing `event.element`
The method includes a not-nil assertion to handle rare cases where a player might have become invalid.
### `Gui.toggle_*_state`
Refers to `Gui.toggle_enabled_state` and `Gui.toggle_visible_state`.
These functions toggle the specified state (either enabled or visible) for a LuaGuiElement, and return the new state after toggling.
If you provide a second argument (true or false), the function becomes `set_*_state` and sets the state directly instead of toggling.
Each function checks if the element is non-nil and still valid before performing any action.
If those checks fail, nothing happens.
### `Gui.destroy_if_valid`
Destroys a given LuaGuiElement, but only if it exists and is valid.
If either condition is not met, the function exits quietly without performing any action.
## Element Definations
This section covers how to define, register, and manage GUI elements using the framework.
These definitions form the foundation of how your GUI behaves, persists, and responds to player interaction.
### `Gui.define`
All GUI elements begin with a call to `Gui.define`, where you provide a unique name for your element.
This name only needs to be unique within your own mod or module.
When you're first setting up a GUI, you may not know its full structure right away.
In these cases, it can be useful to use `:empty()` child elements until you are ready to define them.
```lua
Elements.my_button = Gui.define("my_button")
:empty()
```
### `Gui.add_*_element`
Refers to `Gui.add_top_element`, `Gui.add_left_element`, and `Gui.add_relative_element`.
These functions register a root element to a GUI flow, ensuring it’s created for all players when they join.
Once registered, the framework takes ownership of the element’s lifetime, guaranteeing that it always exists.
This makes them ideal entry points for GUIs that maintain persistent state.
You can retrieve the created instance using `Gui.get_*_element`, passing in the definition as the first argument.
From there, you can perform operations like [`Gui.toggle_visible_state`](#guitoggle__state) or apply custom logic.
If you're using the Toolbar or GuiIter, you likely won’t need to manually retrieve your element at all.
For example, the Toolbar provides convenience methods like [`Toolbar.get_left_element_visible_state`](#guitoolbarset_left_element_visible_state) and [`Toolbar.set_button_toggled_state`](#guitoolbarset_button_toggled_state), both of which accept your element definition directly.
### `ExpElement:draw`
When you're ready to define an element, the first required step is to call `:draw()`.
This method accepts either:
- A table that defines the GUI structure
- A function that returns a LuaGuiElement
Using a table is encouraged and it supports dynamic values via `Gui.from_argument`, allowing you to pass data through arguments easily.
While this doesn't cover every use case, it handles the majority of common needs.
```lua
Elements.my_label = Gui.define("my_label")
:draw{
caption = Gui.from_argument(1),
style = "heading_2_label",
}
```
For elements with many optional values, it's recommended to use an "options" table.
Simply provide named keys instead of using array indexes.
The options table is always assumed to be the final argument, so required values can still be passed by index.
You can also define default values.
```lua
Elements.my_camera = Gui.define("my_camera")
:draw{
surface_index = Gui.from_argument(1),
position = Gui.from_argument("position", { 0, 0 }),
zoom = Gui.from_argument("zoom"),
}
```
When an element is a composite of other elements, i.e. it has children, then you need to use the function defination method.
This is because child elements may need arguments to be supplied to them which is more easily done in a function body rather than inventing a new table syntax.
Your draw function should always return the most "meaningful" LuaGuiElement, this can mean: the element that raises events, the element that children should be added to, or the root element for those registered to a gui flow (top / left / relative).
If multiple of these conditions apply to different children then you will need to look into manually calling `:link_element` for event handling or clearly document where children should be added by callers.
If none of these apply, then consider if you should be using an element defination at all, if you must then you can return `Gui.no_return`.
If your element is a composite (i.e. it contains child elements), then using a function is required.
This is because you may need to pass arguments to children which is more cleanly done in a function body rather than a complex table structure.
Your draw function should return the most “meaningful” LuaGuiElement. This might be:
- The element that raises GUI events
- The element where children should be added
- The root element registered to a GUI flow (top, left, or relative)
If these responsibilities apply to different children, you’ll need to either manually link elements to events using `:link_element` or document clearly where children should be added by callers.
If none of these conditions apply, consider whether a standalone element definition is appropriate.
If you still need one, you can return `Gui.no_return`.
```lua
Elements.my_frame = Gui.define("my_Frame")
:draw(function(def, parent)
local player = Gui.get_player(parent)
local frame = parent.add{ type = "frame" }
Elements.my_button(frame)
Element.my_label(frame, "Hello, " .. player.name)
Element.my_camera(frame, player.surface.index, {
zoom = 0.5,
})
return frame
end)
Elements.no_return = Gui.define("no_Return")
:draw(function(def, parent)
return Gui.no_return()
end)
```
### `ExpElement:style`
This method defines the style of your element, and is very similar to `:draw`.
Styling is only applied to the element returned from `:draw`.
If you use a function to define styles, the signature is `fun(def, element, parent)`.
If you return a table from this function, it should mimic the structure of a LuaStyle object.
However, you are not required to return anything.
You can also apply styles directly to the element, which is useful for read-only properties like `LuaStyle.column_alignments`.
```lua
Elements.my_label_big = Gui.define("my_label_big")
:draw{
caption = Gui.from_argument(1),
style = "heading_2_label",
}
:style{
width = 400,
}
Elements.right_aligned_numbers = Gui.define("right_aligned_numbers")
:draw{
caption = Gui.from_argument(1),
}
:style(function(def, element, parent, caption)
return {
width = 400,
horizontal_align = tonumber(caption) and "right" or "left"
}
end)
```
### `ExpElement:*_data`
Refers to `ExpElement:element_data`, `ExpElement:player_data`, `ExpElement:force_data`, and `ExpElement:global_data`; standlone use of `GuiData` is not covered.
These methods initialize GUI-related data within your element definition.
You can access the data later through `ExpElement.data`, or more commonly as `def.data` in event handlers.
If you pass a non-function value, it will be deep-copied to create the initial data (if it does not already exist).
If you pass a function, it will be called to either mutate existing data or return a new value to be used as the inital data.
For complex data structures, especially those involving references to child elements, it’s often better to assign data directly inside your `:draw` method.
Keep in mind that initializers do not run until after `:draw` completes, so you cannot rely on data being in a consistent state during draw.
```lua
Elements.my_primaitve_data = Gui.define("my_primaitve_data")
:empty()
:element_data(0)
Elements.my_table_data = Gui.define("my_table_data")
:empty()
:element_data{
count = 0,
}
Elements.my_function_data = Gui.define("my_function_data")
:empty()
:element_data(function(def, element, parent)
return {
seed = math.random()
}
end)
Elements.shared_counter = Gui.define("shared_counter")
:draw(function(def, parent)
local player = Gui.get_player(parent)
local count = def.data[player.force] or 0
return parent.add{
type = "button",
caption = tostring(count),
}
end)
:force_data(0)
:on_click(function(def, player, element, event)
local old_count = def.data[player.force]
local new_count = old_count + 1
def.data[player.force] = new_count
element.caption = tostring(new_count)
end)
Elements.composite = Gui.define("composite")
:draw(function(def, parent)
local frame = parent.add{ type = "frame" }
def.data[frame] = {
shared_counter = Elements.shared_counter(frame),
label = frame.add{ type = "label" },
}
return frame
end)
```
### `ExpElement:on_*`
Refers to all gui events and `ExpElement:on_event` for other arbitary events.
Gui events are converted from `on_gui_` to `on_` for examplse `on_gui_clicked` to `on_clicked`.
These methods allow you to attach event handlers to your element definition.
For general `on_event` usage, there’s no extra filtering, the handler will be called when the event occurs.
For GUI-specific events, the handler is only called for linked elements.
Handlers are automatically linked to any element returned from `:draw`.
You can manually link other elements using `:link_element`.
If you want to prevent an element from being linked automatically, you can call and return `:unlink_element`.
However, needing to do this might suggest a misalignment in how your functions responsibilities are structured.
In the example below, it would be best practice to introduce `Elements.title_label` which has an `on_click` handler.
```lua
Elements.my_clickable_button = Gui.define("my_clickable_button")
:draw{
type = "button",
caption = "Click Me",
}
:on_click(function(def, player, element, event)
player.print("Clicked!")
end)
Elements.my_clickable_title = Gui.define("my_clickable_title")
:draw(function(def, parent)
local frame = parent.add{ type = "frame" }
local title = frame.add{ type = "label", caption = "Click Me" }
def:link_element(title)
return def:unlink_element(frame)
end)
:on_click(function(def, player, element, event)
player.print("The title was clicked!")
end)
```
### `ExpElement:track_all_elements`
The most common use of the GUI iterator is to track all created elements.
Therefore `track_all_elements` was added which will track every element that is returned from your draw function.
You can also manually track additional elements with `:track_element`, and you can exclude elements from tracking using `:untrack_element`.
```lua
Elements.my_tracked_label = Gui.define("my_tracked_label")
:track_all_elements()
:draw{
type = "label",
caption = "Im tracked by GuiIter",
}
Element.my_tracked_children = Gui.define("my_tracked_children")
:draw(function(def, parent)
local frame = parent.add{ type = "frame" }
def:track_element(frame.add{ type = "label", caption = "Im tracked 1" })
def:track_element(frame.add{ type = "label", caption = "Im tracked 2" })
def:track_element(frame.add{ type = "label", caption = "Im tracked 3" })
return frame
end)
Elements.my_sometimes_tracked_label = Gui.define("my_sometimes_tracked_label")
:track_all_elements()
:draw(function(def, parent)
local player = Gui.get_player(parent)
if player.admin then
return parent.add{ type = "label", caption = "Im tracked" }
end
return def:untrack_element(parent.add{ type = "label", caption = "Im tracked" })
end)
```
## Gui Iterator
Refers to `ExpElement:tracked_elements` and `ExpElement:online_elements`; standalone use of `GuiIter` is not covered.
Once an element has been tracked using `:track_all_elements` or `:track_element`, it can be iterated over using these custom GUI iterators.
Each method accepts an optional filter parameter, which can be: LuaPlayer, LuaForce, or an array of LuaPlayer.
As their names suggest, `:tracked_elements` returns all tracked elements while `:online_elements` limits the results to online players only.
If you're caching data per force, it is more efficient to use a single unfiltered iteration rather than multiple filtered ones.
The naming convention to be followed is:
- `refresh` when the first argument is an instance of the element.
- `refresh_all` when there using `:tracked_elements` without a filter.
- `refresh_online` when there using `:online_elements` without a filter.
- `refresh_*` when there using `:tracked_elements` with a filter, e.g. `refresh_force`.
- `refresh_*_online` when there using `:online_elements` with a filter, e.g. `refresh_force_online`.
- `update` can be used when the new state is dependend on the old state, e.g. incrementing a counter.
- `reset` can be used when the element has a default state it can be returned to.
- `save` can be used when the current state is stored in some way.
- `*_row` when the action applies to a row within a table rather than an element.
- The name does not indicate if a cache is used, this is because a cache should be used where possible.
```lua
function Elements.my_tracked_label.calculate_force_data(force)
return {
caption = "I was refreshed: " .. force.name,
}
end
function Elements.my_tracked_label.refresh_all()
for player, element in Elements.my_tracked_label:tracked_elements() do
element.caption = "I was refreshed"
end
end
function Elements.my_tracked_label.refresh_online()
for player, element in Elements.my_tracked_label:online_elements() do
element.caption = "I was refreshed: online"
end
end
function Elements.my_tracked_label.refresh_force(force)
local force_data = Elements.my_tracked_label.calculate_force_data(force)
for player, element in Elements.my_tracked_label:tracked_elements(force) do
element.caption = force_data.caption
end
end
-- a different implimention of refresh all with a force cache
function Elements.my_tracked_label.refresh_all()
local _force_data = {}
for _, force in pairs(game.forces) do
_force_data[force.name] = Elements.my_tracked_label.calculate_force_data(force)
end
for player, element in Elements.my_tracked_label:tracked_elements() do
local force_data = _force_data[player.force.name]
element.caption = force_data.caption
end
end
-- a different implimention of refresh online with a force cache
function Elements.my_tracked_label.refresh_online()
local _force_data = {}
for _, force in pairs(game.forces) do
if next(force.connected_players) then
_force_data[force.name] = Elements.my_tracked_label.calculate_force_data(force)
end
end
for player, element in Elements.my_tracked_label:online_elements() do
local force_data = _force_data[player.force.name]
element.caption = force_data.caption
end
end
```
## Toolbar
The toolbar API provides convenience methods for adding toggleable buttons and syncing them with GUI elements in the left flow.
This is especially useful for building persistent interfaces.
### `Gui.toolbar.create_button`
Creates a new button on the toolbar, with the option to link it to an element defined in the left flow.
This method also creates a new element definition for the button, so the provided name must be unique within your mod or module.
You can attach event handlers (such as `on_click` or `on_button_toggled`) to the button as needed.
If a left-side element definition is provided, the button is automatically set to toggle the visibility of that element when clicked.
The button type is set automatically based on the presence of a `sprite` option.
If `sprite` is defined, it creates a sprite button; otherwise, a standard button is used.
```lua
Gui.toolbar.create_button{
name = "click_me",
caption = "Click Me!",
}
:on_click(function(def, player, element, event)
player.print("Clicked!")
end)
Elements.toggle_me =
Gui.toolbar.create_button{
name = "toggle_me",
caption = "Toggle Me!",
auto_toggle = true,
}
:on_button_toggled(function(def, player, element, event)
player.print("I am now: " .. event.state)
end)
Gui.add_left_element(Elements.my_frame)
Gui.toolbar.create_button{
name = "toggle_my_frame",
caption = "Toggle Me!",
left_element = Elements.my_frame,
}
```
### `Gui.toolbar.set_button_toggled_state`
Sets the toggled state of a toolbar button, keeping it in sync with a linked left-side element if one is defined.
The element definition must have been previously returned by `create_button`.
If a state argument is not given then this becomes `toggle_button_toggled_state`.
This method does not raise `on_click`; instead, it raises `on_button_toggled`
```lua
Gui.toolbar.set_button_toggled_state(Elements.toggle_me, true)
```
### `Gui.toolbar.set_left_element_visible_state`
Sets the visibility state of a left-flow GUI element, and updates the state of a linked toolbar button if one is defined.
The element definition must have been previously passed to `Gui.add_left_element`.
If a state argument is not given then this becomes `toggle_left_element_visible_state`.
When a toolbar button is linked, this method also raises `on_button_toggled` for that button to reflect the change.
```lua
Gui.toolbar.set_button_toggled_state(Elements.my_frame, true)
```

485
exp_gui/docs/reference_full.md Normal file
View File

@@ -0,0 +1,485 @@
# ExpGui Full API Reference
If you haven’t already, please read the [framework guide](../readme.md) and [condensed reference](./reference.md) first, this full reference won’t be very useful without that context.
Additionally, if you find yourself needing to rely heavily on this document, I strongly recommend reading the actual implementation of each function.
It will give you a far better understanding than the limited comments provided here.
[Pre-defined elements](../module/elements.lua), [styles](../module/styles.lua), and elements defined by the toolbar are not included in this reference.
## Control ([`control.lua`](../module/control.lua))
It is expected this file is required as `modules/exp_gui` and is assigned to the variable `Gui`.
### `Gui.define`
This is a reference to [`ExpElement.new`](#expelementnew)
It creates new element definations.
The name provided must be unqiue to your mod.
### `Gui.from_argument`
This is a reference to [`ExpElement.from_argument`](#expelementfrom_argument)
It is used within defiantion tables (draw, style, and data) to use a value from an argument.
The argument can be named or positional, and a default value can be provided.
### `Gui.from_name`
This is a reference to [`ExpElement.from_name`](#expelementfrom_name)
It is used within defiantion tables (draw, style, and data) to use a value from the defination name. The most common use case is `name = Gui.from_name` within a draw table.
### `Gui.no_return`
This is a reference to [`ExpElement.no_return`](#expelementno_return)
It is used exclusively within [`ExpElement:draw`](#expelementdraw) to signal the intental lack of a return value.
### `Gui.top_elements`
This is a table of all registered elements for the top flow.
The keys are ExpElement and the values are the default visibltiy callback / boolean.
### `Gui.left_elements`
This is a table of all registered elements for the left flow.
The keys are ExpElement and the values are the default visibltiy callback / boolean.
### `Gui.relative_elements`
This is a table of all registered elements for relative locations.
The keys are ExpElement and the values are the default visibltiy callback / boolean.
### `Gui.get_top_flow`
This is a reference to `mod_gui.get_button_flow`
It gets the flow where top elements are added to.
### `Gui.get_left_flow`
This is a reference to `mod_gui.get_frame_flow`
It gets the flow where left elements are added to.
### `Gui._debug`
After this function is called, all players GUIs will be redrawn every join.
This is helpful for structure and style debugging.
### `Gui.get_player`
A version of `game.get_player` that accepts LuaGuiElement and events containing `event.element` as a property.
### `Gui.toggle_enabled_state`
Toggles the enabled state of the passed LuaGuiElement.
It will return the new enabled state.
The second argument makes this `set_enabled_state`
### `Gui.toggle_visible_state`
Toggles the visible state of the passed LuaGuiElement.
It will return the new visible state.
The second argument makes this `set_visible_state`
### `destroy_if_valid`
Destories the passed LuaGuiElement.
Does nothing if the element is nil or an invalid reference.
### `Gui.add_top_element`
Registers an ExpElement to be drawn on the top flow.
The second argument is the default visible state, which can be a function.
### `Gui.add_left_element`
Registers an ExpElement to be drawn on the left flow.
The second argument is the default visible state, which can be a function.
### `Gui.add_relative_element`
Registers an ExpElement to be drawn relative to a core GUI.
The second argument is the default visible state, which can be a function.
The core gui is defined with `:draw{ anchor: GuiAnchor }`
### `Gui.get_top_element`
Returns the LuaGuiElement for the passed ExpElement.
Errors if the element is not registered to the top flow.
### `Gui.get_left_element`
Returns the LuaGuiElement for the passed ExpElement.
Errors if the element is not registered to the left flow.
### `Gui.get_relative_element`
Returns the LuaGuiElement for the passed ExpElement.
Errors if the element is not registered to the relative flow.
### `Gui._ensure_consistency`
If for any reason registered elements need to be redrawn, this method will handle it.
One example is updates within a custom permission system.
## Gui Data ([`data.lua`](../module/data.lua))
It is expected this file is required as `modules/exp_gui/data` and is assigned to the variable `GuiData`.
Alternativly, instances of GuiData exist on all ExpElements as `ExpElement.data`.
### `GuiData:__index`
No data is directly stored within an instance of GuiData, instead `__index` will be called and fetch the data from `GuiData._raw`.
Currently accepted indexes are: LuaGuiElement, LuaPlayer, LuaForce, and "global_data".
### `GuiData:__newindex`
No data is directly stored within an instance of GuiData, instead `__newindex` will be called and store the data in `GuiData._raw`.
Currently accepted indexes are: LuaGuiElement, LuaPlayer, LuaForce.
Setting "global_data" is not supported, although settings keys of "global_data" is permitted.
### `GuiData.create`
Creates a new instance of GuiData with a given scope.
Only a single instance can exist for any scope, use [`GuiData.get`](#guidataget) to retrive existing instances.
### `GuiData.get`
Retrives and existing instance of GuiData for a given scope.
Only use this if you have a circular dependency, otherwise you should be passing by reference.
## Gui Iter ([`iter.lua`](../module/iter.lua))
It is expected this file is required as `modules/exp_gui/iter` and is assigned to the variable `GuiIter`.
Alternativly, references to GuiIter exist on all ExpElements as `ExpElement:track_element`, `ExpElement:untrack_element`, `ExpElement:tracked_elements`, `ExpElement:online_elements`, and `ExpElement:track_all_elements`
### `GuiIter.player_elements`
Iterates all elements for a single player in a given scope.
The returned tupple is `LuaPlayer, LuaGuiElement`.
### `GuiIter.filtered_elements`
Iterates all elements for the provided players in a given scope.
The returned tupple is `LuaPlayer, LuaGuiElement`.
This method is named "filtered" because it is expected that the player list provided has been filtered on some condition and only elements for players in this list are returned.
The optional third argument can be provided to filter to online only if you have not done so yourself.
### `GuiIter.all_element`
Iterates all elements for all players in a given scope.
The returned tupple is `LuaPlayer, LuaGuiElement`.
### `GuiIter.get_tracked_elements`
Iterates all elements for all players in a given scope who pass the provided filter.
The returned tupple is `LuaPlayer, LuaGuiElement`.
The accepted filters are: nil, LuaPlayer, LuaPlayer[], and LuaForce.
Functions are NOT supported, instead pass an array of players you have pre-filtered.
### `GuiIter.get_online_elements`
Iterates all elements for online players in a given scope who pass the provided filter.
The returned tupple is `LuaPlayer, LuaGuiElement`.
The accepted filters are: nil, LuaPlayer, LuaPlayer[], and LuaForce.
Functions are NOT supported, instead pass an array of players you have pre-filtered.
### `GuiIter.add_element`
Adds an element to be tracked within a scope.
Elements can be tracked in multiple scopes.
### `GuiIter.remove_element`
Remove an element from a scope.
Does nothing if the element was not tracked.
Elements are automatically removed when destoryed.
## ExpElement ([`prototype.lua`](../module/prototype.lua))
It is expected this file is required as `modules/exp_gui/prototype` and is assigned to the variable `ExpElement`.
Alternativly, instances of ExpElement can be created with [`Gui.define`](#guidefine).
### `ExpElement.no_return`
It is used exclusively within `ExpElement:draw` to signal the intental lack of a return value.
Also accessible through [`Gui.no_return`](#guino_return)
### `ExpElement.from_name`
It is used within defiantion tables (draw, style, and data) to use a value from the defination name.
Also accessible through [`Gui.from_name`](#guifrom_name)
### `ExpElement.from_argument`
It is used within defiantion tables (draw, style, and data) to use a value from an argument.
The argument can be named or positional, and a default value can be provided.
Also accessible through [`Gui.from_argument`](#guifrom_argument)
### `ExpElement.new`
It creates new element definations.
The name provided must be unqiue to your mod.
Also accessible through [`Gui.define`](#guidefine)
### `ExpElement.get`
Gets the existing ExpElement with the given name.
Only use this if you have a circular dependency, otherwise you should be passing by reference.
### `ExpElement:create`
Creates a LuaGuiElement following the element defination.
Also accessible through `__call` allowing direct calls of this table to create an element.
Order of operations is: [draw](#expelementdraw), [style](#expelementstyle), [element_data](#expelementelement_data), [player_data](#expelementplayer_data), [force_data](#expelementforce_data), [global_data](#expelementglobal_data), [track_element](#expelementtrack_element), [link_element](#expelementlink_element).
### `ExpElement:track_all_elements`
When called, `ExpElement:track_element` will be called for all elements at the end of [`ExpElement:create`](#expelementcreate)
### `ExpElement:empty`
Defines [`ExpElement:draw`](#expelementdraw) as an empty flow.
This is intended to be used when you are first setting up the structure of your gui.
When used warnings will be logged, do not rely on this when you want an empty flow.
### `ExpElement:draw`
Defines the draw function for you element defination.
Successive calls will overwrite previous calls.
Accepts either a table to be passed to `LuaGuiElement.add` or a function that returns a LuaGuiElement.
### `ExpElement:style`
Defines the style function for you element defination.
Successive calls will overwrite previous calls.
Accepts either a table with key values equlaient to LuaStyle, or a function that can return this table, or [`ExpElement:from_argument`](#expelementfrom_argument).
### `ExpElement:element_data`
Defines the element data init function for you element defination.
Successive calls will overwrite previous calls.
Accepts any non-function value to deep copy, or a function that can return this value, or [`ExpElement:from_argument`](#expelementfrom_argument).
When a non-function value is used or returned, it will not overwrite existing data.
If you want this behaviour then modify the data directly in your function rather than returning a value.
### `ExpElement:player_data`
Defines the player data init function for you element defination.
Successive calls will overwrite previous calls.
Accepts any non-function value to deep copy, or a function that can return this value, or [`ExpElement:from_argument`](#expelementfrom_argument).
When a non-function value is used or returned, it will not overwrite existing data.
If you want this behaviour then modify the data directly in your function rather than returning a value.
### `ExpElement:force_data`
Defines the force data init function for you element defination.
Successive calls will overwrite previous calls.
Accepts any non-function value to deep copy, or a function that can return this value, or [`ExpElement:from_argument`](#expelementfrom_argument).
When a non-function value is used or returned, it will not overwrite existing data.
If you want this behaviour then modify the data directly in your function rather than returning a value.
### `ExpElement:global_data`
Defines the global data init function for you element defination.
Successive calls will overwrite previous calls.
Accepts only a table value to deep copy, or a function that can return a table, or [`ExpElement:from_argument`](#expelementfrom_argument).
When a table is used or returned, it will not overwrite existing data.
If you want this behaviour then modify the data directly in your function rather than returning a table.
### `ExpElement:tracked_elements`
A proxy call to [`GuiIter.get_tracked_elements`](#guiiterget_tracked_elements) with the scope pre-populated.
### `ExpElement:online_elements`
A proxy call to [`GuiIter.get_online_elements`](#guiiterget_online_elements) with the scope pre-populated.
### `ExpElement:track_element`
A proxy call to [`GuiIter.add_element`](#guiiteradd_element) with the scope pre-populated.
### `ExpElement:untrack_element`
A proxy call to [`GuiIter.remove_element`](#guiiterremove_element) with the scope pre-populated.
If returned from a draw function then [`ExpElement:track_all_elements`](#expelementtrack_all_elements) is ignored.
### `ExpElement:link_element`
Links an element to this define in order to trigger event handlers.
Should only be used to link additional elements because elements returned from draw are linked automatically.
### `ExpElement:unlink_element`
Unlinks an element from this define in order to prevent event handlers triggering.
If returned from a draw function then automatic linking will be prevented.
### `ExpElement:raise_event`
Raise an event on this define.
This can be useful for defering events to other definiations or for raising custom events.
### `ExpElement:on_event`
Allows connecting to arbitary events.
Multiple handlers are supported.
### `ExpElement:on_checked_state_changed`
Connects a handler to `defines.events.on_gui_checked_state_changed`.
### `ExpElement:on_click`
Connects a handler to `defines.events.on_gui_click`.
### `ExpElement:on_closed`
Connects a handler to `defines.events.on_gui_closed`.
### `ExpElement:on_confirmed`
Connects a handler to `defines.events.on_gui_confirmed`.
### `ExpElement:on_elem_changed`
Connects a handler to `defines.events.on_gui_elem_changed`.
### `ExpElement:on_hover`
Connects a handler to `defines.events.on_gui_hover`.
### `ExpElement:on_leave`
Connects a handler to `defines.events.on_gui_leave`.
### `ExpElement:on_location_changed`
Connects a handler to `defines.events.on_gui_location_changed`.
### `ExpElement:on_opened`
Connects a handler to `defines.events.on_gui_opened`.
### `ExpElement:on_selected_tab_changed`
Connects a handler to `defines.events.on_gui_selected_tab_changed`.
### `ExpElement:on_selection_state_changed`
Connects a handler to `defines.events.on_gui_selection_state_changed`.
### `ExpElement:on_switch_state_changed`
Connects a handler to `defines.events.on_gui_switch_state_changed`.
### `ExpElement:on_text_changed`
Connects a handler to `defines.events.on_gui_text_changed`.
### `ExpElement:on_value_changed`
Connects a handler to `defines.events.on_gui_value_changed`.
## Toolbar ([`toolbar.lua`](../module/toolbar.lua))
It is expected this file is required as `modules/exp_gui/toolbar` and is assigned to the variable `Toolbar`.
Alternativly, it can be accessed through `Gui.toolbar`.
A point of clarifcation, the "toolbar" in this framework refers to the top flow which may also be refered to as the "favoruites bar", while the "toolbox" is the custom gui for configruing the toolbar.
### `Toolbar.set_visible_state`
Sets the visible state of the toolbar for a player.
If a state is not given then this becomes `toggle_visible_state` and returns the new visible state.
The name difference compared to [`Gui.toggle_visible_state`](#guitoggle_visible_state) despite same beaviour is due to the expected use case for each function.
### `Toolbar.get_visible_state`
Gets the visible state of the toolbar for a player.
### `Toolbar.set_button_toggled_state`
Sets the toggled state for a toolbar button. It is expected that the element define is given not the LuaGuiElement because all instances of a toolbar button should be in sync, and the toolbar does not expose the LuaGuiElement except though [`Gui.get_top_element`](#guiget_top_element).
If a state is not given then this becomes `toggle_button_toggled_state` and returns the new visible state.
### `Toolbar.get_button_toggled_state`
Gets the toggled state for a toolbar button. It is expected that the element define is given not the LuaGuiElement because all instances of a toolbar button should be in sync, and the toolbar does not expose the LuaGuiElement except though [`Gui.get_top_element`](#guiget_top_element).
### `Toolbar.set_left_element_visible_state`
Sets the visible state for a left element. It is expected that the element define is given not the LuaGuiElement because only a single left element can exist, and the toolbar does not expose the LuaGuiElement except though [`Gui.get_left_element`](#guiget_left_element).
If a state is not given then this becomes `toggle_left_element_visible_state` and returns the new visible state.
### `Toolbar.get_left_element_visible_state`
Gets the visible state for a left element. It is expected that the element define is given not the LuaGuiElement because only a single left element can exist, and the toolbar does not expose the LuaGuiElement except though [`Gui.get_left_element`](#guiget_left_element).
### `Toolbar.has_visible_buttons`
Returns true if the player has any visible toolbar buttons.
### `Toolbar.has_visible_left_elements`
Returns true if the player has any visible left elements.
### `Toolbar.create_button`
Creates a new element define representing a toolbar button.
The new button is automaticaly registered to the top flow, has the option to auto toggle, and the option to have a left element linked to it. As this creates a new element define the name provided must be unqiue to your mod.
### `Toolbar.set_state`
Sets the whole state of the toolbar for a player, the value given should be a value previously returned from [`Toolbar.get_state`](#toolbarget_state).
### `Toolbar.get_state`
Gets the whol state of the toolbar for a player which can later be restored with [`Toolbar.set_state`](#toolbarset_state).

BIN
exp_gui/docs/toolbox.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 241 KiB