Update

druid/base/back_handler.lua

@@ -16,14 +16,11 @@ function M:init(callback, params)
 end
 
 
----@param action_id string
+---@param action_id hash
 ---@param action table
+---@return boolean
 function M:on_input(action_id, action)
-	if not action.released then
+	if action.released and (action_id == const.ACTION_BACK or action_id == const.ACTION_BACKSPACE) then
-		return false
-	end
-
-	if action_id == const.ACTION_BACK or action_id == const.ACTION_BACKSPACE then
 		self.on_back:trigger(self:get_context(), self.params)
 		return true
 	end

druid/base/button.lua

@@ -211,7 +211,7 @@ end
 
 ---Get button enabled state.
 ---By default all Buttons is enabled on creating.
----@return boolean @True, if button is enabled now, False overwise
+---@return boolean is_enabled True, if button is enabled now, False overwise
 function M:is_enabled()
 	return not self.disabled
 end

druid/base/drag.lua

@@ -1,62 +1,3 @@
--- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
-
---- Component to handle drag action on node.
--- Drag have correct handling for multitouch and swap
--- touched while dragging. Drag will be processed even
--- the cursor is outside of node, if drag is already started
---
--- <a href="https://insality.github.io/druid/druid/index.html?example=general_drag" target="_blank"><b>Example Link</b></a>
--- @module Drag
--- @within BaseComponent
--- @alias druid.drag
-
---- Drag node
--- @tfield node node
-
---- Event on touch start callback(self)
--- @tfield event on_touch_start event
-
---- Event on touch end callback(self)
--- @tfield event on_touch_end event
-
---- Event on drag start callback(self, touch)
--- @tfield event on_drag_start event
-
---- on drag progress callback(self, dx, dy, total_x, total_y, touch)
--- @tfield event on_drag Event event
-
---- Event on drag end callback(self, total_x, total_y, touch)
--- @tfield event on_drag_end event
-
---- Is component now touching
--- @tfield boolean is_touch
-
---- Is component now dragging
--- @tfield boolean is_drag
-
---- Is drag component process vertical dragging. Default - true
--- @tfield boolean can_x
-
---- Is drag component process horizontal. Default - true
--- @tfield boolean can_y
-
---- Current touch x position
--- @tfield number x
-
---- Current touch y position
--- @tfield number y
-
---- Current touch x screen position
--- @tfield number screen_x
-
---- Current touch y screen position
--- @tfield number screen_y
-
---- Touch start position
--- @tfield vector3 touch_start_pos
-
----
-
 local event = require("event.event")
 local const = require("druid.const")
 local helper = require("druid.helper")
@@ -151,7 +92,11 @@ end
 
 
 ---Return current touch action from action input data
--- If touch_id stored - return exact this touch action
+---If touch_id stored - return exact this touch action
+---@param action_id hash Action id from on_input
+---@param action table Action from on_input
+---@param touch_id number Touch id
+---@return table|nil Touch action
 local function find_touch(action_id, action, touch_id)
 	local act = helper.is_mobile() and const.ACTION_MULTITOUCH or const.ACTION_TOUCH
 
@@ -174,7 +119,10 @@ end
 
 
 ---Process on touch release. We should to find, if any other
--- touches exists to switch to another touch.
+---touches exists to switch to another touch.
+---@param self druid.drag
+---@param action_id hash Action id from on_input
+---@param action table Action from on_input
 local function on_touch_release(self, action_id, action)
 	if #action.touch >= 2 then
 		-- Find next unpressed touch
@@ -199,12 +147,7 @@ local function on_touch_release(self, action_id, action)
 end
 
 
