http://ufoai.org/w/index.php?title=UFO-Scripts/ui/LUA-utility-functions&feed=atom&action=historyUFO-Scripts/ui/LUA-utility-functions - Revision history2024-03-28T22:05:57ZRevision history for this page on the wikiMediaWiki 1.35.4http://ufoai.org/w/index.php?title=UFO-Scripts/ui/LUA-utility-functions&diff=42400&oldid=prevDarkRain: /* Caveats */ Added example2016-01-28T04:29:57Z<p><span dir="auto"><span class="autocomment">Caveats: </span> Added example</span></p>
<p><b>New page</b></p><div>==Ufox extensions==<br />
<br />
Using the lua api to create a hierarchy of ui nodes leads to a lot of typing. So there is an alternative. Using the ufox utility library. This library contains a set of functions to create a ui tree from a set of nested lua tables specifying the structure of the ui nodes and the values of the properties. Currently ufox supports the following three functions for creating ui node structures:<br />
<br />
<pre><br />
ufox.build (data, parent) create a tree of ui nodes from data and assign them as child to prent<br />
ufox.build_window (data) create a window and associated child controls from data<br />
ufox.buidl_component (data) create a component and associated child controls from data<br />
</pre><br />
<br />
Using these functions leads to code like this:<br />
<br />
<pre><br />
local ui_data = {<br />
class = "panel",<br />
name = "pnlTest",<br />
<br />
pos = { 10, 250 },<br />
size = { 200, 200 },<br />
layout = ufo.LAYOUT_TOP_DOWN_FLOW,<br />
layoutmargin = 15,<br />
backgroundcolor = { 0.50, 0.00, 0.00, 1.00 },<br />
<br />
{<br />
class = "MainMenuBtn",<br />
name = "btnTest1",<br />
text = "_Test 1",<br />
<br />
on_click = function (sender)<br />
ufo.print("Hello Ufo AI!\n")<br />
end<br />
},<br />
<br />
{<br />
class = "MainMenuBtn",<br />
name = "btnTest2",<br />
text = "_Test 2"<br />
},<br />
<br />
{<br />
class = "MainMenuBtn",<br />
name = "btnTest3",<br />
text = "_Test 3"<br />
}<br />
}<br />
<br />
local ui_node = ufox.build(ui_data, node_parent)<br />
</pre><br />
<br />
The above code creates a subtree of ui nodes based on the data foun in ui_data and assigns the subtree to the parent node specified in node_parent (usually the window).<br />
<br />
Using the ufox build-functions requires you to adhere to the following guidelines:<br />
* if a table declaration is to be converted to a ui control, at least the fields 'class' and 'name' must be specified<br />
* a property can only be specified in the table declaration if there is a corresponding set function, so 'text' requires a set_text(..) function, 'background' a set_background(..) and so on<br />
* the build_window function requires the top-level table declaration to have a 'class' field with value 'window'<br />
<br />
==Common mistakes==<br />
Although the use of the table hierarchy actually looks a lot like the old UFO-script, it is not the same. The most notable difference is the use of the 'comma' to separate field-value definitions. A common mistake is to omit a comma. If you do, you'll get an error like the following.<br />
<br />
<pre><br />
lua load error: [string "main.ufo"]:136: '}' expected (to close '{' at line 11) near 'version'<br />
</pre><br />
<br />
The above error simply states that somewhere in the file main.ufo (near line 136) in the list of field-value definitions a comma is missing.<br />
<br />
==Caveats==<br />
Note that while the ui engine relies on creation order for the layering order of ui nodes, lua does '''not''' guarantee the order of elements within a table, and so the build functions detailed above '''cannot''' guarantee the creation order of the nodes specified in the given table — using them in a ui tree with nodes that require a specific layering order '''will''' lead to the resulting window/component/ui nodes misbehaving. This can be worked around by making consecutive calls to the needed functions to ensure the correct layering.<br />
<br />
<pre><br />
local ui_tree = {<br />
name = "inv_stats_hud",<br />
class = "window",<br />
pos = {236, 60},<br />
size = {560, 418},<br />
backgroundcolor = {0, 0.15, 0.1, 0.7},<br />
bordercolor = {0.58, 0.81, 0.758, 0.7},<br />
bordersize = 2,<br />
-- Inventory area background image - needs to layer below the other inventory nodes.<br />
{<br />
name = "inv_bg",<br />
class = "image",<br />
pos = {10, 59},<br />
size = {351, 349},<br />
source = "/ui/inv_bg"<br />
},<br />
-- Other bottom layer or layer independent nodes here<br />
}<br />
local inv_stats_hud = ufox.build_window(ui_tree)<br />
<br />
-- This node needs to layer on top of the background image above<br />
-- hence we create it in a separate step to ensure proper creation (and thus layering) order.<br />
do<br />
local container = { name = "headgear", class = "container", pos = {88, 85} }<br />
ufox.build(container, inv_stats_hud)<br />
end<br />
-- Other nodes to layer on top of the above here.<br />
</pre></div>DarkRain