diff --git a/druid/annotations.lua b/druid/annotations.lua index 159a221..4312422 100644 --- a/druid/annotations.lua +++ b/druid/annotations.lua @@ -42,8 +42,8 @@ function druid.set_text_function(callback) end ---@class druid.back_handler : druid.base_component ----@field on_back druid.event @{DruidEvent} function(self, [params]) . ----@field params any Params to pass in the callback +---@field on_back druid.event @{DruidEvent} Event on back handler action. +---@field params any Custom args to pass in the callback local druid__back_handler = {} @@ -147,15 +147,21 @@ function druid__base_component.component:set_template(self, template) end ---@class druid.blocker : druid.base_component ----@field node node Trigger node +---@field node node Blocker node local druid__blocker = {} +--- @{Blocker} constructor +---@param self druid.blocker @{Blocker} +---@param node node Gui node +function druid__blocker.init(self, node) end + --- Return blocker enabled state ---@param self druid.blocker @{Blocker} ---@return bool True, if blocker is enabled function druid__blocker.is_enabled(self) end ---- Set enabled blocker component state +--- Set enabled blocker component state. +--- Don't change node enabled state. ---@param self druid.blocker @{Blocker} ---@param state bool Enabled state function druid__blocker.set_enabled(self, state) end @@ -164,9 +170,9 @@ function druid__blocker.set_enabled(self, state) end ---@class druid.button : druid.base_component ---@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 node Node Button trigger node +---@field node_id hash The GUI node id from button 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. @@ -183,15 +189,16 @@ local druid__button = {} ---@return hash The action_id of the input key function druid__button.get_key_trigger(self) end ---- Button component constructor +--- @{Button} constructor ---@param self druid.button @{Button} ----@param node node Gui node ----@param callback function Button callback ----@param params table Button callback params ----@param anim_node node Button anim node (node, if not provided) -function druid__button.init(self, node, callback, params, anim_node) end +---@param node string|Node Node name or GUI Node itself +---@param callback function On click button callback +---@param custom_args any Button events custom arguments +---@param anim_node string|Node Node to animate instead of trigger node. +function druid__button.init(self, node, callback, custom_args, anim_node) end --- Get button enabled state. +--- By default all Buttons is enabled on creating. ---@param self druid.button @{Button} ---@return bool True, if button is enabled now, False overwise function druid__button.is_enabled(self) end @@ -199,7 +206,7 @@ function druid__button.is_enabled(self) end --- Set function for additional check for button click availability ---@param self druid.button ---@param check_function function Should return true or false. If true - button can be pressed. ----@param failure_callback function Function what will be called on button click, if check function return false +---@param failure_callback function Function will be called on button click, if check function return false ---@return druid.button Current button instance function druid__button.set_check_function(self, check_function, failure_callback) end @@ -217,19 +224,19 @@ 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 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 name to trigger this button by keyboard. ---@param self druid.button @{Button} ---@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 +--- Set Button mode to work inside user HTML5 interaction event. +--- It's required to make protected things like copy & paste text, show mobile keyboard, etc The HTML5 button's doesn't call any events except on_click event. If the game is not HTML, HTML html mode will be not enabled +---@param self druid.button +---@param is_web_mode boolean If true - button will be called inside html5 callback +---@return druid.button Current button instance +function druid__button.set_web_user_interaction(self, is_web_mode) end + ---@class druid.button.style ---@field AUTOHOLD_TRIGGER field Maximum hold time to trigger button release while holding @@ -713,12 +720,12 @@ local druid__lang_text = {} ---@return druid.lang_text Current instance function druid__lang_text.format(self, a, b, c, d, e, f, g) end ---- Component init function +--- @{LangText} constructor ---@param self druid.lang_text @{LangText} ----@param node node The text node +---@param node string|node Node name or GUI Text Node itself ---@param locale_id string Default locale id or text from node as default ----@param no_adjust bool If true, will not correct text size -function druid__lang_text.init(self, node, locale_id, no_adjust) end +---@param adjust_type string Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference +function druid__lang_text.init(self, node, locale_id, adjust_type) end --- Setup raw text to lang_text component ---@param self druid.lang_text @{LangText} @@ -834,7 +841,7 @@ function druid__pin_knob.set_friction(self, value) end ---@class druid.progress : druid.base_component ----@field key string The progress bar direction +---@field key string The progress bar direction. ---@field max_size number Maximum size of progress bar ---@field node node Progress bar fill node ---@field on_change druid.event On progress bar change callback(self, new_value) @@ -856,9 +863,9 @@ function druid__progress.fill(self) end ---@param self druid.progress @{Progress} function druid__progress.get(self) end ---- Component init function +--- @{Progress} constructor ---@param self druid.progress @{Progress} ----@param node string|node Progress bar fill node or node name +---@param node string|node Node name or GUI Node itself. ---@param key string Progress bar direction: const.SIDE.X or const.SIDE.Y ---@param init_value number Initial value of progress bar function druid__progress.init(self, node, key, init_value) end @@ -1210,9 +1217,9 @@ function druid__static_grid.get_pos(self, index) end ---@return vector3 The grid content size function druid__static_grid.get_size(self) end ---- Component init function +--- @{StaticGrid} constructor ---@param self druid.static_grid @{StaticGrid} ----@param parent node The gui node parent, where items will be placed +---@param parent string|Node The GUI Node container, where grid's items will be placed ---@param element node Element prefab. Need to get it size ---@param in_row number How many nodes in row can be placed function druid__static_grid.init(self, parent, element, in_row) end @@ -1308,11 +1315,11 @@ function druid__text.get_text_adjust(self, adjust_type) end ---@return number Height function druid__text.get_text_size(self, text) end ---- Component init function +--- @{Text} constructor ---@param self druid.text @{Text} ----@param node node Gui text node +---@param node string|node Node name or GUI Text Node itself ---@param value string Initial text. Default value is node text from GUI scene. ----@param adjust_type int Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference +---@param adjust_type string Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference function druid__text.init(self, node, value, adjust_type) end --- Return true, if text with line break diff --git a/druid/base/back_handler.lua b/druid/base/back_handler.lua index 227103e..15b8de6 100644 --- a/druid/base/back_handler.lua +++ b/druid/base/back_handler.lua @@ -6,13 +6,11 @@ -- 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. +-- +-- • Back Handler react on release action ACTION_BACK or ACTION_BACKSPACE -- @usage -- local callback = function(self, params) ... end -- @@ -22,7 +20,7 @@ -- @within BaseComponent -- @alias druid.back_handler ---- @{DruidEvent} function(self, [params]) . +--- @{DruidEvent} Event on back handler action. -- -- Trigger on input action ACTION_BACK or ACTION_BACKSPACE -- @usage @@ -30,7 +28,7 @@ -- back_handler.on_back:subscribe(callback) -- @tfield DruidEvent on_back @{DruidEvent} ---- Params to pass in the callback +--- Custom args to pass in the callback -- @usage -- -- Replace params on runtime: -- back_handler.params = { ... } @@ -45,13 +43,13 @@ local component = require("druid.component") local BackHandler = component.create("back_handler") ---- Component initialize function +--- @{BackHandler} constructor -- @tparam BackHandler self @{BackHandler} -- @tparam callback callback On back button --- @tparam[opt] any params Callback argument +-- @tparam[opt] any custom_args Button events custom arguments -- @local -function BackHandler.init(self, callback, params) - self.params = params +function BackHandler.init(self, callback, custom_args) + self.params = custom_args self.on_back = Event(callback) end diff --git a/druid/base/blocker.lua b/druid/base/blocker.lua index 3c232f9..4905280 100644 --- a/druid/base/blocker.lua +++ b/druid/base/blocker.lua @@ -1,19 +1,15 @@ -- Copyright (c) 2023 Maksim Tuprikov . This code is licensed under MIT license ---- Component to block input in special zone defined by GUI node. +--- Component to consume input in special zone defined by GUI node. -- # Overview # -- --- Blocker component необходим, чтобы блокировать пользовательский ввод в определенной зоне. --- Зона задается размером ноды, на которой находится компонент. Blocker блокирует ввод только для тех --- элементов, которые находятся перед ним in input stack (созданы до него). --- --- # Tech Info # --- --- Blocker consume input if `gui.pick_node` works on it. --- -- # Notes # -- +-- Blocker consume input if `gui.pick_node` works on it. +-- -- • Blocker inheritance @{BaseComponent}, you can use all of its methods in addition to those described here. +-- +-- • Blocker initial enabled state is `gui.is_enabled(node, true)` -- @usage -- local node = gui.get_node("blocker_node") -- local blocker = self.druid:new_blocker(node) @@ -21,7 +17,7 @@ -- @within BaseComponent -- @alias druid.blocker ----Trigger node +---Blocker node -- @tfield node node --- @@ -32,12 +28,12 @@ local component = require("druid.component") local Blocker = component.create("blocker") ---- Component initialize function +--- @{Blocker} constructor -- @tparam Blocker self @{Blocker} -- @tparam node node Gui node --- @local function Blocker.init(self, node) self.node = self:get_node(node) + self._is_enabled = gui.is_enabled(node, true) end @@ -65,11 +61,13 @@ function Blocker.on_input(self, action_id, action) end ---- Set enabled blocker component state +--- Set enabled blocker component state. +-- +-- Don't change node enabled state. -- @tparam Blocker self @{Blocker} -- @tparam bool state Enabled state function Blocker.set_enabled(self, state) - gui.set_enabled(self.node, state) + self._is_enabled = state end @@ -77,7 +75,7 @@ end -- @tparam Blocker self @{Blocker} -- @treturn bool True, if blocker is enabled function Blocker.is_enabled(self) - return gui.is_enabled(self.node) + return self._is_enabled end diff --git a/druid/base/button.lua b/druid/base/button.lua index 566336b..62b85ed 100755 --- a/druid/base/button.lua +++ b/druid/base/button.lua @@ -3,7 +3,7 @@ --- 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. +-- The most generic component you can use. Set any GUI node clickable and provide different callbacks. -- -- # Notes # -- @@ -107,11 +107,11 @@ -- end) -- @tfield DruidEvent on_pressed @{DruidEvent} ---- Button clickable node --- @tfield node node +--- Button trigger node +-- @tfield Node node ---The GUI node id from button node --- @tfield node_id hash +-- @tfield hash node_id --- Button animation node. -- In default case equals to clickable node. @@ -274,8 +274,8 @@ end -- @tparam Button self @{Button} -- @tparam string|Node node Node name or GUI Node itself -- @tparam function callback On click button callback --- @tparam[opt] table custom_args Button events custom arguments --- @tparam[opt] string|Node anim_node Node to animate instead of trigger node +-- @tparam[opt] any custom_args Button events custom arguments +-- @tparam[opt] string|Node anim_node Node to animate instead of trigger node. function Button.init(self, node, callback, custom_args, anim_node) self.druid = self:get_druid() self.node = self:get_node(node) diff --git a/druid/base/scroll.lua b/druid/base/scroll.lua index 3850e12..39c3b6b 100755 --- a/druid/base/scroll.lua +++ b/druid/base/scroll.lua @@ -1,12 +1,30 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Component to handle scroll content. +-- # Overview # +-- -- Scroll consist from two nodes: scroll parent and scroll input -- Scroll input the user input zone, it's static -- Scroll parent the scroll moving part, it will change position. -- Setup initial scroll size by changing scroll parent size. If scroll parent --- size will be less than scroll_input size, no scroll is available. For scroll --- parent size should be more than input size +-- size will be less than scroll_input size, no scroll is available. +-- +-- # Notes # +-- +-- • Scroll by default style have inertion and extra size for strecthing effect. +-- It can be adjust via scroll style settings +-- +-- • You can setup "points of interest". Scroll always will be centered on closes point of interest. +-- It is able to create slider without inertion and points of interest on each scroll element. +-- +-- • You can adjust scroll content size by `scroll:set_size(node_size)`. +-- It will setup new size to _content node_ +-- +-- • You can enabled or disable inertion mode via `scroll:set_inert(state)` +-- +-- • You can adjust extra stretch size via `scroll:set_extra_stretch_size` +-- +-- • Multitouch is required for scroll. Scroll is correctly handling touch_id swap while dragging scroll -- @module Scroll -- @within BaseComponent -- @alias druid.scroll @@ -132,10 +150,10 @@ function Scroll.on_style_change(self, style) end ---- Scroll constructor +--- @{Scroll} constructor -- @tparam Scroll self @{Scroll} --- @tparam node view_node GUI view scroll node --- @tparam node content_node GUI content scroll node +-- @tparam string|node view_node GUI view scroll node +-- @tparam string|node content_node GUI content scroll node function Scroll.init(self, view_node, content_node) self.druid = self:get_druid() diff --git a/druid/base/static_grid.lua b/druid/base/static_grid.lua index 93e4e86..938f604 100644 --- a/druid/base/static_grid.lua +++ b/druid/base/static_grid.lua @@ -1,7 +1,27 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license ---- Component to handle placing components by row and columns. --- Grid can anchor your elements, get content size and other +--- Component to handle component's position by row and columns. +-- # Overview # +-- +-- # Notes # +-- +-- • Static grid have constant node size, so it possible to calculate node positions before placement. Nodes can be placed with gaps. +-- +-- • Static grid can shift elements on add/remove functions. +-- +-- • On _add node_ grid will set node parent to _parent_node_ +-- +-- • You can get array of position of every element for setup points of interest in scroll component +-- +-- • You can get size of all elements for setup size in scroll component +-- +-- • You can bind the grid to the scroll component for auto resize scroll content size +-- +-- • Pivot of parent_node matter for node placement +-- +-- • Prefab node used to get node size and anchor +-- +-- • You can point *position_function* for animations with _static_grid:set_position_function(node, pos)_ callback. Default - *gui.set_position()* -- @module StaticGrid -- @within BaseComponent -- @alias druid.static_grid @@ -81,9 +101,9 @@ function StaticGrid.on_style_change(self, style) end ---- Component init function +--- @{StaticGrid} constructor -- @tparam StaticGrid self @{StaticGrid} --- @tparam node parent The gui node parent, where items will be placed +-- @tparam string|Node parent The GUI Node container, where grid's 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 function StaticGrid.init(self, parent, element, in_row) diff --git a/druid/base/text.lua b/druid/base/text.lua index 286295f..be74cd8 100755 --- a/druid/base/text.lua +++ b/druid/base/text.lua @@ -1,8 +1,29 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license ---- Component to handle all GUI texts. --- Druid Text adjust itself for text node size --- Text will never will be outside of his text size (even multiline) +--- Component to wrap over GUI Text nodes. +-- # Overview # +-- +-- Druid Text provide different adjust modes. Text will be scaled down to fit into Text Node area size. +-- +-- # Notes # +-- +-- • Text pivot can be changed with `text:set_pivot`. The anchoring will be inside text node area size. +-- +-- • There is several text adjust types. Default DOWNSCALE. You can change the default adjust type in the Text style. See all adjust types in example here. +-- +-- - const.TEXT_ADJUST.DOWNSCALE - Change text's scale to fit into the text node size +-- +-- - const.TEXT_ADJUST.TRIM - Trim the text with postfix (default - "...", override in styles) to fit in the text node size +-- +-- - const.TEXT_ADJUST.NO_ADJUST - No any adjust, like default Defold Text Node +-- +-- - const.TEXT_ADJUST.DOWNSCALE_LIMITED - Change text's scale list downscale, but there is limit for text's scale. +-- Set minimal scale with `text:set_minimal_scale()` function. +-- +-- - const.TEXT_ADJUST.SCROLL - Change text's pivot to imitate scrolling in the text box. Use with stencil node for better effect. +-- +-- - const.TEXT_ADJUST.SCALE_THEN_SCROLL - Combine two modes: first limited downscale, then scroll +-- -- @module Text -- @within BaseComponent -- @alias druid.text @@ -188,11 +209,11 @@ function Text.on_style_change(self, style) end ---- Component init function +--- @{Text} constructor -- @tparam Text self @{Text} --- @tparam node node Gui text node +-- @tparam string|node node Node name or GUI Text Node itself -- @tparam[opt] string value Initial text. Default value is node text from GUI scene. --- @tparam[opt=0] int adjust_type Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference +-- @tparam[opt=downscale] string adjust_type Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference function Text.init(self, node, value, adjust_type) self.node = self:get_node(node) self.pos = gui.get_position(self.node) diff --git a/druid/const.lua b/druid/const.lua index aedd768..87013a1 100755 --- a/druid/const.lua +++ b/druid/const.lua @@ -52,7 +52,6 @@ M.MESSAGE_INPUT = { BUTTON_LONG_CLICK = "button_long_click", BUTTON_DOUBLE_CLICK = "button_double_click", BUTTON_REPEATED_CLICK = "button_repeated_click", - -- (value) TEXT_SET = "text_set", } diff --git a/druid/extended/lang_text.lua b/druid/extended/lang_text.lua index f30b48a..5be7f6e 100755 --- a/druid/extended/lang_text.lua +++ b/druid/extended/lang_text.lua @@ -1,7 +1,15 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license ---- Component to handle all GUI texts --- Good working with localization system +--- Component to wrap over GUI Text nodes with localization helpers +-- +-- # Overview # +-- +-- • The `druid.set_text_function` should be inited to get the localization by localization_id +-- +-- • The LangText supports up to 7 string format params, due the some issues with `...` args. +-- +-- # Notes # +-- -- @module LangText -- @within BaseComponent -- @alias druid.lang_text @@ -21,14 +29,14 @@ local component = require("druid.component") local LangText = component.create("lang_text") ---- Component init function +--- @{LangText} constructor -- @tparam LangText self @{LangText} --- @tparam node node The text node +-- @tparam string|node node Node name or GUI Text Node itself -- @tparam string locale_id Default locale id or text from node as default --- @tparam bool no_adjust If true, will not correct text size -function LangText.init(self, node, locale_id, no_adjust) +-- @tparam[opt=downscale] string adjust_type Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference +function LangText.init(self, node, locale_id, adjust_type) self.druid = self:get_druid() - self.text = self.druid:new_text(node, locale_id, no_adjust) + self.text = self.druid:new_text(node, locale_id, adjust_type) self.node = self.text.node self.last_locale_args = {} diff --git a/druid/extended/progress.lua b/druid/extended/progress.lua index ed08326..227e9f3 100644 --- a/druid/extended/progress.lua +++ b/druid/extended/progress.lua @@ -1,7 +1,18 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license ---- Basic progress bar component. --- For correct progress bar init it should be in max size from gui +--- Druid component to handle the progress bars. +-- # Overview # +-- +-- # Notes # +-- +-- • Progress Node should be fully filled in your GUI scene node. It will be the progress maximum size +-- +-- • Progress correct working with Slice9 nodes, it trying to set size by _set_size_ first, if it is not possible, it set up sizing via _set_scale_ +-- +-- • Progress bar can fill only by vertical or horizontal size. If you want make diagonal progress bar, just rotate node in GUI scene +-- +-- • If you have glitchy or dark texture bug with progress bar, try to disable mipmaps in your texture profiles +-- -- @module Progress -- @within BaseComponent -- @alias druid.progress @@ -12,7 +23,9 @@ --- Progress bar fill node -- @tfield node node ---- The progress bar direction +--- The progress bar direction. +-- +-- The values are: "x" or "y". (const.SIDE.X or const.SIDE.Y) -- @tfield string key --- Current progress bar scale @@ -95,16 +108,16 @@ function Progress.on_style_change(self, style) end ---- Component init function +--- @{Progress} constructor -- @tparam Progress self @{Progress} --- @tparam string|node node Progress bar fill node or node name +-- @tparam string|node node Node name or GUI Node itself. -- @tparam string key Progress bar direction: const.SIDE.X or const.SIDE.Y -- @tparam[opt=1] number init_value Initial value of progress bar function Progress.init(self, node, key, init_value) assert(key == const.SIDE.X or const.SIDE.Y, "Progress bar key should be 'x' or 'y'") - self.prop = hash("scale."..key) self.key = key + self.prop = hash("scale." .. self.key) self._init_value = init_value or 1 self.node = self:get_node(node) @@ -114,7 +127,7 @@ function Progress.init(self, node, key, init_value) self.slice = gui.get_slice9(self.node) self.last_value = self._init_value - if key == const.SIDE.X then + if self.key == const.SIDE.X then self.slice_size = self.slice.x + self.slice.z else self.slice_size = self.slice.y + self.slice.w