---- Component style params.
+---@param style druid.drag.style
--- You can override this component styles params in druid styles table
--- or create your own style
--- @table style
--- @tfield number|nil DRAG_DEADZONE Distance in pixels to start dragging. Default: 10
--- @tfield boolean|nil NO_USE_SCREEN_KOEF If screen aspect ratio affects on drag values. Default: false
 function M:on_style_change(style)
 	self.style = {
 		DRAG_DEADZONE = style.DRAG_DEADZONE or 10,
@@ -289,7 +232,7 @@ end
 
 
 ---@local
----@param action_id string
+---@param action_id hash
 ---@param action table
 function M:on_input(action_id, action)
 	if action_id ~= const.ACTION_TOUCH and action_id ~= const.ACTION_MULTITOUCH then
@@ -388,7 +331,7 @@ function M:set_enabled(is_enabled)
 end
 
 
----Check if Drag component is enabled
+---Check if Drag component is capture input
 ---@return boolean
 function M:is_enabled()
 	return self._is_enabled

druid/base/hover.lua

@@ -1,31 +1,17 @@
--- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
-
---- Component to handle hover node interaction
--- @module Hover
--- @within BaseComponent
--- @alias druid.hover
-
---- Hover node
--- @tfield node node
-
---- On hover callback(self, state, hover_instance)
--- @tfield event on_hover event
-
---- On mouse hover callback(self, state, hover_instance)
--- @tfield event on_mouse_hover event
-
----
-
 local event = require("event.event")
 local const = require("druid.const")
 local helper = require("druid.helper")
 local component = require("druid.component")
 
+---@class druid.hover.style
+---@field ON_HOVER_CURSOR string|nil Mouse hover style on node hover
+---@field ON_MOUSE_HOVER_CURSOR string|nil Mouse hover style on node mouse hover
+
 ---@class druid.hover: druid.component
 ---@field node node
 ---@field on_hover event
 ---@field on_mouse_hover event
----@field style table
+---@field style druid.hover.style
 ---@field click_zone node
 ---@field private _is_hovered boolean|nil
 ---@field private _is_mouse_hovered boolean|nil
@@ -34,7 +20,6 @@ local component = require("druid.component")
 local M = component.create("hover")
 
 
---- The Hover constructor
 ---@param node node Gui node
 ---@param on_hover_callback function Hover callback
 ---@param on_mouse_hover function On mouse hover callback
@@ -61,12 +46,7 @@ function M:on_late_init()
 end
 
 
---- Component style params.
+---@param style druid.hover.style
--- You can override this component styles params in druid styles table
--- or create your own style
--- @table style
--- @tfield[opt] string ON_HOVER_CURSOR Mouse hover style on node hover
--- @tfield[opt] string ON_MOUSE_HOVER_CURSOR Mouse hover style on node mouse hover
 function M:on_style_change(style)
 	self.style = {}
 	self.style.ON_HOVER_CURSOR = style.ON_HOVER_CURSOR or nil
@@ -74,6 +54,9 @@ function M:on_style_change(style)
 end
 
 
+---@param action_id hash
+---@param action table
+---@return boolean
 function M:on_input(action_id, action)
 	if action_id ~= const.ACTION_TOUCH and action_id ~= nil then
 		return false
@@ -130,7 +113,7 @@ end
 
 
 ---Return current hover state. True if touch action was on the node at current time
----@return boolean The current hovered state
+---@return boolean is_hovered The current hovered state
 function M:is_hovered()
 	return self._is_hovered
 end
@@ -159,8 +142,7 @@ function M:is_mouse_hovered()
 end
 
 
---- Strict hover click area. Useful for
+---Strict hover click area. Useful for no click events outside stencil node
--- no click events outside stencil node
 ---@param zone node|string|nil Gui node
 function M:set_click_zone(zone)
 	if not zone then
@@ -173,8 +155,8 @@ end
 
 
 ---Set enable state of hover component.
--- If hover is not enabled, it will not generate
+---If hover is not enabled, it will not generate
--- any hover events
+---any hover events
 ---@param state boolean|nil The hover enabled state
 function M:set_enabled(state)
 	self._is_enabled = state

druid/base/static_grid.lua

@@ -1,87 +1,12 @@
--- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
-
---- Component to handle component's position by row and columns.
--- <b># Overview #</b>
---
--- The Static Grid component allows for positioning components in rows and columns.
--- It provides a static grid layout with constant node sizes, allowing for pre-calculated
--- node positions and the option to include gaps between nodes.
---
--- <b># Notes #</b>
---
--- • In a static grid, the node size remains constant, enabling the calculation of node
--- positions before placement. If you want add gaps between nodes, increase the root prefab size,
--- including the padding and margin.
---
--- • The static grid can automatically shift elements when nodes are added or removed.
---
--- • When a node is added, the grid will set the node's parent to the specified parent_node.
---
--- • You can obtain an array of positions for each element, which can be used to set
--- points of interest in a scroll component.
---
--- • The size of all elements can be retrieved for setting up the size in a scroll component.
---
--- • The grid can be bound to a scroll component for automatic resizing of the scroll content size.
---
--- • The pivot of the parent_node affects the node placement within the grid.
---
--- • A prefab node is used to determine the node size and anchor.
---
--- • You can specify a position_function for animations using the
--- _static_grid:set_position_function(node, pos) callback. The default position function is gui.set_position().
---
--- <a href="https://insality.github.io/druid/druid/index.html?example=general_grid" target="_blank"><b>Example Link</b></a>
--- @module StaticGrid
--- @within BaseComponent
--- @alias druid.grid
-
---- On item add callback(self, node, index)
--- @tfield event on_add_item event
-
---- On item remove callback(self, index)
--- @tfield event on_remove_item event
-
---- On item add, remove or change in_row callback(self, index|nil)
--- @tfield event on_change_items event
-
---- On grid clear callback(self)
--- @tfield event on_clear event
-
---- On update item positions callback(self)
--- @tfield event on_update_positions event
-
---- Parent gui node
--- @tfield node parent
-
---- List of all grid nodes
--- @tfield node[] nodes
-
---- The first index of node in grid
--- @tfield number first_index
-
---- The last index of node in grid
--- @tfield number last_index
-
---- Item anchor [0..1]
--- @tfield vector3 anchor
-
---- Item pivot [-0.5..0.5]
--- @tfield vector3 pivot
-
---- Item size
--- @tfield vector3 node_size
-
---- The size of item content
--- @tfield vector4 border
-
----
-
 local const = require("druid.const")
 local event = require("event.event")
 local helper = require("druid.helper")
 local component = require("druid.component")
 
+---@class druid.grid.style
+---@field IS_DYNAMIC_NODE_POSES boolean|nil If true, always center grid content as grid pivot sets. Default: false
+---@field IS_ALIGN_LAST_ROW boolean|nil If true, always align last row of the grid as grid pivot sets. Default: false
+
 ---@class druid.grid: druid.component
 ---@field on_add_item event
 ---@field on_remove_item event
@@ -98,7 +23,7 @@ local component = require("druid.component")
 ---@field border vector4
 ---@field in_row number
 ---@field style table
-local M = component.create("static_grid")
+local M = component.create("grid")
 
 
 local function _extend_border(border, pos, size, pivot)
@@ -114,20 +39,15 @@ local function _extend_border(border, pos, size, pivot)
 end
 
 
---- Component style params.
+---@param style druid.grid.style
--- You can override this component styles params in druid styles table
--- or create your own style
--- @table style
--- @tfield boolean|nil IS_DYNAMIC_NODE_POSES If true, always center grid content as grid pivot sets. Default: false
--- @tfield boolean|nil IS_ALIGN_LAST_ROW If true, always align last row of the grid as grid pivot sets. Default: false
 function M:on_style_change(style)
-	self.style = {}
+	self.style = {
-	self.style.IS_DYNAMIC_NODE_POSES = style.IS_DYNAMIC_NODE_POSES or false
+		IS_DYNAMIC_NODE_POSES = style.IS_DYNAMIC_NODE_POSES or false,
-	self.style.IS_ALIGN_LAST_ROW = style.IS_ALIGN_LAST_ROW or false
+		IS_ALIGN_LAST_ROW = style.IS_ALIGN_LAST_ROW or false,
+	}
 end
 
 
---- The StaticGrid constructor
 ---@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|nil How many nodes in row can be placed. By default 1
@@ -238,11 +158,6 @@ function M:set_pivot(pivot)
 
 	local width = gui.get(self.parent, "size.x")
 	local height = gui.get(self.parent, "size.y")
-	--local pos_offset = vmath.vector3(
-	--	width * (self.pivot.x - prev_pivot.x),
-	--	height * (self.pivot.y - prev_pivot.y),
-	--	0
-	--)
 
 	local position = gui.get_position(self.parent)
 	position.x = position.x + width * (self.pivot.x - prev_pivot.x)

druid/base/text.lua

@@ -1,81 +1,3 @@
--- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
-
---- Component for Wrapping GUI Text Nodes: Druid Text
---
--- ## Overview ##
---
--- Druid Text is a component that provides various adjustment modes for text nodes. It allows text to be scaled down to fit within the size of the text node.
---
--- ## Notes ##
---
--- • The text pivot can be changed using the text:set_pivot method.
--- The anchoring will be inside the text node's area size.
---
--- • There are several text adjustment types available. The default is DOWNSCALE.
--- You can change the default adjustment type in the Text style. Refer to the example below to see all available adjustment types:
---
--- - const.TEXT_ADJUST.DOWNSCALE: Changes the text's scale to fit within the text node's size.
---
--- - const.TEXT_ADJUST.TRIM: Trims the text with a postfix (default: "...", can be overridden in styles)
--- to fit within the text node's size.
---
--- - const.TEXT_ADJUST.NO_ADJUST: No adjustment is applied, similar
--- to the default Defold Text Node behavior.
---
--- - const.TEXT_ADJUST.DOWNSCALE_LIMITED: Changes the text's scale
--- with a limited downscale. You can set the minimum scale using the text:set_minimal_scale() function.
---
--- - const.TEXT_ADJUST.SCROLL: Changes the text's pivot to imitate scrolling within the text box.
--- For better effect, use with a stencil node.
---
--- - const.TEXT_ADJUST.SCALE_THEN_SCROLL: Combines two modes: limited downscale first, then scroll.
---
--- <a href="https://insality.github.io/druid/druid/index.html?example=texts_general" target="_blank"><b>Example Link</b></a>
--- @module Text
--- @within BaseComponent
--- @alias druid.text
-
---- On set text callback(self, text)
--- @tfield event on_set_text event
-
---- On adjust text size callback(self, new_scale, text_metrics)
--- @tfield event on_update_text_scale event
-
---- On change pivot callback(self, pivot)
--- @tfield event on_set_pivot event
-
---- Text node
--- @tfield node node
-
---- The node id of text node
--- @tfield hash node_id
-
---- Current text position
--- @tfield vector3 pos
-
---- The last text value
--- @tfield string last_value
-
---- Initial text node scale
--- @tfield vector3 start_scale
-
---- Current text node scale
--- @tfield vector3 scale
-
---- Initial text node size
--- @tfield vector3 start_size
-
---- Current text node available are
--- @tfield vector3 text_area
-
---- Current text size adjust settings
--- @tfield number adjust_type
-
---- Current text color
--- @tfield vector3 color
-
----
-
 local event = require("event.event")
 local const = require("druid.const")
 local helper = require("druid.helper")
@@ -83,14 +5,20 @@ local utf8_lua = require("druid.system.utf8")
 local component = require("druid.component")
 local utf8 = utf8 or utf8_lua --[[@as utf8]]
 
+---@class druid.text.style
+---@field TRIM_POSTFIX string|nil The postfix for TRIM adjust type. Default: ...
+---@field DEFAULT_ADJUST string|nil The default adjust type for any text component. Default: DOWNSCALE
+---@field ADJUST_STEPS number|nil Amount of iterations for text adjust by height. Default: 20
+---@field ADJUST_SCALE_DELTA number|nil Scale step on each height adjust step. Default: 0.02
+
 ---@class druid.text: druid.component
----@field node node
+---@field node node The text node
----@field on_set_text event
+---@field on_set_text event The event triggered when the text is set, fun(self, text)
----@field on_update_text_scale event
+---@field on_update_text_scale event The event triggered when the text scale is updated, fun(self, scale, metrics)
----@field on_set_pivot event
+---@field on_set_pivot event The event triggered when the text pivot is set, fun(self, pivot)
----@field style table
+---@field style druid.text.style The style of the text
----@field private start_pivot userdata
+---@field private start_pivot userdata The start pivot of the text
----@field private start_scale vector3
+---@field private start_scale vector3 The start scale of the text
 ---@field private scale vector3
 local M = component.create("text")
 
@@ -305,20 +233,14 @@ local function update_adjust(self)
 end
 
 
---- Component style params.
+---@param style druid.text.style
--- You can override this component styles params in druid styles table
--- or create your own style
--- @table style
--- @tfield string|nil TRIM_POSTFIX The postfix for TRIM adjust type. Default: ...
--- @tfield string|nil DEFAULT_ADJUST The default adjust type for any text component. Default: DOWNSCALE
--- @tfield string|nil ADJUST_STEPS Amount of iterations for text adjust by height. Default: 20
--- @tfield string|nil ADJUST_SCALE_DELTA Scale step on each height adjust step. Default: 0.02
 function M:on_style_change(style)
-	self.style = {}
+	self.style = {
-	self.style.TRIM_POSTFIX = style.TRIM_POSTFIX or "..."
+		TRIM_POSTFIX = style.TRIM_POSTFIX or "...",
-	self.style.DEFAULT_ADJUST = style.DEFAULT_ADJUST or const.TEXT_ADJUST.DOWNSCALE
+		DEFAULT_ADJUST = style.DEFAULT_ADJUST or const.TEXT_ADJUST.DOWNSCALE,
-	self.style.ADJUST_STEPS = style.ADJUST_STEPS or 20
+		ADJUST_STEPS = style.ADJUST_STEPS or 20,
-	self.style.ADJUST_SCALE_DELTA = style.ADJUST_SCALE_DELTA or 0.02
+		ADJUST_SCALE_DELTA = style.ADJUST_SCALE_DELTA or 0.02
+	}
 end
 
 

druid/color.lua

@@ -113,10 +113,10 @@ end
 
 
 ---Convert hsb color to rgb color
----@param r number @Red value
+---@param r number Red value
----@param g number @Green value
+---@param g number Green value
----@param b number @Blue value
+---@param b number Blue value
----@param alpha number|nil @Alpha value. Default is 1
+---@param alpha number|nil Alpha value. Default is 1
 function M.rgb2hsb(r, g, b, alpha)
 	alpha = alpha or 1
 	local min, max = math.min(r, g, b), math.max(r, g, b)
@@ -143,10 +143,10 @@ end
 
 
 ---Convert hsb color to rgb color
----@param h number @Hue
+---@param h number Hue
----@param s number @Saturation
+---@param s number Saturation
----@param v number @Value
+---@param v number Value
----@param alpha number|nil @Alpha value. Default is 1
+---@param alpha number|nil Alpha value. Default is 1
 function M.hsb2rgb(h, s, v, alpha)
 	local r, g, b
 	local i = math.floor(h * 6)
@@ -170,9 +170,9 @@ end
 
 
 ---Convert rgb color to hex color
----@param red number @Red value
+---@param red number Red value
----@param green number @Green value
+---@param green number Green value
----@param blue number @Blue value
+---@param blue number Blue value
 function M.rgb2hex(red, green, blue)
 	local r = string.format("%x", math.floor(red * 255))
 	local g = string.format("%x", math.floor(green * 255))

druid/const.lua

@@ -114,5 +114,4 @@ M.SIDE = {
 	Y = "y"
 }
 
-
 return M

druid/helper.lua

@@ -7,7 +7,7 @@ local gui_pick_node = gui.pick_node
 
 ---The helper module contains various functions that are used in the Druid library.
 ---You can use these functions in your projects as well.
----@class druid.system.helper
+---@class druid.helper
 local M = {}
 
 local POSITION_X = hash("position.x")
@@ -51,8 +51,8 @@ end
 
 
 ---Center two nodes.
---Nodes will be center around 0 x position
+---Nodes will be center around 0 x position
---text_node will be first (at left side)
+---text_node will be first (at left side)
 ---@param text_node node|nil Gui text node
 ---@param icon_node node|nil Gui box node
 ---@param margin number Offset between nodes
@@ -63,8 +63,8 @@ end
 
 
 ---Center two nodes.
---Nodes will be center around 0 x position
+---Nodes will be center around 0 x position
---icon_node will be first (at left side)
+---icon_node will be first (at left side)
 ---@param icon_node node|nil Gui box node
 ---@param text_node node|nil Gui text node
 ---@param margin number|nil Offset between nodes
@@ -115,8 +115,8 @@ end
 
 
 ---@param node_id string|node
----@param template string|nil @Full Path to the template
+---@param template string|nil Full Path to the template
----@param nodes table<hash, node>|nil @Nodes what created with gui.clone_tree
+---@param nodes table<hash, node>|nil Nodes what created with gui.clone_tree
 ---@return node
 function M.get_node(node_id, template, nodes)
 	if type(node_id) ~= "string" then
@@ -177,7 +177,7 @@ function M.step(current, target, step)
 end
 
 
----Clamp value between min and max
+---Clamp value between min and max. Works with nil values and swap min and max if needed.
 ---@param value number Value
 ---@param v1 number|nil Min value. If nil, value will be clamped to positive infinity
 ---@param v2 number|nil Max value If nil, value will be clamped to negative infinity
@@ -450,15 +450,20 @@ function M.get_border(node, offset)
 end
 
 
+local TEXT_METRICS_OPTIONS = {
+	line_break = false,
+	tracking = 0,
+	leading = 0,
+	width = 0,
+}
+
 ---Get text metric from GUI node.
 ---@param text_node node
 ---@return GUITextMetrics
 function M.get_text_metrics_from_node(text_node)
-	local font_resource = gui.get_font_resource(gui.get_font(text_node))
+	local options = TEXT_METRICS_OPTIONS
-	local options = {
+	options.tracking = gui.get_tracking(text_node)
-		tracking = gui.get_tracking(text_node),
+	options.line_break = gui.get_line_break(text_node)
-		line_break = gui.get_line_break(text_node),
-	}
 
 	-- Gather other options only if it used in node
 	if options.line_break then
@@ -466,6 +471,7 @@ function M.get_text_metrics_from_node(text_node)
 		options.leading = gui.get_leading(text_node)
 	end
 
+	local font_resource = gui.get_font_resource(gui.get_font(text_node))
 	return resource.get_text_metrics(font_resource, gui.get_text(text_node), options)
 end
 
@@ -548,16 +554,16 @@ end
 
 
 ---@class druid.animation_data
----@field frames table<number, table<string, number>> @List of frames with uv coordinates and size
+---@field frames table<number, table<string, number>> List of frames with uv coordinates and size
----@field width number @Width of the animation
+---@field width number Width of the animation
----@field height number @Height of the animation
+---@field height number Height of the animation
----@field fps number @Frames per second
+---@field fps number Frames per second
----@field current_frame number @Current frame
+---@field current_frame number Current frame
----@field node node @Node with flipbook animation
+---@field node node Node with flipbook animation
----@field v vector4 @Vector with UV coordinates and size
+---@field v vector4 Vector with UV coordinates and size
 
 ---@param node node
----@param atlas_path string @Path to the atlas
+---@param atlas_path string Path to the atlas
 ---@return druid.animation_data
 function M.get_animation_data_from_node(node, atlas_path)
 	local atlas_data = resource.get_atlas(atlas_path)