Partydeck/Druid-Extension
3
0
Fork 0
mirror of https://github.com/Insality/druid synced 2025-06-27 02:17:52 +02:00
Code Issues Packages Projects Releases Wiki Activity
Druid-Extension/docs/modules/Helper.html
Insality 86189d6e3e Update docs, annotations
2024-10-19 11:22:24 +03:00

928 lines
23 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
<title>Defold Druid UI Framework</title>
<link rel="stylesheet" href="../ldoc_fixed.css" type="text/css" />
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
<!-- Menu -->
<div id="navigation">
<br/>
<h1>Druid</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><a href="../modules/BackHandler.html">BackHandler</a></li>
<li><a href="../modules/BaseComponent.html">BaseComponent</a></li>
<li><a href="../modules/Blocker.html">Blocker</a></li>
<li><a href="../modules/Button.html">Button</a></li>
<li><a href="../modules/DataList.html">DataList</a></li>
<li><a href="../modules/Drag.html">Drag</a></li>
<li><a href="../modules/Druid.html">Druid</a></li>
<li><a href="../modules/DruidEvent.html">DruidEvent</a></li>
<li><a href="../modules/DruidInstance.html">DruidInstance</a></li>
<li><a href="../modules/DynamicGrid.html">DynamicGrid</a></li>
<li><strong>Helper</strong></li>
<li><a href="../modules/Hotkey.html">Hotkey</a></li>
<li><a href="../modules/Hover.html">Hover</a></li>
<li><a href="../modules/Input.html">Input</a></li>
<li><a href="../modules/LangText.html">LangText</a></li>
<li><a href="../modules/Layout.html">Layout</a></li>
<li><a href="../modules/Progress.html">Progress</a></li>
<li><a href="../modules/RichInput.html">RichInput</a></li>
<li><a href="../modules/RichText.html">RichText</a></li>
<li><a href="../modules/Scroll.html">Scroll</a></li>
<li><a href="../modules/Slider.html">Slider</a></li>
<li><a href="../modules/StaticGrid.html">StaticGrid</a></li>
<li><a href="../modules/Swipe.html">Swipe</a></li>
<li><a href="../modules/Text.html">Text</a></li>
<li><a href="../modules/Timer.html">Timer</a></li>
</ul>
</div>
<div id="content">
<h1>Module <code>Helper</code></h1>
<p>Helper module with various usefull GUI functions.</p>
<p></p>
<h3>Usage:</h3>
<ul>
<pre class="example">local helper = require(&quot;druid.helper&quot;)
helper.centrate_nodes(0, node_1, node_2)
</pre>
</ul>
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#helper.add_array">helper.add_array(target, source)</a></td>
<td class="summary">Add all elements from source array to the target array</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.centrate_nodes">helper.centrate_nodes(margin, ...)</a></td>
<td class="summary">Centerate nodes by x position with margin.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.clamp">helper.clamp(a, min, max)</a></td>
<td class="summary">Clamp value between min and max</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.contains">helper.contains(t, value)</a></td>
<td class="summary">Check if value is in array and return index of it</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.deepcopy">helper.deepcopy(orig_table)</a></td>
<td class="summary">Make a copy table with all nested tables</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.distance">helper.distance(x1, y1, x2, y2)</a></td>
<td class="summary">Calculate distance between two points</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.get_border">helper.get_border(node, offset)</a></td>
<td class="summary">Distance from node position to his borders</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.get_closest_stencil_node">helper.get_closest_stencil_node(node)</a></td>
<td class="summary">Return closest non inverted clipping parent node for given node</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.get_gui_scale">helper.get_gui_scale()</a></td>
<td class="summary">Get current GUI scale for each side</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.get_pivot_offset">helper.get_pivot_offset(pivot)</a></td>
<td class="summary">Get node offset for given GUI pivot.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.get_scaled_size">helper.get_scaled_size(node)</a></td>
<td class="summary">Get node size adjusted by scale</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.get_scene_scale">helper.get_scene_scale(node, include_passed_node_scale)</a></td>
<td class="summary">Get cumulative parent's node scale</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.get_screen_aspect_koef">helper.get_screen_aspect_koef()</a></td>
<td class="summary">Get current screen stretch multiplier for each side</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.get_text_metrics_from_node">helper.get_text_metrics_from_node(text_node)</a></td>
<td class="summary">Get text metric from GUI node.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.insert_with_shift">helper.insert_with_shift(array, any, index, shift_policy)</a></td>
<td class="summary">Add value to array with shift policy</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.is_mobile">helper.is_mobile()</a></td>
<td class="summary">Check if device is native mobile (Android or iOS)</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.is_multitouch_supported">helper.is_multitouch_supported()</a></td>
<td class="summary">Check if device is mobile and can support multitouch</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.is_web">helper.is_web()</a></td>
<td class="summary">Check if device is HTML5</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.is_web_mobile">helper.is_web_mobile()</a></td>
<td class="summary">Check if device is HTML5 mobile</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.lerp">helper.lerp(a, b, t)</a></td>
<td class="summary">Lerp between two values</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.remove_with_shift">helper.remove_with_shift(array, index, shift_policy)</a></td>
<td class="summary">Remove value from array with shift policy</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.round">helper.round(num, num_decimal_places)</a></td>
<td class="summary">Round number to specified decimal places</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.sign">helper.sign(val)</a></td>
<td class="summary">Return sign of value (-1, 0, 1)</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.step">helper.step(current, target, step)</a></td>
<td class="summary">Move value from current to target value with step amount</td>
</tr>
<tr>
<td class="name" nowrap><a href="#helper.table_to_string">helper.table_to_string(t)</a></td>
<td class="summary">Simple table to one-line string converter</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
<dl class="function">
<dt>
<a name = "helper.add_array"></a>
<strong>helper.add_array(target, source)</strong>
</dt>
<dd>
Add all elements from source array to the target array
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">target</span>
<span class="types"><span class="type">any[]</span></span>
Array to put elements from source
</li>
<li><span class="parameter">source</span>
<span class="types"><span class="type">any[]</span> or <span class="type">nil</span></span>
The source array to get elements from
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">any[]</span></span>
The target array
</ol>
</dd>
<dt>
<a name = "helper.centrate_nodes"></a>
<strong>helper.centrate_nodes(margin, ...)</strong>
</dt>
<dd>
Centerate nodes by x position with margin.
<p> This functions calculate total width of nodes and set position for each node.
The centrate will be around 0 x position.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">margin</span>
<span class="types"><span class="type">number</span> or <span class="type">nil</span></span>
Offset between nodes
</li>
<li><span class="parameter">...</span>
Gui nodes
</li>
</ul>
</dd>
<dt>
<a name = "helper.clamp"></a>
<strong>helper.clamp(a, min, max)</strong>
</dt>
<dd>
Clamp value between min and max
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">a</span>
<span class="types"><span class="type">number</span></span>
Value
</li>
<li><span class="parameter">min</span>
<span class="types"><span class="type">number</span></span>
Min value
</li>
<li><span class="parameter">max</span>
<span class="types"><span class="type">number</span></span>
Max value
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
Clamped value
</ol>
</dd>
<dt>
<a name = "helper.contains"></a>
<strong>helper.contains(t, value)</strong>
</dt>
<dd>
Check if value is in array and return index of it
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">t</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
Array
</li>
<li><span class="parameter">value</span>
Value
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span> or <span class="type">nil</span></span>
Index of value or nil
</ol>
</dd>
<dt>
<a name = "helper.deepcopy"></a>
<strong>helper.deepcopy(orig_table)</strong>
</dt>
<dd>
Make a copy table with all nested tables
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">orig_table</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
Original table
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
Copy of original table
</ol>
</dd>
<dt>
<a name = "helper.distance"></a>
<strong>helper.distance(x1, y1, x2, y2)</strong>
</dt>
<dd>
Calculate distance between two points
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x1</span>
<span class="types"><span class="type">number</span></span>
First point x
</li>
<li><span class="parameter">y1</span>
<span class="types"><span class="type">number</span></span>
First point y
</li>
<li><span class="parameter">x2</span>
<span class="types"><span class="type">number</span></span>
Second point x
</li>
<li><span class="parameter">y2</span>
<span class="types"><span class="type">number</span></span>
Second point y
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
Distance
</ol>
</dd>
<dt>
<a name = "helper.get_border"></a>
<strong>helper.get_border(node, offset)</strong>
</dt>
<dd>
Distance from node position to his borders
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">node</span>
<span class="types"><span class="type">node</span></span>
GUI node
</li>
<li><span class="parameter">offset</span>
<span class="types"><span class="type">vector3</span> or <span class="type">nil</span></span>
Offset from node position. Pass current node position to get non relative border values
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">vector4</span></span>
Vector4 with border values (left, top, right, down)
</ol>
</dd>
<dt>
<a name = "helper.get_closest_stencil_node"></a>
<strong>helper.get_closest_stencil_node(node)</strong>
</dt>
<dd>
Return closest non inverted clipping parent node for given node
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">node</span>
<span class="types"><span class="type">node</span></span>
GUI node
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">node</span> or <span class="type">nil</span></span>
The closest stencil node or nil
</ol>
</dd>
<dt>
<a name = "helper.get_gui_scale"></a>
<strong>helper.get_gui_scale()</strong>
</dt>
<dd>
Get current GUI scale for each side
<h3>Returns:</h3>
<ol>
<li>
<span class="types"><span class="type">number</span></span>
scale_x</li>
<li>
<span class="types"><span class="type">number</span></span>
scale_y</li>
</ol>
</dd>
<dt>
<a name = "helper.get_pivot_offset"></a>
<strong>helper.get_pivot_offset(pivot)</strong>
</dt>
<dd>
Get node offset for given GUI pivot.
<p> Offset shown in [-0.5 .. 0.5] range, where -0.5 is left or bottom, 0.5 is right or top.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">pivot</span>
<span class="types"><span class="type">number</span></span>
The gui.PIVOT_* constant
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">vector3</span></span>
Vector offset with [-0.5..0.5] values
</ol>
</dd>
<dt>
<a name = "helper.get_scaled_size"></a>
<strong>helper.get_scaled_size(node)</strong>
</dt>
<dd>
Get node size adjusted by scale
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">node</span>
<span class="types"><span class="type">node</span></span>
GUI node
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">vector3</span></span>
Scaled size
</ol>
</dd>
<dt>
<a name = "helper.get_scene_scale"></a>
<strong>helper.get_scene_scale(node, include_passed_node_scale)</strong>
</dt>
<dd>
Get cumulative parent's node scale
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">node</span>
<span class="types"><span class="type">node</span></span>
Gui node
</li>
<li><span class="parameter">include_passed_node_scale</span>
<span class="types"><span class="type">boolean</span> or <span class="type">nil</span></span>
True if add current node scale to result
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">vector3</span></span>
The scene node scale
</ol>
</dd>
<dt>
<a name = "helper.get_screen_aspect_koef"></a>
<strong>helper.get_screen_aspect_koef()</strong>
</dt>
<dd>
Get current screen stretch multiplier for each side
<h3>Returns:</h3>
<ol>
<li>
<span class="types"><span class="type">number</span></span>
stretch_x</li>
<li>
<span class="types"><span class="type">number</span></span>
stretch_y</li>
</ol>
</dd>
<dt>
<a name = "helper.get_text_metrics_from_node"></a>
<strong>helper.get_text_metrics_from_node(text_node)</strong>
</dt>
<dd>
Get text metric from GUI node.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">text_node</span>
<span class="types"><span class="type">node</span></span>
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">GUITextMetrics</span></span>
</ol>
<h3>Usage:</h3>
<ul>
<pre class="example"><span class="global">type</span> GUITextMetrics = {
width: number,
height: number,
max_ascent: number,
max_descent: number
}</pre>
</ul>
</dd>
<dt>
<a name = "helper.insert_with_shift"></a>
<strong>helper.insert_with_shift(array, any, index, shift_policy)</strong>
</dt>
<dd>
Add value to array with shift policy Shift policy can be: left, right, no_shift
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">array</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
Array
</li>
<li><span class="parameter">any</span>
Item to insert
</li>
<li><span class="parameter">index</span>
<span class="types"><span class="type">number</span> or <span class="type">nil</span></span>
Index to insert. If nil, item will be inserted at the end of array
</li>
<li><span class="parameter">shift_policy</span>
<span class="types"><span class="type">number</span> or <span class="type">nil</span></span>
The druid_const.SHIFT.* constant
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">any</span></span>
Inserted item
</ol>
</dd>
<dt>
<a name = "helper.is_mobile"></a>
<strong>helper.is_mobile()</strong>
</dt>
<dd>
Check if device is native mobile (Android or iOS)
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">boolean</span></span>
Is mobile
</ol>
</dd>
<dt>
<a name = "helper.is_multitouch_supported"></a>
<strong>helper.is_multitouch_supported()</strong>
</dt>
<dd>
Check if device is mobile and can support multitouch
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">boolean</span></span>
Is multitouch supported
</ol>
</dd>
<dt>
<a name = "helper.is_web"></a>
<strong>helper.is_web()</strong>
</dt>
<dd>
Check if device is HTML5
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">boolean</span></span>
Is web
</ol>
</dd>
<dt>
<a name = "helper.is_web_mobile"></a>
<strong>helper.is_web_mobile()</strong>
</dt>
<dd>
Check if device is HTML5 mobile
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">boolean</span></span>
Is web mobile
</ol>
</dd>
<dt>
<a name = "helper.lerp"></a>
<strong>helper.lerp(a, b, t)</strong>
</dt>
<dd>
Lerp between two values
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">a</span>
<span class="types"><span class="type">number</span></span>
First value
</li>
<li><span class="parameter">b</span>
<span class="types"><span class="type">number</span></span>
Second value
</li>
<li><span class="parameter">t</span>
<span class="types"><span class="type">number</span></span>
Lerp amount
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
Lerped value
</ol>
</dd>
<dt>
<a name = "helper.remove_with_shift"></a>
<strong>helper.remove_with_shift(array, index, shift_policy)</strong>
</dt>
<dd>
Remove value from array with shift policy Shift policy can be: left, right, no_shift
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">array</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
Array
</li>
<li><span class="parameter">index</span>
<span class="types"><span class="type">number</span> or <span class="type">nil</span></span>
Index to remove. If nil, item will be removed from the end of array
</li>
<li><span class="parameter">shift_policy</span>
<span class="types"><span class="type">number</span> or <span class="type">nil</span></span>
The druid_const.SHIFT.* constant
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">any</span></span>
Removed item
</ol>
</dd>
<dt>
<a name = "helper.round"></a>
<strong>helper.round(num, num_decimal_places)</strong>
</dt>
<dd>
Round number to specified decimal places
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">num</span>
<span class="types"><span class="type">number</span></span>
Number
</li>
<li><span class="parameter">num_decimal_places</span>
<span class="types"><span class="type">number</span> or <span class="type">nil</span></span>
Decimal places
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
Rounded number
</ol>
</dd>
<dt>
<a name = "helper.sign"></a>
<strong>helper.sign(val)</strong>
</dt>
<dd>
Return sign of value (-1, 0, 1)
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">val</span>
<span class="types"><span class="type">number</span></span>
Value
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
Sign
</ol>
</dd>
<dt>
<a name = "helper.step"></a>
<strong>helper.step(current, target, step)</strong>
</dt>
<dd>
Move value from current to target value with step amount
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">current</span>
<span class="types"><span class="type">number</span></span>
Current value
</li>
<li><span class="parameter">target</span>
<span class="types"><span class="type">number</span></span>
Target value
</li>
<li><span class="parameter">step</span>
<span class="types"><span class="type">number</span></span>
Step amount
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
New value
</ol>
</dd>
<dt>
<a name = "helper.table_to_string"></a>
<strong>helper.table_to_string(t)</strong>
</dt>
<dd>
Simple table to one-line string converter
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">t</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
</ol>
</dd>
</dl>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc TESTING</a></i>
<i style="float:right;">Last updated 2015-01-01 12:00:00 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink