Partydeck/Extension-Druid
3
0
Fork 0
mirror of https://github.com/Insality/druid.git synced 2025-09-27 10:02:18 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Insality
2025-04-15 21:49:22 +03:00
parent e2c9a7d9d6
commit 9e2a14c6dd
48 changed files with 1097 additions and 1289 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
api/components/base/back_handler_api.md
View File

@@ -2,14 +2,21 @@
> at /druid/base/back_handler.lua
The component that handles the back handler action, like backspace or android back button
Component to handle back button. It handles Android back button and Backspace key.
### Setup
Create back handler component with druid: `druid:new_back_handler(callback)`
### Notes
- Key triggers in `input.binding` should be setup for correct working
- It uses a key_back and key_backspace action ids
## Functions
- [init](#init)
## Fields
- [on_back](#on_back)
- [params](#params)
@@ -22,6 +29,8 @@ The component that handles the back handler action, like backspace or android ba
back_handler:init([callback], [params])
```
The Back Handler constructor
- **Parameters:**
- `[callback]` *(function|nil)*: The callback to call when the back handler is triggered
- `[params]` *(any)*: Custom args to pass in the callback

16
api/components/base/blocker_api.md
View File

@@ -2,14 +2,24 @@
> at /druid/base/blocker.lua
Druid component for block input. Use it to block input in special zone.
### Setup
Create blocker component with druid: `druid:new_blocker(node_name)`
### Notes
- Blocker can be used to create safe zones, where you have big buttons
- Blocker will capture all input events that hit the node, preventing them from reaching other components
- Blocker works placed as usual component in stack, so any other component can be placed on top of it and will work as usual
## Functions
- [init](#init)
- [set_enabled](#set_enabled)
- [is_enabled](#is_enabled)
## Fields
- [node](#node)
@@ -21,6 +31,8 @@
blocker:init(node)
```
The Blocker constructor
- **Parameters:**
- `node` *(string|node)*: The node to use as a blocker
@@ -54,5 +66,5 @@ Get blocker enabled state
## Fields
<a name="node"></a>
- **node** (_node_)
- **node** (_node_): The node that will block input

31
api/components/base/button_api.md
View File

@@ -2,10 +2,25 @@
> at /druid/base/button.lua
Druid component to make clickable node with various interaction callbacks
Basic Druid input component. Handle input on node and provide different callbacks on touch events.
### Setup
Create button with druid: `button = druid:new_button(node_name, callback, [params], [animation_node])`
Where node_name is name of node from GUI scene. You can use `node_name` as input trigger zone and point another node for animation via `animation_node`
### Notes
- Button callback have next params: (self, params, button_instance)
- - **self** - Druid self context
- - **params** - Additional params, specified on button creating
- - **button_instance** - button itself
- You can set _params_ on button callback on button creating: `druid:new_button("node_name", callback, params)`.
- Button have several events like on_click, on_repeated_click, on_long_click, on_hold_click, on_double_click
- Click event will not trigger if between pressed and released state cursor was outside of node zone
- Button can have key trigger to use them by key: `button:set_key_trigger`
-
## Functions
- [init](#init)
- [set_animations_disabled](#set_animations_disabled)
- [set_enabled](#set_enabled)
@@ -16,8 +31,8 @@ Druid component to make clickable node with various interaction callbacks
- [set_check_function](#set_check_function)
- [set_web_user_interaction](#set_web_user_interaction)
## Fields
- [on_click](#on_click)
- [on_pressed](#on_pressed)
- [on_repeated_click](#on_repeated_click)
@@ -57,8 +72,8 @@ The constructor for the button component
- **Parameters:**
- `node_or_node_id` *(string|node)*: Node name or GUI Node itself
- `[callback]` *(fun()|nil)*: Callback on button click
- `[custom_args]` *(any)*: Custom args for any Button event
- `[anim_node]` *(string|node|nil)*: Node to animate instead of trigger node
- `[custom_args]` *(any)*: Custom args for any Button event, will be passed to callbacks
- `[anim_node]` *(string|node|nil)*: Node to animate instead of trigger node, useful for animating small icons on big panels
### set_animations_disabled
@@ -189,16 +204,16 @@ If the game is not HTML, html mode will be not enabled
- **on_pressed** (_event_): function(self, custom_args, button_instance)
<a name="on_repeated_click"></a>
- **on_repeated_click** (_event_): function(self, custom_args, button_instance, click_count)
- **on_repeated_click** (_event_): function(self, custom_args, button_instance, click_count) Repeated click callback, while holding the button
<a name="on_long_click"></a>
- **on_long_click** (_event_): function(self, custom_args, button_instance, hold_time)
- **on_long_click** (_event_): function(self, custom_args, button_instance, hold_time) Callback on long button tap
<a name="on_double_click"></a>
- **on_double_click** (_event_): function(self, custom_args, button_instance, click_amount)
- **on_double_click** (_event_): function(self, custom_args, button_instance, click_amount) Different callback, if tap button 2+ in row
<a name="on_hold_callback"></a>
- **on_hold_callback** (_event_): function(self, custom_args, button_instance, press_time)
- **on_hold_callback** (_event_): function(self, custom_args, button_instance, press_time) Hold callback, before long_click trigger
<a name="on_click_outside"></a>
- **on_click_outside** (_event_): function(self, custom_args, button_instance)

4
api/components/base/component_api.md
View File

@@ -2,8 +2,8 @@
> at /druid/component.lua
## Functions
- [create](#create)
- [create_widget](#create_widget)
@@ -39,8 +39,8 @@
- [get_nodes](#get_nodes)
- [get_childrens](#get_childrens)
## Fields
- [druid](#druid)

4
api/components/base/drag_api.md
View File

@@ -4,16 +4,16 @@
A component that allows you to subscribe to drag events over a node
## Functions
- [init](#init)
- [set_drag_cursors](#set_drag_cursors)
- [set_click_zone](#set_click_zone)
- [set_enabled](#set_enabled)
- [is_enabled](#is_enabled)
## Fields
- [node](#node)
- [on_touch_start](#on_touch_start)
- [on_touch_end](#on_touch_end)

4
api/components/base/hover_api.md
View File

@@ -4,8 +4,8 @@
The component for handling hover events on a node
## Functions
- [init](#init)
- [set_hover](#set_hover)
- [is_hovered](#is_hovered)
@@ -15,8 +15,8 @@ The component for handling hover events on a node
- [set_enabled](#set_enabled)
- [is_enabled](#is_enabled)
## Fields
- [node](#node)
- [on_hover](#on_hover)
- [on_mouse_hover](#on_mouse_hover)

32
api/components/base/scroll_api.md
View File

@@ -2,8 +2,26 @@
> at /druid/base/scroll.lua
Basic Druid scroll component. Handles all scrolling behavior in Druid GUI.
### Setup
Create scroll component with druid: `druid:new_scroll(view_node, content_node)`
### Notes
- View_node is the static part that captures user input and recognizes scrolling touches
- Content_node is the dynamic part that will change position according to the scroll system
- Initial scroll size will be equal to content_node size
- The initial view box will be equal to view_node size
- Scroll by default style has inertia and extra size for stretching effect
- You can setup "points of interest" to make scroll always center on closest point
- Scroll events:
- - on_scroll(self, position): On scroll move callback
- - on_scroll_to(self, position, is_instant): On scroll_to function callback
- - on_point_scroll(self, item_index, position): On scroll_to_index function callback
- Multitouch is required for scroll. Scroll correctly handles touch_id swap while dragging
## Functions
- [init](#init)
- [scroll_to](#scroll_to)
- [scroll_to_index](#scroll_to_index)
@@ -23,8 +41,8 @@
- [bind_grid](#bind_grid)
- [set_click_zone](#set_click_zone)
## Fields
- [node](#node)
- [click_zone](#click_zone)
- [on_scroll](#on_scroll)
@@ -60,8 +78,8 @@ scroll:init(view_node, content_node)
The Scroll constructor
- **Parameters:**
- `view_node` *(string|node)*: GUI view scroll node
- `content_node` *(string|node)*: GUI content scroll node
- `view_node` *(string|node)*: GUI view scroll node - the static part that captures user input
- `content_node` *(string|node)*: GUI content scroll node - the dynamic part that will change position
### scroll_to
@@ -316,13 +334,13 @@ Strict drag scroll area. Useful for
- **click_zone** (_node_): Optional click zone to restrict scroll area
<a name="on_scroll"></a>
- **on_scroll** (_event_): Triggered on scroll move with (self, position)
- **on_scroll** (_event_): Triggered on scroll move with fun(self, position)
<a name="on_scroll_to"></a>
- **on_scroll_to** (_event_): Triggered on scroll_to with (self, target, is_instant)
- **on_scroll_to** (_event_): Triggered on scroll_to with fun(self, target, is_instant)
<a name="on_point_scroll"></a>
- **on_point_scroll** (_event_): Triggered on scroll_to_index with (self, index, point)
- **on_point_scroll** (_event_): Triggered on scroll_to_index with fun(self, index, point)
<a name="view_node"></a>
- **view_node** (_node_): The scroll view node (static part)
@@ -370,7 +388,7 @@ Strict drag scroll area. Useful for
- **points** (_table_)
<a name="available_pos_extra"></a>
- **available_pos_extra** (_unknown_)
- **available_pos_extra** (_vector4_)
<a name="available_size_extra"></a>
- **available_size_extra** (_vector3_)

387
api/components/base/static_grid_api.md
View File

@@ -6,6 +6,14 @@ The component for manage the nodes position in the grid with various options
## Functions
- [init](#init)# druid.grid API
> at /druid/base/static_grid.lua
The component for manage the nodes position in the grid with various options
## Functions
- [init](#init)
- [get_pos](#get_pos)
- [get_index](#get_index)
@@ -27,6 +35,385 @@ The component for manage the nodes position in the grid with various options
- [set_item_size](#set_item_size)
- [sort_nodes](#sort_nodes)
## Fields
- [on_add_item](#on_add_item)
- [on_remove_item](#on_remove_item)
- [on_change_items](#on_change_items)
- [on_clear](#on_clear)
- [on_update_positions](#on_update_positions)
- [parent](#parent)
- [nodes](#nodes)
- [first_index](#first_index)
- [last_index](#last_index)
- [anchor](#anchor)
- [pivot](#pivot)
- [node_size](#node_size)
- [border](#border)
- [in_row](#in_row)
- [style](#style)
- [node_pivot](#node_pivot)
### init
---
```lua
grid:init(parent, element, [in_row])
```
The constructor for the grid component
- **Parameters:**
- `parent` *(string|node)*: The GUI Node container, where grid's items will be placed
- `element` *(node)*: Element prefab. Need to get it size
- `[in_row]` *(number|nil)*: How many nodes in row can be placed. By default 1
### get_pos
---
```lua
grid:get_pos(index)
```
Return pos for grid node index
- **Parameters:**
- `index` *(number)*: The grid element index
- **Returns:**
- `position` *(vector3)*: Node position
### get_index
---
```lua
grid:get_index(pos)
```
Return grid index by position
- **Parameters:**
- `pos` *(vector3)*: The node position in the grid
- **Returns:**
- `index` *(number)*: The node index
### get_index_by_node
---
```lua
grid:get_index_by_node(node)
```
Return grid index by node
- **Parameters:**
- `node` *(node)*: The gui node in the grid
- **Returns:**
- `index` *(number|nil)*: The node index
### set_anchor
---
```lua
grid:set_anchor(anchor)
```
Set grid anchor. Default anchor is equal to anchor of grid parent node
- **Parameters:**
- `anchor` *(vector3)*: Anchor
### refresh
---
```lua
grid:refresh()
```
Instantly update the grid content
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
### set_pivot
---
```lua
grid:set_pivot(pivot)
```
Set grid pivot
- **Parameters:**
- `pivot` *(constant)*: The new pivot
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
### add
---
```lua
grid:add(item, [index], [shift_policy], [is_instant])
```
Add new item to the grid
- **Parameters:**
- `item` *(node)*: GUI node
- `[index]` *(number|nil)*: The item position. By default add as last item
- `[shift_policy]` *(number|nil)*: How shift nodes, if required. Default: const.SHIFT.RIGHT
- `[is_instant]` *(boolean|nil)*: If true, update node positions instantly
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
### set_items
---
```lua
grid:set_items(nodes, [is_instant])
```
Set new items to the grid. All previous items will be removed
- **Parameters:**
- `nodes` *(node[])*: The new grid nodes
- `[is_instant]` *(boolean|nil)*: If true, update node positions instantly
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
### remove
---
```lua
grid:remove(index, [shift_policy], [is_instant])
```
Remove the item from the grid. Note that gui node will be not deleted
- **Parameters:**
- `index` *(number)*: The grid node index to remove
- `[shift_policy]` *(number|nil)*: How shift nodes, if required. Default: const.SHIFT.RIGHT
- `[is_instant]` *(boolean|nil)*: If true, update node positions instantly
- **Returns:**
- `node` *(node)*: The deleted gui node from grid
### get_size
---
```lua
grid:get_size()
```
Return grid content size
- **Returns:**
- `size` *(vector3)*: The grid content size
### get_size_for
---
```lua
grid:get_size_for(count)
```
Return grid content size for given count of nodes
- **Parameters:**
- `count` *(number)*: The count of nodes
- **Returns:**
- `size` *(vector3)*: The grid content size
### get_borders
---
```lua
grid:get_borders()
```
Return grid content borders
- **Returns:**
- `borders` *(vector4)*: The grid content borders
### get_all_pos
---
```lua
grid:get_all_pos()
```
Return array of all node positions
- **Returns:**
- `positions` *(vector3[])*: All grid node positions
### set_position_function
---
```lua
grid:set_position_function(callback)
```
Change set position function for grid nodes. It will call on
update poses on grid elements. Default: gui.set_position
- **Parameters:**
- `callback` *(function)*: Function on node set position
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
### clear
---
```lua
grid:clear()
```
Clear grid nodes array. GUI nodes will be not deleted!
If you want to delete GUI nodes, use static_grid.nodes array before grid:clear
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
### get_offset
---
```lua
grid:get_offset()
```
Return StaticGrid offset, where StaticGrid content starts.
- **Returns:**
- `offset` *(vector3)*: The StaticGrid offset
### set_in_row
---
```lua
grid:set_in_row(in_row)
```
Set new in_row elements for grid
- **Parameters:**
- `in_row` *(number)*: The new in_row value
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
### set_item_size
---
```lua
grid:set_item_size([width], [height])
```
Set new node size for grid
- **Parameters:**
- `[width]` *(number|nil)*: The new node width
- `[height]` *(number|nil)*: The new node height
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
### sort_nodes
---
```lua
grid:sort_nodes(comparator)
```
Sort grid nodes by custom comparator function
- **Parameters:**
- `comparator` *(function)*: The comparator function. (a, b) -> boolean
- **Returns:**
- `self` *(druid.grid)*: Current grid instance
## Fields
<a name="on_add_item"></a>
- **on_add_item** (_event_): Trigger on add item event, fun(self, item, index)
<a name="on_remove_item"></a>
- **on_remove_item** (_event_): Trigger on remove item event, fun(self, index)
<a name="on_change_items"></a>
- **on_change_items** (_event_): Trigger on change items event, fun(self, index)
<a name="on_clear"></a>
- **on_clear** (_event_): Trigger on clear event, fun(self)
<a name="on_update_positions"></a>
- **on_update_positions** (_event_): Trigger on update positions event, fun(self)
<a name="parent"></a>
- **parent** (_node_): Parent node
<a name="nodes"></a>
- **nodes** (_node[]_): Nodes array
<a name="first_index"></a>
- **first_index** (_number_): First index
<a name="last_index"></a>
- **last_index** (_number_): Last index
<a name="anchor"></a>
- **anchor** (_vector3_): Anchor
<a name="pivot"></a>
- **pivot** (_vector3_): Pivot
<a name="node_size"></a>
- **node_size** (_vector3_): Node size
<a name="border"></a>
- **border** (_vector4_): Border
<a name="in_row"></a>
- **in_row** (_number_): In row
<a name="style"></a>
- **style** (_druid.grid.style_): Style
<a name="node_pivot"></a>
- **node_pivot** (_unknown_)
- [get_pos](#get_pos)
- [get_index](#get_index)
- [get_index_by_node](#get_index_by_node)
- [set_anchor](#set_anchor)
- [refresh](#refresh)
- [set_pivot](#set_pivot)
- [add](#add)
- [set_items](#set_items)
- [remove](#remove)
- [get_size](#get_size)
- [get_size_for](#get_size_for)
- [get_borders](#get_borders)
- [get_all_pos](#get_all_pos)
- [set_position_function](#set_position_function)
- [clear](#clear)
- [get_offset](#get_offset)
- [set_in_row](#set_in_row)
- [set_item_size](#set_item_size)
- [sort_nodes](#sort_nodes)
## Fields
- [on_add_item](#on_add_item)

65
api/components/base/text_api.md
View File

@@ -2,10 +2,27 @@
> at /druid/base/text.lua
The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
Basic Druid text component. Text components by default have the text size adjusting.
### Setup
Create text node with druid: `text = druid:new_text(node_name, [initial_value], [text_adjust_type])`
### Notes
- Text component by default have auto adjust text sizing. Text never will be bigger, than text node size, which you can setup in GUI scene.
- Text pivot can be changed with `text:set_pivot`, and text will save their position inside their text size box
- There are several text adjust types:
- - **"downscale"** - Change text's scale to fit in the text node size (default)
- - **"trim"** - Trim the text with postfix (default - "...") to fit in the text node size
- - **"no_adjust"** - No any adjust, like default Defold text node
- - **"downscale_limited"** - Change text's scale like downscale, but there is limit for text's scale
- - **"scroll"** - Change text's pivot to imitate scrolling in the text box. Use with stencil node for better effect.
- - **"scale_then_scroll"** - Combine two modes: first limited downscale, then scroll
- - **"trim_left"** - Trim the text with postfix (default - "...") to fit in the text node size
- - **"scale_then_trim"** - Combine two modes: first limited downscale, then trim
- - **"scale_then_trim_left"** - Combine two modes: first limited downscale, then trim left
## Functions
- [init](#init)
- [get_text_size](#get_text_size)
- [get_text_index_by_width](#get_text_index_by_width)
@@ -22,8 +39,8 @@ The component to handle text behaviour over a GUI Text node, mainly used to auto
- [set_minimal_scale](#set_minimal_scale)
- [get_text_adjust](#get_text_adjust)
## Fields
- [node](#node)
- [on_set_text](#on_set_text)
- [on_update_text_scale](#on_update_text_scale)
@@ -44,15 +61,27 @@ The component to handle text behaviour over a GUI Text node, mainly used to auto
---
```lua
text:init(node, [value], [adjust_type])
text:init(node, [value], adjust_type)
```
The Text constructor
```lua
adjust_type:
| "downscale"
| "trim"
| "no_adjust"
| "downscale_limited"
| "scroll"
| "scale_then_scroll"
| "trim_left"
| "scale_then_trim"
| "scale_then_trim_left"
```
- **Parameters:**
- `node` *(string|node)*: Node name or GUI Text Node itself
- `[value]` *(string|nil)*: Initial text. Default value is node text from GUI scene. Default: nil
- `[adjust_type]` *(string|nil)*: Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference. Default: DOWNSCALE
- `adjust_type` *("downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"|"scale_then_trim"...(+5))*: Adjust type for text. By default is "downscale". Options: "downscale", "trim", "no_adjust", "downscale_limited", "scroll", "scale_then_scroll", "trim_left", "scale_then_trim", "scale_then_trim_left"
### get_text_size
@@ -214,15 +243,25 @@ Return true, if text with line break
---
```lua
text:set_text_adjust([adjust_type], [minimal_scale])
text:set_text_adjust(adjust_type, [minimal_scale])
```
Set text adjust, refresh the current text visuals, if needed
Values are: "downscale", "trim", "no_adjust", "downscale_limited",
"scroll", "scale_then_scroll", "trim_left", "scale_then_trim", "scale_then_trim_left"
```lua
adjust_type:
| "downscale"
| "trim"
| "no_adjust"
| "downscale_limited"
| "scroll"
| "scale_then_scroll"
| "trim_left"
| "scale_then_trim"
| "scale_then_trim_left"
```
- **Parameters:**
- `[adjust_type]` *(string|nil)*: See const.TEXT_ADJUST. If pass nil - use current adjust type
- `adjust_type` *("downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"|"scale_then_trim"...(+5))*: The adjust type to set, values: "downscale", "trim", "no_adjust", "downscale_limited", "scroll", "scale_then_scroll", "trim_left", "scale_then_trim", "scale_then_trim_left"
- `[minimal_scale]` *(number|nil)*: To remove minimal scale, use `text:set_minimal_scale(nil)`, if pass nil - not change minimal scale
- **Returns:**
@@ -235,7 +274,7 @@ Values are: "downscale", "trim", "no_adjust", "downscale_limited",
text:set_minimal_scale(minimal_scale)
```
Set minimal scale for DOWNSCALE_LIMITED or SCALE_THEN_SCROLL adjust types
Set minimal scale for "downscale_limited" or "scale_then_scroll" adjust types
- **Parameters:**
- `minimal_scale` *(number)*: If pass nil - not use minimal scale
@@ -261,13 +300,13 @@ Return current text adjust type
- **node** (_node_): The text node
<a name="on_set_text"></a>
- **on_set_text** (_event_): The event triggered when the text is set, fun(self, text)
- **on_set_text** (_event_): fun(self, text) The event triggered when the text is set
<a name="on_update_text_scale"></a>
- **on_update_text_scale** (_event_): The event triggered when the text scale is updated, fun(self, scale, metrics)
- **on_update_text_scale** (_event_): fun(self, scale, metrics) The event triggered when the text scale is updated
<a name="on_set_pivot"></a>
- **on_set_pivot** (_event_): The event triggered when the text pivot is set, fun(self, pivot)
- **on_set_pivot** (_event_): fun(self, pivot) The event triggered when the text pivot is set
<a name="style"></a>
- **style** (_druid.text.style_): The style of the text
@@ -285,7 +324,7 @@ Return current text adjust type
- **text_area** (_unknown_)
<a name="adjust_type"></a>
- **adjust_type** (_string|nil_)
- **adjust_type** (_string|"downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"...(+6)_)
<a name="color"></a>
- **color** (_unknown_)