Update readme and docs

2025-09-27 18:12:19 +02:00 · 2023-07-08 09:59:35 +03:00
parent 487851302b
commit 4896f38e09
10 changed files with 351 additions and 180 deletions
--- a/druid/annotations.lua
+++ b/druid/annotations.lua
@@ -20,7 +20,7 @@ function druid.on_language_change() end
 function druid.on_window_callback(event) end

 --- Register a new external Druid component.
--- You can register your own components by creating them with the druid:new_{name} function.  For example, if you want to 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 re-create each time.
+--- You can register your own components to make new alias: the druid:new_{name} function.  For example, if you want to 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 re-create each time.
 ---@param name string module name
 ---@param module table lua table with component
 function druid.register(name, module) end
@@ -125,7 +125,7 @@ function druid__base_component.component:set_input_enabled(self, state) end
 function druid__base_component.component:set_input_priority(self, value, is_temporary) end

 --- Set current component nodes
--- Used if your component nodes was cloned with `gui.clone_tree`
+--- Use if your component nodes was cloned with `gui.clone_tree` and you got the node tree.
 ---@param self druid.base_component @{BaseComponent}
 ---@param nodes table BaseComponent nodes table
 ---@return druid.base_component @{BaseComponent}
@@ -162,31 +162,28 @@ function druid__blocker.set_enabled(self, state) end


 ---@class druid.button : druid.base_component
---@field anim_node node Animation node
---@field click_zone node Restriction zone
---@field hash node_id The hash of trigger node
---@field hover druid.hover Druid hover logic component
---@field node node Trigger node
---@field on_click druid.event On release button callback(self, params, button_instance)
---@field on_click_outside druid.event On click outside of button(self, params, button_instance)
---@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
---@field start_pos vector3 Initial pos of anim_node
---@field start_scale vector3 Initial scale of anim_node
+---@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 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.
+---@field on_hold_callback druid.event @{DruidEvent}: Event calls every frame before on_long_click event.
+---@field on_long_click druid.event @{DruidEvent}: Event on long tap action over button.
+---@field on_pressed druid.event @{DruidEvent}: Event triggered if button was pressed by user.
+---@field on_repeated_click druid.event @{DruidEvent}: Event on repeated action over button.
+---@field params any Custom args for any Button event.
 ---@field style druid.button.style Component style params.
 local druid__button = {}

--- Get key-code to trigger this button
+--- Get current key name to trigger this button.
 ---@param self druid.button
---@return hash The action_id of the key
+---@return hash The action_id of the input key
 function druid__button.get_key_trigger(self) end

--- Component init function
+--- Button component constructor
 ---@param self druid.button @{Button}
 ---@param node node Gui node
 ---@param callback function Button callback
@@ -194,9 +191,9 @@ function druid__button.get_key_trigger(self) end
 ---@param anim_node node Button anim node (node, if not provided)
 function druid__button.init(self, node, callback, params, anim_node) end

--- Return button enabled state
+--- Get button enabled state.
 ---@param self druid.button @{Button}
---@return bool True, if button is enabled
+---@return bool True, if button is enabled now, False overwise
 function druid__button.is_enabled(self) end

 --- Set function for additional check for button click availability
@@ -206,29 +203,30 @@ function druid__button.is_enabled(self) end
 ---@return druid.button Current button instance
 function druid__button.set_check_function(self, check_function, failure_callback) end

--- Strict button click area.
--- Useful for  no click events outside stencil node
+--- Set additional button click area.
+--- Useful to restrict click outside out stencil node or scrollable content.  This functions calls automatically if you don't disable it in game.project: druid.no_stencil_check
 ---@param self druid.button @{Button}
 ---@param zone node Gui node
 ---@return druid.button Current button instance
 function druid__button.set_click_zone(self, zone) end

--- Set enabled button component state
+--- Set button enabled state.
+--- The style.on_set_enabled will be triggered.  Disabled button is not clickable.
 ---@param self druid.button @{Button}
 ---@param state bool Enabled state
 ---@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
+--- 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-code to trigger this button
+--- Set key name to trigger this button by keyboard.
 ---@param self druid.button @{Button}
---@param key hash The action_id of the key
+---@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

@@ -647,7 +645,7 @@ function druid__input.get_text(self) end

 --- Component init function
 ---@param self druid.input @{Input}
---@param click_node node Button node to enabled input component
+---@param click_node node Node to enabled input component
 ---@param text_node node|druid.text Text node what will be changed on user input. You can pass text component instead of text node name @{Text}
 ---@param keyboard_type number Gui keyboard type for input field
 function druid__input.init(self, click_node, text_node, keyboard_type) end
@@ -942,6 +940,31 @@ function druid__rich_input.set_placeholder(self, placeholder_text) end
 ---@field component field The component druid instance
 local druid__rich_text = {}

+--- Clear all created words.
+function druid__rich_text.clean() end
+
+--- Get all current words.
+---@return table Words
+function druid__rich_text.get_words() end
+
+--- Rich Text component constructor
+---@param self druid.rich_text @{RichText}
+---@param template string The Rich Text template name
+---@param nodes table The node table, if prefab was copied by gui.clone_tree()
+function druid__rich_text.init(self, template, nodes) end
+
+--- Set text for Rich Text
+---@param self druid.rich_text @{RichText}
+---@param text string The text to set
+---@return table words
+---@return table line_metrics
+function druid__rich_text.set_text(self, text) end
+
+--- Get all words, which has a passed tag
+---@param tag string
+---@return table Words
+function druid__rich_text.tagged(tag) end
+

 ---@class druid.scroll : druid.base_component
 ---@field available_pos vector4 Available position for content node: (min_x, max_y, max_x, min_y)
@@ -1578,7 +1601,7 @@ function druid_instance.on_input(self, action_id, action) end
 ---@param sender hash Sender from on_message
 function druid_instance.on_message(self, message_id, message, sender) end

--- Remove component from Druid instance.
+--- Remove created component from Druid instance.
 --- Component `on_remove` function will be invoked, if exist.
 ---@param self druid_instance
 ---@param component Component Component instance
--- a/druid/base/button.lua
+++ b/druid/base/button.lua
@@ -1,56 +1,131 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license

--- Component to handle basic GUI button
+--- 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.
+--
+-- # Notes #
+--
+-- • The click callback will not trigger if between pressed and released state cursor was outside of node zone
+--
+-- • If button have double click event subscriber and it is triggered, usual callback will be not triggered
+--
+-- • Button can have key trigger to use then by key: `button:set_key_trigger`
+--
+-- • Animation node can be used for example to animate small icon on big panel. Node name of trigger zone will be `big panel` and animation node will be `small icon`
+--
+-- @usage
+-- local function on_button_click(self, args, button)
+--     print("Button has clicked with params: " .. args)
+--     print("Also the button component is passed in callback params")
+-- end
+--
+-- local custom_args = "Any variable to pass inside callback"
+-- local button = self.druid:new_button("button_name", on_button_click, custom_args)
+--
 -- @module Button
 -- @within BaseComponent
 -- @alias druid.button

--- On release button callback(self, params, button_instance)
+
+--- @{DruidEvent}: Event on successful release action over button.
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_click:subscribe(function(self, custom_args, button_instance)
+--     print("On button click!")
+-- end)
 -- @tfield DruidEvent on_click @{DruidEvent}

--- On repeated action button callback(self, params, button_instance, click_amount)
+
+--- @{DruidEvent}: Event on repeated action over button.
+--
+-- This callback will be triggered if user hold the button. The repeat rate pick from `input.repeat_interval` in game.project
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_repeated_click:subscribe(function(self, custom_args, button_instance, click_count)
+--     print("On repeated Button click!")
+-- end)
 -- @tfield DruidEvent on_repeated_click @{DruidEvent}

---On long tap button callback(self, params, button_instance, time)
+
+--- @{DruidEvent}: Event on long tap action over button.
+--
+-- This callback will be triggered if user pressed the button and hold the some amount of time.
+-- The amount of time picked from button style param: LONGTAP_TIME
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_long_click:subscribe(function(self, custom_args, button_instance, hold_time)
+--     print("On long Button click!")
+-- end)
 -- @tfield DruidEvent on_long_click @{DruidEvent}

---On double tap button callback(self, params, button_instance, click_amount)
+
+--- @{DruidEvent}: Event on double tap action over button.
+--
+-- If secondary click was too fast after previous one, the double
+-- click will be called instead usual click (if on_double_click subscriber exists)
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_double_click:subscribe(function(self, custom_args, button_instance, click_amount)
+--     print("On double Button click!")
+-- end)
 -- @tfield DruidEvent on_double_click @{DruidEvent}

---On button hold before long_click callback(self, params, button_instance, time)
+
+--- @{DruidEvent}: Event calls every frame before on_long_click event.
+--
+-- If long_click subscriber exists, the on_hold_callback will be called before long_click trigger.
+--
+-- Usecase: Animate button progress of long tap
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_double_click:subscribe(function(self, custom_args, button_instance, time)
+--     print("On hold Button callback!")
+-- end)
 -- @tfield DruidEvent on_hold_callback @{DruidEvent}

---On click outside of button(self, params, button_instance)
+
+--- @{DruidEvent}: Event calls if click event was outside of button.
+--
+-- This event will be triggered for each button what was not clicked on user click action
+--
+-- Usecase: Hide the popup when click outside
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_click_outside:subscribe(function(self, custom_args, button_instance)
+--     print("On click Button outside!")
+-- end)
 -- @tfield DruidEvent on_click_outside @{DruidEvent}

---On pressed button callback(self, params, button_instance)
+
+--- @{DruidEvent}: Event triggered if button was pressed by user.
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_pressed:subscribe(function(self, custom_args, button_instance)
+--     print("On Button pressed!")
+-- end)
 -- @tfield DruidEvent on_pressed @{DruidEvent}

---Trigger node
+--- Button clickable node
 -- @tfield node node

---The hash of trigger node
+---The GUI node id from button node
 -- @tfield node_id hash

---Animation node
+--- Button animation node.
+-- In default case equals to clickable node.
+--
+-- Usecase: You have the big clickable panel, but want to animate only one small icon on it.
 -- @tfield[opt=node] node anim_node

---Initial scale of anim_node
-- @tfield vector3 start_scale
-
---Initial pos of anim_node
-- @tfield vector3 start_pos
-
---Initial pos of anim_node
-- @tfield vector3 pos
-
---Params to click callbacks
+---Custom args for any Button event. Setup in Button constructor
 -- @tfield any params

---Druid hover logic component
+--- @{Hover}: Button Hover component
 -- @tfield Hover hover @{Hover}

---Restriction zone
+--- Additional button click area, defined by another GUI Node
 -- @tfield[opt] node click_zone

 ---
@@ -195,7 +270,7 @@ function Button.on_style_change(self, style)
 end


--- Component init function
+--- Button component constructor
 -- @tparam Button self @{Button}
 -- @tparam node node Gui node
 -- @tparam function callback Button callback
@@ -357,10 +432,15 @@ function Button.on_message_input(self, node_id, message)
 end


--- Set enabled button component state
+--- Set button enabled state.
+-- The style.on_set_enabled will be triggered.
+-- Disabled button is not clickable.
 -- @tparam Button self @{Button}
 -- @tparam bool state Enabled state
 -- @treturn Button Current button instance
+-- @usage
+-- button:set_enabled(false)
+-- button:set_enabled(true)
 function Button.set_enabled(self, state)
 	self.disabled = not state
 	self.hover:set_enabled(state)
@@ -370,19 +450,25 @@ function Button.set_enabled(self, state)
 end


--- Return button enabled state
+--- Get button enabled state.
 -- @tparam Button self @{Button}
-- @treturn bool True, if button is enabled
+-- @treturn bool True, if button is enabled now, False overwise
+-- @usage
+-- local is_enabled = button:is_enabled()
 function Button.is_enabled(self)
 	return not self.disabled
 end


--- Strict button click area. Useful for
-- no click events outside stencil node
+--- Set additional button click area.
+-- Useful to restrict click outside out stencil node or scrollable content.
+--
+-- This functions calls automatically if you don't disable it in game.project: druid.no_stencil_check
 -- @tparam Button self @{Button}
 -- @tparam node zone Gui node
 -- @treturn Button Current button instance
+-- @usage
+-- button:set_click_zone("stencil_node")
 function Button.set_click_zone(self, zone)
 	self.click_zone = self:get_node(zone)
 	self.hover:set_click_zone(zone)
@@ -391,10 +477,12 @@ function Button.set_click_zone(self, zone)
 end


--- Set key-code to trigger this button
+--- Set key name to trigger this button by keyboard.
 -- @tparam Button self @{Button}
-- @tparam hash key The action_id of the key
+-- @tparam hash key The action_id of the input key
 -- @treturn Button Current button instance
+-- @usage
+-- button:set_key_trigger("key_space")
 function Button.set_key_trigger(self, key)
 	self.key_trigger = hash(key)

@@ -402,9 +490,11 @@ function Button.set_key_trigger(self, key)
 end


--- Get key-code to trigger this button
+--- Get current key name to trigger this button.
 -- @tparam Button self
-- @treturn hash The action_id of the key
+-- @treturn hash The action_id of the input key
+-- @usage
+-- local key_hash = button:get_key_trigger()
 function Button.get_key_trigger(self)
 	return self.key_trigger
 end
@@ -423,10 +513,12 @@ 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
+-- The HTML5 button doesn't call any events except on_click event
 -- @tparam Button self
 -- @tparam[opt] boolean is_html_mode If true - button will be called inside html5 callback
 -- @treturn Button Current button instance
+-- @usage
+-- button:set_html5_user_interaction(true)
 function Button.set_html5_user_interaction(self, is_html_mode)
 	self._is_html5_mode = is_html_mode and html5
 	return self
--- a/druid/component.lua
+++ b/druid/component.lua
@@ -64,7 +64,7 @@ BaseComponent.SPECIFIC_UI_MESSAGES = {


 local uid = 0
-function BaseComponent.static.get_uid()
+function BaseComponent.create_uid()
 	uid = uid + 1
 	return uid
 end
@@ -128,7 +128,7 @@ end

 --- Set current component nodes
 --
-- Used if your component nodes was cloned with `gui.clone_tree`
+-- Use if your component nodes was cloned with `gui.clone_tree` and you got the node tree.
 -- @function component:set_nodes
 -- @tparam BaseComponent self @{BaseComponent}
 -- @tparam table nodes BaseComponent nodes table
@@ -226,7 +226,7 @@ end
 -- @tparam BaseComponent self @{BaseComponent}
 -- @treturn string The component name
 function BaseComponent.get_name(self)
-	return self._component.name .. self:get_uid()
+	return self._component.name .. BaseComponent.create_uid()
 end


@@ -362,7 +362,7 @@ end


 --- Basic constructor of component. It will call automaticaly
-- by `BaseComponent.static.create`
+-- by `BaseComponent.create`
 -- @function component:initialize
 -- @tparam BaseComponent self @{BaseComponent}
 -- @tparam string name BaseComponent name
@@ -375,7 +375,7 @@ function BaseComponent.initialize(self, name, input_priority)
 		default_input_priority = input_priority or const.PRIORITY_INPUT,
 		is_debug = false,
 		_is_input_priority_changed = true, -- Default true for sort once time after GUI init
-		_uid = BaseComponent.get_uid()
+		_uid = BaseComponent.create_uid()
 	}
 end

@@ -512,11 +512,11 @@ end


 --- Create new component. It will inheritance from basic Druid component.
-- @function BaseComponent.static.create
+-- @function BaseComponent.create
 -- @tparam string name BaseComponent name
 -- @tparam[opt=DEFAULT] number input_priority The input priority. The bigger number processed first
 -- @local
-function BaseComponent.static.create(name, input_priority)
+function BaseComponent.create(name, input_priority)
 	-- Yea, inheritance here
 	local new_class = class(name, BaseComponent)

--- a/druid/custom/rich_text/rich_text.lua
+++ b/druid/custom/rich_text/rich_text.lua
@@ -1,6 +1,18 @@
 -- Copyright (c) 2022 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license

 --- Druid Rich Text custom component.
+-- # Overview #
+--
+--
+--
+-- # Notes #
+--
+-- @usage
+-- local RichText = require("druid.custom.rich_text.rich_text")
+-- ...
+-- self.rich_text = self.druid:new(RichText, "rich_text")
+-- self.rich_text:set_text("Hello, Druid Rich Text!")
+--
 -- @module RichText
 -- @within BaseComponent
 -- @alias druid.rich_text
@@ -21,7 +33,11 @@ local SCHEME = {
 }


-function RichText:init(template, nodes)
+--- Rich Text component constructor
+-- @tparam RichText self @{RichText}
+-- @tparam string template The Rich Text template name
+-- @tparam table nodes The node table, if prefab was copied by gui.clone_tree()
+function RichText.init(self, template, nodes)
 	self:set_template(template)
 	self:set_nodes(nodes)

@@ -38,7 +54,12 @@ function RichText:init(template, nodes)
 end


-function RichText:set_text(text)
+--- Set text for Rich Text
+-- @tparam RichText self @{RichText}
+-- @tparam string text The text to set
+-- @treturn table words
+-- @treturn table line_metrics
+function RichText.set_text(self, text)
 	self:clean()

 	local words, settings, line_metrics = rich_text.create(text, self._settings)
@@ -56,6 +77,9 @@ function RichText:on_remove()
 end


+--- Get all words, which has a passed tag
+-- @tparam string tag
+-- @treturn table Words
 function RichText:tagged(tag)
 	if not self._words then
 		return
@@ -65,6 +89,8 @@ function RichText:tagged(tag)
 end


+--- Get all current words.
+-- @treturn table Words
 function RichText:get_words()
 	return self._words
 end
@@ -99,6 +125,7 @@ function RichText:_create_settings()
 end


+--- Clear all created words.
 function RichText:clean()
 	if self._words then
 		rich_text.remove(self._words)
--- a/druid/extended/input.lua
+++ b/druid/extended/input.lua
@@ -115,7 +115,7 @@ end

 --- Component init function
 -- @tparam Input self @{Input}
-- @tparam node click_node Button node to enabled input component
+-- @tparam node click_node Node to enabled input component
 -- @tparam node|Text text_node Text node what will be changed on user input. You can pass text component instead of text node name @{Text}
 -- @tparam[opt] number keyboard_type Gui keyboard type for input field
 function Input.init(self, click_node, text_node, keyboard_type)
--- a/druid/system/druid_instance.lua
+++ b/druid/system/druid_instance.lua
@@ -288,7 +288,7 @@ function DruidInstance.final(self)
 end


--- Remove component from Druid instance.
+--- Remove created component from Druid instance.
 --
 -- Component `on_remove` function will be invoked, if exist.
 -- @tparam DruidInstance self