Update

druid/druid.lua

@@ -1,53 +1,6 @@
--- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
-
---- Druid UI Component Framework.
--- <b># Overview #</b>
---
--- Druid - powerful Defold component UI library. Use basic and extended
--- Druid components or make your own game-specific components to make
--- amazing GUI in your games.
---
--- To start using Druid, please refer to the Usage section below.
---
--- <b># Notes #</b>
---
--- • Each Druid instance maintains the self context from the constructor and passes it to each Druid callback.
---
--- See next: DruidInstance
---
--- @usage
--- local druid = require("druid.druid")
---
--- local function on_play(self)
---     print("Gonna play!")
--- end
---
--- function init(self)
---     self.druid = druid.new(self)
---     self.druid:new_button("button_play", on_play)
--- end
---
--- function final(self)
---     self.druid:final()
--- end
---
--- function update(self, dt)
---     self.druid:update(dt)
--- end
---
--- function on_message(self, message_id, message, sender)
---     self.druid:on_message(message_id, message, sender)
--- end
---
--- function on_input(self, action_id, action)
---     return self.druid:on_input(action_id, action)
--- end
---
--- @module Druid
-
 local const = require("druid.const")
-local base_component = require("druid.component")
 local settings = require("druid.system.settings")
+local base_component = require("druid.component")
 local druid_instance = require("druid.system.druid_instance")
 
 local default_style = require("druid.styles.default.style")
@@ -73,9 +26,9 @@ end
 
 
 ---Register a new external Druid component.
----You can register your own components to make new alias: the druid:new_{name} function.
+---Register component just makes 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(...).
+---For example, if you 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.
+---This can be useful if you have your own "basic" components that you don't want to require in every file.
 ---@param name string Module name
 ---@param module table Lua table with component
 function M.register(name, module)

druid/event.lua

@@ -1,15 +1,6 @@
--- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
-
---- Druid Event Module
---
--- The Event module provides a simple class for handling callbacks. It is used in many Druid components.
---
--- You can subscribe to an event using the `:subscribe` method and unsubscribe using the `:unsubscribe` method.
--- @module DruidEvent
--- @alias druid.event
-
 ---@class druid.event
 local M = {}
+
 M.COUNTER = 0
 
 -- Forward declaration
@@ -20,13 +11,11 @@ local pcall = pcall
 local tinsert = table.insert
 local tremove = table.remove
 
---- DruidEvent constructor
+--- Return new event instance
--- @tparam function|nil callback Subscribe the callback on new event, if callback exist
+---@param callback fun()|nil Subscribe the callback on new event, if callback exist
--- @tparam any|nil callback_context Additional context as first param to callback call
+---@param callback_context any|nil Additional context as first param to callback call
--- @usage
+---@return druid.event
--- local Event = require("druid.event")
+---@nodiscard
--- ...
--- local event = Event(callback)
 function M.create(callback, callback_context)
 	local instance = setmetatable({}, EVENT_METATABLE)
 
@@ -40,9 +29,8 @@ end
 
 
 --- Check is event subscribed.
--- @tparam DruidEvent self DruidEvent
+---@param callback fun() Callback itself
--- @tparam function callback Callback itself
+---@param callback_context any|nil Additional context as first param to callback call
--- @tparam any|nil callback_context Additional context as first param to callback call
 -- @treturn boolean, number|nil @Is event subscribed, return index of callback in event as second param
 function M:is_subscribed(callback, callback_context)
 	if #self == 0 then
@@ -61,17 +49,9 @@ end
 
 
 ---Subscribe callback on event
--- @tparam DruidEvent self DruidEvent
+---@param callback fun() Callback itself
--- @tparam function callback Callback itself
+---@param callback_context any|nil Additional context as first param to callback call, usually it's self
--- @tparam any|nil callback_context Additional context as first param to callback call, usually it's self
+---@return boolean
--- @treturn boolean True if callback was subscribed
--- @usage
--- local function on_long_callback(self)
---     print("Long click!")
--- end
--- ...
--- local button = self.druid:new_button("button", callback)
--- button.on_long_click:subscribe(on_long_callback, self)
 function M:subscribe(callback, callback_context)
 	assert(type(self) == "table", "You should subscribe to event with : syntax")
 	assert(callback, "A function must be passed to subscribe to an event")
@@ -86,15 +66,9 @@ end
 
 
 ---Unsubscribe callback on event
--- @tparam DruidEvent self DruidEvent
+---@param callback fun() Callback itself
--- @tparam function callback Callback itself
+---@param callback_context any|nil Additional context as first param to callback call
--- @tparam any|nil callback_context Additional context as first param to callback call
+---@return boolean
--- @usage
--- local function on_long_callback(self)
---     print("Long click!")
--- end
--- ...
--- button.on_long_click:unsubscribe(on_long_callback, self)
 function M:unsubscribe(callback, callback_context)
 	assert(callback, "A function must be passed to subscribe to an event")
 
@@ -109,29 +83,20 @@ end
 
 
 ---Return true, if event have at lease one handler
--- @tparam DruidEvent self DruidEvent
+---@return boolean
--- @treturn boolean True if event have handlers
--- @usage
--- local is_long_click_handler_exists = button.on_long_click:is_exist()
 function M:is_exist()
 	return #self > 0
 end
 
 
 ---Return true, if event not have handler
---- @tparam DruidEvent self DruidEvent
+---@return boolean True if event not have handlers
---- @treturn boolean True if event not have handlers
---- @usage
---- local is_long_click_handler_not_exists = button.on_long_click:is_empty()
 function M:is_empty()
 	return #self == 0
 end
 
 
 ---Clear the all event handlers
--- @tparam DruidEvent self DruidEvent
--- @usage
--- button.on_long_click:clear()
 function M:clear()
 	for index = #self, 1, -1 do
 		self[index] = nil
@@ -140,13 +105,8 @@ end
 
 
 --- Trigger the event and call all subscribed callbacks
--- @tparam DruidEvent self DruidEvent
+---@param ... any All event params
--- @tparam any ... All event params
+---@return any result Last returned value from subscribers
--- @usage
--- local Event = require("druid.event")
--- ...
--- local event = Event()
--- event:trigger("Param1", "Param2")
 function M:trigger(...)
 	if #self == 0 then
 		return
@@ -163,10 +123,9 @@ function M:trigger(...)
 end
 
 
--- @tparam table callback Callback data {function, context}
+---@param callback table Callback data {function, context}
--- @tparam any ... All event params
+---@param ... any All event params
--- @treturn any Result of the callback
+---@return any result Result of the callback
--- @local
 function M:call_callback(callback, ...)
 	local event_callback = callback[1]
 	local event_callback_context = callback[2]

druid/helper.lua

@@ -344,14 +344,8 @@ function M.get_closest_stencil_node(node)
 end
 
 
---- Get node offset for given GUI pivot.
---
--- Offset shown in [-0.5 .. 0.5] range, where -0.5 is left or bottom, 0.5 is right or top.
--- @function helper.get_pivot_offset
--- @tparam number pivot The gui.PIVOT_* constant
--- @treturn vector3 Vector offset with [-0.5..0.5] values
-
 ---Get pivot offset for given pivot or node
+---Offset shown in [-0.5 .. 0.5] range, where -0.5 is left or bottom, 0.5 is right or top.
 ---@param pivot_or_node number|node GUI pivot or node
 ---@return vector3 offset The pivot offset
 function M.get_pivot_offset(pivot_or_node)
@@ -363,25 +357,22 @@ end
 
 
 ---Check if device is native mobile (Android or iOS)
--- @function helper.is_mobile
+---@return boolean Is mobile
--- @treturn boolean Is mobile
 function M.is_mobile()
-	return const.CURRENT_SYSTEM_NAME == const.OS.IOS or
+	local sys_name = const.CURRENT_SYSTEM_NAME
-			 const.CURRENT_SYSTEM_NAME == const.OS.ANDROID
+	return sys_name == const.OS.IOS or sys_name == const.OS.ANDROID
 end
 
 
 ---Check if device is HTML5
--- @function helper.is_web
+---@return boolean
--- @treturn boolean Is web
 function M.is_web()
 	return const.CURRENT_SYSTEM_NAME == const.OS.BROWSER
 end
 
 
 ---Check if device is HTML5 mobile
--- @function helper.is_web_mobile
+---@return boolean
--- @treturn boolean Is web mobile
 function M.is_web_mobile()
 	if html5 then
 		return html5.run("(typeof window.orientation !== 'undefined') || (navigator.userAgent.indexOf('IEMobile') !== -1);") == "true"
@@ -391,17 +382,15 @@ end
 
 
 ---Check if device is mobile and can support multitouch
