diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b280ec2..c9bdbe5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,12 +6,6 @@ Finally, there are set of instructions that will help you to contribute to the p
Thanks for your help!
-## Update Documentation
-
-If you see any mistakes in the documentation, you can update it by yourself.
-
-You can push changes to the `master` branch directly. In case of small fixes, please also update the relative API `md` files. If there is a lot of changes, I will regenerate them manually.
-
## Issue Reporting
If you find any bugs, please report them to the [issue tracker](https://github.com/druid-js/druid/issues).
@@ -26,6 +20,17 @@ You fix should contains only changes, which are related to the issue. Also pleas
Thanks <3
+## Update Documentation
+
+If you see any mistakes in the documentation, you can update it by yourself with the following steps:
+
+- Fork Druid repository
+- Create a new branch for your changes
+- Make your changes and commit them
+- Push your changes to your fork
+- Create a pull request to the Druid repository `develop` branch
+
+
## Add or Update Examples
Examples contains a GUI scene, a Druid widget for this GUI. This GUI is included to the `examples.gui` and the information about examples are added in `examples_list.lua` file
@@ -34,4 +39,12 @@ You can add new examples or update existing ones.
To add new example, you need to create a new folder in the `examples` directory.
+On your repo fork:
+
+- Create a gui file with the example inside `/example/examples` directory
+- Add the example info to the `examples_list.lua` file.
+- Add this GUI template to the `/example/druid.gui` file
+ - GUI should be placed inside relative example parent, e.g. `root -> container_center -> examples -> widgets`
+- Test the example by running the game
+- Create a pull request to the `develop` branch
diff --git a/README.md b/README.md
index 57276f7..e2d2e99 100644
--- a/README.md
+++ b/README.md
@@ -17,8 +17,8 @@ In this example you can inspect a variety of **Druid** components and see how th
## Features
-- **Components** - Provides a extensive set of components, from basic buttons to infinity data lists and rich texts
-- **Customizable** - You can customize components appearance and behaviour
+- **Components Rich** - Provides a extensive set of components, from basic buttons to infinity data lists and rich texts
+- **Customizable** - You can customize components appearance and behaviour with their API and styles
- **Widgets** - Powerful way to create your own reusable components
- **Input Handling** - Handles input in a stack-based manner and manage input priority
- **Event Based** - Uses [Defold Event](https://github.com/Insality/defold-event) for components callbacks and communication between components
@@ -66,7 +66,34 @@ Here is a list of [all releases](https://github.com/Insality/druid/releases).
### Basic usage
-Read more in the [Basic Usage](wiki/basic_usage.md)
+The basic template for `gui_script` is:
+
+```lua
+local druid = require("druid.druid")
+
+function init(self)
+ self.druid = druid.new(self)
+end
+
+function final(self)
+ self.druid:final()
+end
+
+function update(self, dt)
+ self.druid:update(dt)
+end
+
+function on_message(self, message_id, message, sender)
+ self.druid:on_message(message_id, message, sender)
+end
+
+function on_input(self, action_id, action)
+ return self.druid:on_input(action_id, action)
+end
+```
+
+Read the [Basic Usage](wiki/basic_usage.md) to learn how to use **Druid**, how to create your own components and how to use widgets.
+
### API Documentation
@@ -160,8 +187,8 @@ To better understand **Druid**, read the following documentation:
- [How To GUI in Defold](https://forum.defold.com/t/how-to-gui-in-defold/73256)
- [Widgets](wiki/widgets.md)
-- [Create custom components](docs_md/02-creating_custom_components.md)
-- [Druid styles](docs_md/03-styles.md)
+- [Create custom components](wiki/creating_custom_components.md)
+- [Druid styles](wiki/styles.md)
## Licenses
diff --git a/api/components/base/back_handler_api.md b/api/components/base/back_handler_api.md
index f55d129..01b4e59 100644
--- a/api/components/base/back_handler_api.md
+++ b/api/components/base/back_handler_api.md
@@ -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
diff --git a/api/components/base/blocker_api.md b/api/components/base/blocker_api.md
index e7390f1..7068f05 100644
--- a/api/components/base/blocker_api.md
+++ b/api/components/base/blocker_api.md
@@ -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
-- **node** (_node_)
+- **node** (_node_): The node that will block input
diff --git a/api/components/base/button_api.md b/api/components/base/button_api.md
index c80a6ee..ffcf86f 100644
--- a/api/components/base/button_api.md
+++ b/api/components/base/button_api.md
@@ -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)
-- **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
-- **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
-- **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
-- **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
- **on_click_outside** (_event_): function(self, custom_args, button_instance)
diff --git a/api/components/base/component_api.md b/api/components/base/component_api.md
index 4501b2b..ae182de 100644
--- a/api/components/base/component_api.md
+++ b/api/components/base/component_api.md
@@ -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)
diff --git a/api/components/base/drag_api.md b/api/components/base/drag_api.md
index 34640c6..18974de 100644
--- a/api/components/base/drag_api.md
+++ b/api/components/base/drag_api.md
@@ -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)
diff --git a/api/components/base/hover_api.md b/api/components/base/hover_api.md
index 5064a7d..eb96672 100644
--- a/api/components/base/hover_api.md
+++ b/api/components/base/hover_api.md
@@ -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)
diff --git a/api/components/base/scroll_api.md b/api/components/base/scroll_api.md
index cf747dd..141f20b 100644
--- a/api/components/base/scroll_api.md
+++ b/api/components/base/scroll_api.md
@@ -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
-- **on_scroll** (_event_): Triggered on scroll move with (self, position)
+- **on_scroll** (_event_): Triggered on scroll move with fun(self, position)
-- **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)
-- **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)
- **view_node** (_node_): The scroll view node (static part)
@@ -370,7 +388,7 @@ Strict drag scroll area. Useful for
- **points** (_table_)
-- **available_pos_extra** (_unknown_)
+- **available_pos_extra** (_vector4_)
- **available_size_extra** (_vector3_)
diff --git a/api/components/base/static_grid_api.md b/api/components/base/static_grid_api.md
index 795349a..2498d60 100644
--- a/api/components/base/static_grid_api.md
+++ b/api/components/base/static_grid_api.md
@@ -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
+
+- **on_add_item** (_event_): Trigger on add item event, fun(self, item, index)
+
+
+- **on_remove_item** (_event_): Trigger on remove item event, fun(self, index)
+
+
+- **on_change_items** (_event_): Trigger on change items event, fun(self, index)
+
+
+- **on_clear** (_event_): Trigger on clear event, fun(self)
+
+
+- **on_update_positions** (_event_): Trigger on update positions event, fun(self)
+
+
+- **parent** (_node_): Parent node
+
+
+- **nodes** (_node[]_): Nodes array
+
+
+- **first_index** (_number_): First index
+
+
+- **last_index** (_number_): Last index
+
+
+- **anchor** (_vector3_): Anchor
+
+
+- **pivot** (_vector3_): Pivot
+
+
+- **node_size** (_vector3_): Node size
+
+
+- **border** (_vector4_): Border
+
+
+- **in_row** (_number_): In row
+
+
+- **style** (_druid.grid.style_): Style
+
+
+- **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)
diff --git a/api/components/base/text_api.md b/api/components/base/text_api.md
index 4d29dcf..1418939 100644
--- a/api/components/base/text_api.md
+++ b/api/components/base/text_api.md
@@ -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
-- **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
-- **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
-- **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
- **style** (_druid.text.style_): The style of the text
@@ -285,7 +324,7 @@ Return current text adjust type
- **text_area** (_unknown_)
-- **adjust_type** (_string|nil_)
+- **adjust_type** (_string|"downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"...(+6)_)
- **color** (_unknown_)
diff --git a/api/components/custom/rich_input_api.md b/api/components/custom/rich_input_api.md
index 1ebca04..0b2198b 100644
--- a/api/components/custom/rich_input_api.md
+++ b/api/components/custom/rich_input_api.md
@@ -4,10 +4,9 @@
The component that handles a rich text input field, it's a wrapper around the druid.input component
-
## Functions
+
- [init](#init)
-- [on_input](#on_input)
- [set_placeholder](#set_placeholder)
- [select](#select)
- [set_text](#set_text)
@@ -15,8 +14,8 @@ The component that handles a rich text input field, it's a wrapper around the dr
- [get_text](#get_text)
- [set_allowed_characters](#set_allowed_characters)
-
## Fields
+
- [root](#root)
- [input](#input)
- [cursor](#cursor)
@@ -43,20 +42,6 @@ rich_input:init(template, nodes)
- `template` *(string)*: The template string name
- `nodes` *(table)*: Nodes table from gui.clone_tree
-### on_input
-
----
-```lua
-rich_input:on_input([action_id], [action])
-```
-
-- **Parameters:**
- - `[action_id]` *(any)*:
- - `[action]` *(any)*:
-
-- **Returns:**
- - `` *(boolean)*:
-
### set_placeholder
---
@@ -176,7 +161,7 @@ Set allowed charaters for input field.
- **drag** (_druid.drag_): A component that allows you to subscribe to drag events over a node
-- **placeholder** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
+- **placeholder** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting.
- **text_position** (_unknown_)
diff --git a/api/components/custom/rich_text_api.md b/api/components/custom/rich_text_api.md
index a234ae8..4bbaa65 100644
--- a/api/components/custom/rich_text_api.md
+++ b/api/components/custom/rich_text_api.md
@@ -4,8 +4,8 @@
The component that handles a rich text display, allows to custom color, size, font, etc. of the parts of the text
-
## Functions
+
- [init](#init)
- [set_text](#set_text)
- [get_text](#get_text)
@@ -14,8 +14,8 @@ The component that handles a rich text display, allows to custom color, size, fo
- [get_words](#get_words)
- [get_line_metric](#get_line_metric)
-
## Fields
+
- [root](#root)
- [text_prefab](#text_prefab)
- [style](#style)
@@ -52,22 +52,30 @@ Set text for Rich Text
- **Example Usage:**
```lua
+-- Color
rich_text:set_text("<color=red>Foobar</color>")
rich_text:set_text("<color=1.0,0,0,1.0>Foobar</color>")
rich_text:set_text("<color=#ff0000>Foobar</color>")
rich_text:set_text("<color=#ff0000ff>Foobar</color>")
+-- Shadow
rich_text:set_text("<shadow=red>Foobar</shadow>")
rich_text:set_text("<shadow=1.0,0,0,1.0>Foobar</shadow>")
rich_text:set_text("<shadow=#ff0000>Foobar</shadow>")
rich_text:set_text("<shadow=#ff0000ff>Foobar</shadow>")
+-- Outline
rich_text:set_text("<outline=red>Foobar</outline>")
rich_text:set_text("<outline=1.0,0,0,1.0>Foobar</outline>")
rich_text:set_text("<outline=#ff0000>Foobar</outline>")
rich_text:set_text("<outline=#ff0000ff>Foobar</outline>")
+-- Font
rich_text:set_text("<font=MyCoolFont>Foobar</font>")
+-- Size
rich_text:set_text("<size=2>Twice as large</size>")
+-- Line break
rich_text:set_text("<br/>Insert a line break")
+-- No break
rich_text:set_text("<nobr>Prevent the text from breaking")
+-- Image
rich_text:set_text("<img=texture:image>Display image")
rich_text:set_text("<img=texture:image,size>Display image with size")
rich_text:set_text("<img=texture:image,width,height>Display image with width and height")
diff --git a/api/components/extended/container_api.md b/api/components/extended/container_api.md
index 88044d1..a6880a3 100644
--- a/api/components/extended/container_api.md
+++ b/api/components/extended/container_api.md
@@ -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
diff --git a/api/components/extended/data_list_api.md b/api/components/extended/data_list_api.md
index 934cb1b..818bbb2 100644
--- a/api/components/extended/data_list_api.md
+++ b/api/components/extended/data_list_api.md
@@ -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
---
diff --git a/api/components/extended/hotkey_api.md b/api/components/extended/hotkey_api.md
index 5231bd0..6252692 100644
--- a/api/components/extended/hotkey_api.md
+++ b/api/components/extended/hotkey_api.md
@@ -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
---
diff --git a/api/components/extended/input_api.md b/api/components/extended/input_api.md
index 738498c..fbfab44 100644
--- a/api/components/extended/input_api.md
+++ b/api/components/extended/input_api.md
@@ -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
- **style** (_druid.input.style_): The style of the input component
-
-- **text** (_druid.text_): The text component
-
-
-- **ALLOWED_ACTIONS** (_table_)
-
- **druid** (_druid.instance_): The Druid Factory used to create components
+
+- **text** (_druid.text|node_): Basic Druid text component. Text components by default have the text size adjusting.
+
- **is_selected** (_boolean_)
@@ -304,10 +297,10 @@ Change cursor position by delta
- **allowed_characters** (_nil_)
-- **keyboard_type** (_number_)
+- **keyboard_type** (_constant_)
-- **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.
- **marked_text_width** (_number_)
diff --git a/api/components/extended/lang_text_api.md b/api/components/extended/lang_text_api.md
index 8bd9b10..ebb23ac 100644
--- a/api/components/extended/lang_text_api.md
+++ b/api/components/extended/lang_text_api.md
@@ -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
diff --git a/api/components/extended/layout_api.md b/api/components/extended/layout_api.md
index 470ac7c..29cffba 100644
--- a/api/components/extended/layout_api.md
+++ b/api/components/extended/layout_api.md
@@ -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
-- **is_dirty** (_boolean_)
+- **is_dirty** (_boolean_): True if layout needs to be updated
- **entities** (_node[]_): The entities to manage the layout of
diff --git a/api/components/extended/progress_api.md b/api/components/extended/progress_api.md
index e14f5a1..e3c8947 100644
--- a/api/components/extended/progress_api.md
+++ b/api/components/extended/progress_api.md
@@ -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
-- **node** (_node_)
+- **node** (_node_): The progress bar node
-- **on_change** (_event_)
+- **on_change** (_event_): Event triggered when progress value changes
-- **style** (_druid.progress.style_)
+- **style** (_druid.progress.style_): Component style parameters
-- **key** (_string_)
+- **key** (_string_): Progress bar direction: "x" or "y"
-- **prop** (_hash_)
+- **prop** (_hash_): Property for scaling the progress bar
- **scale** (_unknown_)
diff --git a/api/components/extended/slider_api.md b/api/components/extended/slider_api.md
index 1d74989..834ee4b 100644
--- a/api/components/extended/slider_api.md
+++ b/api/components/extended/slider_api.md
@@ -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
---
diff --git a/api/components/extended/swipe_api.md b/api/components/extended/swipe_api.md
index 0ecb1cb..2b5fa1d 100644
--- a/api/components/extended/swipe_api.md
+++ b/api/components/extended/swipe_api.md
@@ -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)
diff --git a/api/components/extended/timer_api.md b/api/components/extended/timer_api.md
index e483443..58a9c91 100644
--- a/api/components/extended/timer_api.md
+++ b/api/components/extended/timer_api.md
@@ -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)*:
diff --git a/api/components/widgets/fps_panel_api.md b/api/components/widgets/fps_panel_api.md
index 273120d..abcf84f 100644
--- a/api/components/widgets/fps_panel_api.md
+++ b/api/components/widgets/fps_panel_api.md
@@ -2,15 +2,15 @@
> at /druid/widget/fps_panel/fps_panel.lua
-
## Functions
+
- [init](#init)
- [on_remove](#on_remove)
- [update](#update)
- [push_fps_value](#push_fps_value)
-
## Fields
+
- [root](#root)
- [delta_time](#delta_time)
- [collect_time](#collect_time)
@@ -78,16 +78,12 @@ fps_panel:push_fps_value()
- **mini_graph** (_druid.widget.mini_graph_): Widget to display a several lines with different height in a row
-Init, set amount of samples and max value of value means that the line will be at max height
-Use `push_line_value` to add a new value to the line
-Or `set_line_value` to set a value to the line by index
-Setup colors inside template file (at minimum and maximum)
-- **text_min_fps** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
+- **text_min_fps** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting.
-- **text_fps** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
+- **text_fps** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting.
- **timer_id** (_unknown_)
diff --git a/api/components/widgets/memory_panel_api.md b/api/components/widgets/memory_panel_api.md
index a530bc8..0661cce 100644
--- a/api/components/widgets/memory_panel_api.md
+++ b/api/components/widgets/memory_panel_api.md
@@ -2,16 +2,16 @@
> at /druid/widget/memory_panel/memory_panel.lua
-
## Functions
+
- [init](#init)
- [on_remove](#on_remove)
- [set_low_memory_limit](#set_low_memory_limit)
- [push_next_value](#push_next_value)
- [update_text_memory](#update_text_memory)
-
## Fields
+
- [root](#root)
- [delta_time](#delta_time)
- [samples_count](#samples_count)
@@ -80,19 +80,15 @@ memory_panel:update_text_memory()
- **mini_graph** (_druid.widget.mini_graph_): Widget to display a several lines with different height in a row
-Init, set amount of samples and max value of value means that the line will be at max height
-Use `push_line_value` to add a new value to the line
-Or `set_line_value` to set a value to the line by index
-Setup colors inside template file (at minimum and maximum)
-- **max_value** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
+- **max_value** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting.
-- **text_per_second** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
+- **text_per_second** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting.
-- **text_memory** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
+- **text_memory** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting.
- **memory** (_unknown_)
diff --git a/api/components/widgets/mini_graph_api.md b/api/components/widgets/mini_graph_api.md
index e34291e..d0bf501 100644
--- a/api/components/widgets/mini_graph_api.md
+++ b/api/components/widgets/mini_graph_api.md
@@ -8,8 +8,8 @@ Use `push_line_value` to add a new value to the line
Or `set_line_value` to set a value to the line by index
Setup colors inside template file (at minimum and maximum)
-
## Functions
+
- [init](#init)
- [on_remove](#on_remove)
- [clear](#clear)
@@ -25,8 +25,8 @@ Setup colors inside template file (at minimum and maximum)
- [on_drag_widget](#on_drag_widget)
- [toggle_hide](#toggle_hide)
-
## Fields
+
- [root](#root)
- [text_header](#text_header)
- [icon_drag](#icon_drag)
@@ -190,7 +190,7 @@ mini_graph:toggle_hide()
- **root** (_node_)
-- **text_header** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
+- **text_header** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting.
- **icon_drag** (_node_)
@@ -199,7 +199,7 @@ mini_graph:toggle_hide()
- **content** (_node_)
-- **layout** (_druid.layout_): 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
+- **layout** (_druid.layout_): Druid component to manage the layout of nodes, placing them inside the node size with respect to the size and pivot of each node.
- **prefab_line** (_node_)
@@ -223,7 +223,7 @@ mini_graph:toggle_hide()
- **values** (_table_)
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
+- **container** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts.
- **default_size** (_vector3_)
diff --git a/api/components/widgets/properties_panel/property_button_api.md b/api/components/widgets/properties_panel/property_button_api.md
deleted file mode 100644
index fd9daa4..0000000
--- a/api/components/widgets/properties_panel/property_button_api.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# druid.widget.property_button API
-
-> at /druid/widget/properties_panel/properties/property_button.lua
-
-
-## Functions
-- [init](#init)
-- [on_click](#on_click)
-- [set_text_property](#set_text_property)
-- [set_text_button](#set_text_button)
-- [set_color](#set_color)
-
-
-## Fields
-- [root](#root)
-- [container](#container)
-- [text_name](#text_name)
-- [button](#button)
-- [text_button](#text_button)
-- [druid](#druid)
-- [selected](#selected)
-
-
-
-### init
-
----
-```lua
-property_button:init()
-```
-
-### on_click
-
----
-```lua
-property_button:on_click()
-```
-
-### set_text_property
-
----
-```lua
-property_button:set_text_property(text)
-```
-
-- **Parameters:**
- - `text` *(string)*:
-
-- **Returns:**
- - `` *(druid.widget.property_button)*:
-
-### set_text_button
-
----
-```lua
-property_button:set_text_button(text)
-```
-
-- **Parameters:**
- - `text` *(string)*:
-
-- **Returns:**
- - `` *(druid.widget.property_button)*:
-
-### set_color
-
----
-```lua
-property_button:set_color([color_value])
-```
-
-- **Parameters:**
- - `[color_value]` *(any)*:
-
-
-## Fields
-
-- **root** (_node_)
-
-
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
-
-
-- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks
-
-
-- **text_button** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **druid** (_druid.instance_): The Druid Factory used to create components
-
-
-- **selected** (_node_)
-
diff --git a/api/components/widgets/properties_panel/property_checkbox_api.md b/api/components/widgets/properties_panel/property_checkbox_api.md
deleted file mode 100644
index 95cf50c..0000000
--- a/api/components/widgets/properties_panel/property_checkbox_api.md
+++ /dev/null
@@ -1,112 +0,0 @@
-
-# druid.widget.property_checkbox API
-
-> at /druid/widget/properties_panel/properties/property_checkbox.lua
-
-
-## Functions
-- [init](#init)
-- [set_value](#set_value)
-- [get_value](#get_value)
-- [on_click](#on_click)
-- [set_text_property](#set_text_property)
-- [on_change](#on_change)
-
-
-## Fields
-- [root](#root)
-- [druid](#druid)
-- [text_name](#text_name)
-- [button](#button)
-- [selected](#selected)
-- [icon](#icon)
-- [container](#container)
-- [on_change_value](#on_change_value)
-
-
-
-### init
-
----
-```lua
-property_checkbox:init()
-```
-
-### set_value
-
----
-```lua
-property_checkbox:set_value(value, [is_instant])
-```
-
-- **Parameters:**
- - `value` *(boolean)*:
- - `[is_instant]` *(any)*:
-
-### get_value
-
----
-```lua
-property_checkbox:get_value()
-```
-
-- **Returns:**
- - `` *(boolean)*:
-
-### on_click
-
----
-```lua
-property_checkbox:on_click()
-```
-
-### set_text_property
-
----
-```lua
-property_checkbox:set_text_property(text)
-```
-
-Set the text property of the checkbox
-
-- **Parameters:**
- - `text` *(string)*:
-
-### on_change
-
----
-```lua
-property_checkbox:on_change(callback)
-```
-
-Set the callback function for when the checkbox value changes
-
-- **Parameters:**
- - `callback` *(function)*:
-
-
-## Fields
-
-- **root** (_node_)
-
-
-- **druid** (_druid.instance_): The Druid Factory used to create components
-
-
-- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks
-
-
-- **selected** (_node_)
-
-
-- **icon** (_node_)
-
-
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
-
-
-- **on_change_value** (_unknown_)
-
diff --git a/api/components/widgets/properties_panel/property_input_api.md b/api/components/widgets/properties_panel/property_input_api.md
deleted file mode 100644
index f889ddb..0000000
--- a/api/components/widgets/properties_panel/property_input_api.md
+++ /dev/null
@@ -1,90 +0,0 @@
-# druid.widget.property_input API
-
-> at /druid/widget/properties_panel/properties/property_input.lua
-
-## Functions
-
-- [init](#init)
-- [set_text_property](#set_text_property)
-- [set_text_value](#set_text_value)
-- [on_change](#on_change)
-
-## Fields
-
-- [root](#root)
-- [container](#container)
-- [text_name](#text_name)
-- [button](#button)
-- [druid](#druid)
-- [selected](#selected)
-- [rich_input](#rich_input)
-
-
-
-### init
-
----
-```lua
-property_input:init()
-```
-
-### set_text_property
-
----
-```lua
-property_input:set_text_property(text)
-```
-
-- **Parameters:**
- - `text` *(string)*:
-
-- **Returns:**
- - `` *(druid.widget.property_input)*:
-
-### set_text_value
-
----
-```lua
-property_input:set_text_value(text)
-```
-
-- **Parameters:**
- - `text` *(string|number)*:
-
-- **Returns:**
- - `` *(druid.widget.property_input)*:
-
-### on_change
-
----
-```lua
-property_input:on_change(callback, [callback_context])
-```
-
-- **Parameters:**
- - `callback` *(fun(self: druid.widget.property_input, text: string))*:
- - `[callback_context]` *(any)*:
-
-
-## Fields
-
-- **root** (_node_)
-
-
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
-
-
-- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks
-
-
-- **druid** (_druid.instance_): The Druid Factory used to create components
-
-
-- **selected** (_node_)
-
-
-- **rich_input** (_druid.rich_input_): The component that handles a rich text input field, it's a wrapper around the druid.input component
-
diff --git a/api/components/widgets/properties_panel/property_left_right_selector_api.md b/api/components/widgets/properties_panel/property_left_right_selector_api.md
deleted file mode 100644
index db194e2..0000000
--- a/api/components/widgets/properties_panel/property_left_right_selector_api.md
+++ /dev/null
@@ -1,171 +0,0 @@
-# druid.widget.property_left_right_selector API
-
-> at /druid/widget/properties_panel/properties/property_left_right_selector.lua
-
-
-## Functions
-- [init](#init)
-- [set_text](#set_text)
-- [on_button_left](#on_button_left)
-- [on_button_right](#on_button_right)
-- [add_step](#add_step)
-- [set_number_type](#set_number_type)
-- [set_array_type](#set_array_type)
-- [set_value](#set_value)
-- [get_value](#get_value)
-
-
-## Fields
-- [root](#root)
-- [druid](#druid)
-- [text_name](#text_name)
-- [button](#button)
-- [selected](#selected)
-- [value](#value)
-- [on_change_value](#on_change_value)
-- [text_value](#text_value)
-- [button_left](#button_left)
-- [button_right](#button_right)
-- [container](#container)
-- [number_type](#number_type)
-- [array_type](#array_type)
-
-
-
-### init
-
----
-```lua
-property_left_right_selector:init()
-```
-
-### set_text
-
----
-```lua
-property_left_right_selector:set_text([text])
-```
-
-- **Parameters:**
- - `[text]` *(any)*:
-
-- **Returns:**
- - `` *(druid.widget.property_left_right_selector)*:
-
-### on_button_left
-
----
-```lua
-property_left_right_selector:on_button_left()
-```
-
-### on_button_right
-
----
-```lua
-property_left_right_selector:on_button_right()
-```
-
-### add_step
-
----
-```lua
-property_left_right_selector:add_step(koef)
-```
-
-- **Parameters:**
- - `koef` *(number)*: -1 0 1, on 0 will not move
-
-### set_number_type
-
----
-```lua
-property_left_right_selector:set_number_type([min], [max], [is_loop], [steps])
-```
-
-- **Parameters:**
- - `[min]` *(any)*:
- - `[max]` *(any)*:
- - `[is_loop]` *(any)*:
- - `[steps]` *(any)*:
-
-- **Returns:**
- - `` *(druid.widget.property_left_right_selector)*:
-
-### set_array_type
-
----
-```lua
-property_left_right_selector:set_array_type([array], [is_loop], [steps])
-```
-
-- **Parameters:**
- - `[array]` *(any)*:
- - `[is_loop]` *(any)*:
- - `[steps]` *(any)*:
-
-- **Returns:**
- - `` *(druid.widget.property_left_right_selector)*:
-
-### set_value
-
----
-```lua
-property_left_right_selector:set_value(value, [is_instant])
-```
-
-- **Parameters:**
- - `value` *(string|number)*:
- - `[is_instant]` *(any)*:
-
-### get_value
-
----
-```lua
-property_left_right_selector:get_value()
-```
-
-- **Returns:**
- - `` *(string|number)*:
-
-
-## Fields
-
-- **root** (_node_)
-
-
-- **druid** (_druid.instance_): The Druid Factory used to create components
-
-
-- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks
-
-
-- **selected** (_node_)
-
-
-- **value** (_string_)
-
-
-- **on_change_value** (_event_): fun(value: string|number)
-
-
-- **text_value** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **button_left** (_druid.button_): Druid component to make clickable node with various interaction callbacks
-
-
-- **button_right** (_druid.button_): Druid component to make clickable node with various interaction callbacks
-
-
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
-
-
-- **number_type** (_table_)
-
-
-- **array_type** (_table_)
-
diff --git a/api/components/widgets/properties_panel/property_slider_api.md b/api/components/widgets/properties_panel/property_slider_api.md
deleted file mode 100644
index 3c0cb19..0000000
--- a/api/components/widgets/properties_panel/property_slider_api.md
+++ /dev/null
@@ -1,150 +0,0 @@
-# druid.widget.property_slider API
-
-> at /druid/widget/properties_panel/properties/property_slider.lua
-
-
-## Functions
-- [init](#init)
-- [set_text_function](#set_text_function)
-- [set_text_property](#set_text_property)
-- [on_change](#on_change)
-- [set_value](#set_value)
-- [get_value](#get_value)
-- [update_value](#update_value)
-- [set_number_type](#set_number_type)
-
-
-## Fields
-- [root](#root)
-- [container](#container)
-- [druid](#druid)
-- [text_name](#text_name)
-- [text_value](#text_value)
-- [slider](#slider)
-- [on_change_value](#on_change_value)
-- [selected](#selected)
-- [min](#min)
-- [max](#max)
-- [step](#step)
-
-
-
-### init
-
----
-```lua
-property_slider:init()
-```
-
-### set_text_function
-
----
-```lua
-property_slider:set_text_function(callback)
-```
-
-- **Parameters:**
- - `callback` *(fun(value: number):string)*:
-
-### set_text_property
-
----
-```lua
-property_slider:set_text_property(text)
-```
-
-Sets the text property of the slider
-
-- **Parameters:**
- - `text` *(string)*:
-
-### on_change
-
----
-```lua
-property_slider:on_change(callback)
-```
-
-Sets the callback function for when the slider value changes
-
-- **Parameters:**
- - `callback` *(fun(value: number))*:
-
-### set_value
-
----
-```lua
-property_slider:set_value(value, [is_instant])
-```
-
-- **Parameters:**
- - `value` *(number)*:
- - `[is_instant]` *(any)*:
-
-### get_value
-
----
-```lua
-property_slider:get_value()
-```
-
-- **Returns:**
- - `` *(number)*:
-
-### update_value
-
----
-```lua
-property_slider:update_value([value])
-```
-
-- **Parameters:**
- - `[value]` *(any)*:
-
-### set_number_type
-
----
-```lua
-property_slider:set_number_type([min], [max], [step])
-```
-
-- **Parameters:**
- - `[min]` *(any)*:
- - `[max]` *(any)*:
- - `[step]` *(any)*:
-
-
-## Fields
-
-- **root** (_node_)
-
-
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
-
-
-- **druid** (_druid.instance_): The Druid Factory used to create components
-
-
-- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **text_value** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **slider** (_druid.slider_): The component to make a draggable node over a line with a progress report
-
-
-- **on_change_value** (_event_): fun(value:number)
-
-
-- **selected** (_node_)
-
-
-- **min** (_integer_)
-
-
-- **max** (_integer_)
-
-
-- **step** (_number_)
-
diff --git a/api/components/widgets/properties_panel/property_text_api.md b/api/components/widgets/properties_panel/property_text_api.md
deleted file mode 100644
index 331e1bf..0000000
--- a/api/components/widgets/properties_panel/property_text_api.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# druid.widget.property_text API
-
-> at /druid/widget/properties_panel/properties/property_text.lua
-
-
-## Functions
-- [init](#init)
-- [set_text_property](#set_text_property)
-- [set_text_value](#set_text_value)
-
-
-## Fields
-- [root](#root)
-- [container](#container)
-- [text_name](#text_name)
-- [text_right](#text_right)
-
-
-
-### init
-
----
-```lua
-property_text:init()
-```
-
-### set_text_property
-
----
-```lua
-property_text:set_text_property(text)
-```
-
-- **Parameters:**
- - `text` *(string)*:
-
-- **Returns:**
- - `` *(druid.widget.property_text)*:
-
-### set_text_value
-
----
-```lua
-property_text:set_text_value([text])
-```
-
-- **Parameters:**
- - `[text]` *(string|nil)*:
-
-- **Returns:**
- - `` *(druid.widget.property_text)*:
-
-
-## Fields
-
-- **root** (_node_)
-
-
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
-
-
-- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **text_right** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
diff --git a/api/components/widgets/properties_panel/property_vector3_api.md b/api/components/widgets/properties_panel/property_vector3_api.md
deleted file mode 100644
index a7eda57..0000000
--- a/api/components/widgets/properties_panel/property_vector3_api.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# druid.widget.property_vector3 API
-
-> at /druid/widget/properties_panel/properties/property_vector3.lua
-
-
-## Functions
-- [init](#init)
-- [set_text_property](#set_text_property)
-- [set_value](#set_value)
-
-
-## Fields
-- [root](#root)
-- [container](#container)
-- [text_name](#text_name)
-- [button](#button)
-- [druid](#druid)
-- [selected_x](#selected_x)
-- [selected_y](#selected_y)
-- [selected_z](#selected_z)
-- [rich_input_x](#rich_input_x)
-- [rich_input_y](#rich_input_y)
-- [rich_input_z](#rich_input_z)
-- [value](#value)
-- [on_change](#on_change)
-
-
-
-### init
-
----
-```lua
-property_vector3:init()
-```
-
-### set_text_property
-
----
-```lua
-property_vector3:set_text_property(text)
-```
-
-- **Parameters:**
- - `text` *(string)*:
-
-- **Returns:**
- - `` *(druid.widget.property_vector3)*:
-
-### set_value
-
----
-```lua
-property_vector3:set_value(x, y, z)
-```
-
-- **Parameters:**
- - `x` *(number)*:
- - `y` *(number)*:
- - `z` *(number)*:
-
-- **Returns:**
- - `` *(druid.widget.property_vector3)*:
-
-
-## Fields
-
-- **root** (_node_)
-
-
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
-
-
-- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
-
-
-- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks
-
-
-- **druid** (_druid.instance_): The Druid Factory used to create components
-
-
-- **selected_x** (_node_)
-
-
-- **selected_y** (_node_)
-
-
-- **selected_z** (_node_)
-
-
-- **rich_input_x** (_druid.rich_input_): The component that handles a rich text input field, it's a wrapper around the druid.input component
-
-
-- **rich_input_y** (_druid.rich_input_): The component that handles a rich text input field, it's a wrapper around the druid.input component
-
-
-- **rich_input_z** (_druid.rich_input_): The component that handles a rich text input field, it's a wrapper around the druid.input component
-
-
-- **value** (_unknown_)
-
-
-- **on_change** (_unknown_)
-
diff --git a/api/components/widgets/properties_panel_api.md b/api/components/widgets/properties_panel_api.md
index 2b82694..94ed4a3 100644
--- a/api/components/widgets/properties_panel_api.md
+++ b/api/components/widgets/properties_panel_api.md
@@ -2,8 +2,8 @@
> at /druid/widget/properties_panel/properties_panel.lua
-
## Functions
+
- [properties_constructors](#properties_constructors)
- [init](#init)
- [on_remove](#on_remove)
@@ -27,8 +27,8 @@
- [set_properties_per_page](#set_properties_per_page)
- [set_page](#set_page)
-
## Fields
+
- [root](#root)
- [scroll](#scroll)
- [layout](#layout)
@@ -299,28 +299,28 @@ properties_panel:set_page([page])
- **root** (_node_)
-- **scroll** (_druid.scroll_)
+- **scroll** (_druid.scroll_): Basic Druid scroll component. Handles all scrolling behavior in Druid GUI.
-- **layout** (_druid.layout_): 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
+- **layout** (_druid.layout_): Druid component to manage the layout of nodes, placing them inside the node size with respect to the size and pivot of each node.
-- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
+- **container** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts.
-- **container_content** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
+- **container_content** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts.
-- **container_scroll_view** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
+- **container_scroll_view** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts.
-- **contaienr_scroll_content** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts
+- **contaienr_scroll_content** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts.
-- **button_hidden** (_druid.button_): Druid component to make clickable node with various interaction callbacks
+- **button_hidden** (_druid.button_): Basic Druid input component. Handle input on node and provide different callbacks on touch events.
-- **text_header** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area
+- **text_header** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting.
- **paginator** (_druid.widget.property_left_right_selector_)
diff --git a/api/druid_api.md b/api/druid_api.md
index aa43670..52ae0f9 100644
--- a/api/druid_api.md
+++ b/api/druid_api.md
@@ -5,17 +5,19 @@
Entry point for Druid UI Framework.
Create a new Druid instance and adjust the Druid settings here.
-## Table of Contents
-
-
## Functions
+
- [new](#new)
+- [register](#register)
- [set_default_style](#set_default_style)
- [set_text_function](#set_text_function)
- [set_sound_function](#set_sound_function)
- [init_window_listener](#init_window_listener)
- [on_window_callback](#on_window_callback)
- [on_language_change](#on_language_change)
+- [get_widget](#get_widget)
+- [register_druid_as_widget](#register_druid_as_widget)
+- [unregister_druid_as_widget](#unregister_druid_as_widget)
@@ -35,6 +37,23 @@ Create a new Druid instance for creating GUI components.
- **Returns:**
- `druid_instance` *(druid.instance)*: The new Druid instance
+### register
+
+---
+```lua
+druid.register(name, module)
+```
+
+Register a new external Druid component.
+Register component just makes the druid:new_{name} function.
+For example, if you register a component called "my_component", you can create it using druid:new_my_component(...).
+This can be useful if you have your own "basic" components that you don't want to require in every file.
+The default way to create component is `druid_instance:new(component_class, ...)`.
+
+- **Parameters:**
+ - `name` *(string)*: Module name
+ - `module` *(table)*: Lua table with component
+
### set_default_style
---
@@ -102,3 +121,52 @@ druid.on_language_change()
Call this function when the game language changes.
It will notify all Druid instances to update the lang text components.
+
+### get_widget
+
+---
+```lua
+druid.get_widget(widget_class, gui_url)
+```
+
+Create a widget from the binded Druid GUI instance.
+The widget will be created and all widget functions can be called from Game Object contexts.
+This allow use only `druid_widget.gui_script` for GUI files and call this widget functions from Game Object script file.
+Widget class here is a your lua file for the GUI scene (a widgets in Druid)
+
+- **Parameters:**
+ - `widget_class` *()*: The class of the widget to return
+ - `gui_url` *(url)*: GUI url
+
+- **Returns:**
+ - `widget` *(?)*: The new created widget,
+
+- **Example Usage:**
+
+```lua
+msg.url(nil, nil, "gui_widget") -- current game object
+msg.url(nil, object_url, "gui_widget") -- other game object
+```
+### register_druid_as_widget
+
+---
+```lua
+druid.register_druid_as_widget(druid)
+```
+
+Bind a Druid GUI instance to the current game object.
+This instance now can produce widgets from `druid.get_widget()` function.
+Only one widget can be set per game object.
+
+- **Parameters:**
+ - `druid` *(druid.instance)*: The druid instance to register
+
+### unregister_druid_as_widget
+
+---
+```lua
+druid.unregister_druid_as_widget()
+```
+
+Should be called on final, where druid instance is destroyed.
+
diff --git a/api/druid_helper_api.md b/api/druid_helper_api.md
index 98ba510..121ea6e 100644
--- a/api/druid_helper_api.md
+++ b/api/druid_helper_api.md
@@ -5,8 +5,8 @@
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)
@@ -27,6 +27,7 @@ You can use these functions in your projects as well.
- [get_scene_scale](#get_scene_scale)
- [get_closest_stencil_node](#get_closest_stencil_node)
- [get_pivot_offset](#get_pivot_offset)
+- [is_desktop](#is_desktop)
- [is_mobile](#is_mobile)
- [is_web](#is_web)
- [is_web_mobile](#is_web_mobile)
@@ -40,13 +41,6 @@ You can use these functions in your projects as well.
- [get_animation_data_from_node](#get_animation_data_from_node)
-## 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
@@ -194,7 +188,7 @@ Calculate distance between two points
- `y2` *(number)*: Second point y
- **Returns:**
- - `Distance` *(number)*:
+ - `distance` *(number)*:
### sign
@@ -258,7 +252,7 @@ Check if value contains in array
- `[value]` *(any)*: Value
- **Returns:**
- - `` *(integer|nil)*:
+ - `index` *(number|nil)*: Index of value in array or nil if value not found
### deepcopy
@@ -371,6 +365,18 @@ Offset shown in [-0.5 .. 0.5] range, where -0.5 is left or bottom, 0.5 is right
- **Returns:**
- `offset` *(vector3)*: The pivot offset
+### is_desktop
+
+---
+```lua
+helper.is_desktop()
+```
+
+Check if device is desktop
+
+- **Returns:**
+ - `` *(boolean)*:
+
### is_mobile
---
@@ -532,17 +538,3 @@ helper.get_animation_data_from_node(node, atlas_path)
- **Returns:**
- `` *(druid.system.animation_data)*:
-
-## Fields
-
-- **PROP_SIZE_X** (_unknown_)
-
-
-- **PROP_SIZE_Y** (_unknown_)
-
-
-- **PROP_SCALE_X** (_unknown_)
-
-
-- **PROP_SCALE_Y** (_unknown_)
-
diff --git a/api/druid_instance_api.md b/api/druid_instance_api.md
index 5979f00..4ff1195 100644
--- a/api/druid_instance_api.md
+++ b/api/druid_instance_api.md
@@ -4,9 +4,10 @@
The Druid Factory used to create components
-
## Functions
+
- [create_druid_instance](#create_druid_instance)
+
- [new](#new)
- [final](#final)
- [remove](#remove)
@@ -39,11 +40,6 @@ The Druid Factory used to create components
- [new_rich_input](#new_rich_input)
-## Fields
-- [components_all](#components_all)
-- [components_interest](#components_interest)
-
-
### create_druid_instance
@@ -59,7 +55,7 @@ Druid class constructor which used to create a Druid's components
- `[style]` *(table?)*: Druid style table
- **Returns:**
- - `` *(druid.instance)*:
+ - `instance` *(druid.instance)*: The new Druid instance
### new
@@ -94,7 +90,7 @@ instance:remove(component)
```
Remove created component from Druid instance.
- Component `on_remove` function will be invoked, if exist.
+Component `on_remove` function will be invoked, if exist.
- **Parameters:**
- `component` *()*: Component instance
@@ -202,7 +198,7 @@ Create new Druid widget instance
- **Parameters:**
- `widget` *()*: The widget class to create
- `[template]` *(string|nil)*: The template name used by widget
- - `[nodes]` *(node|table|nil)*: The nodes table from gui.clone_tree or prefab node to use for clone
+ - `[nodes]` *(string|node|table|nil)*: The nodes table from gui.clone_tree or prefab node to use for clone or node id to clone
- `...` *(...)*: vararg
- **Returns:**
@@ -251,7 +247,7 @@ instance:new_back_handler([callback], [params])
Create BackHandler component
- **Parameters:**
- - `[callback]` *(function|nil)*: The callback(self, custom_args) to call on back event
+ - `[callback]` *(function|event|nil)*: The callback(self, custom_args) to call on back event
- `[params]` *(any)*: Callback argument
- **Returns:**
@@ -284,7 +280,7 @@ instance:new_text(node, [value], [adjust_type])
Create Text component
- **Parameters:**
- - `node` *(string|node)*: The node_id or gui.get_node(node_id)
+ - `node` *(string|druid.text|node)*: The node_id or gui.get_node(node_id)
- `[value]` *(string|nil)*: Initial text. Default value is node text from GUI scene.
- `[adjust_type]` *(string|nil)*: Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
@@ -368,7 +364,7 @@ Create LangText component
- **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
- - `[adjust_type]` *(string|nil)*: Adjust type for text node. Default: const.TEXT_ADJUST.DOWNSCALE
+ - `[adjust_type]` *(string|nil)*: Adjust type for text node. Default: "downscale"
- **Returns:**
- `lang_text` *(druid.lang_text)*: The new lang text component
@@ -453,7 +449,7 @@ Create Progress component
- **Parameters:**
- `node` *(string|node)*: Progress bar fill node or node name
- - `key` *(string)*: Progress bar direction: const.SIDE.X or const.SIDE.Y
+ - `key` *(string)*: Progress bar direction: "x" or "y"
- `[init_value]` *(number|nil)*: Initial value of progress bar. Default: 1
- **Returns:**
@@ -533,7 +529,7 @@ instance:new_rich_input(template, [nodes])
```
Create RichInput component.
- As a template please check rich_input.gui layout.
+As a template please check rich_input.gui layout.
- **Parameters:**
- `template` *(string)*: The template string name
@@ -542,11 +538,3 @@ Create RichInput component.
- **Returns:**
- `rich_input` *(druid.rich_input)*: The new rich input component
-
-## Fields
-
-- **components_all** (_druid.component[]_): All created components
-
-
-- **components_interest** (_table_): All components sorted by interest
-
diff --git a/api/quick_api_reference.md b/api/quick_api_reference.md
index 2055a62..5eea929 100644
--- a/api/quick_api_reference.md
+++ b/api/quick_api_reference.md
@@ -114,6 +114,7 @@ component:set_style([druid_style])
component:set_template([template])
-- All widgets goes with created Druid instance
+-- All other component's functions also exists
widget.druid
```
@@ -152,23 +153,6 @@ button.on_long_click
button.on_double_click
button.on_hold_callback
button.on_click_outside
-button.node
-button.node_id
-button.anim_node
-button.params
-button.hover
-button.click_zone
-button.start_scale
-button.start_pos
-button.disabled
-button.key_trigger
-button.style
-button.druid
-button.is_repeated_started
-button.last_pressed_time
-button.last_released_time
-button.click_in_row
-button.can_action
```
### [Container](components/extended/container_api.md)
@@ -198,6 +182,8 @@ container:set_pivot(pivot)
container:set_position(pos_x, pos_y)
container:set_size([width], [height], [anchor_pivot])
container:update_child_containers()
+
+container.on_size_changeed
```
### [Data List](components/extended/data_list_api.md)
@@ -218,6 +204,10 @@ data_list:remove_by_data(data, [shift_policy])
data_list:scroll_to_index(index)
data_list:set_data(data)
data_list:set_use_cache(is_use_cache)
+
+data_list.on_scroll_progress_change
+data_list.on_element_add
+data_list.on_element_remove
```
### [Drag](components/base/drag_api.md)
@@ -232,6 +222,12 @@ drag:on_window_resized()
drag:set_click_zone([node])
drag:set_drag_cursors(is_enabled)
drag:set_enabled(is_enabled)
+
+drag.on_touch_start
+drag.on_touch_end
+drag.on_drag_start
+drag.on_drag
+drag.on_drag_end
```
### [Grid](components/base/static_grid_api.md)
@@ -260,6 +256,12 @@ grid:set_items(nodes, [is_instant])
grid:set_pivot([pivot])
grid:set_position_function(callback)
grid:sort_nodes(comparator)
+
+grid.on_add_item
+grid.on_remove_item
+grid.on_change_items
+grid.on_clear
+grid.on_update_positions
```
### [Hotkey](components/extended/hotkey_api.md)
@@ -273,6 +275,9 @@ hotkey:add_hotkey(keys, [callback_argument])
hotkey:is_processing()
hotkey:on_focus_gained()
hotkey:set_repeat(is_enabled_repeated)
+
+hotkey.on_hotkey_pressed
+hotkey.on_hotkey_released
```
### [Hover](components/base/hover_api.md)
@@ -289,6 +294,9 @@ hover:set_click_zone([zone])
hover:set_enabled([state])
hover:set_hover([state])
hover:set_mouse_hover([state])
+
+hover.on_hover
+hover.on_mouse_hover
```
### [Input](components/extended/input_api.md)
@@ -310,6 +318,14 @@ input:set_allowed_characters(characters)
input:set_max_length(max_length)
input:set_text(input_text)
input:unselect()
+
+input.on_input_select
+input.on_input_unselect
+input.on_input_text
+input.on_input_empty
+input.on_input_full
+input.on_input_wrong
+input.on_select_cursor_change
```
### [Lang Text](components/extended/lang_text_api.md)
@@ -324,6 +340,8 @@ lang_text:on_language_change()
lang_text:set_text(text)
lang_text:set_to(text)
lang_text:translate(locale_id, [a], [b], [c], [d], [e], [f], [g])
+
+lang_text.on_change
```
### [Layout](components/extended/layout_api.md)
@@ -351,6 +369,8 @@ layout:set_node_position(node, x, y)
layout:set_padding([padding_x], [padding_y], [padding_z], [padding_w])
layout:set_type(type)
layout:update()
+
+layout.on_size_changed
```
### [Progress](components/extended/progress_api.md)
@@ -368,6 +388,8 @@ progress:set_steps(steps, callback)
progress:set_to(to)
progress:to(to, [callback])
progress:update([dt])
+
+progress.on_change
```
### [Rich Input](components/custom/rich_input_api.md)
@@ -426,6 +448,10 @@ scroll:set_vertical_scroll(state)
scroll:set_view_size(size)
scroll:update([dt])
scroll:update_view_size()
+
+scroll.on_scroll
+scroll.on_scroll_to
+scroll.on_point_scroll
```
### [Slider](components/extended/slider_api.md)
@@ -440,6 +466,8 @@ slider:set(value, [is_silent])
slider:set_enabled(is_enabled)
slider:set_input_node([input_node])
slider:set_steps(steps)
+
+slider.on_change_value
```
### [Swipe](components/extended/swipe_api.md)
@@ -450,6 +478,8 @@ Inspect [API Here](components/extended/swipe_api.md)
local swipe = self.druid:new_swipe(node, [on_swipe_callback])
swipe:set_click_zone([zone])
+
+swipe.on_swipe
```
### [Text](components/base/text_api.md)
@@ -473,6 +503,10 @@ text:set_size(size)
text:set_text([new_text])
text:set_text_adjust([adjust_type], [minimal_scale])
text:set_to(set_to)
+
+text.on_set_text
+text.on_update_text_scale
+text.on_set_pivot
```
### [Timer](components/extended/timer_api.md)
@@ -486,6 +520,10 @@ timer:set_interval(from, to)
timer:set_state([is_on])
timer:set_to(set_to)
timer:update([dt])
+
+timer.on_tick
+timer.on_set_enabled
+timer.on_timer_end
```
## [Helper](druid_helper_api.md)
@@ -540,21 +578,7 @@ Inspect [API Here](widgets/fps_panel_api.md)
local fps_panel = require("druid.widget.fps_panel.fps_panel")
fps_panel:init()
-fps_panel:on_remove()
-fps_panel:update([dt])
fps_panel:push_fps_value()
-
-fps_panel.root
-fps_panel.delta_time
-fps_panel.collect_time
-fps_panel.collect_time_counter
-fps_panel.graph_samples
-fps_panel.fps_samples
-fps_panel.mini_graph
-fps_panel.text_min_fps
-fps_panel.text_fps
-fps_panel.timer_id
-fps_panel.previous_time
```
### [Memory Panel](widgets/memory_panel_api.md)
@@ -565,22 +589,9 @@ Inspect [API Here](widgets/memory_panel_api.md)
local memory_panel = require("druid.widget.memory_panel.memory_panel")
memory_panel:init()
-memory_panel:on_remove()
memory_panel:set_low_memory_limit([limit])
memory_panel:push_next_value()
memory_panel:update_text_memory()
-
-memory_panel.root
-memory_panel.delta_time
-memory_panel.samples_count
-memory_panel.memory_limit
-memory_panel.mini_graph
-memory_panel.max_value
-memory_panel.text_per_second
-memory_panel.text_memory
-memory_panel.memory
-memory_panel.memory_samples
-memory_panel.timer_id
```
### [Mini Graph](widgets/mini_graph_api.md)
@@ -590,8 +601,6 @@ Inspect [API Here](widgets/mini_graph_api.md)
```lua
local mini_graph = require("druid.widget.mini_graph.mini_graph")
-mini_graph:init()
-mini_graph:on_remove()
mini_graph:clear()
mini_graph:set_samples([samples])
mini_graph:get_samples()
@@ -602,24 +611,7 @@ mini_graph:set_max_value([max_value])
mini_graph:set_line_height([index])
mini_graph:get_lowest_value()
mini_graph:get_highest_value()
-mini_graph:on_drag_widget([dx], [dy])
mini_graph:toggle_hide()
-
-mini_graph.root
-mini_graph.text_header
-mini_graph.icon_drag
-mini_graph.content
-mini_graph.layout
-mini_graph.prefab_line
-mini_graph.color_zero
-mini_graph.color_one
-mini_graph.is_hidden
-mini_graph.max_value
-mini_graph.lines
-mini_graph.values
-mini_graph.container
-mini_graph.default_size
-mini_graph.samples
```
### [Properties Panel](widgets/properties_panel_api.md)
@@ -631,12 +623,8 @@ local properties_panel = require("druid.widget.properties_panel.properties_panel
properties_panel:properties_constructors()
properties_panel:init()
-properties_panel:on_remove()
-properties_panel:on_drag_widget([dx], [dy])
properties_panel:clear_created_properties()
properties_panel:clear()
-properties_panel:on_size_changed([new_size])
-properties_panel:update([dt])
properties_panel:add_checkbox([on_create])
properties_panel:add_slider([on_create])
properties_panel:add_button([on_create])
@@ -651,28 +639,4 @@ properties_panel:set_hidden([is_hidden])
properties_panel:is_hidden()
properties_panel:set_properties_per_page(properties_per_page)
properties_panel:set_page([page])
-
-properties_panel.root
-properties_panel.scroll
-properties_panel.layout
-properties_panel.container
-properties_panel.container_content
-properties_panel.container_scroll_view
-properties_panel.contaienr_scroll_content
-properties_panel.button_hidden
-properties_panel.text_header
-properties_panel.paginator
-properties_panel.properties
-properties_panel.content
-properties_panel.default_size
-properties_panel.current_page
-properties_panel.properties_per_page
-properties_panel.property_checkbox_prefab
-properties_panel.property_slider_prefab
-properties_panel.property_button_prefab
-properties_panel.property_input_prefab
-properties_panel.property_text_prefab
-properties_panel.property_left_right_selector_prefab
-properties_panel.property_vector3_prefab
-properties_panel.is_dirty
```
diff --git a/druid/druid.lua b/druid/druid.lua
index 028495b..9443885 100644
--- a/druid/druid.lua
+++ b/druid/druid.lua
@@ -32,7 +32,6 @@ end
---The default way to create component is `druid_instance:new(component_class, ...)`.
---@param name string Module name
---@param module table Lua table with component
----@deprecated
function M.register(name, module)
druid_instance["new_" .. name] = function(self, ...)
return druid_instance.new(self, module, ...)
@@ -85,11 +84,11 @@ function M.on_language_change()
end
+---@type table
local REGISTERED_GUI_WIDGETS = {}
---Set a widget to the current game object. The game object can acquire the widget by calling `bindings.get_widget`
---It wraps with events only top level functions cross-context, so you will have no access to nested widgets functions
----Only one widget can be set per game object.
---@param widget druid.widget
---@return druid.widget
local function wrap_widget(widget)
@@ -111,24 +110,27 @@ local function wrap_widget(widget)
end
----Get a binded widget to the current game object with "go_widget" gui component name.
---- msg.url(nil, nil, "go_widget") -- current game object
---- msg.url(nil, object_url, "go_widget") -- other game object
+---Create a widget from the binded Druid GUI instance.
+---The widget will be created and all widget functions can be called from Game Object contexts.
+---This allow use only `druid_widget.gui_script` for GUI files and call this widget functions from Game Object script file.
+---Widget class here is a your lua file for the GUI scene (a widgets in Druid)
+--- msg.url(nil, nil, "gui_widget") -- current game object
+--- msg.url(nil, object_url, "gui_widget") -- other game object
---@generic T: druid.widget
---@param widget_class T The class of the widget to return
---@param gui_url url GUI url
----@return T
+---@return T? widget The new created widget,
function M.get_widget(widget_class, gui_url)
gui_url = gui_url or msg.url()
- local guis = REGISTERED_GUI_WIDGETS[gui_url.socket]
- if not guis then
+ local registered_druids = REGISTERED_GUI_WIDGETS[gui_url.socket]
+ if not registered_druids then
return nil
end
- for index = 1, #guis do
- local gui = guis[index]
- if gui.fragment == gui_url.fragment and gui.path == gui_url.path then
- return gui.new_widget:trigger(widget_class)
+ for index = 1, #registered_druids do
+ local druid = registered_druids[index]
+ if druid.fragment == gui_url.fragment and druid.path == gui_url.path then
+ return druid.new_widget:trigger(widget_class)
end
end
@@ -136,7 +138,9 @@ function M.get_widget(widget_class, gui_url)
end
----Register a widget to the current game object.
+---Bind a Druid GUI instance to the current game object.
+---This instance now can produce widgets from `druid.get_widget()` function.
+---Only one widget can be set per game object.
---@param druid druid.instance The druid instance to register
function M.register_druid_as_widget(druid)
local gui_url = msg.url()
@@ -151,7 +155,7 @@ function M.register_druid_as_widget(druid)
end
----Unregister a druid instance from the current game object.
+---Should be called on final, where druid instance is destroyed.
function M.unregister_druid_as_widget()
local gui_url = msg.url()
local socket = gui_url.socket
diff --git a/druid/extended/container.lua b/druid/extended/container.lua
index a1dbd14..2833059 100644
--- a/druid/extended/container.lua
+++ b/druid/extended/container.lua
@@ -368,6 +368,7 @@ end
-- Glossary
-- Center Offset - vector from node position to visual center of node
+
function M:refresh()
local x_koef, y_koef = self.x_koef, self.y_koef
self:refresh_scale()
diff --git a/druid/helper.lua b/druid/helper.lua
index c4f49ee..3ae5945 100644
--- a/druid/helper.lua
+++ b/druid/helper.lua
@@ -566,6 +566,9 @@ end
---@field node node Node with flipbook animation
---@field v vector4 Vector with UV coordinates and size
+
+---Source: https://github.com/Dragosha/defold-sprite-repeat/blob/main/node_repeat/node_repeat.lua
+---Thanks to Dragosha! ( ・ω・ ) < Hey friend!
---@param node node
---@param atlas_path string Path to the atlas
---@return druid.system.animation_data
diff --git a/game.project b/game.project
index 66da382..d4bc5ff 100644
--- a/game.project
+++ b/game.project
@@ -58,7 +58,7 @@ cssfile = /builtins/manifests/web/dark_theme.css
show_console_banner = 0
[native_extension]
-app_manifest =
+app_manifest =
[graphics]
texture_profiles = /builtins/graphics/default.texture_profiles
@@ -109,3 +109,4 @@ default = es
[event]
use_xpcall = 1
+
diff --git a/wiki/advanced-setup.md b/wiki/advanced-setup.md
index 3744225..abc6914 100644
--- a/wiki/advanced-setup.md
+++ b/wiki/advanced-setup.md
@@ -60,38 +60,77 @@ no_auto_input = 1
```
-## Code Bindings
+## Set Sound Function
+
+You can set the sound function to play sounds in the Druid components. Mostly used as a click sound for the buttons.
-Adjust **Druid** settings as needed:
```lua
local druid = require("druid.druid")
--- Used for button component and custom components
-- The callback should play the sound by name: function(sound_id) ... end
druid.set_sound_function(function(sound_id)
- -- sound_system.play(sound_id)
+ sound.play("/sounds#" .. sound_id)
end)
+```
+
+
+## Set Text Function
+
+You can set the text function to get the localized string by locale ID.
+
+```lua
+local druid = require("druid.druid")
--- Used for lang_text component
-- The callback should return the localized string by locale ID: function(locale_id) ... end
druid.set_text_function(function(locale_id)
- -- return lang.get(locale_id)
+ -- return lang.get(locale_id)
end)
+```
--- Used to change the default Druid style
-druid.set_default_style(your_style)
--- Call this function when the language changes in the game,
--- to retranslate all lang_text components:
-local function on_language_change()
+## Set Default Style
+
+You can set the default style for the Druid components.
+
+```lua
+-- Copy the default style from the Druid folder and modify it as needed
+local my_custom_style = require("my.custom.style")
+local druid = require("druid.druid")
+
+druid.set_default_style(my_custom_style)
+```
+
+
+## On Language Change
+
+You can set the function to be called when the language changes.
+
+```lua
+local lang = require("lang.lang")
+local druid = require("druid.druid")
+
+function M.next_language()
+ lang.set_next_lang()
+ -- When game language changes, call this function to retranslate all Druid components
druid.on_language_change()
end
-
--- Call this function inside window.set_listener
--- to capture game focus lost/gained callbacks:
--- window.set_listener(function(self, event, data) druid.on_window_callback(event, data) end))
-local function on_window_callback(self, event, data)
- druid.on_window_callback(event)
-end
-window.set_listener(on_window_callback)
+```
+
+
+## On Window Callback
+
+You can set the function to be called when the window event occurs.
+
+```lua
+local druid = require("druid.druid")
+
+-- Initialize the window listener, will override the previous window listener
+druid.init_window_listener()
+
+-- Or call this function inside window.set_listener
+
+-- The callback should be called when the window event occurs: function(event) ... end
+window.set_listener(function(self, event)
+ druid.on_window_callback(event)
+end)
```
diff --git a/wiki/basic_usage.md b/wiki/basic_usage.md
index 187dd52..5e6b325 100644
--- a/wiki/basic_usage.md
+++ b/wiki/basic_usage.md
@@ -51,7 +51,7 @@ end
function init(self)
self.druid = druid.new(self)
- -- We can use the node_id instead of gui.get_node():
+ -- We can use the node_id instead of gui.get_node():
self.button = self.druid:new_button("button_node_id", on_button_callback)
self.text = self.druid:new_text("text_node_id", "Hello, Druid!")
end
@@ -79,39 +79,57 @@ Widgets are reusable UI components that encapsulate multiple **Druid** component
### Creating a Widget
-Create a new Lua file for your widget class. This file should be placed near the corresponding GUI file with the same name.
+Create a new Lua file for your widget class. This file better to be placed near the corresponding GUI file with the same name.
Define `init` function to initialize the widget.
Here's a basic widget example:
```lua
----@class your_widget_class: druid.widget
+---@class best_widget_in_the_world: druid.widget
local M = {}
function M:init()
self.root = self:get_node("root")
+
+ -- Create a button and a text components inside your widget
self.button = self.druid:new_button("button_node_id", self.on_click)
self.text = self.druid:new_text("text_node_id", "Hello, Druid!")
+
+ -- They are now accessible by self.button and self.text outside
end
+---The "self" will be invoked correctly inside Druid's callbacks
function M:on_click()
self.text:set_text("The button clicked!")
end
+
+---Add your own functions to the widget
+function M:say_hello()
+ self.text:set_text("Hello, Druid!")
+end
+
+
return M
```
### Using Widgets
-You can create widgets in your GUI script like this:
+You can create widgets in your GUI script:
```lua
local druid = require("druid.druid")
+local best_widget_in_the_world = require("widgets.best_widget_in_the_world")
function init(self)
self.druid = druid.new(self)
- self.my_widget = self.druid:new_widget(your_widget_class)
+
+ local my_widget_template_id_on_gui_scene = "best_widget_in_the_world"
+ self.my_widget = self.druid:new_widget(best_widget_in_the_world, my_widget_template_id_on_gui_scene)
+
+ -- Now you can use the widget functions
+ self.my_widget:say_hello()
end
function final(self)
@@ -137,12 +155,12 @@ Widgets can use templates defined in your GUI scene. Templates are collections o
### Using Templates
-If you have a GUI template with ID `my_widget_example` containing `button_node_id` and `text_node_id` nodes, you can use it like this:
+If you have a GUI template with ID `best_widget_in_the_world` containing `button_node_id` and `text_node_id` nodes, you can use it like this:
```lua
function init(self)
self.druid = druid.new(self)
- self.my_widget = self.druid:new_widget(your_widget_class, "my_widget_example")
+ self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world")
self.my_widget.button.on_click:subscribe(function()
print("my custom callback")
@@ -158,18 +176,18 @@ For dynamically created GUI templates (from prefabs), you can pass nodes directl
```lua
function init(self)
self.druid = druid.new(self)
- self.prefab = gui.get_node("my_widget_prefab/root")
+ self.prefab = gui.get_node("best_widget_in_the_world/root")
local nodes = gui.clone_tree(self.prefab)
- self.my_widget = self.druid:new_widget(your_widget_class, "my_widget_example", nodes)
+ self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", nodes)
end
```
-You can also use the root node ID or node directly:
+You can also use the root node ID or node directly, it will be cloned and used as a template:
```lua
-self.my_widget = self.druid:new_widget(your_widget_class, "my_widget_example", "my_widget_prefab/root")
+self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", "best_widget_in_the_world/root")
-- or
-self.my_widget = self.druid:new_widget(your_widget_class, "my_widget_example", self.prefab)
+self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", self.prefab)
```
diff --git a/wiki/changelog.md b/wiki/changelog.md
index 8288b6f..2c53369 100644
--- a/wiki/changelog.md
+++ b/wiki/changelog.md
@@ -587,39 +587,33 @@ Hello! Druid 1.1 is here! It's brings a lot of new features and improvements. Le
**Changelog 1.1**
- Remove external annotations, remove old HTML API page
- Fully annotated code and new API README page
-- Widgets here!
- - A replacement for `custom_components`. Basically it's the same, but `widgets` contains no boilerplate code and more convinient to use.
- - Now I can include a kind of `widgets` with Druid and you can use it almost instantly in your project.
-- Deprecated `druid.register()`. Now all Druid's components are available by default and available with `self.druid:new_*` functions
+- [Yeay!] No need for the `druid.register()`! Now all Druid's components are available by default and available with `self.druid:new_*` functions
- This means the Druid will be bigger in size, but it's much comfortable to use
- In case you want to delete components you are not using, you can do it in fork in `druid.lua` file
- Read [optimize_druid_size.md](optimize_druid_size.md) to learn how to reduce the size of the Druid library if you need
- - Any additional widgets, color library will be not included until you use it
-- Remove `druid.event`, replaced with `defold-event` library. Now it required to two dependencies to use Druid.
- - This allow to make more flexible features, like shaders and sync init between script and gui_script in various cases.
+ - Any additional new widgets, utilities files will be not included until you use it
+- [BREAKING] Remove `druid.event`, replaced with `defold-event` library. Now it required to two dependencies to use Druid.
+ - This allow to make more flexible features, like shaders and sync init functions between script and gui_script in various cases.
+ - You need to migrate from `require("druid.event")` to `require("event.event")` if you are using it in your project
+ - If you are used `event.is_exist()` now, you should use `#event > 0` or `not event:is_empty()` instead
- Use 11+ version of `defold-event` library: `https://github.com/Insality/defold-event/archive/refs/tags/11.zip`
-- Add Druid UI Kit, contains atlas so now you can use Druid GUI files in your projects.
+ - Read [defold-event](https://github.com/Insality/defold-event) to learn more about the library
+- [UI Kit] Add Druid UI Kit, contains `druid.atlas`, `druid_text_bold.font`, `druid_text_regular.font` so now you can use Druid GUI files in your projects.
- Contains mostly basic shapes for the UI and can contains several icons. Atlas is a small, only `128x128` size and will be included in build only if you use it.
- A long waited feature which allows try or just use some Druid GUI features almost instantly.
+ - Now GUI files from Druid can be added inside your project.
+ - This allow to include `Default Widgets` - ready to use GUI templates
+- [Widgets] Widgets here!
+ - A replacement for Druid's `custom_components`. Basically it's the same, but `widgets` contains no boilerplate code and more convinient to use.
+ - Now I can include a kind of `widgets` with Druid and you can use it almost instantly in your project.
+ - All Druid Examples was migrated to use Widgets instead of Custom Components.
- [System]: Huge code refactoring and improvements. The goal is to raise maintainability and readability of the code to help people to contribute to the Druid.
- Add [CONTRIBUTING.md](/CONTRIBUTING.md) file with various information to help people to contribute to the Druid.
- - All Druid Examples was migrated to use Widgets instead of Custom Components.
- [Text]: Add `trim_left` and `scale_then_trim_left` text adjust modes
- [Text]: Add `set_text` function instead `set_to` (the `set_to` now deprecated)
-- Add `druid.color` module to work with colors and palettes
-- Add `container` component to handle more complex adaptive layouts
- - The container component is still in a development and I expected the various changes in the future
-- [Shaders] Add repeat, hard image stencil and world gui materials
+- [Color] Add `druid.color` module to work with colors and palettes
- [Widget] Add widget `mini_graph`
- [Widget] Add widget `memory_panel`
- [Widget] Add widget `fps_panel`
- [Widget] Add widget `properties_panel`
- - A widget where you can add different properties to the panel to make easy edit/debug panels
- - Include `property_button` widget
- - Include `property_checkbox` widget
- - Include `property_input` widget
- - Include `property_left_right_selector` widget
- - Include `property_slider` widget
- - Include `property_text` widget
- - Include `property_vector3` widget
- Removed old `druid.no_stencil_check` and `druid.no_auto_template` flags. Now it's always disabled
diff --git a/wiki/02-creating_custom_components.md b/wiki/creating_custom_components.md
similarity index 100%
rename from wiki/02-creating_custom_components.md
rename to wiki/creating_custom_components.md
diff --git a/wiki/03-styles.md b/wiki/styles.md
similarity index 84%
rename from wiki/03-styles.md
rename to wiki/styles.md
index 23ab005..15ca3f9 100644
--- a/wiki/03-styles.md
+++ b/wiki/styles.md
@@ -48,6 +48,23 @@ function init(self)
end
```
+## Adjust styles in place
+
+You can adjust styles params right after the component creation.
+
+```lua
+local druid = require("druid.druid")
+
+function init(self)
+ self.druid = druid.new(self)
+ self.grid = self.druid:new_grid("node", "prefab", 1)
+ self.grid.style.IS_ALIGN_LAST_ROW = true
+
+ self.drag = self.druid:new_drag("node")
+ self.drag.style.DRAG_DEADZONE = 0
+end
+```
+
## Create your own styles
diff --git a/wiki/widgets.md b/wiki/widgets.md
index a51c387..8347560 100644
--- a/wiki/widgets.md
+++ b/wiki/widgets.md
@@ -132,3 +132,39 @@ function init(self)
end
end
```
+
+
+## Using Widgets without GUI templates
+
+It's a possible to use widgets without GUI templates. This widget can pick nodes from the parent instance.
+
+```lua
+-- my_widget.lua
+local event = require("event.event")
+
+local M = {}
+
+function M:init()
+ self.on_close = event.create()
+ self.druid:new_hotkey("key_backspace", self.on_close)
+end
+
+return M
+```
+
+```lua
+-- gui_script
+local druid = require("druid.druid")
+local my_widget = require("widgets.my_widget.my_widget")
+
+local function on_close()
+ print("Widget closed")
+end
+
+function init(self)
+ self.druid = druid.new(self)
+ self.my_widget = self.druid:new_widget(my_widget)
+ self.my_widget.on_close:subscribe(on_close, self)
+end
+```
+