From 72cf310d6c3c71dab8ba80546761be4a2a36a83f Mon Sep 17 00:00:00 2001 From: Insality Date: Wed, 30 Oct 2024 23:37:43 +0200 Subject: [PATCH] Update --- druid/druid.lua | 55 ++---------------- druid/event.lua | 93 +++++++++---------------------- druid/helper.lua | 99 +++++++++++++-------------------- druid/system/druid_instance.lua | 8 ++- 4 files changed, 74 insertions(+), 181 deletions(-) diff --git a/druid/druid.lua b/druid/druid.lua index b198728..f933afa 100644 --- a/druid/druid.lua +++ b/druid/druid.lua @@ -1,53 +1,6 @@ --- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license - ---- Druid UI Component Framework. --- # Overview # --- --- 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. --- --- # Notes # --- --- • 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. ----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. +---Register component just makes the druid:new_{name} function. +---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 require in every file. ---@param name string Module name ---@param module table Lua table with component function M.register(name, module) diff --git a/druid/event.lua b/druid/event.lua index 395172b..fab7026 100644 --- a/druid/event.lua +++ b/druid/event.lua @@ -1,15 +1,6 @@ --- Copyright (c) 2021 Maksim Tuprikov . 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 --- @tparam function|nil callback Subscribe the callback on new event, if callback exist --- @tparam any|nil callback_context Additional context as first param to callback call --- @usage --- local Event = require("druid.event") --- ... --- local event = Event(callback) +--- Return new event instance +---@param callback fun()|nil Subscribe the callback on new event, if callback exist +---@param callback_context any|nil Additional context as first param to callback call +---@return druid.event +---@nodiscard function M.create(callback, callback_context) local instance = setmetatable({}, EVENT_METATABLE) @@ -40,9 +29,8 @@ end --- Check is event subscribed. --- @tparam DruidEvent self DruidEvent --- @tparam function callback Callback itself --- @tparam any|nil callback_context Additional context as first param to callback call +---@param callback fun() Callback itself +---@param callback_context any|nil 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 @@ -60,18 +48,10 @@ function M:is_subscribed(callback, callback_context) end ---- Subscribe callback on event --- @tparam DruidEvent self DruidEvent --- @tparam function callback Callback itself --- @tparam any|nil callback_context Additional context as first param to callback call, usually it's self --- @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) +---Subscribe callback on event +---@param callback fun() Callback itself +---@param callback_context any|nil Additional context as first param to callback call, usually it's self +---@return boolean 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") @@ -85,16 +65,10 @@ function M:subscribe(callback, callback_context) end ---- Unsubscribe callback on event --- @tparam DruidEvent self DruidEvent --- @tparam function callback Callback itself --- @tparam any|nil callback_context Additional context as first param to callback call --- @usage --- local function on_long_callback(self) --- print("Long click!") --- end --- ... --- button.on_long_click:unsubscribe(on_long_callback, self) +---Unsubscribe callback on event +---@param callback fun() Callback itself +---@param callback_context any|nil Additional context as first param to callback call +---@return boolean function M:unsubscribe(callback, callback_context) assert(callback, "A function must be passed to subscribe to an event") @@ -108,30 +82,21 @@ function M:unsubscribe(callback, callback_context) end ---- Return true, if event have at lease one handler --- @tparam DruidEvent self DruidEvent --- @treturn boolean True if event have handlers --- @usage --- local is_long_click_handler_exists = button.on_long_click:is_exist() +---Return true, if event have at lease one handler +---@return boolean function M:is_exist() return #self > 0 end ---- Return true, if event not have handler ---- @tparam DruidEvent self DruidEvent ---- @treturn boolean True if event not have handlers ---- @usage ---- local is_long_click_handler_not_exists = button.on_long_click:is_empty() +---Return true, if event not have handler +---@return boolean True if event not have handlers function M:is_empty() return #self == 0 end ---- Clear the all event handlers --- @tparam DruidEvent self DruidEvent --- @usage --- button.on_long_click:clear() +---Clear the all event handlers 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 --- @tparam any ... All event params --- @usage --- local Event = require("druid.event") --- ... --- local event = Event() --- event:trigger("Param1", "Param2") +---@param ... any All event params +---@return any result Last returned value from subscribers function M:trigger(...) if #self == 0 then return @@ -163,10 +123,9 @@ function M:trigger(...) end --- @tparam table callback Callback data {function, context} --- @tparam any ... All event params --- @treturn any Result of the callback --- @local +---@param callback table Callback data {function, context} +---@param ... any All event params +---@return any result Result of the callback function M:call_callback(callback, ...) local event_callback = callback[1] local event_callback_context = callback[2] diff --git a/druid/helper.lua b/druid/helper.lua index 1cf3c38..8d54cee 100644 --- a/druid/helper.lua +++ b/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) @@ -362,26 +356,23 @@ function M.get_pivot_offset(pivot_or_node) end ---- Check if device is native mobile (Android or iOS) --- @function helper.is_mobile --- @treturn boolean Is mobile +---Check if device is native mobile (Android or iOS) +---@return boolean Is mobile function M.is_mobile() - return const.CURRENT_SYSTEM_NAME == const.OS.IOS or - const.CURRENT_SYSTEM_NAME == const.OS.ANDROID + local sys_name = const.CURRENT_SYSTEM_NAME + return sys_name == const.OS.IOS or sys_name == const.OS.ANDROID end ---- Check if device is HTML5 --- @function helper.is_web --- @treturn boolean Is web +---Check if device is HTML5 +---@return boolean function M.is_web() return const.CURRENT_SYSTEM_NAME == const.OS.BROWSER end ---- Check if device is HTML5 mobile --- @function helper.is_web_mobile --- @treturn boolean Is web mobile +---Check if device is HTML5 mobile +---@return boolean function M.is_web_mobile() if html5 then return html5.run("(typeof window.orientation !== 'undefined') || (navigator.userAgent.indexOf('IEMobile') !== -1);") == "true" @@ -390,18 +381,16 @@ function M.is_web_mobile() end ---- Check if device is mobile and can support multitouch --- @function helper.is_multitouch_supported --- @treturn boolean Is multitouch supported +---Check if device is mobile and can support multitouch +---@return boolean is_multitouch 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 --- @tparam table t --- @treturn string +---Simple table to one-line string converter +---@param t table +---@return string function M.table_to_string(t) if not t then return "" @@ -420,11 +409,10 @@ function M.table_to_string(t) end ---- Distance from node position to his borders --- @function helper.get_border --- @tparam node node GUI node --- @tparam vector3|nil offset Offset from node position. Pass current node position to get non relative border values --- @treturn vector4 Vector4 with border values (left, top, right, down) +---Distance from node position to his borders +---@param node node GUI node +---@param offset vector3|nil 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) function M.get_border(node, offset) local pivot = gui.get_pivot(node) local pivot_offset = M.get_pivot_offset(pivot) @@ -447,17 +435,9 @@ function M.get_border(node, offset) end ---- Get text metric from GUI node. --- @function helper.get_text_metrics_from_node --- @tparam node text_node --- @treturn GUITextMetrics --- @usage --- type GUITextMetrics = { --- width: number, --- height: number, --- max_ascent: number, --- max_descent: number --- } +---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 = { @@ -475,15 +455,13 @@ function M.get_text_metrics_from_node(text_node) end ---- Add value to array with shift policy --- +---Add value to array with shift policy -- Shift policy can be: left, right, no_shift --- @function helper.insert_with_shift --- @tparam table array Array --- @param any Item to insert --- @tparam number|nil index Index to insert. If nil, item will be inserted at the end of array --- @tparam number|nil shift_policy The druid_const.SHIFT.* constant --- @treturn any Inserted item +---@param array table Array +---@param item any Item to insert +---@param index number|nil Index to insert. If nil, item will be inserted at the end of array +---@param shift_policy number|nil The druid_const.SHIFT.* constant +---@return any Inserted item function M.insert_with_shift(array, item, index, shift_policy) shift_policy = shift_policy or const.SHIFT.RIGHT @@ -507,14 +485,13 @@ function M.insert_with_shift(array, item, index, shift_policy) end ---- Remove value from array with shift policy +---Remove value from array with shift policy -- -- Shift policy can be: left, right, no_shift --- @function helper.remove_with_shift --- @tparam table array Array --- @tparam number|nil index Index to remove. If nil, item will be removed from the end of array --- @tparam number|nil shift_policy The druid_const.SHIFT.* constant --- @treturn any Removed item +---@param array any[] Array +---@param index number|nil Index to remove. If nil, item will be removed from the end of array +---@param shift_policy number|nil The druid_const.SHIFT.* constant +---@return 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 @@ -554,8 +530,9 @@ function M.deprecated(message) end ---- Show message to require component --- @local +---Show message to require component +---@param component_name string +---@param component_type string function M.require_component_message(component_name, component_type) component_type = component_type or "extended" diff --git a/druid/system/druid_instance.lua b/druid/system/druid_instance.lua index 80712ca..176caff 100755 --- a/druid/system/druid_instance.lua +++ b/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