Partydeck/Extension-Druid
3
0
Fork 0
mirror of https://github.com/Insality/druid.git synced 2025-09-28 10:32:20 +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

22
api/components/extended/container_api.md
View File

@@ -2,10 +2,22 @@
> at /druid/extended/container.lua
The component used for managing the size and positions with other containers relations to create a adaptable layouts
Druid component to manage the size and positions with other containers relations to create a adaptable layouts.
### Setup
Create container component with druid: `container = druid:new_container(node, mode, callback)`
### Notes
- Container can be used to create adaptable layouts that respond to window size changes
- Container supports different layout modes: FIT, STRETCH, STRETCH_X, STRETCH_Y
- Container can be nested inside other containers
- Container supports fixed margins and percentage-based sizing
- Container can be positioned using pivot points
- Container supports minimum size constraints
- Container can be fitted into window or custom size
## Functions
- [init](#init)
- [refresh_origins](#refresh_origins)
- [set_pivot](#set_pivot)
@@ -27,8 +39,8 @@ The component used for managing the size and positions with other containers rel
- [fit_into_node](#fit_into_node)
- [set_min_size](#set_min_size)
## Fields
- [node](#node)
- [druid](#druid)
- [node_offset](#node_offset)
@@ -60,6 +72,8 @@ The component used for managing the size and positions with other containers rel
container:init(node, mode, [callback])
```
The Container constructor
- **Parameters:**
- `node` *(node)*: Gui node
- `mode` *(string)*: Layout mode
@@ -187,7 +201,7 @@ container:add_container(node_or_container, [mode], [on_resize_callback])
```
- **Parameters:**
- `node_or_container` *(string|table|druid.container|node)*: The component used for managing the size and positions with other containers relations to create a adaptable layouts
- `node_or_container` *(string|table|druid.container|node)*: The node or container to add
- `[mode]` *(string|nil)*: stretch, fit, stretch_x, stretch_y. Default: Pick from node, "fit" or "stretch"
- `[on_resize_callback]` *(fun(self: userdata, size: vector3)|nil)*:
@@ -215,7 +229,7 @@ container:set_parent_container([parent_container])
```
- **Parameters:**
- `[parent_container]` *(druid.container|nil)*: The component used for managing the size and positions with other containers relations to create a adaptable layouts
- `[parent_container]` *(druid.container|nil)*: Druid component to manage the size and positions with other containers relations to create a adaptable layouts.
### refresh

27
api/components/extended/data_list_api.md
View File

@@ -2,12 +2,22 @@
> at /druid/extended/data_list.lua
The component used for managing a list of data with a scrollable view, used to manage huge list data and render only visible elements
Druid component to manage a list of data with a scrollable view, used to manage huge list data and render only visible elements.
### Setup
Create data list component with druid: `data_list = druid:new_data_list(scroll, grid, create_function)`
### Notes
- Data List uses a scroll component for scrolling and a grid component for layout
- Data List only renders visible elements for better performance
- Data List supports caching of elements for better performance
- Data List supports adding, removing and updating elements
- Data List supports scrolling to specific elements
- Data List supports custom element creation and cleanup
## Functions
- [init](#init)
- [on_remove](#on_remove)
- [set_use_cache](#set_use_cache)
- [set_data](#set_data)
- [get_data](#get_data)
@@ -20,8 +30,8 @@ The component used for managing a list of data with a scrollable view, used to m
- [get_created_components](#get_created_components)
- [scroll_to_index](#scroll_to_index)
## Fields
- [scroll](#scroll)
- [grid](#grid)
- [on_scroll_progress_change](#on_scroll_progress_change)
@@ -40,20 +50,13 @@ The component used for managing a list of data with a scrollable view, used to m
data_list:init(scroll, grid, create_function)
```
The DataList constructor
- **Parameters:**
- `scroll` *(druid.scroll)*: The Scroll instance for Data List component
- `grid` *(druid.grid)*: The StaticGrid instance for Data List component
- `create_function` *(function)*: The create function callback(self, data, index, data_list). Function should return (node, [component])
### on_remove
---
```lua
data_list:on_remove()
```
Druid System on_remove function
### set_use_cache
---

49
api/components/extended/hotkey_api.md
View File

@@ -2,20 +2,28 @@
> at /druid/extended/hotkey.lua
The component used for managing hotkeys and trigger callbacks when hotkeys are pressed
Druid component to manage hotkeys and trigger callbacks when hotkeys are pressed.
### Setup
Create hotkey component with druid: `hotkey = druid:new_hotkey(keys, callback, callback_argument)`
### Notes
- Hotkey can be triggered by pressing a single key or a combination of keys
- Hotkey supports modificator keys (e.g. Ctrl, Shift, Alt)
- Hotkey can be triggered on key press, release or repeat
- Hotkey can be added or removed at runtime
- Hotkey can be enabled or disabled
- Hotkey can be set to repeat on key hold
## Functions
- [init](#init)
- [on_style_change](#on_style_change)
- [add_hotkey](#add_hotkey)
- [is_processing](#is_processing)
- [on_focus_gained](#on_focus_gained)
- [on_input](#on_input)
- [set_repeat](#set_repeat)
## Fields
- [on_hotkey_pressed](#on_hotkey_pressed)
- [on_hotkey_released](#on_hotkey_released)
- [style](#style)
@@ -37,16 +45,6 @@ The Hotkey constructor
- `callback` *(function)*: The callback function
- `[callback_argument]` *(any)*: The argument to pass into the callback function
### on_style_change
---
```lua
hotkey:on_style_change(style)
```
- **Parameters:**
- `style` *(druid.hotkey.style)*:
### add_hotkey
---
@@ -73,27 +71,6 @@ hotkey:is_processing()
- **Returns:**
- `` *(boolean)*:
### on_focus_gained
---
```lua
hotkey:on_focus_gained()
```
### on_input
---
```lua
hotkey:on_input([action_id], action)
```
- **Parameters:**
- `[action_id]` *(hash|nil)*: The action id
- `action` *(action)*: The action
- **Returns:**
- `is_consume` *(boolean)*: True if the action is consumed
### set_repeat
---

63
api/components/extended/input_api.md
View File

@@ -2,13 +2,22 @@
> at /druid/extended/input.lua
The component used for managing input fields in basic way
Basic Druid text input component. Handles user text input via component with button and text.
### Setup
Create input component with druid: `input = druid:new_input(button_node_name, text_node_name, keyboard_type)`
### Notes
- Input component handles user text input. Input contains button and text components
- Button needed for selecting/unselecting input field
- Click outside of button to unselect input field
- On focus lost (game minimized) input field will be unselected
- You can setup max length of the text
- You can setup allowed characters. On add not allowed characters `on_input_wrong` will be called
## Functions
- [init](#init)
- [on_focus_lost](#on_focus_lost)
- [on_input_interrupt](#on_input_interrupt)
- [get_text_selected](#get_text_selected)
- [get_text_selected_replaced](#get_text_selected_replaced)
- [set_text](#set_text)
@@ -21,8 +30,8 @@ The component used for managing input fields in basic way
- [select_cursor](#select_cursor)
- [move_selection](#move_selection)
## Fields
- [on_input_select](#on_input_select)
- [on_input_unselect](#on_input_unselect)
- [on_input_text](#on_input_text)
@@ -31,9 +40,8 @@ The component used for managing input fields in basic way
- [on_input_wrong](#on_input_wrong)
- [on_select_cursor_change](#on_select_cursor_change)
- [style](#style)
- [text](#text)
- [ALLOWED_ACTIONS](#ALLOWED_ACTIONS)
- [druid](#druid)
- [text](#text)
- [is_selected](#is_selected)
- [value](#value)
- [previous_value](#previous_value)
@@ -64,21 +72,7 @@ input:init(click_node, text_node, [keyboard_type])
- **Parameters:**
- `click_node` *(node)*: Node to enabled input component
- `text_node` *(druid.text|node)*: Text node what will be changed on user input. You can pass text component instead of text node name Text
- `[keyboard_type]` *(number|nil)*: Gui keyboard type for input field
### on_focus_lost
---
```lua
input:on_focus_lost()
```
### on_input_interrupt
---
```lua
input:on_input_interrupt()
```
- `[keyboard_type]` *(constant|nil)*: Gui keyboard type for input field
### get_text_selected
@@ -109,13 +103,13 @@ Replace selected text with new text
---
```lua
input:set_text(input_text)
input:set_text([input_text])
```
Set text for input field
- **Parameters:**
- `input_text` *(string)*: The string to apply for input field
- `[input_text]` *(string?)*: The string to apply for input field, if nil - will be set to empty string
### select
@@ -155,7 +149,7 @@ input:set_max_length(max_length)
```
Set maximum length for input field.
Pass nil to make input field unliminted (by default)
Pass nil to make input field unliminted (by default)
- **Parameters:**
- `max_length` *(number)*: Maximum length for input text field
@@ -171,11 +165,13 @@ input:set_allowed_characters(characters)
```
Set allowed charaters for input field.
See: https://defold.com/ref/stable/string/
ex: [%a%d] for alpha and numeric
See: https://defold.com/ref/stable/string/
ex: [%a%d] for alpha and numeric
ex: [abcdef] to allow only these characters
ex: [^%s] to allow only non-space characters
- **Parameters:**
- `characters` *(string)*: Regulax exp. for validate user input
- `characters` *(string)*: Regular expression for validate user input
- **Returns:**
- `self` *(druid.input)*: Current input instance
@@ -252,15 +248,12 @@ Change cursor position by delta
<a name="style"></a>
- **style** (_druid.input.style_): The style of the input component
<a name="text"></a>
- **text** (_druid.text_): The text component
<a name="ALLOWED_ACTIONS"></a>
- **ALLOWED_ACTIONS** (_table_)
<a name="druid"></a>
- **druid** (_druid.instance_): The Druid Factory used to create components
<a name="text"></a>
- **text** (_druid.text|node_): Basic Druid text component. Text components by default have the text size adjusting.
<a name="is_selected"></a>
- **is_selected** (_boolean_)
@@ -304,10 +297,10 @@ Change cursor position by delta
- **allowed_characters** (_nil_)
<a name="keyboard_type"></a>
- **keyboard_type** (_number_)
- **keyboard_type** (_constant_)
<a name="button"></a>
- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks
- **button** (_druid.button_): Basic Druid input component. Handle input on node and provide different callbacks on touch events.
<a name="marked_text_width"></a>
- **marked_text_width** (_number_)

33
api/components/extended/lang_text_api.md
View File

@@ -2,19 +2,27 @@
> at /druid/extended/lang_text.lua
The component used for displaying localized text, can automatically update text when locale is changed
The component used for displaying localized text, can automatically update text when locale is changed.
It wraps the Text component to handle localization using druid's get_text_function to set text by its id.
### Setup
Create lang text component with druid: `text = druid:new_lang_text(node_name, locale_id)`
### Notes
- Component automatically updates text when locale is changed
- Uses druid's get_text_function to get localized text by id
- Supports string formatting with additional parameters
## Functions
- [init](#init)
- [on_language_change](#on_language_change)
- [set_to](#set_to)
- [set_text](#set_text)
- [translate](#translate)
- [format](#format)
## Fields
- [text](#text)
- [node](#node)
- [on_change](#on_change)
@@ -31,19 +39,12 @@ lang_text:init(node, [locale_id], [adjust_type])
- **Parameters:**
- `node` *(string|node)*: The node_id or gui.get_node(node_id)
- `[locale_id]` *(string|nil)*: Default locale id or text from node as default
- `[locale_id]` *(string|nil)*: Default locale id or text from node as default. If not provided, will use text from the node
- `[adjust_type]` *(string|nil)*: Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
- **Returns:**
- `` *(druid.lang_text)*:
### on_language_change
---
```lua
lang_text:on_language_change()
```
### set_to
---
@@ -51,7 +52,7 @@ lang_text:on_language_change()
lang_text:set_to(text)
```
Setup raw text to lang_text component
Setup raw text to lang_text component. This will clear any locale settings.
- **Parameters:**
- `text` *(string)*: Text for text node
@@ -66,7 +67,7 @@ Setup raw text to lang_text component
lang_text:set_text(text)
```
Setup raw text to lang_text component
Setup raw text to lang_text component. This will clear any locale settings.
- **Parameters:**
- `text` *(string)*: Text for text node
@@ -81,10 +82,10 @@ Setup raw text to lang_text component
lang_text:translate(locale_id, ...)
```
Translate the text by locale_id
Translate the text by locale_id. The text will be automatically updated when locale changes.
- **Parameters:**
- `locale_id` *(string)*: Locale id
- `locale_id` *(string)*: Locale id to get text from
- `...` *(...)*: vararg
- **Returns:**
@@ -97,7 +98,7 @@ Translate the text by locale_id
lang_text:format(...)
```
Format string with new text params on localized text
Format string with new text params on localized text. Keeps the current locale but updates the format parameters.
- **Parameters:**
- `...` *(...)*: vararg

32
api/components/extended/layout_api.md
View File

@@ -2,10 +2,21 @@
> at /druid/extended/layout.lua
The component used for managing the layout of nodes, placing them inside the node size with respect to the size and pivot of each node
Druid component to manage the layout of nodes, placing them inside the node size with respect to the size and pivot of each node.
### Setup
Create layout component with druid: `layout = druid:new_layout(node, layout_type)`
### Notes
- Layout can be horizontal, vertical or horizontal with wrapping
- Layout can resize parent node to fit content
- Layout can justify content
- Layout supports margins and padding
- Layout automatically updates when nodes are added or removed
- Layout can be manually updated by calling set_dirty()
## Functions
- [init](#init)
- [update](#update)
- [get_entities](#get_entities)
@@ -26,8 +37,8 @@ The component used for managing the layout of nodes, placing them inside the nod
- [calculate_rows_data](#calculate_rows_data)
- [set_node_position](#set_node_position)
## Fields
- [node](#node)
- [rows_data](#rows_data)
- [is_dirty](#is_dirty)
@@ -58,8 +69,8 @@ layout_type:
```
- **Parameters:**
- `node_or_node_id` *(string|node)*:
- `layout_type` *("horizontal"|"horizontal_wrap"|"vertical")*:
- `node_or_node_id` *(string|node)*: The node to manage the layout of
- `layout_type` *("horizontal"|"horizontal_wrap"|"vertical")*: The type of layout (horizontal, vertical, horizontal_wrap)
### update
@@ -151,11 +162,18 @@ layout:set_justify(is_justify)
---
```lua
layout:set_type(type)
layout:set_type(layout_type)
```
```lua
layout_type:
| "horizontal"
| "vertical"
| "horizontal_wrap"
```
- **Parameters:**
- `type` *(string)*: The layout type: "horizontal", "vertical", "horizontal_wrap"
- `layout_type` *("horizontal"|"horizontal_wrap"|"vertical")*:
- **Returns:**
- `self` *(druid.layout)*: Current layout instance
@@ -295,7 +313,7 @@ layout:set_node_position(node, x, y)
- **rows_data** (_druid.layout.rows_data_): Last calculated rows data
<a name="is_dirty"></a>
- **is_dirty** (_boolean_)
- **is_dirty** (_boolean_): True if layout needs to be updated
<a name="entities"></a>
- **entities** (_node[]_): The entities to manage the layout of

53
api/components/extended/progress_api.md
View File

@@ -2,14 +2,21 @@
> at /druid/extended/progress.lua
The component used to manage a node as a progress bar, changing the size and scale of the node
Basic Druid progress bar component. Changes the size or scale of a node to represent progress.
### Setup
Create progress bar component with druid: `progress = druid:new_progress(node_name, key, init_value)`
### Notes
- Node should have maximum node size in GUI scene, it's represent the progress bar maximum size
- Key is value from druid const: "x" or "y"
- Progress works correctly with 9slice nodes, it tries to set size by _set_size_ first, until minimum size is reached, then it sizing via _set_scale_
- Progress bar can fill only by vertical or horizontal size. For diagonal progress bar, just rotate node in GUI scene
- If you have glitchy or dark texture bugs with progress bar, try to disable mipmaps in your texture profiles
## Functions
- [init](#init)
- [on_style_change](#on_style_change)
- [on_layout_change](#on_layout_change)
- [on_remove](#on_remove)
- [update](#update)
- [fill](#fill)
- [empty](#empty)
@@ -19,8 +26,8 @@ The component used to manage a node as a progress bar, changing the size and sca
- [to](#to)
- [set_max_size](#set_max_size)
## Fields
- [node](#node)
- [on_change](#on_change)
- [style](#style)
@@ -49,31 +56,7 @@ progress:init(node, key, [init_value])
- **Parameters:**
- `node` *(string|node)*: Node name or GUI Node itself.
- `key` *(string)*: Progress bar direction: "x" or "y"
- `[init_value]` *(number|nil)*: Initial value of progress bar. Default: 1
### on_style_change
---
```lua
progress:on_style_change(style)
```
- **Parameters:**
- `style` *(druid.progress.style)*:
### on_layout_change
---
```lua
progress:on_layout_change()
```
### on_remove
---
```lua
progress:on_remove()
```
- `[init_value]` *(number|nil)*: Initial value of progress bar (0 to 1). Default: 1
### update
@@ -186,19 +169,19 @@ Set progress bar max node size
## Fields
<a name="node"></a>
- **node** (_node_)
- **node** (_node_): The progress bar node
<a name="on_change"></a>
- **on_change** (_event_)
- **on_change** (_event_): Event triggered when progress value changes
<a name="style"></a>
- **style** (_druid.progress.style_)
- **style** (_druid.progress.style_): Component style parameters
<a name="key"></a>
- **key** (_string_)
- **key** (_string_): Progress bar direction: "x" or "y"
<a name="prop"></a>
- **prop** (_hash_)
- **prop** (_hash_): Property for scaling the progress bar
<a name="scale"></a>
- **scale** (_unknown_)

53
api/components/extended/slider_api.md
View File

@@ -2,23 +2,29 @@
> at /druid/extended/slider.lua
The component to make a draggable node over a line with a progress report
Basic Druid slider component. Creates a draggable node over a line with progress reporting.
### Setup
Create slider component with druid: `slider = druid:new_slider(node_name, end_pos, callback)`
### Notes
- Pin node should be placed in initial position at zero progress
- It will be available to move Pin node between start pos and end pos
- You can setup points of interests on slider via `slider:set_steps`. If steps exist, slider values will be only from these steps (notched slider)
- Start pos and end pos should be on vertical or horizontal line (their x or y value should be equal)
- To catch input across all slider, you can setup input node via `slider:set_input_node`
## Functions
- [init](#init)
- [on_layout_change](#on_layout_change)
- [on_remove](#on_remove)
- [on_window_resized](#on_window_resized)
- [on_input](#on_input)
- [set](#set)
- [set_steps](#set_steps)
- [set_input_node](#set_input_node)
- [set_enabled](#set_enabled)
- [is_enabled](#is_enabled)
## Fields
- [node](#node)
- [on_change_value](#on_change_value)
- [style](#style)
@@ -39,41 +45,6 @@ The Slider constructor
- `end_pos` *(vector3)*: The end position of slider, should be on the same axis as the node
- `[callback]` *(function|nil)*: On slider change callback
### on_layout_change
---
```lua
slider:on_layout_change()
```
### on_remove
---
```lua
slider:on_remove()
```
### on_window_resized
---
```lua
slider:on_window_resized()
```
### on_input
---
```lua
slider:on_input(action_id, action)
```
- **Parameters:**
- `action_id` *(number)*: The action id
- `action` *(action)*: The action table
- **Returns:**
- `is_consumed` *(boolean)*: True if the input was consumed
### set
---

4
api/components/extended/swipe_api.md
View File

@@ -4,13 +4,13 @@
The component to manage swipe events over a node
## Functions
- [init](#init)
- [set_click_zone](#set_click_zone)
## Fields
- [node](#node)
- [on_swipe](#on_swipe)
- [style](#style)

14
api/components/extended/timer_api.md
View File

@@ -2,17 +2,25 @@
> at /druid/extended/timer.lua
The component that handles a text to display a seconds timer
Druid component to handle timer work on gui text node. Displays time in a formatted way.
### Setup
Create timer component with druid: `timer = druid:new_timer(text_node, from_seconds, to_seconds, callback)`
### Notes
- Timer fires callback when timer value equals to _to_seconds_
- Timer will set text node with current timer value
- Timer uses update function to handle time
## Functions
- [init](#init)
- [set_to](#set_to)
- [set_state](#set_state)
- [set_interval](#set_interval)
## Fields
- [on_tick](#on_tick)
- [on_set_enabled](#on_set_enabled)
- [on_timer_end](#on_timer_end)
@@ -37,7 +45,7 @@ timer:init(node, [seconds_from], [seconds_to], [callback])
- `node` *(node)*: Gui text node
- `[seconds_from]` *(number|nil)*: Start timer value in seconds
- `[seconds_to]` *(number|nil)*: End timer value in seconds
- `[callback]` *(function|nil)*: Function on timer end
- `[callback]` *(function|nil)*: Function that triggers when timer value equals to seconds_to
- **Returns:**
- `` *(druid.timer)*: