mirror of
https://github.com/Insality/druid.git
synced 2025-06-27 18:37:44 +02:00
519 lines
9.4 KiB
Markdown
519 lines
9.4 KiB
Markdown
# druid.helper API
|
|
|
|
> at /druid/helper.lua
|
|
|
|
The helper module contains various functions that are used in the Druid library.
|
|
You can use these functions in your projects as well.
|
|
|
|
|
|
## Functions
|
|
- [centrate_text_with_icon](#centrate_text_with_icon)
|
|
- [centrate_icon_with_text](#centrate_icon_with_text)
|
|
- [centrate_nodes](#centrate_nodes)
|
|
- [get_node](#get_node)
|
|
- [get_screen_aspect_koef](#get_screen_aspect_koef)
|
|
- [get_gui_scale](#get_gui_scale)
|
|
- [step](#step)
|
|
- [clamp](#clamp)
|
|
- [distance](#distance)
|
|
- [sign](#sign)
|
|
- [round](#round)
|
|
- [lerp](#lerp)
|
|
- [contains](#contains)
|
|
- [deepcopy](#deepcopy)
|
|
- [add_array](#add_array)
|
|
- [pick_node](#pick_node)
|
|
- [get_scaled_size](#get_scaled_size)
|
|
- [get_scene_scale](#get_scene_scale)
|
|
- [get_closest_stencil_node](#get_closest_stencil_node)
|
|
- [get_pivot_offset](#get_pivot_offset)
|
|
- [is_mobile](#is_mobile)
|
|
- [is_web](#is_web)
|
|
- [is_web_mobile](#is_web_mobile)
|
|
- [is_multitouch_supported](#is_multitouch_supported)
|
|
- [table_to_string](#table_to_string)
|
|
- [get_border](#get_border)
|
|
- [get_text_metrics_from_node](#get_text_metrics_from_node)
|
|
- [insert_with_shift](#insert_with_shift)
|
|
- [remove_with_shift](#remove_with_shift)
|
|
- [get_full_position](#get_full_position)
|
|
|
|
|
|
## Fields
|
|
- [PROP_SIZE_X](#PROP_SIZE_X)
|
|
- [PROP_SIZE_Y](#PROP_SIZE_Y)
|
|
- [PROP_SCALE_X](#PROP_SCALE_X)
|
|
- [PROP_SCALE_Y](#PROP_SCALE_Y)
|
|
|
|
|
|
|
|
### centrate_text_with_icon
|
|
|
|
---
|
|
```lua
|
|
helper.centrate_text_with_icon([text_node], [icon_node], margin)
|
|
```
|
|
|
|
Center two nodes.
|
|
Nodes will be center around 0 x position
|
|
text_node will be first (at left side)
|
|
|
|
- **Parameters:**
|
|
- `[text_node]` *(node|nil)*: Gui text node
|
|
- `[icon_node]` *(node|nil)*: Gui box node
|
|
- `margin` *(number)*: Offset between nodes
|
|
|
|
- **Returns:**
|
|
- `` *(unknown)*:
|
|
|
|
### centrate_icon_with_text
|
|
|
|
---
|
|
```lua
|
|
helper.centrate_icon_with_text([icon_node], [text_node], [margin])
|
|
```
|
|
|
|
Center two nodes.
|
|
Nodes will be center around 0 x position
|
|
icon_node will be first (at left side)
|
|
|
|
- **Parameters:**
|
|
- `[icon_node]` *(node|nil)*: Gui box node
|
|
- `[text_node]` *(node|nil)*: Gui text node
|
|
- `[margin]` *(number|nil)*: Offset between nodes
|
|
|
|
- **Returns:**
|
|
- `` *(unknown)*:
|
|
|
|
### centrate_nodes
|
|
|
|
---
|
|
```lua
|
|
helper.centrate_nodes([margin], ...)
|
|
```
|
|
|
|
Centerate nodes by x position with margin.
|
|
This functions calculate total width of nodes and set position for each node.
|
|
The centrate will be around 0 x position.
|
|
|
|
- **Parameters:**
|
|
- `[margin]` *(number|nil)*: Offset between nodes
|
|
- `...` *(...)*: vararg
|
|
|
|
- **Returns:**
|
|
- `` *(unknown)*:
|
|
|
|
### get_node
|
|
|
|
---
|
|
```lua
|
|
helper.get_node(node_id, [template], [nodes])
|
|
```
|
|
|
|
- **Parameters:**
|
|
- `node_id` *(string|node)*:
|
|
- `[template]` *(string|nil)*: Full Path to the template
|
|
- `[nodes]` *(table<hash, node>|nil)*: Nodes what created with gui.clone_tree
|
|
|
|
- **Returns:**
|
|
- `` *(node)*:
|
|
|
|
### get_screen_aspect_koef
|
|
|
|
---
|
|
```lua
|
|
helper.get_screen_aspect_koef()
|
|
```
|
|
|
|
Get current screen stretch multiplier for each side
|
|
|
|
- **Returns:**
|
|
- `stretch_x` *(number)*:
|
|
- `stretch_y` *(number)*:
|
|
|
|
### get_gui_scale
|
|
|
|
---
|
|
```lua
|
|
helper.get_gui_scale()
|
|
```
|
|
|
|
Get current GUI scale for each side
|
|
|
|
- **Returns:**
|
|
- `scale_x` *(number)*:
|
|
|
|
### step
|
|
|
|
---
|
|
```lua
|
|
helper.step(current, target, step)
|
|
```
|
|
|
|
Move value from current to target value with step amount
|
|
|
|
- **Parameters:**
|
|
- `current` *(number)*: Current value
|
|
- `target` *(number)*: Target value
|
|
- `step` *(number)*: Step amount
|
|
|
|
- **Returns:**
|
|
- `New` *(number)*: value
|
|
|
|
### clamp
|
|
|
|
---
|
|
```lua
|
|
helper.clamp(value, [v1], [v2])
|
|
```
|
|
|
|
Clamp value between min and max. Works with nil values and swap min and max if needed.
|
|
|
|
- **Parameters:**
|
|
- `value` *(number)*: Value
|
|
- `[v1]` *(number|nil)*: Min value. If nil, value will be clamped to positive infinity
|
|
- `[v2]` *(number|nil)*: Max value If nil, value will be clamped to negative infinity
|
|
|
|
- **Returns:**
|
|
- `value` *(number)*: Clamped value
|
|
|
|
### distance
|
|
|
|
---
|
|
```lua
|
|
helper.distance(x1, y1, x2, y2)
|
|
```
|
|
|
|
Calculate distance between two points
|
|
|
|
- **Parameters:**
|
|
- `x1` *(number)*: First point x
|
|
- `y1` *(number)*: First point y
|
|
- `x2` *(number)*: Second point x
|
|
- `y2` *(number)*: Second point y
|
|
|
|
- **Returns:**
|
|
- `Distance` *(number)*:
|
|
|
|
### sign
|
|
|
|
---
|
|
```lua
|
|
helper.sign(val)
|
|
```
|
|
|
|
Return sign of value
|
|
|
|
- **Parameters:**
|
|
- `val` *(number)*: Value
|
|
|
|
- **Returns:**
|
|
- `sign` *(number)*: Sign of value, -1, 0 or 1
|
|
|
|
### round
|
|
|
|
---
|
|
```lua
|
|
helper.round(num, [num_decimal_places])
|
|
```
|
|
|
|
Round number to specified decimal places
|
|
|
|
- **Parameters:**
|
|
- `num` *(number)*: Number
|
|
- `[num_decimal_places]` *(number|nil)*: Decimal places
|
|
|
|
- **Returns:**
|
|
- `value` *(number)*: Rounded number
|
|
|
|
### lerp
|
|
|
|
---
|
|
```lua
|
|
helper.lerp(a, b, t)
|
|
```
|
|
|
|
Lerp between two values
|
|
|
|
- **Parameters:**
|
|
- `a` *(number)*: First value
|
|
- `b` *(number)*: Second value
|
|
- `t` *(number)*: Lerp amount
|
|
|
|
- **Returns:**
|
|
- `value` *(number)*: Lerped value
|
|
|
|
### contains
|
|
|
|
---
|
|
```lua
|
|
helper.contains([array], [value])
|
|
```
|
|
|
|
Check if value contains in array
|
|
|
|
- **Parameters:**
|
|
- `[array]` *(any[])*: Array to check
|
|
- `[value]` *(any)*: Value
|
|
|
|
- **Returns:**
|
|
- `` *(integer|nil)*:
|
|
|
|
### deepcopy
|
|
|
|
---
|
|
```lua
|
|
helper.deepcopy(orig_table)
|
|
```
|
|
|
|
Make a copy table with all nested tables
|
|
|
|
- **Parameters:**
|
|
- `orig_table` *(table)*: Original table
|
|
|
|
- **Returns:**
|
|
- `Copy` *(table)*: of original table
|
|
|
|
### add_array
|
|
|
|
---
|
|
```lua
|
|
helper.add_array([target], [source])
|
|
```
|
|
|
|
Add all elements from source array to the target array
|
|
|
|
- **Parameters:**
|
|
- `[target]` *(any[])*: Array to put elements from source
|
|
- `[source]` *(any[]|nil)*: The source array to get elements from
|
|
|
|
- **Returns:**
|
|
- `The` *(any[])*: target array
|
|
|
|
### pick_node
|
|
|
|
---
|
|
```lua
|
|
helper.pick_node(node, x, y, [node_click_area])
|
|
```
|
|
|
|
Make a check with gui.pick_node, but with additional node_click_area check.
|
|
|
|
- **Parameters:**
|
|
- `node` *(node)*:
|
|
- `x` *(number)*:
|
|
- `y` *(number)*:
|
|
- `[node_click_area]` *(node|nil)*: Additional node to check for click area. If nil, only node will be checked
|
|
|
|
- **Returns:**
|
|
- `` *(unknown)*:
|
|
|
|
### get_scaled_size
|
|
|
|
---
|
|
```lua
|
|
helper.get_scaled_size(node)
|
|
```
|
|
|
|
Get size of node with scale multiplier
|
|
|
|
- **Parameters:**
|
|
- `node` *(node)*: GUI node
|
|
|
|
- **Returns:**
|
|
- `scaled_size` *(vector3)*:
|
|
|
|
### get_scene_scale
|
|
|
|
---
|
|
```lua
|
|
helper.get_scene_scale(node, [include_passed_node_scale])
|
|
```
|
|
|
|
Get cumulative parent's node scale
|
|
|
|
- **Parameters:**
|
|
- `node` *(node)*: Gui node
|
|
- `[include_passed_node_scale]` *(boolean|nil)*: True if add current node scale to result
|
|
|
|
- **Returns:**
|
|
- `The` *(vector3)*: scene node scale
|
|
|
|
### get_closest_stencil_node
|
|
|
|
---
|
|
```lua
|
|
helper.get_closest_stencil_node(node)
|
|
```
|
|
|
|
Return closest non inverted clipping parent node for given node
|
|
|
|
- **Parameters:**
|
|
- `node` *(node)*: GUI node
|
|
|
|
- **Returns:**
|
|
- `stencil_node` *(node|nil)*: The closest stencil node or nil
|
|
|
|
### get_pivot_offset
|
|
|
|
---
|
|
```lua
|
|
helper.get_pivot_offset(pivot_or_node)
|
|
```
|
|
|
|
Get pivot offset for given pivot or node
|
|
Offset shown in [-0.5 .. 0.5] range, where -0.5 is left or bottom, 0.5 is right or top.
|
|
|
|
- **Parameters:**
|
|
- `pivot_or_node` *(number|node)*: GUI pivot or node
|
|
|
|
- **Returns:**
|
|
- `offset` *(vector3)*: The pivot offset
|
|
|
|
### is_mobile
|
|
|
|
---
|
|
```lua
|
|
helper.is_mobile()
|
|
```
|
|
|
|
Check if device is native mobile (Android or iOS)
|
|
|
|
- **Returns:**
|
|
- `Is` *(boolean)*: mobile
|
|
|
|
### is_web
|
|
|
|
---
|
|
```lua
|
|
helper.is_web()
|
|
```
|
|
|
|
Check if device is HTML5
|
|
|
|
- **Returns:**
|
|
- `` *(boolean)*:
|
|
|
|
### is_web_mobile
|
|
|
|
---
|
|
```lua
|
|
helper.is_web_mobile()
|
|
```
|
|
|
|
Check if device is HTML5 mobile
|
|
|
|
- **Returns:**
|
|
- `` *(boolean)*:
|
|
|
|
### is_multitouch_supported
|
|
|
|
---
|
|
```lua
|
|
helper.is_multitouch_supported()
|
|
```
|
|
|
|
Check if device is mobile and can support multitouch
|
|
|
|
- **Returns:**
|
|
- `is_multitouch` *(boolean)*: Is multitouch supported
|
|
|
|
### table_to_string
|
|
|
|
---
|
|
```lua
|
|
helper.table_to_string(t)
|
|
```
|
|
|
|
Simple table to one-line string converter
|
|
|
|
- **Parameters:**
|
|
- `t` *(table)*:
|
|
|
|
- **Returns:**
|
|
- `` *(string)*:
|
|
|
|
### get_border
|
|
|
|
---
|
|
```lua
|
|
helper.get_border(node, [offset])
|
|
```
|
|
|
|
Distance from node position to his borders
|
|
|
|
- **Parameters:**
|
|
- `node` *(node)*: GUI node
|
|
- `[offset]` *(vector3|nil)*: Offset from node position. Pass current node position to get non relative border values
|
|
|
|
- **Returns:**
|
|
- `border` *(vector4)*: Vector4 with border values (left, top, right, down)
|
|
|
|
### get_text_metrics_from_node
|
|
|
|
---
|
|
```lua
|
|
helper.get_text_metrics_from_node(text_node)
|
|
```
|
|
|
|
Get text metric from GUI node.
|
|
|
|
- **Parameters:**
|
|
- `text_node` *(node)*:
|
|
|
|
- **Returns:**
|
|
- `` *(GUITextMetrics)*:
|
|
|
|
### insert_with_shift
|
|
|
|
---
|
|
```lua
|
|
helper.insert_with_shift(array, [item], [index], [shift_policy])
|
|
```
|
|
|
|
Add value to array with shift policy
|
|
Shift policy can be: left, right, no_shift
|
|
|
|
- **Parameters:**
|
|
- `array` *(table)*: Array
|
|
- `[item]` *(any)*: Item to insert
|
|
- `[index]` *(number|nil)*: Index to insert. If nil, item will be inserted at the end of array
|
|
- `[shift_policy]` *(number|nil)*: The druid_const.SHIFT.* constant
|
|
|
|
- **Returns:**
|
|
- `Inserted` *(any)*: item
|
|
|
|
### remove_with_shift
|
|
|
|
---
|
|
```lua
|
|
helper.remove_with_shift([array], [index], [shift_policy])
|
|
```
|
|
|
|
Remove value from array with shift policy
|
|
Shift policy can be: left, right, no_shift
|
|
|
|
- **Parameters:**
|
|
- `[array]` *(any[])*: Array
|
|
- `[index]` *(number|nil)*: Index to remove. If nil, item will be removed from the end of array
|
|
- `[shift_policy]` *(number|nil)*: The druid_const.SHIFT.* constant
|
|
|
|
- **Returns:**
|
|
- `Removed` *(any)*: item
|
|
|
|
### get_full_position
|
|
|
|
---
|
|
```lua
|
|
helper.get_full_position(node, [root])
|
|
```
|
|
|
|
Get full position of node in the GUI tree
|
|
|
|
- **Parameters:**
|
|
- `node` *(node)*: GUI node
|
|
- `[root]` *(node|nil)*: GUI root node to stop search
|
|
|
|
- **Returns:**
|
|
- `` *(unknown)*:
|