Start update docs

druid/annotations.lua

@@ -41,22 +41,10 @@ function druid.set_text_function(callback) end
 
 
 ---@class druid.back_handler : druid.base_component
----@field on_back druid.event On back handler callback(self, params)
----@field params any Params to back callback
+---@field on_back druid.event @{DruidEvent} function(self, [params]) .
+---@field params any Params to pass in the callback
 local druid__back_handler = {}
 
---- Component init function
----@param self druid.back_handler @{BackHandler}
----@param callback callback On back button
----@param params any Callback argument
-function druid__back_handler.init(self, callback, params) end
-
---- Input handler for component
----@param self druid.back_handler @{BackHandler}
----@param action_id string on_input action id
----@param action table on_input action
-function druid__back_handler.on_input(self, action_id, action) end
-
 
 ---@class druid.base_component
 ---@field ON_INPUT field Component Interests
@@ -179,12 +167,7 @@ function druid__base_component.set_template(self, template) end
 ---@field node node Trigger node
 local druid__blocker = {}
 
---- Component init function
----@param self druid.blocker @{Blocker}
----@param node node Gui node
-function druid__blocker.init(self, node) end
-
---- Return blocked enabled state
+--- Return blocker enabled state
 ---@param self druid.blocker @{Blocker}
 ---@return bool True, if blocker is enabled
 function druid__blocker.is_enabled(self) end
@@ -206,6 +189,7 @@ function druid__blocker.set_enabled(self, state) end
 ---@field on_double_click druid.event On double tap button callback(self, params, button_instance, click_amount)
 ---@field on_hold_callback druid.event On button hold before long_click callback(self, params, button_instance, time)
 ---@field on_long_click druid.event On long tap button callback(self, params, button_instance, time)
+---@field on_pressed druid.event On pressed button callback(self, params, button_instance)
 ---@field on_repeated_click druid.event On repeated action button callback(self, params, button_instance, click_amount)
 ---@field params any Params to click callbacks
 ---@field pos vector3 Initial pos of anim_node
@@ -252,6 +236,13 @@ 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 don't call any events except on_click
+---@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-code to trigger this button
 ---@param self druid.button @{Button}
 ---@param key hash The action_id of the key
@@ -441,6 +432,7 @@ function druid__drag.set_enabled(self, is_enabled) end
 
 ---@class druid.drag.style
 ---@field DRAG_DEADZONE field  Distance in pixels to start dragging
+---@field NO_USE_SCREEN_KOEF field  If screen aspect ratio affects on drag values
 local druid__drag__style = {}
 
 
@@ -573,6 +565,18 @@ function druid__event.unsubscribe(self, callback, context) end
 ---@class druid.helper
 local druid__helper = {}
 
+--- Get text metric from gui node.
+--- Replacement of previous gui.get_text_metrics_from_node function
+---@param text_node Node
+---@return table {width, height, max_ascent, max_descent}
+function druid__helper.get_text_metrics_from_node(text_node) end
+
+--- Get text metric from gui node.
+--- Replacement of previous gui.get_text_metrics_from_node function
+---@param text_node Node
+---@return table {width, height, max_ascent, max_descent}
+function druid__helper.get_text_metrics_from_node(text_node) end
+
 --- Transform table to oneline string
 ---@param t table
 ---@return string
@@ -607,8 +611,8 @@ local druid__hotkey__style = {}
 
 
 ---@class druid.hover : druid.base_component
----@field on_hover druid.event On hover callback(self, state)
----@field on_mouse_hover druid.event On mouse hover callback(self, state)
+---@field on_hover druid.event On hover callback(self, state, hover_instance)
+---@field on_mouse_hover druid.event On mouse hover callback(self, state, hover_instance)
 local druid__hover = {}
 
 --- Component init function
@@ -622,6 +626,18 @@ function druid__hover.init(self, node, on_hover_callback) end
 ---@return bool The hover enabled state
 function druid__hover.is_enabled(self) end
 
