Update docs

druid/annotations.lua

@@ -42,8 +42,8 @@ function druid.set_text_function(callback) end
 
 
 ---@class druid.back_handler : druid.base_component
----@field on_back druid.event @{DruidEvent} function(self, [params]) .
+---@field on_back druid.event @{DruidEvent} Event on back handler action.
----@field params any Params to pass in the callback
+---@field params any Custom args to pass in the callback
 local druid__back_handler = {}
 
 
@@ -147,15 +147,21 @@ function druid__base_component.component:set_template(self, template) end
 
 
 ---@class druid.blocker : druid.base_component
----@field node node Trigger node
+---@field node node Blocker node
 local druid__blocker = {}
 
+--- @{Blocker} constructor
+---@param self druid.blocker @{Blocker}
+---@param node node Gui node
+function druid__blocker.init(self, node) end
+
 --- Return blocker enabled state
 ---@param self druid.blocker @{Blocker}
 ---@return bool True, if blocker is enabled
 function druid__blocker.is_enabled(self) end
 
---- Set enabled blocker component state
+--- Set enabled blocker component state.
+--- Don't change node enabled state.
 ---@param self druid.blocker @{Blocker}
 ---@param state bool Enabled state
 function druid__blocker.set_enabled(self, state) end
@@ -164,9 +170,9 @@ function druid__blocker.set_enabled(self, state) end
 ---@class druid.button : druid.base_component
 ---@field anim_node node Button animation node.
 ---@field click_zone node Additional button click area, defined by another GUI Node
----@field hash node_id The GUI node id from button node
 ---@field hover druid.hover @{Hover}: Button Hover component
----@field node node Button clickable node
+---@field node Node Button trigger node
+---@field node_id hash The GUI node id from button node
 ---@field on_click druid.event @{DruidEvent}: Event on successful release action over button.
 ---@field on_click_outside druid.event @{DruidEvent}: Event calls if click event was outside of button.
 ---@field on_double_click druid.event @{DruidEvent}: Event on double tap action over button.
@@ -183,15 +189,16 @@ local druid__button = {}
 ---@return hash The action_id of the input key
 function druid__button.get_key_trigger(self) end
 
---- Button component constructor
+--- @{Button} constructor
 ---@param self druid.button @{Button}
----@param node node Gui node
+---@param node string|Node Node name or GUI Node itself
----@param callback function Button callback
+---@param callback function On click button callback
----@param params table Button callback params
+---@param custom_args any Button events custom arguments
----@param anim_node node Button anim node (node, if not provided)
+---@param anim_node string|Node Node to animate instead of trigger node.
-function druid__button.init(self, node, callback, params, anim_node) end
+function druid__button.init(self, node, callback, custom_args, anim_node) end
 
 --- Get button enabled state.
+--- By default all Buttons is enabled on creating.
 ---@param self druid.button @{Button}
 ---@return bool True, if button is enabled now, False overwise
 function druid__button.is_enabled(self) end
@@ -199,7 +206,7 @@ function druid__button.is_enabled(self) end
 --- Set function for additional check for button click availability
 ---@param self druid.button
 ---@param check_function function Should return true or false. If true - button can be pressed.
----@param failure_callback function Function what will be called on button click, if check function return false
+---@param failure_callback function Function will be called on button click, if check function return false
 ---@return druid.button Current button instance
 function druid__button.set_check_function(self, check_function, failure_callback) end
 
@@ -217,19 +224,19 @@ function druid__button.set_click_zone(self, zone) end
 ---@return druid.button Current button instance
 function druid__button.set_enabled(self, state) end
 
---- Set buttom click mode to call itself inside html5 callback in user interaction event  It required to do protected stuff like copy/paste text, show html keyboard, etc  The HTML5 button doesn't call any events except on_click event
----@protected
----@param self druid.button
----@param is_html_mode boolean If true - button will be called inside html5 callback
----@return druid.button Current button instance
-function druid__button.set_html5_user_interaction(self, is_html_mode) end
-
 --- Set key name to trigger this button by keyboard.
 ---@param self druid.button @{Button}
 ---@param key hash The action_id of the input key
 ---@return druid.button Current button instance
 function druid__button.set_key_trigger(self, key) end
 
+--- Set Button mode to work inside user HTML5 interaction event.
+--- It's required to make protected things like copy & paste text, show mobile keyboard, etc  The HTML5 button's doesn't call any events except on_click event.  If the game is not HTML, HTML html mode will be not enabled
+---@param self druid.button
+---@param is_web_mode boolean If true - button will be called inside html5 callback
+---@return druid.button Current button instance
+function druid__button.set_web_user_interaction(self, is_web_mode) end
+
 
 ---@class druid.button.style
 ---@field AUTOHOLD_TRIGGER field  Maximum hold time to trigger button release while holding
@@ -713,12 +720,12 @@ local druid__lang_text = {}
 ---@return druid.lang_text Current instance
 function druid__lang_text.format(self, a, b, c, d, e, f, g) end
 
---- Component init function
+--- @{LangText} constructor
 ---@param self druid.lang_text @{LangText}
----@param node node The text node
+---@param node string|node Node name or GUI Text Node itself
 ---@param locale_id string Default locale id or text from node as default
----@param no_adjust bool If true, will not correct text size
+---@param adjust_type string Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
-function druid__lang_text.init(self, node, locale_id, no_adjust) end
+function druid__lang_text.init(self, node, locale_id, adjust_type) end
 
 --- Setup raw text to lang_text component
 ---@param self druid.lang_text @{LangText}
@@ -834,7 +841,7 @@ function druid__pin_knob.set_friction(self, value) end
 
 
 ---@class druid.progress : druid.base_component
----@field key string The progress bar direction
+---@field key string The progress bar direction.
 ---@field max_size number Maximum size of progress bar
 ---@field node node Progress bar fill node
 ---@field on_change druid.event On progress bar change callback(self, new_value)
@@ -856,9 +863,9 @@ function druid__progress.fill(self) end
 ---@param self druid.progress @{Progress}
 function druid__progress.get(self) end
 
---- Component init function
+--- @{Progress} constructor
 ---@param self druid.progress @{Progress}
----@param node string|node Progress bar fill node or node name
+---@param node string|node Node name or GUI Node itself.
 ---@param key string Progress bar direction: const.SIDE.X or const.SIDE.Y
 ---@param init_value number Initial value of progress bar
 function druid__progress.init(self, node, key, init_value) end
@@ -1210,9 +1217,9 @@ function druid__static_grid.get_pos(self, index) end
 ---@return vector3 The grid content size
 function druid__static_grid.get_size(self) end
 
---- Component init function
+--- @{StaticGrid} constructor
 ---@param self druid.static_grid @{StaticGrid}
----@param parent node The gui node parent, where items will be placed
+---@param parent string|Node The GUI Node container, where grid's items will be placed
 ---@param element node Element prefab. Need to get it size
 ---@param in_row number How many nodes in row can be placed
 function druid__static_grid.init(self, parent, element, in_row) end
@@ -1308,11 +1315,11 @@ function druid__text.get_text_adjust(self, adjust_type) end
 ---@return number Height
 function druid__text.get_text_size(self, text) end
 
---- Component init function
+--- @{Text} constructor
 ---@param self druid.text @{Text}
----@param node node Gui text node
+---@param node string|node Node name or GUI Text Node itself
 ---@param value string Initial text. Default value is node text from GUI scene.
----@param adjust_type int Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
+---@param adjust_type string Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
 function druid__text.init(self, node, value, adjust_type) end
 
 --- Return true, if text with line break

druid/base/back_handler.lua

@@ -6,13 +6,11 @@
 -- Back Handler is recommended to put in every game window to close it
 -- or in main screen to call settings window.
 --
--- # Tech Info #
---
--- Back Handler react on release action ACTION_BACK or ACTION_BACKSPACE
---
 -- # Notes #
 --
 -- • Back Handler inheritance @{BaseComponent}, you can use all of its methods in addition to those described here.
+--
+-- • Back Handler react on release action ACTION_BACK or ACTION_BACKSPACE
 -- @usage
 -- local callback = function(self, params) ... end
 --
@@ -22,7 +20,7 @@
 -- @within BaseComponent
 -- @alias druid.back_handler
 
---- @{DruidEvent} function(self, [params]) .
+--- @{DruidEvent} Event on back handler action.
 --
 -- Trigger on input action ACTION_BACK or ACTION_BACKSPACE
 -- @usage
@@ -30,7 +28,7 @@
 -- back_handler.on_back:subscribe(callback)
 -- @tfield DruidEvent on_back @{DruidEvent}
 
---- Params to pass in the callback
+--- Custom args to pass in the callback
 -- @usage
 -- -- Replace params on runtime:
 -- back_handler.params = { ... }
@@ -45,13 +43,13 @@ local component = require("druid.component")
 local BackHandler = component.create("back_handler")
 
 
---- Component initialize function
+--- @{BackHandler} constructor
 -- @tparam BackHandler self @{BackHandler}
 -- @tparam callback callback On back button