--- @function helper.is_multitouch_supported
+---@return boolean is_multitouch Is multitouch supported
--- @treturn boolean Is multitouch supported
 function M.is_multitouch_supported()
 	return M.is_mobile() or M.is_web_mobile()
 end
 
 
 ---Simple table to one-line string converter
--- @function helper.table_to_string
+---@param t table
--- @tparam table t
+---@return string
--- @treturn string
 function M.table_to_string(t)
 	if not t then
 		return ""
@@ -421,10 +410,9 @@ end
 
 
 ---Distance from node position to his borders
--- @function helper.get_border
+---@param node node GUI node
--- @tparam node node GUI node
+---@param offset vector3|nil Offset from node position. Pass current node position to get non relative border values
--- @tparam vector3|nil offset Offset from node position. Pass current node position to get non relative border values
+---@return vector4 border Vector4 with border values (left, top, right, down)
--- @treturn vector4 Vector4 with border values (left, top, right, down)
 function M.get_border(node, offset)
 	local pivot = gui.get_pivot(node)
 	local pivot_offset = M.get_pivot_offset(pivot)
@@ -448,16 +436,8 @@ end
 
 
 ---Get text metric from GUI node.
--- @function helper.get_text_metrics_from_node
+---@param text_node node
--- @tparam node text_node
+---@return GUITextMetrics
--- @treturn GUITextMetrics
--- @usage
--- type GUITextMetrics = {
---   width: number,
---   height: number,
---   max_ascent: number,
---   max_descent: number
--- }
 function M.get_text_metrics_from_node(text_node)
 	local font_resource = gui.get_font_resource(gui.get_font(text_node))
 	local options = {
@@ -476,14 +456,12 @@ end
 
 
 ---Add value to array with shift policy
---
 -- Shift policy can be: left, right, no_shift
--- @function helper.insert_with_shift
+---@param array table Array
--- @tparam table array Array
+---@param item any Item to insert
--- @param any Item to insert
+---@param index number|nil Index to insert. If nil, item will be inserted at the end of array
--- @tparam number|nil index Index to insert. If nil, item will be inserted at the end of array
+---@param shift_policy number|nil The druid_const.SHIFT.* constant
--- @tparam number|nil shift_policy The druid_const.SHIFT.* constant
+---@return any Inserted item
--- @treturn any Inserted item
 function M.insert_with_shift(array, item, index, shift_policy)
 	shift_policy = shift_policy or const.SHIFT.RIGHT
 
@@ -510,11 +488,10 @@ end
 ---Remove value from array with shift policy
 --
 -- Shift policy can be: left, right, no_shift
--- @function helper.remove_with_shift
+---@param array any[] Array
--- @tparam table array Array
+---@param index number|nil Index to remove. If nil, item will be removed from the end of array
--- @tparam number|nil index Index to remove. If nil, item will be removed from the end of array
+---@param shift_policy number|nil  The druid_const.SHIFT.* constant
--- @tparam number|nil shift_policy The druid_const.SHIFT.* constant
+---@return any Removed item
--- @treturn any Removed item
 function M.remove_with_shift(array, index, shift_policy)
 	shift_policy = shift_policy or const.SHIFT.RIGHT
 
@@ -539,11 +516,10 @@ function M.remove_with_shift(array, index, shift_policy)
 end
 
 
---- Show deprecated message. Once time per message
--- @function helper.deprecated
--- @tparam string message The deprecated message
--- @local
 local _deprecated_messages = {}
+
+---Show deprecated message. Once time per message
+---@param message string The deprecated message
 function M.deprecated(message)
 	if _deprecated_messages[message] then
 		return
@@ -555,7 +531,8 @@ end
 
 
 ---Show message to require component
--- @local
+---@param component_name string
+---@param component_type string
 function M.require_component_message(component_name, component_type)
 	component_type = component_type or "extended"
 

druid/system/druid_instance.lua

@@ -163,7 +163,9 @@ end
 
 local WIDGET_METATABLE = { __index = base_component }
 
--- Create the Druid component instance
+---Create the Druid component instance
+---@param self druid_instance
+---@param widget_class druid.base_component
 local function create_widget(self, widget_class)
 	local instance = setmetatable({}, {
 		__index = setmetatable(widget_class, WIDGET_METATABLE)
@@ -206,7 +208,9 @@ local function create_widget(self, widget_class)
 end
 
 
--- Before processing any input check if we need to update input stack
+---Before processing any input check if we need to update input stack
+---@param self druid_instance
+---@param components table[]
 local function check_sort_input_stack(self, components)
 	if not components or #components == 0 then
 		return