+--- Return current hover state.
+--- True if touch action was on the node at current time
+---@param self druid.hover @{Hover}
+---@return bool The current hovered state
+function druid__hover.is_hovered(self) end
+
+--- Return current hover state.
+--- True if nil action_id (usually desktop mouse) was on the node at current time
+---@param self druid.hover @{Hover}
+---@return bool The current hovered state
+function druid__hover.is_mouse_hovered(self) end
+
 --- Strict hover click area.
 --- Useful for  no click events outside stencil node
 ---@param self druid.hover @{Hover}
@@ -712,6 +728,7 @@ function druid__input.unselect(self) end
 ---@field IS_LONGTAP_ERASE field  Is long tap will erase current input data
 ---@field IS_UNSELECT_ON_RESELECT field  If true, call unselect on select selected input
 ---@field MASK_DEFAULT_CHAR field  Default character mask for password input
+---@field NO_CONSUME_INPUT_WHILE_SELECTED field  If true, will not consume input while input is selected. It's allow to interact with other components while input is selected (text input still captured)
 ---@field button_style field  Custom button style for input node
 ---@field on_input_wrong field  (self, button_node) Callback on wrong user input
 ---@field on_select field  (self, button_node) Callback on input field selecting
@@ -794,6 +811,13 @@ function druid__layout.fit_into_window(self) end
 ---@param on_size_changed_callback function The callback on window resize
 function druid__layout.init(self, node, mode, on_size_changed_callback) end
 
+--- Set max gui upscale for FIT adjust mode (or side).
+--- It happens on bigger render gui screen
+---@param self druid.layout @{Layout}
+---@param max_gui_upscale number
+---@return druid.layout @{Layout}
+function druid__layout.set_max_gui_upscale(self, max_gui_upscale) end
+
 --- Set maximum size of layout node
 ---@param self druid.layout @{Layout}
 ---@param max_size vector3
@@ -952,6 +976,11 @@ function druid__rich_input.init(self, template, nodes) end
 function druid__rich_input.set_placeholder(self, placeholder_text) end
 
 
+---@class druid.rich_text : druid.base_component
+---@field component field The component druid instance
+local druid__rich_text = {}
+
+
 ---@class druid.scroll : druid.base_component
 ---@field available_pos vector4 Available position for content node: (min_x, max_y, max_x, min_y)
 ---@field available_size vector3 Size of available positions: (width, height, 0)
@@ -1272,7 +1301,7 @@ local druid__swipe__style = {}
 ---@field node_id hash The node id of text node
 ---@field on_set_pivot druid.event On change pivot callback(self, pivot)
 ---@field on_set_text druid.event On set text callback(self, text)
----@field on_update_text_scale druid.event On adjust text size callback(self, new_scale)
+---@field on_update_text_scale druid.event On adjust text size callback(self, new_scale, text_metrics)
 ---@field pos vector3 Current text position
 ---@field scale vector3 Current text node scale
 ---@field start_scale vector3 Initial text node scale
@@ -1405,7 +1434,7 @@ local druid_instance = {}
 ---@param self druid_instance
 function druid_instance.final(self) end
 
---- Druid late update function call after init and before udpate step
+--- Druid late update function call after init and before update step
 ---@param self druid_instance
 function druid_instance.late_init(self) end
 
@@ -1578,7 +1607,7 @@ function druid_instance.new_swipe(self, node, on_swipe_callback) end
 ---@param node node Gui text node
 ---@param value string Initial text. Default value is node text from GUI scene.
 ---@param no_adjust bool If true, text will be not auto-adjust size
----@return Tet text component
+---@return druid.text text component
 function druid_instance.new_text(self, node, value, no_adjust) end
 
 --- Create timer component
@@ -1700,6 +1729,12 @@ function helper.get_closest_stencil_node(node) end
 ---@return vector3 Vector offset with [-1..1] values
 function helper.get_pivot_offset(pivot) end
 
+--- Get cumulative parent's node scale
+---@param node node Gui node
+---@param include_passed_node_scale bool True if add current node scale to result
+---@return vector3 The scene node scale
+function helper.get_scene_scale(node, include_passed_node_scale) end
+
 --- Check if node is enabled in gui hierarchy.
 --- Return false, if node or any his parent is disabled
 ---@param node node Gui node

druid/base/back_handler.lua

@@ -1,15 +1,40 @@
--- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
+-- Copyright (c) 2023 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to handle back key (android, backspace)
+--- Component with event on back or backspace button.
+-- # Overview #
+--
+-- 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.
+-- @usage
+-- local callback = function(self, params) ... end
+--
+-- local params = {}
+-- local back_handler = self.druid:new_back_handler(callback, [params])
 -- @module BackHandler
 -- @within BaseComponent
 -- @alias druid.back_handler
 
---- On back handler callback(self, params)
+--- @{DruidEvent} function(self, [params]) .
+--
+-- Trigger on input action ACTION_BACK or ACTION_BACKSPACE
+-- @usage
+-- -- Subscribe additional callbacks:
+-- back_handler.on_back:subscribe(callback)
 -- @tfield DruidEvent on_back @{DruidEvent}
 
---- Params to back callback
--- @tfield any params
+--- Params to pass in the callback
+-- @usage
+-- -- Replace params on runtime:
+-- back_handler.params = { ... }
+-- @tfield[opt] any params
 
 ---
 
@@ -20,20 +45,22 @@ local component = require("druid.component")
 local BackHandler = component.create("back_handler")
 
 
---- Component init function
+--- Component initialize function
 -- @tparam BackHandler self @{BackHandler}
 -- @tparam callback callback On back button
 -- @tparam[opt] any params Callback argument
+-- @local
 function BackHandler.init(self, callback, params)
 	self.params = params
 	self.on_back = Event(callback)
 end
 
 
---- Input handler for component
+--- Component input handler
 -- @tparam BackHandler self @{BackHandler}
 -- @tparam string action_id on_input action id
 -- @tparam table action on_input action
+-- @local
 function BackHandler.on_input(self, action_id, action)
 	if not action[const.RELEASED] then
 		return false

druid/component.lua

@@ -1,7 +1,11 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
 --- Basic class for all Druid components.
--- To create you component, use `component.create`
+-- To create you custom component, use `component.create`
+-- @usage
+-- -- Create your component:
+-- local component = require("druid.component")
+-- local AwesomeComponent = component.create("awesome_component")
 -- @module BaseComponent
 -- @alias druid.base_component
 

druid/custom/rich_text/module/rt.lua

@@ -2,6 +2,10 @@
 -- Author: Britzl
 -- Modified by: Insality
 
+--- RT
+-- @module rich_text.rt
+-- @local
+
 local helper = require("druid.helper")
 local parser = require("druid.custom.rich_text.module.rt_parse")
 local utf8_lua = require("druid.system.utf8")
@@ -203,6 +207,7 @@ function M._fill_properties(word, metrics, settings)
 	word.position = vmath.vector3(0)
 
 	if word.image then
+		-- Image properties
 		word.scale = gui.get_scale(settings.node_prefab) * word.relative_scale * settings.adjust_scale
 		word.pivot = gui.get_pivot(settings.node_prefab)
 		word.size = metrics.node_size
@@ -212,6 +217,7 @@ function M._fill_properties(word, metrics, settings)
 			word.size.x = word.image.width
 		end
 	else
+		-- Text properties
 		word.scale = gui.get_scale(settings.text_prefab) * word.relative_scale * settings.adjust_scale
 		word.pivot = gui.get_pivot(settings.text_prefab)
 		word.size = vmath.vector3(metrics.width, metrics.height, 0)
@@ -510,32 +516,6 @@ function M.is_fit_info_area(lines, settings)
 end
 
 
---- Detected click/touch events on words with an anchor tag
--- These words act as "hyperlinks" and will generate a message when clicked
--- @param words Words to search for anchor tags
--- @param action The action table from on_input
--- @return true if a word was clicked, otherwise false
-function M.on_click(words, action)
-	for i = 1, #words do
-		local word = words[i]
-		if word.anchor and gui.pick_node(word.node, action.x, action.y) then
-			if word.tags and word.tags.a then
-				local message = {
-					node_id = gui.get_id(word.node),
-					text = word.text,
-					x = action.x, y = action.y,
-					screen_x = action.screen_x, screen_y = action.screen_y
-				}
-				msg.post("#", word.tags.a, message)
-				return true
-			end
-		end
-	end
-
-	return false
-end
-
-
 --- Get all words with a specific tag
 -- @param words The words to search (as received from richtext.create)
 -- @param tag The tag to search for. Nil to search for words without a tag

druid/custom/rich_text/rich_text.lua

@@ -1,7 +1,18 @@
+-- Copyright (c) 2022 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
+
+--- Druid Rich Text custom component.
+-- It's wrapper on Input component with cursor and placeholder text
+-- @module RichText
+-- @within BaseComponent
+-- @alias druid.rich_text
+
+--- The component druid instance
+-- @tfield DruidInstance druid @{DruidInstance}
+
+
 local component = require("druid.component")
 local rich_text = require("druid.custom.rich_text.module.rt")
 
----@class druid.rich_text
 local RichText = component.create("rich_text")
 
 local SCHEME = {
@@ -14,9 +25,9 @@ local SCHEME = {
 function RichText:init(template, nodes)
 	self:set_template(template)
 	self:set_nodes(nodes)
+
 	self.root = self:get_node(SCHEME.ROOT)
 	self.druid = self:get_druid()
-	self.root_size = gui.get_size(self.root)
 
 	self.text_prefab = self:get_node(SCHEME.TEXT_PREFAB)
 	self.icon_prefab = self:get_node(SCHEME.ICON_PREFAB)
@@ -24,12 +35,10 @@ function RichText:init(template, nodes)
 	gui.set_enabled(self.text_prefab, false)
 	gui.set_enabled(self.icon_prefab, false)
 
-	self._settings = self:_get_settings()
+	self._settings = self:_create_settings()
 end
 
 
----@param text string
----@return rich_text.word[], rich_text.lines_metrics
 function RichText:set_text(text)
 	self:clean()
 
@@ -57,24 +66,25 @@ function RichText:tagged(tag)
 end
 
 
----@return druid.rich_text_word[]
 function RichText:get_words()
 	return self._words
 end
 
 
-function RichText:_get_settings()
+function RichText:_create_settings()
+	local root_size = gui.get_size(self.root)
 	return {
 		-- General settings
+		-- Adjust scale using to fit the text to the root node area
 		adjust_scale = 1,
 		parent = self.root,
-		width = self.root_size.x,
-		height = self.root_size.y,
+		width = root_size.x,
+		height = root_size.y,
+		combine_words = false,
 		text_prefab = self.text_prefab,
 		node_prefab = self.icon_prefab,
 
 		-- Text Settings
-		size = gui.get_scale(self.text_prefab).x,
 		shadow = gui.get_shadow(self.text_prefab),
 		outline = gui.get_outline(self.text_prefab),
 		text_scale = gui.get_scale(self.text_prefab),
@@ -82,7 +92,6 @@ function RichText:_get_settings()
 		is_multiline = gui.get_line_break(self.text_prefab),
 
 		-- Image settings
-		combine_words = false,
 		image_pixel_grid_snap = false,
 		node_scale = gui.get_scale(self.icon_prefab),
 		image_scale = gui.get_scale(self.icon_prefab),