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
Files
361f9adc4e990eae2080373b719ed670680a8d3f
factorio-scenario-ExpCluster/docs/core/Gui.html
Cooldude2606 361f9adc4e Doc Changes
2019-08-30 23:04:54 +01:00

3805 lines
122 KiB
HTML
Raw Blame History

<!doctype html>
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>Gui core</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="../spectre.min.css" type="text/css" />
<link rel="stylesheet" href="../spectre-icons.min.css" type="text/css" />
<link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>
<div class="container grid-1280">
<div class="columns">
<!-- sidebar start -->
<div id="sidebar" class="column col-3 col-sm-12">
<div class="sidebar-custom">
<div class="project-infobox">
<!-- project title -->
<a href="../index.html"><h1>ExpGaming Scenario</h1></a>
<!-- project description -->
<p class="project-desc">Explosive Gaming's server scenario for 0.17</p>
<!-- project full description -->
</div>
<!-- sidebar navigation -->
<!-- list of items in a module -->
<ul class="nav nav-module-contents">
<li class="nav-item">
<h2>Sections</h2>
<ul class="nav">
<li class="nav-item"><a href="#Elements"><span class="fragment-hashtag">#</span> Elements</a></li>
<li class="nav-item"><a href="#Dropdowns"><span class="fragment-hashtag">#</span> Dropdowns </a></li>
<li class="nav-item"><a href="#Concept_Control"><span class="fragment-hashtag">#</span> Concept Control </a></li>
<li class="nav-item"><a href="#Element_Control"><span class="fragment-hashtag">#</span> Element Control </a></li>
<li class="nav-item"><a href="#Store_Categories"><span class="fragment-hashtag">#</span> Store Categories </a></li>
<li class="nav-item"><a href="#Concept_Base"><span class="fragment-hashtag">#</span> Concept Base </a></li>
<li class="nav-item"><a href="#Concept_Instances"><span class="fragment-hashtag">#</span> Concept Instances </a></li>
<li class="nav-item"><a href="#Concept_Data"><span class="fragment-hashtag">#</span> Concept Data </a></li>
<li class="nav-item"><a href="#Concept_Combined_Instances"><span class="fragment-hashtag">#</span> Concept Combined Instances </a></li>
<li class="nav-item"><a href="#Tests"><span class="fragment-hashtag">#</span> Tests </a></li>
</ul>
</li>
</ul>
<ul class="nav nav-modules">
<li class="nav-item">
<h2>Core</h2>
<ul class="nav">
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../core/Commands.html"><span class="module-name-item">Commands</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../core/Common-Library.html"><span class="module-name-item">Common-Library</span></a></div></li>
<li class="nav-item active"><div class="nav-item-block-active block"><a href="../core/Gui.html"><span class="module-name-item">Gui</span></a><i class="icon icon-arrow-left icon-arrow-left-custom"></i></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../core/Permissions-Groups.html"><span class="module-name-item">Permissions-Groups</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../core/Roles.html"><span class="module-name-item">Roles</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../core/Store.html"><span class="module-name-item">Store</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../core/Sudo.html"><span class="module-name-item">Sudo</span></a></div></li>
</ul>
</li>
</ul>
<ul class="nav nav-modules">
<li class="nav-item">
<h2>Addons</h2>
<ul class="nav">
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Advanced-Start.html"><span class="module-name-item">Advanced-Start</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Chat-Popups.html"><span class="module-name-item">Chat-Popups</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Chat-Reply.html"><span class="module-name-item">Chat-Reply</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Compilatron.html"><span class="module-name-item">Compilatron</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Damage-Popups.html"><span class="module-name-item">Damage-Popups</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Death-Logger.html"><span class="module-name-item">Death-Logger</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Discord-Alerts.html"><span class="module-name-item">Discord-Alerts</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Pollution-Grading.html"><span class="module-name-item">Pollution-Grading</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Player-Colours.html"><span class="module-name-item">Player-Colours</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Scorched-Earth.html"><span class="module-name-item">Scorched-Earth</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../addons/Spawn-Area.html"><span class="module-name-item">Spawn-Area</span></a></div></li>
</ul>
</li>
</ul>
<ul class="nav nav-modules">
<li class="nav-item">
<h2>Commands</h2>
<ul class="nav">
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Admin-Chat.html"><span class="module-name-item">Admin-Chat</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Bonus.html"><span class="module-name-item">Bonus</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Cheat-Mode.html"><span class="module-name-item">Cheat-Mode</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Clear-Inventory.html"><span class="module-name-item">Clear-Inventory</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Debug.html"><span class="module-name-item">Debug</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Find.html"><span class="module-name-item">Find</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Help.html"><span class="module-name-item">Help</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Home.html"><span class="module-name-item">Home</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Interface.html"><span class="module-name-item">Interface</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Jail.html"><span class="module-name-item">Jail</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Kill.html"><span class="module-name-item">Kill</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Me.html"><span class="module-name-item">Me</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Rainbow.html"><span class="module-name-item">Rainbow</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Repair.html"><span class="module-name-item">Repair</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Reports.html"><span class="module-name-item">Reports</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Roles.html"><span class="module-name-item">Roles</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Spawn.html"><span class="module-name-item">Spawn</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Tag.html"><span class="module-name-item">Tag</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Teleport.html"><span class="module-name-item">Teleport</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../commands/Warnings.html"><span class="module-name-item">Warnings</span></a></div></li>
</ul>
</li>
</ul>
<ul class="nav nav-modules">
<li class="nav-item">
<h2>Control</h2>
<ul class="nav">
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../control/Jail.html"><span class="module-name-item">Jail</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../control/Production.html"><span class="module-name-item">Production</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../control/Reports.html"><span class="module-name-item">Reports</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../control/Rockets.html"><span class="module-name-item">Rockets</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../control/Tasks.html"><span class="module-name-item">Tasks</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../control/Warnings.html"><span class="module-name-item">Warnings</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../control/Warps.html"><span class="module-name-item">Warps</span></a></div></li>
</ul>
</li>
</ul>
<ul class="nav nav-modules">
<li class="nav-item">
<h2>Guis</h2>
<ul class="nav">
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../guis/Player-List.html"><span class="module-name-item">Player-List</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../guis/Rocket-Info.html"><span class="module-name-item">Rocket-Info</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../guis/Science-Info.html"><span class="module-name-item">Science-Info</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../guis/Task-List.html"><span class="module-name-item">Task-List</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../guis/Warps-List.html"><span class="module-name-item">Warps-List</span></a></div></li>
</ul>
</li>
</ul>
<ul class="nav nav-modules">
<li class="nav-item">
<h2>Configs</h2>
<ul class="nav">
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/File-Loader.html"><span class="module-name-item">File-Loader</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Player-List.html"><span class="module-name-item">Player-List</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Advanced-Start.html"><span class="module-name-item">Advanced-Start</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Bonuses.html"><span class="module-name-item">Bonuses</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Chat-Reply.html"><span class="module-name-item">Chat-Reply</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Compilatron.html"><span class="module-name-item">Compilatron</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Death-Logger.html"><span class="module-name-item">Death-Logger</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Discord-Alerts.html"><span class="module-name-item">Discord-Alerts</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Commands-Auth-Admin.html"><span class="module-name-item">Commands-Auth-Admin</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Commands-Auth-Roles.html"><span class="module-name-item">Commands-Auth-Roles</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Commands-Auth-Runtime-Disable.html"><span class="module-name-item">Commands-Auth-Runtime-Disable</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Commands-Parse.html"><span class="module-name-item">Commands-Parse</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Commands-Parse-Roles.html"><span class="module-name-item">Commands-Parse-Roles</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Permission-Groups.html"><span class="module-name-item">Permission-Groups</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Pollution-Grading.html"><span class="module-name-item">Pollution-Grading</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Popup-Messages.html"><span class="module-name-item">Popup-Messages</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Preset-Player-Colours.html"><span class="module-name-item">Preset-Player-Colours</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Repair.html"><span class="module-name-item">Repair</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Rockets.html"><span class="module-name-item">Rockets</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Roles.html"><span class="module-name-item">Roles</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Science.html"><span class="module-name-item">Science</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Scorched-Earth.html"><span class="module-name-item">Scorched-Earth</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Spawn-Area.html"><span class="module-name-item">Spawn-Area</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Tasks.html"><span class="module-name-item">Tasks</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Warnings.html"><span class="module-name-item">Warnings</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../configs/Warps.html"><span class="module-name-item">Warps</span></a></div></li>
</ul>
</li>
</ul>
<ul class="nav nav-modules">
<li class="nav-item">
<h2>Modules</h2>
<ul class="nav">
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/control.html"><span class="module-name-item">control</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.alien_evolution_progress.html"><span class="module-name-item">utils.alien_evolution_progress</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.core.html"><span class="module-name-item">utils.core</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.debug.html"><span class="module-name-item">utils.debug</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.dump_env.html"><span class="module-name-item">utils.dump_env</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.event.html"><span class="module-name-item">utils.event</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.event_core.html"><span class="module-name-item">utils.event_core</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.math.html"><span class="module-name-item">utils.math</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.recipe_locker.html"><span class="module-name-item">utils.recipe_locker</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.state_machine.html"><span class="module-name-item">utils.state_machine</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.table.html"><span class="module-name-item">utils.table</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.task.html"><span class="module-name-item">utils.task</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../modules/utils.timestamp.html"><span class="module-name-item">utils.timestamp</span></a></div></li>
</ul>
</li>
</ul>
<ul class="nav nav-modules">
<li class="nav-item">
<h2>Topics</h2>
<ul class="nav">
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../topics/readme.md.html"><span class="module-name-item">readme.md</span></a></div></li>
<li class="nav-item"><div class="nav-item-block-inactive block"><a href="../topics/license.html"><span class="module-name-item">license</span></a></div></li>
</ul>
</li>
</ul>
</div>
<div class="up-to-top">
<!-- list of items in a module -->
<ul class="nav nav-module-contents">
<li class="nav-item">
<h4>Jump to Section</h4>
<ul class="nav">
<li class="nav-item"><a href="#Elements"><span class="fragment-hashtag">#</span> Elements</a></li>
<li class="nav-item"><a href="#Dropdowns"><span class="fragment-hashtag">#</span> Dropdowns </a></li>
<li class="nav-item"><a href="#Concept_Control"><span class="fragment-hashtag">#</span> Concept Control </a></li>
<li class="nav-item"><a href="#Element_Control"><span class="fragment-hashtag">#</span> Element Control </a></li>
<li class="nav-item"><a href="#Store_Categories"><span class="fragment-hashtag">#</span> Store Categories </a></li>
<li class="nav-item"><a href="#Concept_Base"><span class="fragment-hashtag">#</span> Concept Base </a></li>
<li class="nav-item"><a href="#Concept_Instances"><span class="fragment-hashtag">#</span> Concept Instances </a></li>
<li class="nav-item"><a href="#Concept_Data"><span class="fragment-hashtag">#</span> Concept Data </a></li>
<li class="nav-item"><a href="#Concept_Combined_Instances"><span class="fragment-hashtag">#</span> Concept Combined Instances </a></li>
<li class="nav-item"><a href="#Tests"><span class="fragment-hashtag">#</span> Tests </a></li>
</ul>
</li>
</ul>
<a href="#">Top <i class="icon icon-upward"></i></a>
</div>
</div>
<!-- sidebar end -->
<!-- content body start -->
<div class="column col-9 col-sm-12">
<!-- module list on the main page start -->
<!-- module list on the main page end -->
<!-- module contents -->
<!-- module content header start -->
<h2><span class="body-module-name"><strong><em>Gui</em></strong></span> core</h2>
<p>Core Module - Gui</p>
<p></p>
<!-- module info start -->
<!-- module info end -->
<!-- module usage start -->
<h3>Usage</h3>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making the base button concept
</span><span class="keyword">local</span> button =
Gui.new_concept(<span class="string">'Button'</span>)
:new_event(<span class="string">'on_click'</span>,defines.events.on_gui_click)
:new_property(<span class="string">'tooltip'</span>)
:new_property(<span class="string">'caption'</span>,<span class="keyword">nil</span>,<span class="keyword">function</span>(properties,value)
properties.caption = value
properties.sprite = <span class="keyword">nil</span>
properties.<span class="global">type</span> = <span class="string">'button'</span>
<span class="keyword">end</span>)
:new_property(<span class="string">'sprite'</span>,<span class="keyword">nil</span>,<span class="keyword">function</span>(properties,value)
properties.image = value
properties.caption = <span class="keyword">nil</span>
properties.<span class="global">type</span> = <span class="string">'sprite-button'</span>
<span class="keyword">end</span>)
:define_draw(<span class="keyword">function</span>(properties,parent,element)
<span class="comment">-- Note that element might be nil if this is the first draw function
</span> <span class="comment">-- in this case button is a new concept so we know this is the first function and element is nil
</span> <span class="keyword">if</span> properties.<span class="global">type</span> == <span class="string">'button'</span> <span class="keyword">then</span>
element = parent.add{
<span class="global">type</span> = properties.<span class="global">type</span>,
name = properties.name,
caption = properties.caption,
tooltip = properties.tooltip
}
<span class="keyword">else</span>
element = parent.add{
<span class="global">type</span> = properties.<span class="global">type</span>,
name = properties.name,
sprite = properties.sprite,
tooltip = properties.tooltip
}
<span class="keyword">end</span>
<span class="comment">-- We must return the element or what we want to be seen as the instance, this is so other draw functions have access to it
</span> <span class="comment">-- for example if our custom button defined a draw function to change the font color to red
</span> <span class="keyword">return</span> element
<span class="keyword">end</span>)</code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Makeing a alternative button based on the first
</span><span class="keyword">local</span> custom_button =
button:clone(<span class="string">'CustomButton'</span>)
:new_event(<span class="string">'on_admin_clicked'</span>,defines.events.on_gui_click,<span class="keyword">function</span>(event)
<span class="keyword">return</span> event.player.admin <span class="comment">-- only raise custom event when an admin clicks the button
</span><span class="keyword">end</span>)
:set_caption(<span class="string">'Custom Button'</span>)
:set_tooltip(<span class="string">'Only admins can press this button'</span>)
:on_click(<span class="keyword">function</span>(event)
<span class="keyword">if</span> <span class="keyword">not</span> event.player.admin <span class="keyword">then</span>
event.player.<span class="global">print</span>(<span class="string">'You must be admin to use this button'</span>)
<span class="keyword">end</span>
<span class="keyword">end</span>)
:on_admin_clicked(<span class="keyword">function</span>(event)
<span class="comment">-- Yes i know this can just be an if else but its an example
</span> game.<span class="global">print</span>(event.player.name..<span class="string">' pressed my admin button'</span>)
<span class="keyword">end</span>)</code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Drawing a concept
</span>custom_button:draw(game.player.gui.left)</code></pre>
<!-- module usage end -->
<!-- module content header end -->
<!-- module section list start -->
<table class="section-content-list">
<thead>
<h3><a href="#Elements">Elements</a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#button">button</a></td>
<td class="summary">The basic button element</td>
</tr>
<tr>
<td class="name"><a href="#checkbox">checkbox</a></td>
<td class="summary">The basic checkbox element</td>
</tr>
<tr>
<td class="name"><a href="#dropdown">dropdown</a></td>
<td class="summary">The basic dropdown element</td>
</tr>
<tr>
<td class="name"><a href="#frame">frame</a></td>
<td class="summary">The basic frame element</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Dropdowns">Dropdowns </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#set_dropdown_value">set_dropdown_value(element, value)</a></td>
<td class="summary">Selects the index of a dropdown with this value</td>
</tr>
<tr>
<td class="name"><a href="#get_dropdown_value">get_dropdown_value(element)</a></td>
<td class="summary">Gets the selected item value of a dropdown</td>
</tr>
<tr>
<td class="name"><a href="#add_dropdown_items">add_dropdown_items(element[, start_index], new_items)</a></td>
<td class="summary">Adds the given items into the list of items for this dropdown</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Concept_Control">Concept Control </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#require_concept">require_concept(concept)</a></td>
<td class="summary">Loads a concept from the concepts file, used internally</td>
</tr>
<tr>
<td class="name"><a href="#get_concept">get_concept(name)</a></td>
<td class="summary">Gets the gui concept with this name</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:change_name">Prototype:change_name([new_name=self.name])</a></td>
<td class="summary">Used internally to save concept names to the core gui module</td>
</tr>
<tr>
<td class="name"><a href="#new_concept">new_concept(name)</a></td>
<td class="summary">Returns a new gui concept with no properties or events</td>
</tr>
<tr>
<td class="name"><a href="#clone_concept">clone_concept(name, new_name)</a></td>
<td class="summary">Make a new concept based on the properties and drawing of another</td>
</tr>
<tr>
<td class="name"><a href="#draw_concept">draw_concept(name, parent)</a></td>
<td class="summary">Used to draw a concept to a parent element</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Element_Control">Element Control </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#get_player_from_element">get_player_from_element(element)</a></td>
<td class="summary">Gets the player who owns this element</td>
</tr>
<tr>
<td class="name"><a href="#valid">valid(element)</a></td>
<td class="summary">Simple check for if an element is valid</td>
</tr>
<tr>
<td class="name"><a href="#destroy">destroy(element)</a></td>
<td class="summary">Destroies and element if it is valid</td>
</tr>
<tr>
<td class="name"><a href="#toggle_enabled">toggle_enabled(element)</a></td>
<td class="summary">Toggles the enabled state of an element</td>
</tr>
<tr>
<td class="name"><a href="#toggle_visible">toggle_visible(element)</a></td>
<td class="summary">Toggles the visible state of an element</td>
</tr>
<tr>
<td class="name"><a href="#set_padding">set_padding(element[, up=0][, down=0][, left=0][, right=0])</a></td>
<td class="summary">Sets the padding for a gui element</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Store_Categories">Store Categories </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#categorize_by_player">categorize_by_player(element)</a></td>
<td class="summary">A categorize function to be used with add_store, each player has their own category</td>
</tr>
<tr>
<td class="name"><a href="#categorize_by_force">categorize_by_force(element)</a></td>
<td class="summary">A categorize function to be used with add_store, each force has its own category</td>
</tr>
<tr>
<td class="name"><a href="#categorize_by_surface">categorize_by_surface(element)</a></td>
<td class="summary">A categorize function to be used with add_store, each surface has its own category</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Concept_Base">Concept Base </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#Prototype:clone">Prototype:clone(concept_name)</a></td>
<td class="summary">Used to copy all the settings from one concept to another and removing links to the orginal</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:change_name">Prototype:change_name([new_name=self.name])</a></td>
<td class="summary">Used internally to save concept names to the core gui module</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:new_event">Prototype:new_event(event_name[, factorio_event][, event_condition])</a></td>
<td class="summary">Adds a new event trigger to the concept which can be linked to a factorio event</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:on_custom_event">Prototype:on_custom_event(handler)</a></td>
<td class="summary">Adds a custom event handler, replace with the name of the event</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:raise_event">Prototype:raise_event(event_name[, event={}][, from_factorio=false])</a></td>
<td class="summary">Raises a custom event, folowing keys included automaticlly: concept, event name, game tick, player from player_index, element if valid</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:new_property">Prototype:new_property(property_name, default[, setter_callback])</a></td>
<td class="summary">Adds a new property to the concept, such as caption, tooltip, or some custom property you want to control</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:set_custom_property">Prototype:set_custom_property(value)</a></td>
<td class="summary">Sets a new value for a property, triggers setter method if provided, replace with property name</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:define_draw">Prototype:define_draw(draw_callback)</a></td>
<td class="summary">Used to define how the concept is turned into an ingame element or "instance" as we may refer to them</td>
</tr>
<tr>
<td class="name"><a href="#Prototype:draw">Prototype:draw(parent_element)</a></td>
<td class="summary">Calls all the draw functions in order to create this concept in game; will also store and sync the instance if stores are used</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Concept_Instances">Concept Instances </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#Prototype:define_instance_store">Prototype:define_instance_store([category_callback])</a></td>
<td class="summary">Adds an instance store to the concept; when a new instance is made it is stored so you can access it later</td>
</tr>
<tr>
<td class="name"><a href="#Prototype.get_instances">Prototype.get_instances([category])</a></td>
<td class="summary">Gets all insatnces in a category, category may be nil to return all</td>
</tr>
<tr>
<td class="name"><a href="#Prototype.add_instance">Prototype.add_instance(element[, category])</a></td>
<td class="summary">Adds an instance to this concept, used automatically during concept:draw</td>
</tr>
<tr>
<td class="name"><a href="#Prototype.update_instances">Prototype.update_instances([category], update_callback)</a></td>
<td class="summary">Applies an update function to all instances, simialr use to what table.forEach would be</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Concept_Data">Concept Data </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#Prototype:define_data_store">Prototype:define_data_store([category_callback])</a></td>
<td class="summary">Adds a data store to this concept which allows you to store synced/percistent data between instances</td>
</tr>
<tr>
<td class="name"><a href="#Prototype.get_data">Prototype.get_data([category])</a></td>
<td class="summary">Gets the data that is stored for this category</td>
</tr>
<tr>
<td class="name"><a href="#Prototype.set_data">Prototype.set_data([category], value)</a></td>
<td class="summary">Sets the data that is stored for this category</td>
</tr>
<tr>
<td class="name"><a href="#Prototype.clear_data">Prototype.clear_data([category])</a></td>
<td class="summary">Clears the data that is stored for this category</td>
</tr>
<tr>
<td class="name"><a href="#Prototype.update_data">Prototype.update_data([category], update_callback)</a></td>
<td class="summary">Updates the data that is stored for this category</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Concept_Combined_Instances">Concept Combined Instances </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#Prototype:define_combined_store">Prototype:define_combined_store([category_callback], sync_callback)</a></td>
<td class="summary">Used to add a both instance and data store which are linked together, new instances are synced to the current value, changing the stored value will change all instances</td>
</tr>
<tr>
<td class="name"><a href="#Prototype.sync_instance">Prototype.sync_instance(element)</a></td>
<td class="summary">Will sync an instance to match the stored value based on the given sync callback</td>
</tr>
</tbody>
</table>
<table class="section-content-list">
<thead>
<h3><a href="#Tests">Tests </a></h3>
<span></span>
</thead>
<tbody>
<tr>
<td class="name"><a href="#run_tests">run_tests(player[, category])</a></td>
<td class="summary">Runs a set of gui tests to ensure that the system is working</td>
</tr>
</tbody>
</table>
<!-- module section list end -->
<br />
<!-- section start -->
<h3><span id="Elements" class="section-title"><a href="#Elements">Elements</a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#button" class="fragment-hashtag">#</a>
<span class="section-item-title" id="button">button</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">The basic button element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Properties / Events:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>on_click</em></strong>
<strong> : </strong>
fired when the player clicks the button
</li>
<li class="section-subitem-li">
<strong><em>on_left_click</em></strong>
<strong> : </strong>
fired when the player clicks with the right mouse button
</li>
<li class="section-subitem-li">
<strong><em>on_left_click</em></strong>
<strong> : </strong>
fired when the player clicks with the right mouse button
</li>
<li class="section-subitem-li">
<strong><em>caption</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/Concepts.html#LocalisedString">LocalisedString</a></span>)
the message that is shown on the button
</li>
<li class="section-subitem-li">
<strong><em>tooltip</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/Concepts.html#LocalisedString">LocalisedString</a></span>)
the tooltip that shows when a player hovers over the button
</li>
<li class="section-subitem-li">
<strong><em>sprite</em></strong>
<strong> : </strong>
(<span class="types"><span class="type">SpritePath</span></span>)
upto three sprites in the order: default, hovered, clicked
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making a basic button
</span><span class="keyword">local</span> basic_button =
Gui.clone_concept(<span class="string">'button'</span>,<span class="string">'basic_button'</span>)
:set_caption(<span class="string">'Basic Button'</span>)
:set_tooltip(<span class="string">'Basic button'</span>)
:on_click(<span class="keyword">function</span>(event)
event.player.<span class="global">print</span>(<span class="string">'You pressed basic button!'</span>)
<span class="keyword">end</span>)</code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making a sprite button
</span><span class="keyword">local</span> sprite_button =
Gui.clone_concept(<span class="string">'button'</span>,<span class="string">'sprite_button'</span>)
:set_sprite(<span class="string">'utility/warning_icon'</span>)
:set_tooltip(<span class="string">'Sprite button'</span>)
:on_click(<span class="keyword">function</span>(event)
event.player.<span class="global">print</span>(<span class="string">'You pressed sprite button!'</span>)
<span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#checkbox" class="fragment-hashtag">#</a>
<span class="section-item-title" id="checkbox">checkbox</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">The basic checkbox element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Properties / Events:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>on_state_change</em></strong>
<strong> : </strong>
fired when the state of the element is changed
</li>
<li class="section-subitem-li">
<strong><em>caption</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/Concepts.html#LocalisedString">LocalisedString</a></span>)
the message that is shown next to the checkbox
</li>
<li class="section-subitem-li">
<strong><em>tooltip</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/Concepts.html#LocalisedString">LocalisedString</a></span>)
the tooltip that shows when a player hovers over the checkbox
</li>
<li class="section-subitem-li">
<strong><em>use_radio</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
setting to true will use radio buttons rather than checkboxs
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making a basic checkbox
</span><span class="keyword">local</span> basic_checkbox =
Gui.clone_concept(<span class="string">'checkbox'</span>,<span class="string">'basic_checkbox'</span>)
:set_caption(<span class="string">'Basic Checkbox'</span>)
:set_tooltip(<span class="string">'Basic checkbox'</span>)
:on_state_change(<span class="keyword">function</span>(event)
event.player.<span class="global">print</span>(<span class="string">'Basic checkbox is now: '</span>..<span class="global">tostring</span>(event.element.state))
<span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#dropdown" class="fragment-hashtag">#</a>
<span class="section-item-title" id="dropdown">dropdown</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">The basic dropdown element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Properties / Events:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>on_selection_change</em></strong>
<strong> : </strong>
fired when the selected value is changed
</li>
<li class="section-subitem-li">
<strong><em>default_selection</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <span class="type">Conepts.LocalisedString</span></span>)
the option which is selected by default
</li>
<li class="section-subitem-li">
<strong><em>use_list_box</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
when true a list box will be used rather than a dropdown menu
</li>
<li class="section-subitem-li">
<strong><em>static_items</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.1.html">nil</a> or <a class="type" href="https://www.lua.org/pil/2.5.html">table</a></span>)
when called with a table the values will be added as items for the dropdown, if called with nil then all items are cleared
</li>
<li class="section-subitem-li">
<strong><em>dynamic_items</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
the given function will be called to return a list of items and optional start index to add items to the dropdown when it is first drawn
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making a basic dropdown
</span><span class="keyword">local</span> static_dropdown =
Gui.clone_concept(<span class="string">'dropdown'</span>,<span class="string">'static_dropdown'</span>)
:set_static_items{<span class="string">'Option 1'</span>,<span class="string">'Option 2'</span>,<span class="string">'Option 3'</span>}
:on_selection_change(<span class="keyword">function</span>(event)
<span class="keyword">local</span> value = Gui.get_dropdown_value(event.element)
event.player.<span class="global">print</span>(<span class="string">'Static dropdown is now: '</span>..value)
<span class="keyword">end</span>)</code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making a dropdown with dynamic items, example is name of online players
</span><span class="keyword">local</span> dynamic_dropdown =
Gui.clone_concept(<span class="string">'dropdown'</span>,<span class="string">'dynamic_dropdown'</span>)
:set_dynamic_items(<span class="keyword">function</span>(element)
<span class="keyword">local</span> items = {}
<span class="keyword">for</span> _,player <span class="keyword">in</span> <span class="global">pairs</span>(game.connected_players) <span class="keyword">do</span>
items[#items+<span class="number">1</span>] = player.name
<span class="keyword">end</span>
<span class="keyword">return</span> items
<span class="keyword">end</span>)
:on_selection_change(<span class="keyword">function</span>(event)
<span class="keyword">local</span> value = Gui.get_dropdown_value(event.element)
event.player.<span class="global">print</span>(<span class="string">'Dynamic dropdown is now: '</span>..value)
<span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#frame" class="fragment-hashtag">#</a>
<span class="section-item-title" id="frame">frame</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">The basic frame element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Properties / Events:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>title</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/Concepts.html#LocalisedString">LocalisedString</a></span>)
the title that will show in the frame
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making a basic frame, contains a label with hello world
</span><span class="keyword">local</span> basic_frame =
Gui.clone_concept(<span class="string">'dropdown'</span>,<span class="string">'basic_frame'</span>)
:set_title(<span class="string">'Basic Frame'</span>)
:define_draw(<span class="keyword">function</span>(properties,parent,element)
element.add{
<span class="global">type</span> = <span class="string">'label'</span>,
caption = <span class="string">'Hello, World!'</span>
}
<span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Dropdowns" class="section-title"><a href="#Dropdowns">Dropdowns </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#set_dropdown_value" class="fragment-hashtag">#</a>
<span class="section-item-title" id="set_dropdown_value">set_dropdown_value(element, value)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Selects the index of a dropdown with this value</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the dropdown that you want to set the selection for
</li>
<li class="section-subitem-li">
<strong><em>value</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <span class="type">Conepts.LocalisedString</span></span>)
the value that you want selected
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
<span class="return-text">if an item with this value was found</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Selecting the item with the value 'foo'
</span>Gui.set_dropdown_value(element,<span class="string">'foo'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#get_dropdown_value" class="fragment-hashtag">#</a>
<span class="section-item-title" id="get_dropdown_value">get_dropdown_value(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Gets the selected item value of a dropdown</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the dropdown that you want the selected value of
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <span class="type">Conepts.LocalisedString</span></span>)
<span class="return-text">the value that is currently selected</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Getting the selected value
</span><span class="keyword">local</span> selected_value = Gui.get_dropdown_value(element)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#add_dropdown_items" class="fragment-hashtag">#</a>
<span class="section-item-title" id="add_dropdown_items">add_dropdown_items(element[, start_index], new_items)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Adds the given items into the list of items for this dropdown</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the dropdown that you want to add the items to
</li>
<li class="section-subitem-li">
<strong><em>start_index</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.3.html">number</a></span>)
the index at which the items will be added, if not given appened to the end
(<em>optional</em>)
</li>
<li class="section-subitem-li">
<strong><em>new_items</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.5.html">table</a></span>)
the list of new items that you want to add
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.5.html">table</a></span>)
<span class="return-text">the list of items that the element now has</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Add the items 'foo' and 'bar' to the end
</span>Gui.add_dropdown_items(element,{<span class="string">'foo'</span>,<span class="string">'bar'</span>})</code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Add the items 'foo' and 'bar' to the start
</span>Gui.add_dropdown_items(element,<span class="number">1</span>,{<span class="string">'foo'</span>,<span class="string">'bar'</span>})</code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Concept_Control" class="section-title"><a href="#Concept_Control">Concept Control </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#require_concept" class="fragment-hashtag">#</a>
<span class="section-item-title" id="require_concept">require_concept(concept)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Loads a concept from the concepts file, used internally</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>concept</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name of the concept to require
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Load a base concept
</span>Gui.require_concept(<span class="string">'frame'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#get_concept" class="fragment-hashtag">#</a>
<span class="section-item-title" id="get_concept">get_concept(name)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Gets the gui concept with this name</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name of the concept that you want to get
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Getting a gui concept
</span><span class="keyword">local</span> button = Gui.get_concept(<span class="string">'Button'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:change_name" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:change_name">Prototype:change_name([new_name=self.name])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Used internally to save concept names to the core gui module</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>new_name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the new name of the concept
(<em>default</em>: self.name)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Internal Saving
</span><span class="comment">-- this is never needed to be done, internal use only!
</span><span class="keyword">local</span> button = Gui.get_concept(<span class="string">'Button'</span>)
button:change_name(<span class="string">'Not Button'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#new_concept" class="fragment-hashtag">#</a>
<span class="section-item-title" id="new_concept">new_concept(name)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Returns a new gui concept with no properties or events</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name that you want this concept to have
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making a new concept, see module usage
</span><span class="keyword">local</span> button = Gui.new_concept(<span class="string">'Button'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#clone_concept" class="fragment-hashtag">#</a>
<span class="section-item-title" id="clone_concept">clone_concept(name, new_name)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Make a new concept based on the properties and drawing of another</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name of the concept that you want as the base
</li>
<li class="section-subitem-li">
<strong><em>new_name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name that you want the new concept to have
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Making a new concept from another, see module usage
</span><span class="keyword">local</span> custom_button = Gui.clone_concept(<span class="string">'Button'</span>,<span class="string">'CustomButton'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#draw_concept" class="fragment-hashtag">#</a>
<span class="section-item-title" id="draw_concept">draw_concept(name, parent)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Used to draw a concept to a parent element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name of the concept that you want to draw
</li>
<li class="section-subitem-li">
<strong><em>parent</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that will act as a parent for the new element
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
<span class="return-text">the element that was created</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Drawing a new element
</span>Gui.draw_concept(<span class="string">'Button'</span>,element)</code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Element_Control" class="section-title"><a href="#Element_Control">Element Control </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#get_player_from_element" class="fragment-hashtag">#</a>
<span class="section-item-title" id="get_player_from_element">get_player_from_element(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Gets the player who owns this element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that you want to get the player of
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaPlayer.html">LuaPlayer</a></span>)
<span class="return-text">the player who owns this element</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Getting the player of an element
</span><span class="keyword">local</span> player = Gui.get_player_from_element(element)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#valid" class="fragment-hashtag">#</a>
<span class="section-item-title" id="valid">valid(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Simple check for if an element is valid</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that you want to check is valid
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
<span class="return-text">true if the element is valid</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Return if not valid
</span><span class="keyword">if</span> <span class="keyword">not</span> Gui.valid(element) <span class="keyword">then</span> <span class="keyword">return</span> <span class="keyword">end</span></code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#destroy" class="fragment-hashtag">#</a>
<span class="section-item-title" id="destroy">destroy(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Destroies and element if it is valid</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that you want to destroy
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
<span class="return-text">true if the element was valid and was destoried</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Destoring an element
</span>Gui.destroy(element)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#toggle_enabled" class="fragment-hashtag">#</a>
<span class="section-item-title" id="toggle_enabled">toggle_enabled(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Toggles the enabled state of an element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that you want to toggle the enabled state of
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
<span class="return-text">the new enabled state of the element</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Toggle the enabled state of an element
</span>Gui.toggle_enabled(element)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#toggle_visible" class="fragment-hashtag">#</a>
<span class="section-item-title" id="toggle_visible">toggle_visible(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Toggles the visible state of an element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that you want to toggle the visible state of
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
<span class="return-text">the new visible state of the element</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Toggle the visible state of an element
</span>Gui.toggle_visible(element)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#set_padding" class="fragment-hashtag">#</a>
<span class="section-item-title" id="set_padding">set_padding(element[, up=0][, down=0][, left=0][, right=0])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Sets the padding for a gui element</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element to set the padding for
</li>
<li class="section-subitem-li">
<strong><em>up</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.3.html">number</a> or <a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
the amount of padding on the top, true leaves unchanged
(<em>default</em>: 0)
</li>
<li class="section-subitem-li">
<strong><em>down</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.3.html">number</a> or <a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
the amount of padding on the bottom, true leaves unchanged
(<em>default</em>: 0)
</li>
<li class="section-subitem-li">
<strong><em>left</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.3.html">number</a> or <a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
the amount of padding on the left, true leaves unchanged
(<em>default</em>: 0)
</li>
<li class="section-subitem-li">
<strong><em>right</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.3.html">number</a> or <a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
the amount of padding on the right, true leaves unchanged
(<em>default</em>: 0)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Remove all padding of an element
</span>Gui.set_padding(element)</code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Remove side padding but keep vertical padding
</span>Gui.set_padding(element,<span class="keyword">true</span>,<span class="keyword">true</span>)</code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Remove all padding but set right to 2
</span>Gui.set_padding(element,<span class="keyword">false</span>,<span class="keyword">false</span>,<span class="keyword">false</span>,<span class="number">2</span>)</code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Store_Categories" class="section-title"><a href="#Store_Categories">Store Categories </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#categorize_by_player" class="fragment-hashtag">#</a>
<span class="section-item-title" id="categorize_by_player">categorize_by_player(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">A categorize function to be used with add_store, each player has their own category</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that will be converted to a string
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
<span class="return-text">the player's name who owns this element</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Storing data on a per player basis, can be used with instances
</span>Gui.get_concept(<span class="string">'CustomButton'</span>)
:define_data_store(Gui.categorize_by_player)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#categorize_by_force" class="fragment-hashtag">#</a>
<span class="section-item-title" id="categorize_by_force">categorize_by_force(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">A categorize function to be used with add_store, each force has its own category</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that will be converted to a string
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
<span class="return-text">the player's force name who owns this element</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Storing data on a per force basis, can be used with instances
</span>Gui.get_concept(<span class="string">'CustomButton'</span>)
:define_data_store(Gui.categorize_by_force)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#categorize_by_surface" class="fragment-hashtag">#</a>
<span class="section-item-title" id="categorize_by_surface">categorize_by_surface(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">A categorize function to be used with add_store, each surface has its own category</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that will be converted to a string
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
<span class="return-text">the player's surface name who owns this element</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Storing data on a per surface basis, can be used with instances
</span>Gui.get_concept(<span class="string">'CustomButton'</span>)
:define_data_store(Gui.categorize_by_surface)</code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Concept_Base" class="section-title"><a href="#Concept_Base">Concept Base </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:clone" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:clone">Prototype:clone(concept_name)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Used to copy all the settings from one concept to another and removing links to the orginal</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>concept_name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name of the new concept; must be unique
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">the base for building a custom gui</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Clones the base Button concept to make a alternative button
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'Button'</span>):clone(<span class="string">'CustomButton'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:change_name" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:change_name">Prototype:change_name([new_name=self.name])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Used internally to save concept names to the core gui module</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>new_name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the new name of the concept
(<em>default</em>: self.name)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Internal Saving
</span><span class="comment">-- this is never needed to be done, internal use only!
</span><span class="keyword">local</span> button = Gui.get_concept(<span class="string">'Button'</span>)
button:change_name(<span class="string">'Not Button'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:new_event" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:new_event">Prototype:new_event(event_name[, factorio_event][, event_condition])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Adds a new event trigger to the concept which can be linked to a factorio event</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>event_name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name of the event to add, must be unique, recomented to start with "on_"
</li>
<li class="section-subitem-li">
<strong><em>factorio_event</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/defines.html#defines.events">defines.events</a></span>)
when given will fire the custom event when the factorio event is raised
(<em>optional</em>)
</li>
<li class="section-subitem-li">
<strong><em>event_condition</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
used to filter when a factorio event triggers the custom event; if the event contains a reference to an element then names are automatically filtered
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">to allow chaining of functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Adds an on_admin_clicked event to fire when ever an admin clicks the button
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'Button'</span>):clone(<span class="string">'CustomButton'</span>)
:new_event(<span class="string">'on_admin_clicked'</span>,defines.events.on_gui_click,<span class="keyword">function</span>(event)
<span class="keyword">return</span> event.player.admin <span class="comment">-- only raise custom event when an admin clicks the button
</span><span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:on_custom_event" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:on_custom_event">Prototype:on_custom_event(handler)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Adds a custom event handler, replace with the name of the event</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>handler</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
the function which will recive the event
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">to allow chaining of functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- When an admin clicks the button a message is printed
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
:on_admin_clicked(<span class="keyword">function</span>(event)
game.<span class="global">print</span>(event.player.name..<span class="string">' pressed my admin button'</span>)
<span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:raise_event" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:raise_event">Prototype:raise_event(event_name[, event={}][, from_factorio=false])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Raises a custom event, folowing keys included automaticlly: concept, event name, game tick, player from player_index, element if valid</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>event_name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name of the event that you want to raise
</li>
<li class="section-subitem-li">
<strong><em>event</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.5.html">table</a></span>)
table containg data you want to send with the event, some keys already included
(<em>default</em>: {})
</li>
<li class="section-subitem-li">
<strong><em>from_factorio</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#boolean">boolean</a></span>)
internal use, if the raise came from the factorio event handler
(<em>default</em>: false)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Raising the custom event on_admin_clicked
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
<span class="comment">-- Note that this is an example and would not work due it expecting a valid element for event.element
</span><span class="comment">-- this will however work fine if you can provide all expected keys, or its not linked to any factorio event
</span>custom_button:raise_event(<span class="string">'on_admin_clicked'</span>,{
player_index = game.player.index
})</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:new_property" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:new_property">Prototype:new_property(property_name, default[, setter_callback])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Adds a new property to the concept, such as caption, tooltip, or some custom property you want to control</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>property_name</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the name of the new property, must be unique
</li>
<li class="section-subitem-li">
<strong><em>default</em></strong>
<strong> : </strong>
(<span class="types"><span class="type">any</span></span>)
the default value for this property, although not strictly required is is strongly recomented
</li>
<li class="section-subitem-li">
<strong><em>setter_callback</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
this function is called when set is called, if not provided then key in concept.properties is updated to new value
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">to allow chaining of functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Adding caption, sprite, and tooltip to the base button concept
</span><span class="keyword">local</span> button =
Gui.get_concept(<span class="string">'Button'</span>)
:new_property(<span class="string">'tooltip'</span>)
:new_property(<span class="string">'caption'</span>,<span class="keyword">nil</span>,<span class="keyword">function</span>(properties,value)
properties.caption = value
properties.sprite = <span class="keyword">nil</span>
properties.<span class="global">type</span> = <span class="string">'button'</span>
<span class="keyword">end</span>)
:new_property(<span class="string">'sprite'</span>,<span class="keyword">nil</span>,<span class="keyword">function</span>(properties,value)
properties.image = value
properties.caption = <span class="keyword">nil</span>
properties.<span class="global">type</span> = <span class="string">'sprite-button'</span>
<span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:set_custom_property" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:set_custom_property">Prototype:set_custom_property(value)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Sets a new value for a property, triggers setter method if provided, replace with property name</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>value</em></strong>
<strong> : </strong>
(<span class="types"><span class="type">any</span></span>)
the value that you want to set for this property
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">to allow chaining of functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Setting the caption on the base button concept after a cloning
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'Button'</span>)
:set_caption(<span class="string">'Default Button'</span>)</code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- In our examples CustomButton is cloned from Button, this means the caption property already exists
</span><span class="comment">-- note that what ever values that properties have at the time of cloning are also copied
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
:set_caption(<span class="string">'Custom Button'</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:define_draw" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:define_draw">Prototype:define_draw(draw_callback)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Used to define how the concept is turned into an ingame element or "instance" as we may refer to them</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>draw_callback</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
the function that will be called to draw/update the instance; this function must return the instance or the new acting instance
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">to allow chaining of functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Adding the draw define for the base button concept, we then return the element
</span><span class="keyword">local</span> button =
Gui.get_concept(<span class="string">'Button'</span>)
:define_draw(<span class="keyword">function</span>(properties,parent,element)
<span class="comment">-- Note that element might be nil if this is the first draw function
</span> <span class="comment">-- for this example we assume button was cloned from Prototype and so has no other draw functions defined
</span> <span class="comment">-- this means that there is no element yet and what we return will be the first time the element is returned
</span> <span class="comment">-- although not shown here you also can recive any extra arguments here from the call to draw
</span> <span class="keyword">if</span> properties.<span class="global">type</span> == <span class="string">'button'</span> <span class="keyword">then</span>
element = parent.draw{
<span class="global">type</span> = properties.<span class="global">type</span>,
name = properties.name,
caption = properties.caption,
tooltip = properties.tooltip
}
<span class="keyword">else</span>
element = parent.draw{
<span class="global">type</span> = properties.<span class="global">type</span>,
name = properties.name,
sprite = properties.sprite,
tooltip = properties.tooltip
}
<span class="keyword">end</span>
<span class="comment">-- We must return the element or what we want to be seen as the instance, this is so other draw functions have access to it
</span> <span class="comment">-- for example if our custom button defined a draw function to change the font color to red
</span> <span class="keyword">return</span> element
<span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:draw" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:draw">Prototype:draw(parent_element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Calls all the draw functions in order to create this concept in game; will also store and sync the instance if stores are used</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>parent_element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that the concept will use as a base
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
<span class="return-text">the element that was created and then passed though and returned by the draw functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Drawing the custom button concept
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
<span class="comment">-- Note that the draw function from button was cloned, so unless we want to alter the base button we dont need a new draw define
</span>custom_button:draw(game.player.gui.left)</code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Concept_Instances" class="section-title"><a href="#Concept_Instances">Concept Instances </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:define_instance_store" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:define_instance_store">Prototype:define_instance_store([category_callback])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Adds an instance store to the concept; when a new instance is made it is stored so you can access it later</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category_callback</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
when given will act as a way to turn an element into a string to act as a key; keys returned can over lap
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">to allow chaining of functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Allowing storing instances of the custom button; stored by the players index
</span><span class="comment">-- Note even thou this is a copy of Button; if Button had an instance store it would not be cloned over
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
:define_instance_store(<span class="keyword">function</span>(element)
<span class="keyword">return</span> element.player_index <span class="comment">-- The instances are stored based on player id
</span><span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype.get_instances" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype.get_instances">Prototype.get_instances([category])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Gets all insatnces in a category, category may be nil to return all</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the category to get, can only be nil if categories are not used
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.5.html">table</a></span>)
<span class="return-text">a table which contains all the instances</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Getting all the instances of the player with index 1
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
custom_button.get_instances(<span class="number">1</span>) -- player index <span class="number">1</span></code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype.add_instance" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype.add_instance">Prototype.add_instance(element[, category])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Adds an instance to this concept, used automatically during concept:draw</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that will be added as an instance
</li>
<li class="section-subitem-li">
<strong><em>category</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
the category to add this element under, if nil the category callback is used to assign one
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Adding an element as a instance for this concept, mostly for internal use
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
custom_button.add_instance(element) -- normally <span class="keyword">not</span> needed due to use <span class="keyword">in</span> concept:draw</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype.update_instances" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype.update_instances">Prototype.update_instances([category], update_callback)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Applies an update function to all instances, simialr use to what table.forEach would be</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the category to get, can only be nil if categories are not used
(<em>optional</em>)
</li>
<li class="section-subitem-li">
<strong><em>update_callback</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
the function which is called on each instance, recives other args passed to update_instances
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Changing the font color of all instances for player 1
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
custom_button.update_instances(<span class="number">1</span>,<span class="keyword">function</span>(element)
element.style.font_color = {r=<span class="number">1</span>,g=<span class="number">0</span>,b=<span class="number">0</span>}
<span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Concept_Data" class="section-title"><a href="#Concept_Data">Concept Data </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:define_data_store" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:define_data_store">Prototype:define_data_store([category_callback])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Adds a data store to this concept which allows you to store synced/percistent data between instances</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category_callback</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
when given will act as a way to turn an element into a string to act as a key; keys returned can over lap
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">to allow chaining of functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Adding a way to store data for this concept; each player has their own store
</span><span class="comment">-- Note even thou this is a copy of Button; if Button had an data store it would not be cloned over
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
:define_data_store(<span class="keyword">function</span>(element)
<span class="keyword">return</span> element.player_index <span class="comment">-- The data is stored based on player id
</span><span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype.get_data" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype.get_data">Prototype.get_data([category])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Gets the data that is stored for this category</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the category to get, can only be nil if categories are not used
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">any</span></span>)
<span class="return-text">the data that you had stored in this location</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Getting the stored data for player 1
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
custom_button.get_data(<span class="number">1</span>) -- player index <span class="number">1</span></code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype.set_data" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype.set_data">Prototype.set_data([category], value)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Sets the data that is stored for this category</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the category to set, can only be nil if categories are not used
(<em>optional</em>)
</li>
<li class="section-subitem-li">
<strong><em>value</em></strong>
<strong> : </strong>
(<span class="types"><span class="type">any</span></span>)
the data that you want to stored in this location
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Setting the data for player 1 to a table with two keys
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
<span class="comment">-- A table is used to show correct way to use a table with self.update_data
</span><span class="comment">-- but a table is not required and can be any data, however upvalues may cause desyncs
</span>custom_button.set_data(<span class="number">1</span>,{
clicks = <span class="number">0</span>,
required_clicks = <span class="number">100</span>
}) -- player index <span class="number">1</span></code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype.clear_data" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype.clear_data">Prototype.clear_data([category])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Clears the data that is stored for this category</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the category to clear, can only be nil if categories are not used
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Clearing the data for player 1
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
custom_button.clear_data(<span class="number">1</span>) -- player index <span class="number">1</span></code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype.update_data" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype.update_data">Prototype.update_data([category], update_callback)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Updates the data that is stored for this category</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a> or <a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the category to clear, can only be nil if categories are not used
(<em>optional</em>)
</li>
<li class="section-subitem-li">
<strong><em>update_callback</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
the function which is called to update the data
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Updating the clicks key in the concept data for player 1
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
custom_button.update_data(<span class="number">1</span>,<span class="keyword">function</span>(tbl)
tbl.clicks = tbl.clicks + <span class="number">1</span> <span class="comment">-- here we are incrementing the clicks by 1
</span><span class="keyword">end</span>) <span class="comment">-- player index 1
</span></code></pre>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Updating a value when a table is not used, alterative to get set
</span><span class="comment">-- so for this example assume that we did custom_button.set_data(1,0)
</span>custom_button.update_data(<span class="number">1</span>,<span class="keyword">function</span>(value)
<span class="keyword">return</span> value + <span class="number">1</span> <span class="comment">-- here we are incrementing the value by 1, we may only be tracking clicks
</span><span class="keyword">end</span>) -- player index <span class="number">1</span></code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Concept_Combined_Instances" class="section-title"><a href="#Concept_Combined_Instances">Concept Combined Instances </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype:define_combined_store" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype:define_combined_store">Prototype:define_combined_store([category_callback], sync_callback)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Used to add a both instance and data store which are linked together, new instances are synced to the current value, changing the stored value will change all instances</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>category_callback</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
when given will act as a way to turn an element into a string to act as a key; keys returned can over lap
(<em>optional</em>)
</li>
<li class="section-subitem-li">
<strong><em>sync_callback</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="https://www.lua.org/pil/2.6.html">function</a></span>)
the function which is called to update an instance to match the store, this is called on all instances when concept.set_data or update_data is used
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<strong>Returns:</strong>
<ul>
<li>
(<span class="types"><span class="type">GuiConcept</span></span>)
<span class="return-text">to allow chaining of functions</span>
</li>
</ul>
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Adding a check box which is a "global setting" synced between all players
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'checkbox'</span>):clone(<span class="string">'my_checkbox'</span>)
:set_caption(<span class="string">'My Checkbox'</span>)
:set_tooltip(<span class="string">'Clicking this check box will change it for everyone'</span>)
:on_state_change(<span class="keyword">function</span>(event)
<span class="keyword">local</span> element = event.element
event.concept.set_data(element,element.state) <span class="comment">-- Update the stored data to trigger an update of all other instances
</span><span class="keyword">end</span>)
:define_combined_store(<span class="keyword">function</span>(element,state) <span class="comment">-- We could add a category function here if we wanted to
</span> element.state = state <span class="keyword">or</span> <span class="keyword">false</span> <span class="comment">-- When you sync an instance this is what is called
</span><span class="keyword">end</span>)</code></pre>
<!-- usage end -->
</dd>
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#Prototype.sync_instance" class="fragment-hashtag">#</a>
<span class="section-item-title" id="Prototype.sync_instance">Prototype.sync_instance(element)</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Will sync an instance to match the stored value based on the given sync callback</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>element</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaGuiElement.html">LuaGuiElement</a></span>)
the element that you want to have update
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Setting the caption of this element to be the same as the stored value
</span><span class="keyword">local</span> custom_button =
Gui.get_concept(<span class="string">'CustomButton'</span>)
<span class="comment">-- Used internally when first draw and automatically when the store updates
</span>custom_button.sync_instance(element)</code></pre>
<!-- usage end -->
</dd>
</dl>
<h3><span id="Tests" class="section-title"><a href="#Tests">Tests </a></span></h3>
<dl class="section-body-container">
<dt>
<div class="divider divider-custom"></div>
<div class="block section-item-header">
<a href="#run_tests" class="fragment-hashtag">#</a>
<span class="section-item-title" id="run_tests">run_tests(player[, category])</span>
</div>
</dt>
<dd>
<div class="section-item-body">
<p class="section-item-summary">Runs a set of gui tests to ensure that the system is working</p>
<p class="section-item-description"></p>
<!-- parameters start -->
<strong>Parameters:</strong>
<ul>
<li class="section-subitem-li">
<strong><em>player</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/LuaPlayer.html">LuaPlayer</a></span>)
the player that the guis are made for and who recives the results
</li>
<li class="section-subitem-li">
<strong><em>category</em></strong>
<strong> : </strong>
(<span class="types"><a class="type" href="http://lua-api.factorio.com/latest/Builtin-Types.html#string">string</a></span>)
when given only tests in this category are ran
(<em>optional</em>)
</li>
</ul>
<!-- parameters end -->
<!-- returns start -->
<!-- returns end -->
<!-- see also start -->
<!-- see also end -->
<!-- usage start -->
<strong>Usage:</strong>
<pre class="code" data-lang="Lua"><code><span class="comment">-- Run all gui tests
</span>Gui.run_tests(game.player)</code></pre>
<!-- usage end -->
</dd>
</dl>
<!-- section end -->
</div>
</div>
</div>
<div class="footer container grid-1280">
<div class="divider divider-custom"></div>
<div class="footer-columns columns">
<div class="sidebar-footer column col-3 col-sm-12">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc </a></i>
</div>
<div class="content-footer column col-9 col-sm-12">
<i>Last updated 2019-08-30 17:29:53 UTC</i>
</div>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink