Update docs

druid/system/druid_instance.lua

@@ -4,30 +4,30 @@
 --
 -- # Component List #
 --
--- See all component list in "See Also" section.
+-- For a list of all available components, please refer to the "See Also" section.
 --
 -- # Notes #
 --
--- Take a look on the next API pages:
+-- Please review the following API pages:
 --
--- - @{Helper} - Useful pack of functions to work with GUI nodes like centrate nodes
+-- @{Helper} - A useful set of functions for working with GUI nodes, such as centering nodes, get GUI scale ratio, etc
 --
--- - @{DruidEvent} - The core event system in Druid. See how to subscribe on any event
+-- @{DruidEvent} - The core event system in Druid. Learn how to subscribe to any event in every Druid component.
 --
--- - @{BaseComponent} - the parent of all Druid components, you can see all default component methods there
+-- @{BaseComponent} - The parent class of all Druid components. You can find all default component methods there.
 --
--- Other things:
+-- Other important information:
 --
--- - To use Druid, first you should create a Druid instance to spawn components and add Druids main engine functions: update, final, on_message and on_input.
+-- • To use Druid, you need to create a Druid instance first. This instance is used to spawn components.
 --
--- - All Druid components take node name string as arguments, don't do gui.get_node() before.
+-- • When using Druid components, provide the node name as a string argument directly. Avoid calling gui.get_node() before passing it to the component. Because Druid can get nodes from template and cloned gui nodes.
 --
--- - All Druid and component methods are called with : like self.druid:new_button().
+-- • All Druid and component methods are called using the colon operator (e.g., self.druid:new_button()).
 -- @usage
 -- local druid = require("druid.druid")
 --
 -- local function close_window(self)
---     print("WOW, you closed the game!")
+--     print("Yeah! You closed the game!")
 -- end
 --
 -- function init(self)
@@ -71,49 +71,57 @@ local settings = require("druid.system.settings")
 local base_component = require("druid.component")
 local druid_input = require("druid.helper.druid_input")
 
-local back_handler = require("druid.base.back_handler")
-local blocker = require("druid.base.blocker")
-local button = require("druid.base.button")
 local drag = require("druid.base.drag")
+local text = require("druid.base.text")
 local hover = require("druid.base.hover")
 local scroll = require("druid.base.scroll")
+local button = require("druid.base.button")
+local blocker = require("druid.base.blocker")
 local static_grid = require("druid.base.static_grid")
-local text = require("druid.base.text")
+local back_handler = require("druid.base.back_handler")
 
 -- To use this components, you should register them first
--- local checkbox = require("druid.extended.checkbox")
--- local checkbox_group = require("druid.extended.checkbox_group")
--- local dynamic_grid = require("druid.extended.dynamic_grid")
 -- local input = require("druid.extended.input")
--- local lang_text = require("druid.extended.lang_text")
--- local progress = require("druid.extended.progress")
--- local radio_group = require("druid.extended.radio_group")
--- local slider = require("druid.extended.slider")
--- local timer_component = require("druid.extended.timer")
--- local data_list = require("druid.extended.data_list")
 -- local swipe = require("druid.extended.swipe")
+-- local slider = require("druid.extended.slider")
+-- local checkbox = require("druid.extended.checkbox")
+-- local progress = require("druid.extended.progress")
+-- local data_list = require("druid.extended.data_list")
+-- local lang_text = require("druid.extended.lang_text")
+-- local timer_component = require("druid.extended.timer")
+-- local radio_group = require("druid.extended.radio_group")
+-- local dynamic_grid = require("druid.extended.dynamic_grid")
+-- local checkbox_group = require("druid.extended.checkbox_group")
 
 local DruidInstance = class("druid.druid_instance")
 
 local IS_NO_AUTO_INPUT = sys.get_config_int("druid.no_auto_input", 0) == 1
 
-local function input_init(self)
-	if IS_NO_AUTO_INPUT or self.input_inited then
+local function set_input_state(self, is_input_inited)
+	if IS_NO_AUTO_INPUT or (self.input_inited == is_input_inited) then
 		return
 	end
 
-	self.input_inited = true
-	druid_input.focus()
+	self.input_inited = is_input_inited
+	if is_input_inited then
+		druid_input.focus()
+	else
+		druid_input.remove()
+	end
 end
 
 
-local function input_release(self)
-	if IS_NO_AUTO_INPUT or not self.input_inited then
-		return
+-- a and b - two Druid components
+-- @local
+local function sort_input_comparator(a, b)
+	local a_priority = a:get_input_priority()
+	local b_priority = b:get_input_priority()
+
+	if a_priority ~= b_priority then
+		return a_priority < b_priority
 	end
 
-	self.input_inited = false
-	druid_input.remove()
+	return a:get_uid() < b:get_uid()
 end
 
 
@@ -123,17 +131,11 @@ local function sort_input_stack(self)
 		return
 	end
 
-	table.sort(input_components, function(a, b)
-		if a:get_input_priority() ~= b:get_input_priority() then
-			return a:get_input_priority() < b:get_input_priority()
-		end
-
-		return a:get_uid() < b:get_uid()
-	end)
+	table.sort(input_components, sort_input_comparator)
 end
 
 
--- Create the component itself
+-- Create the Druid component instance
 local function create(self, instance_class)
 	local instance = instance_class()
 	instance:setup_component(self, self._context, self._style, instance_class)
@@ -150,6 +152,7 @@ local function create(self, instance_class)
 end
 
 
+-- Before processing any input check if we need to update input stack
 local function check_sort_input_stack(self, components)
 	if not components or #components == 0 then
 		return
@@ -177,19 +180,11 @@ local function can_use_input_component(self, component)
 	local can_by_blacklist = true
 
 	if self._input_whitelist and #self._input_whitelist > 0 then
-		if helper.contains(self._input_whitelist, component) then
-			can_by_whitelist = true
-		else
-			can_by_whitelist = false
-		end
+		can_by_whitelist = not not helper.contains(self._input_whitelist, component)
 	end
 
 	if self._input_blacklist and #self._input_blacklist > 0 then
-		if helper.contains(self._input_blacklist, component) then
-			can_by_blacklist = false
-		else
-			can_by_blacklist = true
-		end
+		can_by_blacklist = not helper.contains(self._input_blacklist, component)
 	end
 
 	return can_by_blacklist and can_by_whitelist
@@ -200,7 +195,7 @@ local function process_input(self, action_id, action, components)
 	local is_input_consumed = false
 
 	if #components == 0 then
-		return is_input_consumed
+		return false
 	end
 
 	for i = #components, 1, -1 do
@@ -250,27 +245,15 @@ function DruidInstance.initialize(self, context, style)
 	self._input_blacklist = nil
 	self._input_whitelist = nil
 
-	self.components_interest = {}
 	self.components_all = {}
+	self.components_interest = {}
 	for i = 1, #base_component.ALL_INTERESTS do
 		self.components_interest[base_component.ALL_INTERESTS[i]] = {}
 	end
 end
 
 
---- Create new druid component
--- @tparam DruidInstance self
--- @tparam Component component Component module
--- @tparam args ... Other component params to pass it to component:init function
--- @local
-function DruidInstance.create(self, component, ...)
-	helper.deprecated("The druid:create is deprecated. Please use druid:new instead")
-
-	return DruidInstance.new(self, component, ...)
-end
-
-
---- Create new druid component
+--- Create new component
 -- @tparam DruidInstance self
 -- @tparam Component component Component module
 -- @tparam args ... Other component params to pass it to component:init function
@@ -302,7 +285,7 @@ function DruidInstance.final(self)
 
 	self._deleted = true
 
-	input_release(self)
+	set_input_state(self, false)
 end
 
 
@@ -324,8 +307,8 @@ function DruidInstance.remove(self, component)
 		if parent then
 			parent:__remove_children(children[i])
 		end
+		children[i] = nil
 	end
-	component._meta.children = {}
 
 	local all_components = self.components_all
 	for i = #all_components, 1, -1 do
@@ -350,8 +333,11 @@ function DruidInstance.remove(self, component)
 end
 
 
---- Druid late update function call after init and before update step
+---  Druid late update function called after initialization and before the regular update step
+-- This function is used to check the GUI state and perform actions after all components and nodes have been created.
+-- An example use case is performing an auto stencil check in the GUI hierarchy for input components.
 -- @tparam DruidInstance self
+-- @local
 function DruidInstance.late_init(self)
 	local late_init_components = self.components_interest[base_component.ON_LATE_INIT]
 	while late_init_components[1] do
@@ -361,27 +347,30 @@ function DruidInstance.late_init(self)
 
 	if not self.input_inited and #self.components_interest[base_component.ON_INPUT] > 0 then
 		-- Input init on late init step, to be sure it goes after user go acquire input
-		input_init(self)
+		set_input_state(self, true)
 	end
 end
 
 
---- Druid update function
+--- Call this in gui_script update function.
+-- Used for: scroll, progress, timer components
 -- @tparam DruidInstance self
 -- @tparam number dt Delta time
 function DruidInstance.update(self, dt)
 	self._is_late_remove_enabled = true
+
 	local components = self.components_interest[base_component.ON_UPDATE]
 	for i = 1, #components do
 		components[i]:update(dt)
 	end
-	self._is_late_remove_enabled = false
 
+	self._is_late_remove_enabled = false
 	self:_clear_late_remove()
 end
 
 
---- Druid on_input function
+--- Call this in gui_script on_input function.
+-- Used for almost all components
 -- @tparam DruidInstance self
 -- @tparam hash action_id Action_id from on_input
 -- @tparam table action Action from on_input
@@ -394,23 +383,23 @@ function DruidInstance.on_input(self, action_id, action)
 	local is_input_consumed = process_input(self, action_id, action, components)
 
 	self._is_late_remove_enabled = false
-
 	self:_clear_late_remove()
+
 	return is_input_consumed
 end
 
 
---- Druid on_message function
+--- Call this in gui_script on_message function.
+-- Used for special actions. See SPECIFIC_UI_MESSAGES table
 -- @tparam DruidInstance self
 -- @tparam hash message_id Message_id from on_message
 -- @tparam table message Message from on_message
 -- @tparam hash sender Sender from on_message
 function DruidInstance.on_message(self, message_id, message, sender)
-	-- TODO: refactor for more juicy code
 	local specific_ui_message = base_component.SPECIFIC_UI_MESSAGES[message_id]
-	local on_message_input_message = base_component.ON_MESSAGE_INPUT
 
-	if specific_ui_message == on_message_input_message then
+	if specific_ui_message == base_component.ON_MESSAGE_INPUT then
+		-- ON_MESSAGE_INPUT is special message, need to perform additional logic
 		local components = self.components_interest[base_component.ON_MESSAGE_INPUT]
 		if components then
 			for i = 1, #components do
@@ -421,6 +410,7 @@ function DruidInstance.on_message(self, message_id, message, sender)
 			end
 		end
 	elseif specific_ui_message then
+		-- Resend special message to all components with the related interest
 		local components = self.components_interest[specific_ui_message]
 		if components then
 			for i = 1, #components do
@@ -429,6 +419,7 @@ function DruidInstance.on_message(self, message_id, message, sender)
 			end
 		end
 	else
+		-- Resend message to all components with on_message interest
 		local components = self.components_interest[base_component.ON_MESSAGE]
 		for i = 1, #components do
 			components[i]:on_message(message_id, message, sender)
@@ -437,7 +428,7 @@ function DruidInstance.on_message(self, message_id, message, sender)
 end
 
 
---- Druid on focus lost interest function.
+--- Calls the on_focus_lost function in all related components
 -- This one called by on_window_callback by global window listener
 -- @tparam DruidInstance self
 -- @local
@@ -449,7 +440,7 @@ function DruidInstance.on_focus_lost(self)
 end
 
 
---- Druid on focus gained interest function.
+--- Calls the on_focus_gained function in all related components
 -- This one called by on_window_callback by global window listener
 -- @tparam DruidInstance self
 -- @local
@@ -461,7 +452,7 @@ function DruidInstance.on_focus_gained(self)
 end
 
 
---- Druid on language change.
+--- Calls the on_language_change function in all related components
 -- This one called by global druid.on_language_change, but can be
 -- call manualy to update all translations
 -- @tparam DruidInstance self
@@ -475,6 +466,7 @@ end
 
 
 --- Set whitelist components for input processing.
+--
 -- If whitelist is not empty and component not contains in this list,
 -- component will be not processed on input step
 -- @tparam DruidInstance self
@@ -497,6 +489,7 @@ end
 
 
 --- Set blacklist components for input processing.
+--
 -- If blacklist is not empty and component contains in this list,
 -- component will be not processed on input step
 -- @tparam DruidInstance self @{DruidInstance}
@@ -522,6 +515,7 @@ end
 -- @tparam DruidInstance self @{DruidInstance}
 -- @tparam bool is_debug
 -- @treturn self @{DruidInstance}
+-- @local
 function DruidInstance.set_debug(self, is_debug)
 	self._is_debug = is_debug
 	return self
@@ -532,10 +526,12 @@ end
 -- @tparam DruidInstance self @{DruidInstance}
 -- @tparam string message
 -- @tparam[opt] table context
+-- @local
 function DruidInstance.log_message(self, message, context)
 	if not self._is_debug then
 		return
 	end
+
 	print("[Druid]:", message, helper.table_to_string(context))
 end
 
@@ -544,246 +540,250 @@ end
 -- @tparam DruidInstance self @{DruidInstance}
 -- @local
 function DruidInstance._clear_late_remove(self)
-	if #self._late_remove > 0 then
-		for i = 1, #self._late_remove do
-			self:remove(self._late_remove[i])
-		end
-		self._late_remove = {}
+	if #self._late_remove == 0 then
+		return
 	end
+
+	for i = 1, #self._late_remove do
+		self:remove(self._late_remove[i])
+	end
+	self._late_remove = {}
 end
 
---- Create button basic component
+
+--- Create @{Button} component
 -- @tparam DruidInstance self
--- @tparam node node Gui node
+-- @tparam node node GUI node
 -- @tparam function callback Button callback
 -- @tparam[opt] table params Button callback params
 -- @tparam[opt] node anim_node Button anim node (node, if not provided)
--- @treturn Button button component
+-- @treturn Button @{Button} component
 function DruidInstance.new_button(self, node, callback, params, anim_node)
 	return DruidInstance.new(self, button, node, callback, params, anim_node)
 end
 
 
---- Create blocker basic component
+--- Create @{Blocker} component
 -- @tparam DruidInstance self
 -- @tparam node node Gui node
--- @treturn Blocker blocker component
+-- @treturn Blocker @{Blocker} component
 function DruidInstance.new_blocker(self, node)
 	return DruidInstance.new(self, blocker, node)
 end
 
 
---- Create back_handler basic component
+--- Create @{BackHandler} component
 -- @tparam DruidInstance self
 -- @tparam callback callback On back button
 -- @tparam[opt] any params Callback argument
--- @treturn BackHandler back_handler component
+-- @treturn BackHandler @{BackHandler} component
 function DruidInstance.new_back_handler(self, callback, params)
 	return DruidInstance.new(self, back_handler, callback, params)
 end
 
 
---- Create hover basic component
+--- Create @{Hover} component
 -- @tparam DruidInstance self
 -- @tparam node node Gui node
 -- @tparam function on_hover_callback Hover callback
--- @treturn Hover hover component
+-- @treturn Hover @{Hover} component
 function DruidInstance.new_hover(self, node, on_hover_callback)
 	return DruidInstance.new(self, hover, node, on_hover_callback)
 end
 
 
---- Create text basic component
+--- Create @{Text} component
 -- @tparam DruidInstance self
 -- @tparam node node Gui text node
 -- @tparam[opt] string value Initial text. Default value is node text from GUI scene.
 -- @tparam[opt] bool no_adjust If true, text will be not auto-adjust size
--- @treturn Text text component
+-- @treturn Text @{Text} component
 function DruidInstance.new_text(self, node, value, no_adjust)
 	return DruidInstance.new(self, text, node, value, no_adjust)
 end
 
 
---- Create grid basic component
+--- Create @{StaticGrid} component
 -- Deprecated
 -- @tparam DruidInstance self
 -- @tparam node parent The gui node parent, where 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
--- @treturn StaticGrid grid component
+-- @treturn StaticGrid @{StaticGrid} component
+-- @local
 function DruidInstance.new_grid(self, parent, element, in_row)
 	helper.deprecated("The druid:new_grid is deprecated. Please use druid:new_static_grid instead")
 	return DruidInstance.new(self, static_grid, parent, element, in_row)
 end
 
 
---- Create static grid basic component
+--- Create @{StaticGrid} component
 -- @tparam DruidInstance self
 -- @tparam node parent The gui node parent, where 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
--- @treturn StaticGrid grid component
+-- @treturn StaticGrid @{StaticGrid} component
 function DruidInstance.new_static_grid(self, parent, element, in_row)
 	return DruidInstance.new(self, static_grid, parent, element, in_row)
 end
 
 
---- Create scroll basic component
+--- Create @{Scroll} component
 -- @tparam DruidInstance self
 -- @tparam node view_node GUI view scroll node
 -- @tparam node content_node GUI content scroll node
--- @treturn Scroll scroll component
+-- @treturn Scroll @{Scroll} component
 function DruidInstance.new_scroll(self, view_node, content_node)
 	return DruidInstance.new(self, scroll, view_node, content_node)
 end
 
 
---- Create drag basic component
+--- Create @{Drag} component
 -- @tparam DruidInstance self
 -- @tparam node node GUI node to detect dragging
 -- @tparam function on_drag_callback Callback for on_drag_event(self, dx, dy)
--- @treturn Drag drag component
+-- @treturn Drag @{Drag} component
 function DruidInstance.new_drag(self, node, on_drag_callback)
 	return DruidInstance.new(self, drag, node, on_drag_callback)
 end
 
 
---- Create swipe basic component
+--- Create @{Swipe} component
 -- @tparam DruidInstance self
 -- @tparam node node Gui node
 -- @tparam function on_swipe_callback Swipe callback for on_swipe_end event
--- @treturn Swipe swipe component
+-- @treturn Swipe @{Swipe} component
 function DruidInstance.new_swipe(self, node, on_swipe_callback)
 	return helper.extended_component("swipe")
 end
 
 
---- Create dynamic grid component
+--- Create @{DynamicGrid} component
 -- @tparam DruidInstance self
 -- @tparam node parent The gui node parent, where items will be placed
--- @treturn DynamicGrid grid component
+-- @treturn DynamicGrid @{DynamicGrid} component
 function DruidInstance.new_dynamic_grid(self, parent)
 	return helper.extended_component("dynamic_grid")
 end
 
 
---- Create lang_text component
+--- Create @{LangText} component
 -- @tparam DruidInstance self
 -- @tparam node node The text node
 -- @tparam string locale_id Default locale id
 -- @tparam bool no_adjust If true, will not correct text size
--- @treturn LangText lang_text component
+-- @treturn LangText @{LangText} component
 function DruidInstance.new_lang_text(self, node, locale_id, no_adjust)
 	return helper.extended_component("lang_text")
 end
 
 
---- Create slider component
+--- Create @{Slider} component
 -- @tparam DruidInstance self
 -- @tparam node node Gui pin node
 -- @tparam vector3 end_pos The end position of slider
 -- @tparam[opt] function callback On slider change callback
--- @treturn Slider slider component
+-- @treturn Slider @{Slider} component
 function DruidInstance.new_slider(self, node, end_pos, callback)
 	return helper.extended_component("slider")
 end
 
 
---- Create checkbox component
+--- Create @{Checkbox} component
 -- @tparam DruidInstance self
 -- @tparam node node Gui node
 -- @tparam function callback Checkbox callback
 -- @tparam[opt=node] node click_node Trigger node, by default equals to node
 -- @tparam[opt=false] boolean initial_state The initial state of checkbox, default - false
--- @treturn Checkbox checkbox component
+-- @treturn Checkbox @{Checkbox} component
 function DruidInstance.new_checkbox(self, node, callback, click_node, initial_state)
 	return helper.extended_component("checkbox")
 end
 
 
---- Create input component
+--- Create @{Input} component
 -- @tparam DruidInstance self
 -- @tparam node click_node Button node to enabled input component
 -- @tparam node text_node Text node what will be changed on user input
 -- @tparam[opt] number keyboard_type Gui keyboard type for input field
--- @treturn Input input component
+-- @treturn Input @{Input} component
 function DruidInstance.new_input(self, click_node, text_node, keyboard_type)
 	return helper.extended_component("input")
 end
 
 
---- Create checkbox_group component
+--- Create @{CheckboxGroup} component
 -- @tparam DruidInstance self
 -- @tparam node[] nodes Array of gui node
 -- @tparam function callback Checkbox callback
 -- @tparam[opt=node] node[] click_nodes Array of trigger nodes, by default equals to nodes
--- @treturn CheckboxGroup checkbox_group component
+-- @treturn CheckboxGroup @{CheckboxGroup} component
 function DruidInstance.new_checkbox_group(self, nodes, callback, click_nodes)
 	return helper.extended_component("checkbox_group")
 end
 
 
---- Create data list basic component
+--- Create @{DataList} component
 -- @tparam DruidInstance self
 -- @tparam Scroll druid_scroll The Scroll instance for Data List component
 -- @tparam Grid druid_grid The Grid instance for Data List component
 -- @tparam function create_function The create function callback(self, data, index, data_list). Function should return (node, [component])
--- @treturn DataList data_list component
+-- @treturn DataList @{DataList} component
 function DruidInstance.new_data_list(self, druid_scroll, druid_grid, create_function)
 	return helper.extended_component("data_list")
 end
 
 
---- Create radio_group component
+--- Create @{RadioGroup} component
 -- @tparam DruidInstance self
 -- @tparam node[] nodes Array of gui node
 -- @tparam function callback Radio callback
 -- @tparam[opt=node] node[] click_nodes Array of trigger nodes, by default equals to nodes
--- @treturn RadioGroup radio_group component
+-- @treturn RadioGroup @{RadioGroup} component
 function DruidInstance.new_radio_group(self, nodes, callback, click_nodes)
 	return helper.extended_component("radio_group")
 end
 
 
---- Create timer component
+--- Create @{Timer} component
 -- @tparam DruidInstance self
 -- @tparam node node Gui text node
 -- @tparam number seconds_from Start timer value in seconds
 -- @tparam[opt=0] number seconds_to End timer value in seconds
 -- @tparam[opt] function callback Function on timer end
--- @treturn Timer timer component
+-- @treturn Timer @{Timer} component
 function DruidInstance.new_timer(self, node, seconds_from, seconds_to, callback)
 	return helper.extended_component("timer")
 end
 
 
---- Create progress component
+--- Create @{Progress} component
 -- @tparam DruidInstance self
 -- @tparam string|node node Progress bar fill node or node name
 -- @tparam string key Progress bar direction: const.SIDE.X or const.SIDE.Y
 -- @tparam[opt=1] number init_value Initial value of progress bar
--- @treturn Progress progress component
+-- @treturn Progress @{Progress} component
 function DruidInstance.new_progress(self, node, key, init_value)
 	return helper.extended_component("progress")
 end
 
 
---- Create layout component
+--- Create @{Layout} component
 -- @tparam DruidInstance self
 -- @tparam string|node node Layout node
 -- @tparam string mode The layout mode
--- @treturn Layout layout component
+-- @treturn Layout @{Layout} component
 function DruidInstance.new_layout(self, node, mode)
 	return helper.extended_component("layout")
 end
 
 
---- Create hotkey component
+--- Create @{Hotkey} component
 -- @tparam DruidInstance self
 -- @tparam string|string[] keys_array Keys for trigger action. Should contains one action key and any amount of modificator keys
 -- @tparam function callback Button callback
 -- @tparam[opt] value params Button callback params
--- @treturn Hotkey hotkey component
+-- @treturn Hotkey @{Hotkey} component
 function DruidInstance.new_hotkey(self, keys_array, callback, params)
 	return helper.extended_component("hotkey")
 end