--- @tparam[opt] any params Callback argument
+-- @tparam[opt] any custom_args Button events custom arguments
 -- @local
-function BackHandler.init(self, callback, params)
+function BackHandler.init(self, callback, custom_args)
-	self.params = params
+	self.params = custom_args
 	self.on_back = Event(callback)
 end
 

druid/base/blocker.lua

@@ -1,19 +1,15 @@
 -- Copyright (c) 2023 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to block input in special zone defined by GUI node.
+--- Component to consume input in special zone defined by GUI node.
 -- # Overview #
 --
--- Blocker component необходим, чтобы блокировать пользовательский ввод в определенной зоне.
--- Зона задается размером ноды, на которой находится компонент. Blocker блокирует ввод только для тех
--- элементов, которые находятся перед ним in input stack (созданы до него).
---
--- # Tech Info #
---
--- Blocker consume input if `gui.pick_node` works on it.
---
 -- # Notes #
 --
+-- Blocker consume input if `gui.pick_node` works on it.
+--
 -- • Blocker inheritance @{BaseComponent}, you can use all of its methods in addition to those described here.
+--
+-- • Blocker initial enabled state is `gui.is_enabled(node, true)`
 -- @usage
 -- local node = gui.get_node("blocker_node")
 -- local blocker = self.druid:new_blocker(node)
@@ -21,7 +17,7 @@
 -- @within BaseComponent
 -- @alias druid.blocker
 
----Trigger node
+---Blocker node
 -- @tfield node node
 
 ---
@@ -32,12 +28,12 @@ local component = require("druid.component")
 local Blocker = component.create("blocker")
 
 
---- Component initialize function
+--- @{Blocker} constructor
 -- @tparam Blocker self @{Blocker}
 -- @tparam node node Gui node
--- @local
 function Blocker.init(self, node)
 	self.node = self:get_node(node)
+	self._is_enabled = gui.is_enabled(node, true)
 end
 
 
@@ -65,11 +61,13 @@ function Blocker.on_input(self, action_id, action)
 end
 
 
---- Set enabled blocker component state
+--- Set enabled blocker component state.
+--
+-- Don't change node enabled state.
 -- @tparam Blocker self @{Blocker}
 -- @tparam bool state Enabled state
 function Blocker.set_enabled(self, state)
-	gui.set_enabled(self.node, state)
+	self._is_enabled = state
 end
 
 
@@ -77,7 +75,7 @@ end
 -- @tparam Blocker self @{Blocker}
 -- @treturn bool True, if blocker is enabled
 function Blocker.is_enabled(self)
-	return gui.is_enabled(self.node)
+	return self._is_enabled
 end
 
 

druid/base/button.lua

@@ -3,7 +3,7 @@
 --- Druid Component to handle the user click interactions: click, long click, double click, etc.
 -- # Overview #
 --
--- The most generic and useful component you can use. Set any GUI node clickable and providing different callbacks.
+-- The most generic component you can use. Set any GUI node clickable and provide different callbacks.
 --
 -- # Notes #
 --
@@ -107,11 +107,11 @@
 -- end)
 -- @tfield DruidEvent on_pressed @{DruidEvent}
 
---- Button clickable node
+--- Button trigger node
--- @tfield node node
+-- @tfield Node node
 
 ---The GUI node id from button node
--- @tfield node_id hash
+-- @tfield hash node_id
 
 --- Button animation node.
 -- In default case equals to clickable node.
@@ -274,8 +274,8 @@ end
 -- @tparam Button self @{Button}
 -- @tparam string|Node node Node name or GUI Node itself
 -- @tparam function callback On click button callback
--- @tparam[opt] table custom_args Button events custom arguments
+-- @tparam[opt] any custom_args Button events custom arguments
--- @tparam[opt] string|Node anim_node Node to animate instead of trigger node
+-- @tparam[opt] string|Node anim_node Node to animate instead of trigger node.
 function Button.init(self, node, callback, custom_args, anim_node)
 	self.druid = self:get_druid()
 	self.node = self:get_node(node)

druid/base/scroll.lua

@@ -1,12 +1,30 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
 --- Component to handle scroll content.
+-- # Overview #
+--
 -- Scroll consist from two nodes: scroll parent and scroll input
 -- Scroll input the user input zone, it's static
 -- Scroll parent the scroll moving part, it will change position.
 -- Setup initial scroll size by changing scroll parent size. If scroll parent
--- size will be less than scroll_input size, no scroll is available. For scroll
+-- size will be less than scroll_input size, no scroll is available.
--- parent size should be more than input size
+--
+-- # Notes #
+--
+-- • Scroll by default style have inertion and extra size for strecthing effect.
+-- It can be adjust via scroll <a href="https://insality.github.io/druid/modules/Scroll.html#Style">style settings</a>
+--
+-- • You can setup "points of interest". Scroll always will be centered on closes point of interest.
+-- It is able to create slider without inertion and points of interest on each scroll element.
+--
+-- • You can adjust scroll content size by `scroll:set_size(node_size)`.
+-- It will setup new size to _content node_
+--
+-- • You can enabled or disable inertion mode via `scroll:set_inert(state)`
+--
+-- • You can adjust extra stretch size via `scroll:set_extra_stretch_size`
+--
+-- • Multitouch is required for scroll. Scroll is correctly handling touch_id swap while dragging scroll
 -- @module Scroll
 -- @within BaseComponent
 -- @alias druid.scroll
@@ -132,10 +150,10 @@ function Scroll.on_style_change(self, style)
 end
 
 
---- Scroll constructor
+--- @{Scroll} constructor
 -- @tparam Scroll self @{Scroll}
--- @tparam node view_node GUI view scroll node
+-- @tparam string|node view_node GUI view scroll node
--- @tparam node content_node GUI content scroll node
+-- @tparam string|node content_node GUI content scroll node
 function Scroll.init(self, view_node, content_node)
 	self.druid = self:get_druid()
 

druid/base/static_grid.lua

@@ -1,7 +1,27 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to handle placing components by row and columns.
+--- Component to handle component's position by row and columns.
--- Grid can anchor your elements, get content size and other
+-- # Overview #
+--
+-- # Notes #
+--
+-- • Static grid have constant node size, so it possible to calculate node positions before placement. Nodes can be placed with gaps.
+--
+-- • Static grid can shift elements on add/remove functions.
+--
+-- • On _add node_ grid will set node parent to _parent_node_
+--
+-- • You can get array of position of every element for setup points of interest in scroll component
+--
+-- • You can get size of all elements for setup size in scroll component
+--
+-- • You can bind the grid to the scroll component for auto resize scroll content size
+--
+-- • Pivot of parent_node matter for node placement
+--
+-- • Prefab node used to get node size and anchor
+--
+-- • You can point *position_function* for animations with _static_grid:set_position_function(node, pos)_ callback. Default - *gui.set_position()*
 -- @module StaticGrid
 -- @within BaseComponent
 -- @alias druid.static_grid
@@ -81,9 +101,9 @@ function StaticGrid.on_style_change(self, style)
 end
 
 
---- Component init function
+--- @{StaticGrid} constructor
 -- @tparam StaticGrid self @{StaticGrid}
--- @tparam node parent The gui node parent, where items will be placed
+-- @tparam string|Node parent The GUI Node container, where grid's items will be placed
 -- @tparam node element Element prefab. Need to get it size
 -- @tparam[opt=1] number in_row How many nodes in row can be placed
 function StaticGrid.init(self, parent, element, in_row)

druid/base/text.lua

@@ -1,8 +1,29 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to handle all GUI texts.
+--- Component to wrap over GUI Text nodes.
--- Druid Text adjust itself for text node size
+-- # Overview #
--- Text will never will be outside of his text size (even multiline)
+--
+-- Druid Text provide different adjust modes. Text will be scaled down to fit into Text Node area size.
+--
+-- # Notes #
+--
+-- • Text pivot can be changed with `text:set_pivot`. The anchoring will be inside text node area size.
+--
+-- • There is several text adjust types. Default DOWNSCALE. You can change the default adjust type in the Text style. See all adjust types in example here.
+--
+-- - const.TEXT_ADJUST.DOWNSCALE  - Change text's scale to fit into the text node size
+--
+-- - const.TEXT_ADJUST.TRIM - Trim the text with postfix (default - "...", override in styles) to fit in the text node size
+--
+-- - const.TEXT_ADJUST.NO_ADJUST - No any adjust, like default Defold Text Node
+--
+-- - const.TEXT_ADJUST.DOWNSCALE_LIMITED - Change text's scale list downscale, but there is limit for text's scale.
+-- Set minimal scale with `text:set_minimal_scale()` function.
+--
+-- - const.TEXT_ADJUST.SCROLL - Change text's pivot to imitate scrolling in the text box. Use with stencil node for better effect.
+--
+-- - const.TEXT_ADJUST.SCALE_THEN_SCROLL - Combine two modes: first limited downscale, then scroll
+--
 -- @module Text
 -- @within BaseComponent
 -- @alias druid.text
@@ -188,11 +209,11 @@ function Text.on_style_change(self, style)
 end
 
 
---- Component init function
+--- @{Text} constructor
 -- @tparam Text self @{Text}
--- @tparam node node Gui text node
+-- @tparam string|node node Node name or GUI Text Node itself
 -- @tparam[opt] string value Initial text. Default value is node text from GUI scene.
--- @tparam[opt=0] int adjust_type Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
+-- @tparam[opt=downscale] string adjust_type Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
 function Text.init(self, node, value, adjust_type)
 	self.node = self:get_node(node)
 	self.pos = gui.get_position(self.node)

druid/const.lua

@@ -52,7 +52,6 @@ M.MESSAGE_INPUT = {
 	BUTTON_LONG_CLICK = "button_long_click",
 	BUTTON_DOUBLE_CLICK = "button_double_click",
 	BUTTON_REPEATED_CLICK = "button_repeated_click",
-	-- (value)
 	TEXT_SET = "text_set",
 }
 

druid/extended/lang_text.lua

@@ -1,7 +1,15 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to handle all GUI texts
+--- Component to wrap over GUI Text nodes with localization helpers
--- Good working with localization system
+--
+-- # Overview #
+--
+-- • The `druid.set_text_function` should be inited to get the localization by localization_id
+--
+-- • The LangText supports up to 7 string format params, due the some issues with `...` args.
+--
+-- # Notes #
+--
 -- @module LangText
 -- @within BaseComponent
 -- @alias druid.lang_text
@@ -21,14 +29,14 @@ local component = require("druid.component")
 local LangText = component.create("lang_text")
 
 
---- Component init function
+--- @{LangText} constructor
 -- @tparam LangText self @{LangText}
--- @tparam node node The text node
+-- @tparam string|node node Node name or GUI Text Node itself
 -- @tparam string locale_id Default locale id or text from node as default
--- @tparam bool no_adjust If true, will not correct text size
+-- @tparam[opt=downscale] string adjust_type Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
-function LangText.init(self, node, locale_id, no_adjust)
+function LangText.init(self, node, locale_id, adjust_type)
 	self.druid = self:get_druid()
-	self.text = self.druid:new_text(node, locale_id, no_adjust)
+	self.text = self.druid:new_text(node, locale_id, adjust_type)
 	self.node = self.text.node
 	self.last_locale_args = {}
 

druid/extended/progress.lua

@@ -1,7 +1,18 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Basic progress bar component.
+--- Druid component to handle the progress bars.
--- For correct progress bar init it should be in max size from gui
+-- # Overview #
+--
+-- # Notes #
+--
+-- • Progress Node should be fully filled in your GUI scene node. It will be the progress maximum size
+--
+-- • Progress correct working with Slice9 nodes, it trying to set size by _set_size_ first, if it is not possible, it set up sizing via _set_scale_
+--
+-- • Progress bar can fill only by vertical or horizontal size. If you want make diagonal progress bar, just rotate node in GUI scene
+--
+-- • If you have glitchy or dark texture bug with progress bar, try to disable mipmaps in your texture profiles
+--
 -- @module Progress
 -- @within BaseComponent
 -- @alias druid.progress
@@ -12,7 +23,9 @@
 --- Progress bar fill node
 -- @tfield node node
 
---- The progress bar direction
+--- The progress bar direction.
+--
+-- The values are: "x" or "y". (const.SIDE.X or const.SIDE.Y)
 -- @tfield string key
 
 --- Current progress bar scale
@@ -95,16 +108,16 @@ function Progress.on_style_change(self, style)
 end
 
 
---- Component init function
+--- @{Progress} constructor
 -- @tparam Progress self @{Progress}
--- @tparam string|node node Progress bar fill node or node name
+-- @tparam string|node node Node name or GUI Node itself.
 -- @tparam string key Progress bar direction: const.SIDE.X or const.SIDE.Y
 -- @tparam[opt=1] number init_value Initial value of progress bar
 function Progress.init(self, node, key, init_value)
 	assert(key == const.SIDE.X or const.SIDE.Y, "Progress bar key should be 'x' or 'y'")
 
-	self.prop = hash("scale."..key)
 	self.key = key
+	self.prop = hash("scale." .. self.key)
 
 	self._init_value = init_value or 1
 	self.node = self:get_node(node)
@@ -114,7 +127,7 @@ function Progress.init(self, node, key, init_value)
 	self.slice = gui.get_slice9(self.node)
 	self.last_value = self._init_value
 
-	if key == const.SIDE.X then
+	if self.key == const.SIDE.X then
 		self.slice_size = self.slice.x + self.slice.z
 	else
 		self.slice_size = self.slice.y + self.slice.w