From 1bc916e187a7c0dce8cd2d4b9275b27968b3e737 Mon Sep 17 00:00:00 2001 From: Insality Date: Tue, 18 Mar 2025 21:23:30 +0200 Subject: [PATCH] Update docs --- api/components/base/component_api.md | 445 +++++++++++++++++++++++++ api/quick_api_reference.md | 47 +-- druid/base/back_handler.lua | 11 +- druid/base/blocker.lua | 13 +- druid/base/button.lua | 29 +- druid/base/drag.lua | 69 ++-- druid/base/hover.lua | 19 +- druid/base/scroll.lua | 19 +- druid/base/static_grid.lua | 73 ++-- druid/base/text.lua | 28 +- druid/custom/rich_input/rich_input.lua | 23 +- druid/custom/rich_text/rich_text.lua | 34 +- druid/druid.lua | 1 + druid/extended/container.lua | 79 +++-- druid/extended/data_list.lua | 73 ++-- druid/extended/hotkey.lua | 23 +- druid/extended/input.lua | 36 +- druid/extended/lang_text.lua | 19 +- druid/extended/layout.lua | 59 ++-- druid/extended/progress.lua | 40 ++- druid/extended/slider.lua | 44 ++- druid/extended/swipe.lua | 29 +- druid/extended/timer.lua | 29 +- druid/helper.lua | 4 +- druid/system/druid_instance.lua | 71 ++-- 25 files changed, 937 insertions(+), 380 deletions(-) create mode 100644 api/components/base/component_api.md diff --git a/api/components/base/component_api.md b/api/components/base/component_api.md new file mode 100644 index 0000000..4501b2b --- /dev/null +++ b/api/components/base/component_api.md @@ -0,0 +1,445 @@ +# druid.component API + +> at /druid/component.lua + + +## Functions +- [create](#create) +- [create_widget](#create_widget) + +- [init](#init) +- [update](#update) +- [on_remove](#on_remove) +- [on_input](#on_input) +- [on_input_interrupt](#on_input_interrupt) +- [on_message](#on_message) +- [on_late_init](#on_late_init) +- [on_focus_lost](#on_focus_lost) +- [on_focus_gained](#on_focus_gained) +- [on_style_change](#on_style_change) +- [on_layout_change](#on_layout_change) +- [on_window_resized](#on_window_resized) +- [on_language_change](#on_language_change) +- [set_style](#set_style) +- [set_template](#set_template) +- [get_template](#get_template) +- [set_nodes](#set_nodes) +- [get_context](#get_context) +- [get_node](#get_node) +- [get_druid](#get_druid) +- [get_name](#get_name) +- [get_parent_name](#get_parent_name) +- [get_input_priority](#get_input_priority) +- [set_input_priority](#set_input_priority) +- [reset_input_priority](#reset_input_priority) +- [get_uid](#get_uid) +- [set_input_enabled](#set_input_enabled) +- [get_input_enabled](#get_input_enabled) +- [get_parent_component](#get_parent_component) +- [get_nodes](#get_nodes) +- [get_childrens](#get_childrens) + + +## Fields +- [druid](#druid) + + + +### create + +--- +```lua +component.create([name], [input_priority]) +``` + +Сreate a new component class, which will inherit from the base Druid component. + +- **Parameters:** + - `[name]` *(string|nil)*: The name of the component + - `[input_priority]` *(number|nil)*: The input priority. The bigger number processed first. Default value: 10 + +- **Returns:** + - `` *(druid.component)*: + +### create_widget + +--- +```lua +component.create_widget(self, widget_class, context) +``` + +Create the Druid component instance + +- **Parameters:** + - `self` *(druid.instance)*: The Druid Factory used to create components + - `widget_class` *(druid.widget)*: + - `context` *(table)*: + +- **Returns:** + - `` *(druid.widget)*: + +### init + +--- +```lua +component:init() +``` + +Called when component is created + +### update + +--- +```lua +component:update() +``` + +Called every frame + +### on_remove + +--- +```lua +component:on_remove() +``` + +Called when component is removed + +### on_input + +--- +```lua +component:on_input() +``` + +Called when input event is triggered + +### on_input_interrupt + +--- +```lua +component:on_input_interrupt() +``` + +Called when input event is consumed before + +### on_message + +--- +```lua +component:on_message() +``` + +Called when message is received + +### on_late_init + +--- +```lua +component:on_late_init() +``` + +Called before update once time after GUI init + +### on_focus_lost + +--- +```lua +component:on_focus_lost() +``` + +Called when app lost focus + +### on_focus_gained + +--- +```lua +component:on_focus_gained() +``` + +Called when app gained focus + +### on_style_change + +--- +```lua +component:on_style_change() +``` + +Called when style is changed + +### on_layout_change + +--- +```lua +component:on_layout_change() +``` + +Called when GUI layout is changed + +### on_window_resized + +--- +```lua +component:on_window_resized() +``` + +Called when window is resized + +### on_language_change + +--- +```lua +component:on_language_change() +``` + +Called when language is changed + +### set_style + +--- +```lua +component:set_style([druid_style]) +``` + +Set component style. Pass nil to clear style + +- **Parameters:** + - `[druid_style]` *(table|nil)*: + +- **Returns:** + - `self` *()*: The component itself for chaining + +### set_template + +--- +```lua +component:set_template([template]) +``` + +Set component template name. Pass nil to clear template. +This template id used to access nodes inside the template on GUI scene. +Parent template will be added automatically if exist. + +- **Parameters:** + - `[template]` *(string|nil)*: + +- **Returns:** + - `self` *()*: The component itself for chaining + +### get_template + +--- +```lua +component:get_template() +``` + +Get full template name. + +- **Returns:** + - `` *(string)*: + +### set_nodes + +--- +```lua +component:set_nodes(nodes) +``` + +Set current component nodes, returned from `gui.clone_tree` function. + +- **Parameters:** + - `nodes` *(table)*: + +- **Returns:** + - `` *(druid.component)*: + +### get_context + +--- +```lua +component:get_context() +``` + +Return current component context + +- **Returns:** + - `context` *(any)*: Usually it's self of script but can be any other Druid component + +### get_node + +--- +```lua +component:get_node(node_id) +``` + +Get component node by node_id. Respect to current template and nodes. + +- **Parameters:** + - `node_id` *(string|node)*: + +- **Returns:** + - `` *(node)*: + +### get_druid + +--- +```lua +component:get_druid([template], [nodes]) +``` + +Get Druid instance for inner component creation. + +- **Parameters:** + - `[template]` *(string|nil)*: + - `[nodes]` *(table|nil)*: + +- **Returns:** + - `` *(druid.instance)*: + +### get_name + +--- +```lua +component:get_name() +``` + +Get component name + +- **Returns:** + - `name` *(string)*: The component name + uid + +### get_parent_name + +--- +```lua +component:get_parent_name() +``` + +Get parent component name + +- **Returns:** + - `parent_name` *(string|nil)*: The parent component name if exist or nil + +### get_input_priority + +--- +```lua +component:get_input_priority() +``` + +Get component input priority, the bigger number processed first. Default value: 10 + +- **Returns:** + - `` *(number)*: + +### set_input_priority + +--- +```lua +component:set_input_priority(value, [is_temporary]) +``` + +Set component input priority, the bigger number processed first. Default value: 10 + +- **Parameters:** + - `value` *(number)*: + - `[is_temporary]` *(boolean|nil)*: If true, the reset input priority will return to previous value + +- **Returns:** + - `self` *(druid.component)*: The component itself for chaining + +### reset_input_priority + +--- +```lua +component:reset_input_priority() +``` + +Reset component input priority to it's default value, that was set in `create` function or `set_input_priority` + +- **Returns:** + - `self` *(druid.component)*: The component itself for chaining + +### get_uid + +--- +```lua +component:get_uid() +``` + +Get component UID, unique identifier created in component creation order. + +- **Returns:** + - `uid` *(number)*: The component uid + +### set_input_enabled + +--- +```lua +component:set_input_enabled(state) +``` + +Set component input state. By default it's enabled. +If input is disabled, the component will not receive input events. +Recursive for all children components. + +- **Parameters:** + - `state` *(boolean)*: + +- **Returns:** + - `self` *(druid.component)*: The component itself for chaining + +### get_input_enabled + +--- +```lua +component:get_input_enabled() +``` + +Get component input state. By default it's enabled. Can be disabled by `set_input_enabled` function. + +- **Returns:** + - `` *(boolean)*: + +### get_parent_component + +--- +```lua +component:get_parent_component() +``` + +Get parent component + +- **Returns:** + - `parent_component` *(druid.component|nil)*: The parent component if exist or nil + +### get_nodes + +--- +```lua +component:get_nodes() +``` + +Get current component nodes + +- **Returns:** + - `` *(table|nil)*: + +### get_childrens + +--- +```lua +component:get_childrens() +``` + +Return all children components, recursive + +- **Returns:** + - `Array` *(table)*: of childrens if the Druid component instance + + +## Fields + +- **druid** (_druid.instance_): Druid instance to create inner components + diff --git a/api/quick_api_reference.md b/api/quick_api_reference.md index b306acd..479b850 100644 --- a/api/quick_api_reference.md +++ b/api/quick_api_reference.md @@ -28,7 +28,8 @@ # API Reference -## Druid +## [Druid](druid_api.md) + ```lua local druid = require("druid.druid") @@ -42,7 +43,7 @@ druid.set_text_function(callback) self.druid = druid.new(context, [style]) ``` -## Druid Instance +## [Druid Instance](druid_instance_api.md) ```lua -- Lifecycle self.druid:final() @@ -82,7 +83,7 @@ self.druid:set_whitelist(whitelist_components) ## Components -### Base Component +### [Base Component](components/base/component_api.md) Basic methods for all components. @@ -103,7 +104,7 @@ component:set_style([druid_style]) component:set_template([template]) ``` -### Blocker +### [Blocker](components/base/blocker_api.md) ```lua local blocker = self.druid:new_blocker(node) @@ -112,7 +113,7 @@ blocker:is_enabled() blocker:set_enabled(state) ``` -### Button +### [Button](components/base/button_api.md) ```lua local button = self.druid:new_button(node, [callback], [params], [anim_node]) @@ -126,7 +127,7 @@ button:set_key_trigger(key) button:set_web_user_interaction([is_web_mode]) ``` -### Container +### [Container](components/extended/container_api.md) ```lua local container = self.druid:new_container(node, [mode], [callback]) @@ -153,7 +154,7 @@ container:set_size([width], [height], [anchor_pivot]) container:update_child_containers() ``` -### Data List +### [Data List](components/extended/data_list_api.md) ```lua local data_list = self.druid:new_data_list(druid_scroll, druid_grid, create_function) @@ -171,7 +172,7 @@ data_list:set_data(data) data_list:set_use_cache(is_use_cache) ``` -### Drag +### [Drag](components/base/drag_api.md) ```lua local drag = self.druid:new_drag(node, [on_drag_callback]) @@ -183,7 +184,7 @@ drag:set_drag_cursors(is_enabled) drag:set_enabled(is_enabled) ``` -### Grid +### [Grid](components/base/static_grid_api.md) ```lua local grid = self.druid:new_grid(parent_node, item, [in_row]) @@ -209,7 +210,7 @@ grid:set_position_function(callback) grid:sort_nodes(comparator) ``` -### Hotkey +### [Hotkey](components/extended/hotkey_api.md) ```lua local hotkey = self.druid:new_hotkey(keys_array, [callback], [callback_argument]) @@ -220,7 +221,7 @@ hotkey:on_focus_gained() hotkey:set_repeat(is_enabled_repeated) ``` -### Hover +### [Hover](components/base/hover_api.md) ```lua local hover = self.druid:new_hover(node, [on_hover_callback], [on_mouse_hover_callback]) @@ -234,7 +235,7 @@ hover:set_hover([state]) hover:set_mouse_hover([state]) ``` -### Input +### [Input](components/extended/input_api.md) ```lua local input = self.druid:new_input(click_node, text_node, [keyboard_type]) @@ -253,7 +254,7 @@ input:set_text(input_text) input:unselect() ``` -### Lang Text +### [Lang Text](components/extended/lang_text_api.md) ```lua local lang_text = self.druid:new_lang_text(node, [locale_id], [adjust_type]) @@ -265,7 +266,7 @@ lang_text:set_to(text) lang_text:translate(locale_id, [a], [b], [c], [d], [e], [f], [g]) ``` -### Layout +### [Layout](components/extended/layout_api.md) ```lua local layout = self.druid:new_layout(node, [mode]) @@ -290,7 +291,7 @@ layout:set_type(type) layout:update() ``` -### Progress +### [Progress](components/extended/progress_api.md) ```lua local progress = self.druid:new_progress(node, key, [init_value]) @@ -305,7 +306,7 @@ progress:to(to, [callback]) progress:update([dt]) ``` -### Rich Input +### [Rich Input](components/custom/rich_input_api.md) ```lua local rich_input = self.druid:new_rich_input(template, [nodes]) @@ -318,7 +319,7 @@ rich_input:set_placeholder(placeholder_text) rich_input:set_text(text) ``` -### Rich Text +### [Rich Text](components/custom/rich_text_api.md) ```lua local rich_text = self.druid:new_rich_text(text_node, [value]) @@ -332,7 +333,7 @@ rich_text:set_text([text]) rich_text:tagged(tag) ``` -### Scroll +### [Scroll](components/base/scroll_api.md) ```lua local scroll = self.druid:new_scroll(view_node, content_node) @@ -357,7 +358,7 @@ scroll:update([dt]) scroll:update_view_size() ``` -### Slider +### [Slider](components/extended/slider_api.md) ```lua local slider = self.druid:new_slider(pin_node, end_pos, [callback]) @@ -369,7 +370,7 @@ slider:set_input_node([input_node]) slider:set_steps(steps) ``` -### Swipe +### [Swipe](components/extended/swipe_api.md) ```lua local swipe = self.druid:new_swipe(node, [on_swipe_callback]) @@ -377,7 +378,7 @@ local swipe = self.druid:new_swipe(node, [on_swipe_callback]) swipe:set_click_zone([zone]) ``` -### Text +### [Text](components/base/text_api.md) ```lua local text = self.druid:new_text(node, [value], [no_adjust]) @@ -398,7 +399,7 @@ text:set_text_adjust([adjust_type], [minimal_scale]) text:set_to(set_to) ``` -### Timer +### [Timer](components/extended/timer_api.md) ```lua local timer = self.druid:new_timer(node, [seconds_from], [seconds_to], [callback]) @@ -409,7 +410,7 @@ timer:set_to(set_to) timer:update([dt]) ``` -## Helper +## [Helper](druid_helper_api.md) ```lua local helper = require("druid.helper") diff --git a/druid/base/back_handler.lua b/druid/base/back_handler.lua index e7a5570..ff9b3e2 100644 --- a/druid/base/back_handler.lua +++ b/druid/base/back_handler.lua @@ -2,23 +2,24 @@ local event = require("event.event") local const = require("druid.const") local component = require("druid.component") +---The component that handles the back handler action, like backspace or android back button ---@class druid.back_handler: druid.component ---@field on_back event Trigger on back handler action, fun(self, params) ---@field params any|nil Custom args to pass in the callback local M = component.create("back_handler") ----@param callback function|nil ----@param params any|nil +---@param callback function|nil The callback to call when the back handler is triggered +---@param params any? Custom args to pass in the callback function M:init(callback, params) self.params = params self.on_back = event.create(callback) end ----@param action_id hash ----@param action table ----@return boolean +---@param action_id hash The action id +---@param action table The action table +---@return boolean is_consumed True if the input was consumed function M:on_input(action_id, action) if action.released and (action_id == const.ACTION_BACK or action_id == const.ACTION_BACKSPACE) then self.on_back:trigger(self:get_context(), self.params) diff --git a/druid/base/blocker.lua b/druid/base/blocker.lua index 3e536b0..9859a90 100644 --- a/druid/base/blocker.lua +++ b/druid/base/blocker.lua @@ -7,15 +7,16 @@ local component = require("druid.component") local M = component.create("blocker") ----@param node node +---@param node node|string The node to use as a blocker function M:init(node) self.node = self:get_node(node) self._is_enabled = gui.is_enabled(self.node, true) end ----@param action_id string ----@param action table +---@param action_id string The action id +---@param action table The action table +---@return boolean is_consumed True if the input was consumed function M:on_input(action_id, action) if action_id ~= const.ACTION_TOUCH and action_id ~= const.ACTION_MULTITOUCH and @@ -40,8 +41,8 @@ end ---Set blocker enabled state ----@param state boolean ----@return druid.blocker self +---@param state boolean The new enabled state +---@return druid.blocker self The blocker instance function M:set_enabled(state) self._is_enabled = state @@ -50,7 +51,7 @@ end ---Get blocker enabled state ----@return boolean +---@return boolean is_enabled True if the blocker is enabled function M:is_enabled() return self._is_enabled end diff --git a/druid/base/button.lua b/druid/base/button.lua index 120cdd6..eafe4cd 100755 --- a/druid/base/button.lua +++ b/druid/base/button.lua @@ -38,6 +38,7 @@ local component = require("druid.component") local M = component.create("button") +---The constructor for the button component ---@param node_or_node_id node|string Node name or GUI Node itself ---@param callback fun()|nil Callback on button click ---@param custom_args any|nil Custom args for any Button event @@ -76,6 +77,7 @@ function M:init(node_or_node_id, callback, custom_args, anim_node) end +---@private ---@param style druid.button.style function M:on_style_change(style) self.style = { @@ -92,7 +94,7 @@ function M:on_style_change(style) end ----@return druid.button self +---@return druid.button self The current button instance function M:set_animations_disabled() self.style.on_click = function() end self.style.on_click_disabled = function() end @@ -114,9 +116,9 @@ function M:on_late_init() end ----@param action_id hash ----@param action table ----@return boolean +---@param action_id hash The action id +---@param action table The action table +---@return boolean is_consumed True if the input was consumed function M:on_input(action_id, action) if not self:_is_input_match(action_id) then return false @@ -209,7 +211,7 @@ end ---The style.on_set_enabled will be triggered. ---Disabled button is not clickable. ---@param state boolean|nil Enabled state ----@return druid.button self +---@return druid.button self The current button instance function M:set_enabled(state) self.disabled = not state self.hover:set_enabled(state) @@ -231,7 +233,7 @@ end ---Useful to restrict click outside out stencil node or scrollable content. ---If button node placed inside stencil node, it will be automatically set to this stencil node. ---@param zone node|string|nil Gui node ----@return druid.button self +---@return druid.button self The current button instance function M:set_click_zone(zone) self.click_zone = zone and self:get_node(zone) or nil self.hover:set_click_zone(zone) @@ -242,7 +244,7 @@ end ---Set key name to trigger this button by keyboard. ---@param key hash|string The action_id of the input key. Example: "key_space" ----@return druid.button self +---@return druid.button self The current button instance function M:set_key_trigger(key) if type(key) == "string" then self.key_trigger = hash(key) @@ -264,7 +266,7 @@ end ---Set function for additional check for button click availability ---@param check_function function|nil Should return true or false. If true - button can be pressed. ---@param failure_callback function|nil Function will be called on button click, if check function return false ----@return druid.button self +---@return druid.button self The current button instance function M:set_check_function(check_function, failure_callback) self._check_function = check_function self._failure_callback = failure_callback @@ -280,7 +282,7 @@ end --- ---If the game is not HTML, html mode will be not enabled ---@param is_web_mode boolean|nil If true - button will be called inside html5 callback ----@return druid.button self +---@return druid.button self The current button instance function M:set_web_user_interaction(is_web_mode) self._is_html5_mode = not not (is_web_mode and html5) return self @@ -288,8 +290,8 @@ end ----@param action_id hash ----@return boolean +---@param action_id hash The action id +---@return boolean is_match True if the input matches the button function M:_is_input_match(action_id) if action_id == const.ACTION_TOUCH or action_id == const.ACTION_MULTITOUCH then return true @@ -303,13 +305,13 @@ function M:_is_input_match(action_id) end ----@param hover_state boolean +---@param hover_state boolean True if the hover state is active function M:_on_button_hover(hover_state) self.style.on_hover(self, self.anim_node, hover_state) end ----@param hover_state boolean +---@param hover_state boolean True if the hover state is active function M:_on_button_mouse_hover(hover_state) self.style.on_mouse_hover(self, self.anim_node, hover_state) end @@ -408,5 +410,4 @@ function M:_on_button_release() end - return M diff --git a/druid/base/drag.lua b/druid/base/drag.lua index 1c43765..f2148df 100644 --- a/druid/base/drag.lua +++ b/druid/base/drag.lua @@ -7,35 +7,37 @@ local component = require("druid.component") ---@field DRAG_DEADZONE number Distance in pixels to start dragging. Default: 10 ---@field NO_USE_SCREEN_KOEF boolean If screen aspect ratio affects on drag values. Default: false +---A component that allows you to subscribe to drag events over a node ---@class druid.drag: druid.component ----@field node node ----@field on_touch_start event ----@field on_touch_end event ----@field on_drag_start event ----@field on_drag event ----@field on_drag_end event ----@field style druid.drag.style ----@field click_zone node|nil ----@field is_touch boolean ----@field is_drag boolean ----@field can_x boolean ----@field can_y boolean ----@field dx number ----@field dy number ----@field touch_id number ----@field x number ----@field y number ----@field screen_x number ----@field screen_y number ----@field touch_start_pos vector3 ----@field private _is_enabled boolean ----@field private _x_koef number ----@field private _y_koef number +---@field node node The node to subscribe to drag events over +---@field on_touch_start event fun(self, touch) The event triggered when a touch starts +---@field on_touch_end event fun(self, touch) The event triggered when a touch ends +---@field on_drag_start event fun(self, touch) The event triggered when a drag starts +---@field on_drag event fun(self, touch) The event triggered when a drag occurs +---@field on_drag_end event fun(self, touch) The event triggered when a drag ends +---@field style druid.drag.style The style of Drag component +---@field click_zone node|nil The click zone of Drag component +---@field is_touch boolean True if a touch is active +---@field is_drag boolean True if a drag is active +---@field can_x boolean True if Drag can move horizontally +---@field can_y boolean True if Drag can move vertically +---@field dx number The horizontal drag distance +---@field dy number The vertical drag distance +---@field touch_id number The touch id +---@field x number The current x position +---@field y number The current y position +---@field screen_x number The current screen x position +---@field screen_y number The current screen y position +---@field touch_start_pos vector3 The touch start position +---@field private _is_enabled boolean True if Drag component is enabled +---@field private _x_koef number The x koef +---@field private _y_koef number The y koef local M = component.create("drag", const.PRIORITY_INPUT_HIGH) ----@param node_or_node_id node|string ----@param on_drag_callback function +---The constructor for Drag component +---@param node_or_node_id node|string The node to subscribe to drag events over +---@param on_drag_callback fun(self, touch) The callback to call when a drag occurs function M:init(node_or_node_id, on_drag_callback) self.druid = self:get_druid() self.node = self:get_node(node_or_node_id) @@ -70,7 +72,7 @@ function M:init(node_or_node_id, on_drag_callback) end ----@param style druid.drag.style +---@param style druid.drag.style The style of Drag component function M:on_style_change(style) self.style = { DRAG_DEADZONE = style.DRAG_DEADZONE or 10, @@ -80,7 +82,7 @@ end ---Set Drag component enabled state. ----@param is_enabled boolean +---@param is_enabled boolean True if Drag component is enabled function M:set_drag_cursors(is_enabled) if defos and is_enabled then self.hover.style.ON_HOVER_CURSOR = defos.CURSOR_CROSSHAIR @@ -117,8 +119,9 @@ function M:on_input_interrupt() end ----@param action_id hash ----@param action table +---@param action_id hash Action id from on_input +---@param action table Action from on_input +---@return boolean is_consumed True if the input was consumed function M:on_input(action_id, action) if action_id ~= const.ACTION_TOUCH and action_id ~= const.ACTION_MULTITOUCH then return false @@ -197,7 +200,7 @@ end ---Set Drag click zone ----@param node node|string|nil +---@param node node|string|nil Node or node id ---@return druid.drag self Current instance function M:set_click_zone(node) self.click_zone = node and self:get_node(node) or nil @@ -217,7 +220,7 @@ end ---Check if Drag component is capture input ----@return boolean +---@return boolean is_enabled True if Drag component is enabled function M:is_enabled() return self._is_enabled end @@ -263,7 +266,7 @@ function M:_end_touch(touch) end ----@param touch touch +---@param touch touch Touch action function M:_process_touch(touch) if not self.can_x then self.touch_start_pos.x = touch.x @@ -287,7 +290,7 @@ end ---@param action_id hash Action id from on_input ---@param action table Action from on_input ---@param touch_id number Touch id ----@return table|nil Touch action +---@return table|nil touch Touch action function M:_find_touch(action_id, action, touch_id) local act = helper.is_mobile() and const.ACTION_MULTITOUCH or const.ACTION_TOUCH diff --git a/druid/base/hover.lua b/druid/base/hover.lua index 43723b3..be8cc4f 100644 --- a/druid/base/hover.lua +++ b/druid/base/hover.lua @@ -7,16 +7,17 @@ local component = require("druid.component") ---@field ON_HOVER_CURSOR string|nil Mouse hover style on node hover ---@field ON_MOUSE_HOVER_CURSOR string|nil Mouse hover style on node mouse hover +---The component for handling hover events on a node ---@class druid.hover: druid.component ----@field node node ----@field on_hover event fun(self: druid.hover, is_hover: boolean) ----@field on_mouse_hover event fun(self: druid.hover, is_hover: boolean) ----@field style druid.hover.style ----@field click_zone node ----@field private _is_hovered boolean|nil ----@field private _is_mouse_hovered boolean|nil ----@field private _is_enabled boolean|nil ----@field private _is_mobile boolean +---@field node node Gui node +---@field on_hover event fun(self: druid.hover, is_hover: boolean) Hover event +---@field on_mouse_hover event fun(self: druid.hover, is_hover: boolean) Mouse hover event +---@field style druid.hover.style Style of the hover component +---@field click_zone node Click zone of the hover component +---@field private _is_hovered boolean|nil True if the node is hovered +---@field private _is_mouse_hovered boolean|nil True if the node is mouse hovered +---@field private _is_enabled boolean|nil True if the hover component is enabled +---@field private _is_mobile boolean True if the platform is mobile local M = component.create("hover") diff --git a/druid/base/scroll.lua b/druid/base/scroll.lua index 22c539b..ee46037 100755 --- a/druid/base/scroll.lua +++ b/druid/base/scroll.lua @@ -242,7 +242,7 @@ end -- It will change content gui node size ---@param size vector3 The new size for content node ---@param offset vector3|nil Offset value to set, where content is starts ----@return druid.scroll Current scroll instance +---@return druid.scroll self Current scroll instance function M:set_size(size, offset) if offset then self._offset = offset @@ -256,7 +256,7 @@ end ---Set new scroll view size in case the node size was changed. ---@param size vector3 The new size for view node ----@return druid.scroll Current scroll instance +---@return druid.scroll self Current scroll instance function M:set_view_size(size) gui.set_size(self.view_node, size) self.view_size = size @@ -267,7 +267,8 @@ function M:set_view_size(size) end ----Refresh scroll view size +---Refresh scroll view size, used when view node size is changed +---@return druid.scroll self Current scroll instance function M:update_view_size() self.view_size = helper.get_scaled_size(self.view_node) self.view_border = helper.get_border(self.view_node) @@ -281,7 +282,7 @@ end -- If disabled, scroll through points (if exist) -- If no points, just simple drag without inertion ---@param state boolean Inert scroll state ----@return druid.scroll Current scroll instance +---@return druid.scroll self Current scroll instance function M:set_inert(state) self._is_inert = state @@ -299,7 +300,7 @@ end ---Set extra size for scroll stretching -- Set 0 to disable stretching effect ---@param stretch_size number|nil Size in pixels of additional scroll area ----@return druid.scroll Current scroll instance +---@return druid.scroll self Current scroll instance function M:set_extra_stretch_size(stretch_size) self.style.EXTRA_STRETCH_SIZE = stretch_size or 0 self:_update_size() @@ -318,7 +319,7 @@ end ---Set points of interest. -- Scroll will always centered on closer points ---@param points table Array of vector3 points ----@return druid.scroll Current scroll instance +---@return druid.scroll self Current scroll instance function M:set_points(points) self.points = points @@ -334,7 +335,7 @@ end ---Lock or unlock horizontal scroll ---@param state boolean True, if horizontal scroll is enabled ----@return druid.scroll Current scroll instance +---@return druid.scroll self Current scroll instance function M:set_horizontal_scroll(state) self._is_horizontal_scroll = state self.drag.can_x = self.available_size.x > 0 and state or false @@ -344,7 +345,7 @@ end ---Lock or unlock vertical scroll ---@param state boolean True, if vertical scroll is enabled ----@return druid.scroll Current scroll instance +---@return druid.scroll self Current scroll instance function M:set_vertical_scroll(state) self._is_vertical_scroll = state self.drag.can_y = self.available_size.y > 0 and state or false @@ -395,7 +396,7 @@ end ---Bind the grid component (Static or Dynamic) to recalculate -- scroll size on grid changes ---@param grid druid.grid|nil Druid grid component ----@return druid.scroll Current scroll instance +---@return druid.scroll self Current scroll instance function M:bind_grid(grid) if self._grid_on_change then self._grid_on_change:unsubscribe(self._grid_on_change_callback) diff --git a/druid/base/static_grid.lua b/druid/base/static_grid.lua index f3aad77..5d38ced 100644 --- a/druid/base/static_grid.lua +++ b/druid/base/static_grid.lua @@ -7,25 +7,27 @@ local component = require("druid.component") ---@field IS_DYNAMIC_NODE_POSES boolean|nil If true, always center grid content as grid pivot sets. Default: false ---@field IS_ALIGN_LAST_ROW boolean|nil If true, always align last row of the grid as grid pivot sets. Default: false +---The component for manage the nodes position in the grid with various options ---@class druid.grid: druid.component ----@field on_add_item event ----@field on_remove_item event ----@field on_change_items event ----@field on_clear event ----@field on_update_positions event ----@field parent node ----@field nodes node[] ----@field first_index number ----@field last_index number ----@field anchor vector3 ----@field pivot vector3 ----@field node_size vector3 ----@field border vector4 ----@field in_row number ----@field style table +---@field on_add_item event Trigger on add item event, fun(self, item, index) +---@field on_remove_item event Trigger on remove item event, fun(self, index) +---@field on_change_items event Trigger on change items event, fun(self, index) +---@field on_clear event Trigger on clear event, fun(self) +---@field on_update_positions event Trigger on update positions event, fun(self) +---@field parent node Parent node +---@field nodes node[] Nodes array +---@field first_index number First index +---@field last_index number Last index +---@field anchor vector3 Anchor +---@field pivot vector3 Pivot +---@field node_size vector3 Node size +---@field border vector4 Border +---@field in_row number In row +---@field style druid.grid.style Style local M = component.create("grid") +---The constructor for the grid component ---@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|nil How many nodes in row can be placed. By default 1 @@ -87,9 +89,9 @@ function M:get_pos(index) end ----Return index for grid pos +---Return grid index by position ---@param pos vector3 The node position in the grid ----@return number The node index +---@return number index The node index function M:get_index(pos) -- Offset to left-top corner from node pivot local node_offset_x = self.node_size.x * (-0.5 + self.node_pivot.x) @@ -133,12 +135,18 @@ function M:set_anchor(anchor) end ----Update grid content +---Instantly update the grid content +---@return druid.grid self Current grid instance function M:refresh() self:_update(true) + + return self end +---Set grid pivot +---@param pivot constant The new pivot +---@return druid.grid self Current grid instance function M:set_pivot(pivot) local prev_pivot = helper.get_pivot_offset(gui.get_pivot(self.parent)) self.pivot = helper.get_pivot_offset(pivot) @@ -162,6 +170,8 @@ function M:set_pivot(pivot) ) self:_update(true) + + return self end @@ -170,6 +180,7 @@ end ---@param index number|nil The item position. By default add as last item ---@param shift_policy number|nil How shift nodes, if required. Default: const.SHIFT.RIGHT ---@param is_instant boolean|nil If true, update node positions instantly +---@return druid.grid self Current grid instance function M:add(item, index, shift_policy, is_instant) index = index or ((self.last_index or 0) + 1) @@ -186,12 +197,15 @@ function M:add(item, index, shift_policy, is_instant) self.on_add_item:trigger(self:get_context(), item, index) self.on_change_items:trigger(self:get_context(), index) + + return self end ---Set new items to the grid. All previous items will be removed ---@param nodes node[] The new grid nodes ---@param is_instant boolean|nil If true, update node positions instantly +---@return druid.grid self Current grid instance function M:set_items(nodes, is_instant) self.nodes = nodes for index = 1, #nodes do @@ -202,6 +216,8 @@ function M:set_items(nodes, is_instant) self:_update(is_instant) self.on_change_items:trigger(self:get_context()) + + return self end @@ -209,7 +225,7 @@ end ---@param index number The grid node index to remove ---@param shift_policy number|nil How shift nodes, if required. Default: const.SHIFT.RIGHT ---@param is_instant boolean|nil If true, update node positions instantly ----@return node The deleted gui node from grid +---@return node node The deleted gui node from grid function M:remove(index, shift_policy, is_instant) assert(self.nodes[index], "No grid item at given index " .. index) @@ -226,7 +242,7 @@ end ---Return grid content size ----@return vector3 The grid content size +---@return vector3 size The grid content size function M:get_size() return vmath.vector3( self.border.z - self.border.x, @@ -235,6 +251,9 @@ function M:get_size() end +---Return grid content size for given count of nodes +---@param count number The count of nodes +---@return vector3 size The grid content size function M:get_size_for(count) if not count or count == 0 then return vmath.vector3(0) @@ -258,14 +277,14 @@ end ---Return grid content borders ----@return vector4 The grid content borders +---@return vector4 borders The grid content borders function M:get_borders() return self.border end ---Return array of all node positions ----@return vector3[] All grid node positions +---@return vector3[] positions All grid node positions function M:get_all_pos() local result = {} for i, node in pairs(self.nodes) do @@ -279,7 +298,7 @@ end ---Change set position function for grid nodes. It will call on -- update poses on grid elements. Default: gui.set_position ---@param callback function Function on node set position ----@return druid.grid Current grid instance +---@return druid.grid self Current grid instance function M:set_position_function(callback) self._set_position_function = callback or gui.set_position @@ -289,7 +308,7 @@ end ---Clear grid nodes array. GUI nodes will be not deleted! -- If you want to delete GUI nodes, use static_grid.nodes array before grid:clear ----@return druid.grid Current grid instance +---@return druid.grid self Current grid instance function M:clear() self.border.x = 0 self.border.y = 0 @@ -307,7 +326,7 @@ end ---Return StaticGrid offset, where StaticGrid content starts. ----@return vector3 The StaticGrid offset +---@return vector3 offset The StaticGrid offset function M:get_offset() local borders = self:get_borders() local size = self:get_size() @@ -323,7 +342,7 @@ end ---Set new in_row elements for grid ---@param in_row number The new in_row value ----@return druid.grid Current grid instance +---@return druid.grid self Current grid instance function M:set_in_row(in_row) self.in_row = in_row self._grid_horizonal_offset = self.node_size.x * (self.in_row - 1) * self.anchor.x @@ -342,7 +361,7 @@ end ---Set new node size for grid ---@param width number|nil The new node width ---@param height number|nil The new node height ----@return druid.grid Current grid instance +---@return druid.grid self Current grid instance function M:set_item_size(width, height) if width then self.node_size.x = width diff --git a/druid/base/text.lua b/druid/base/text.lua index f04542c..4fe2ad6 100755 --- a/druid/base/text.lua +++ b/druid/base/text.lua @@ -11,6 +11,7 @@ local utf8 = utf8 or utf8_lua --[[@as utf8]] ---@field ADJUST_STEPS number|nil Amount of iterations for text adjust by height. Default: 20 ---@field ADJUST_SCALE_DELTA number|nil Scale step on each height adjust step. Default: 0.02 +---The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area ---@class druid.text: druid.component ---@field node node The text node ---@field on_set_text event The event triggered when the text is set, fun(self, text) @@ -19,7 +20,7 @@ local utf8 = utf8 or utf8_lua --[[@as utf8]] ---@field style druid.text.style The style of the text ---@field private start_pivot userdata The start pivot of the text ---@field private start_scale vector3 The start scale of the text ----@field private scale vector3 +---@field private scale vector3 The current scale of the text local M = component.create("text") @@ -49,7 +50,6 @@ function M:init(node, value, adjust_type) self.on_update_text_scale = event.create() self:set_text(value or gui.get_text(self.node)) - return self end @@ -64,16 +64,15 @@ function M:on_style_change(style) end - function M:on_layout_change() self:set_text(self.last_value) end ---Calculate text width with font with respect to trailing space ----@param text string|nil ----@return number Width ----@return number Height +---@param text string|nil The text to calculate the size of, if nil - use current text +---@return number width The text width +---@return number height The text height function M:get_text_size(text) text = text or self.last_value local font_name = gui.get_font(self.node) @@ -95,8 +94,8 @@ end ---Get chars count by width ----@param width number ----@return number Chars count +---@param width number The width to get the chars count of +---@return number index The chars count function M:get_text_index_by_width(width) local text = self.last_value local font_name = gui.get_font(self.node) @@ -130,7 +129,7 @@ end ---Set text to text field ---@deprecated ---@param set_to string Text for node ----@return druid.text Current text instance +---@return druid.text self Current text instance function M:set_to(set_to) set_to = tostring(set_to or "") @@ -172,7 +171,7 @@ end ---Set color ---@param color vector4 Color for node ----@return druid.text Current text instance +---@return druid.text self Current text instance function M:set_color(color) self.color = color gui.set_color(self.node, color) @@ -183,7 +182,7 @@ end ---Set alpha ---@param alpha number Alpha for node ----@return druid.text Current text instance +---@return druid.text self Current text instance function M:set_alpha(alpha) self.color.w = alpha gui.set_color(self.node, self.color) @@ -194,7 +193,7 @@ end ---Set scale ---@param scale vector3 Scale for node ----@return druid.text Current text instance +---@return druid.text self Current text instance function M:set_scale(scale) self.last_scale = scale gui.set_scale(self.node, scale) @@ -205,7 +204,7 @@ end ---Set text pivot. Text will re-anchor inside text area ---@param pivot userdata The gui.PIVOT_* constant ----@return druid.text Current text instance +---@return druid.text self Current text instance function M:set_pivot(pivot) local prev_pivot = gui.get_pivot(self.node) local prev_offset = const.PIVOTS[prev_pivot] @@ -252,7 +251,7 @@ end ---Set minimal scale for DOWNSCALE_LIMITED or SCALE_THEN_SCROLL adjust types ---@param minimal_scale number If pass nil - not use minimal scale ----@return druid.text Current text instance +---@return druid.text self Current text instance function M:set_minimal_scale(minimal_scale) self._minimal_scale = minimal_scale @@ -412,6 +411,7 @@ function M:_update_text_with_trim(trim_postfix) end end + ---@private ---@param trim_postfix string function M:_update_text_with_trim_left(trim_postfix) diff --git a/druid/custom/rich_input/rich_input.lua b/druid/custom/rich_input/rich_input.lua index cf86a53..e4d73f3 100644 --- a/druid/custom/rich_input/rich_input.lua +++ b/druid/custom/rich_input/rich_input.lua @@ -4,12 +4,13 @@ local const = require("druid.const") local utf8_lua = require("druid.system.utf8") local utf8 = utf8 or utf8_lua +---The component that handles a rich text input field, it's a wrapper around the druid.input component ---@class druid.rich_input: druid.component ----@field root node ----@field input druid.input ----@field cursor node ----@field cursor_text node ----@field cursor_position vector3 +---@field root node The root node of the rich input +---@field input druid.input The input component +---@field cursor node The cursor node +---@field cursor_text node The cursor text node +---@field cursor_position vector3 The position of the cursor local M = component.create("druid.rich_input") local DOUBLE_CLICK_TIME = 0.35 @@ -131,7 +132,12 @@ local function on_touch_start_callback(self, touch) end - +---@param self druid.rich_input +---@param dx number The delta x position +---@param dy number The delta y position +---@param x number The x position +---@param y number The y position +---@param touch table The touch table local function on_drag_callback(self, dx, dy, x, y, touch) if not self._last_touch_info.cursor_index then return @@ -218,6 +224,7 @@ end ---Set placeholder text ---@param placeholder_text string The placeholder text +---@return druid.rich_input self Current instance function M:set_placeholder(placeholder_text) self.placeholder:set_text(placeholder_text) return self @@ -225,8 +232,10 @@ end ---Select input field +---@return druid.rich_input self Current instance function M:select() self.input:select() + return self end @@ -262,7 +271,7 @@ end -- See: https://defold.com/ref/stable/string/ -- ex: [%a%d] for alpha and numeric ---@param characters string Regulax exp. for validate user input ----@return druid.rich_input Current instance +---@return druid.rich_input self Current instance function M:set_allowed_characters(characters) self.input:set_allowed_characters(characters) diff --git a/druid/custom/rich_text/rich_text.lua b/druid/custom/rich_text/rich_text.lua index 8cb3875..3f36ee2 100644 --- a/druid/custom/rich_text/rich_text.lua +++ b/druid/custom/rich_text/rich_text.lua @@ -65,11 +65,12 @@ local rich_text = require("druid.custom.rich_text.module.rt") ---@field offset_y number|nil ---@field node_size vector3|nil +---The component that handles a rich text display, allows to custom color, size, font, etc. of the parts of the text ---@class druid.rich_text: druid.component ----@field root node ----@field text_prefab node ----@field private _last_value string ----@field private _settings table +---@field root node The root node of the rich text +---@field text_prefab node The text prefab node +---@field private _last_value string The last value of the rich text +---@field private _settings table The settings of the rich text local M = component.create("rich_text") @@ -145,13 +146,14 @@ function M:set_text(text) end ----Get current text ----@return string text +---Get the current text of the rich text +---@return string text The current text of the rich text function M:get_text() return self._last_value end +---@private function M:on_remove() gui.set_scale(self.root, self._default_scale) gui.set_size(self.root, self._default_size) @@ -170,8 +172,8 @@ end ---Get all words, which has a passed tag. ----@param tag string ----@return druid.rich_text.word[] words +---@param tag string The tag to get the words for +---@return druid.rich_text.word[] words The words with the passed tag function M:tagged(tag) if not self._words then return {} @@ -181,28 +183,22 @@ function M:tagged(tag) end ----Split a word into it's characters ----@param word druid.rich_text.word ----@return druid.rich_text.word[] characters -function M:characters(word) - return rich_text.characters(word) -end - - ----Get all current words. +---Get all current created words, each word is a table that contains the information about the word ---@return druid.rich_text.word[] function M:get_words() return self._words end ----Get current line metrics -----@return druid.rich_text.lines_metrics +---Get the current line metrics +---@return druid.rich_text.lines_metrics lines_metrics The line metrics of the rich text function M:get_line_metric() return self._line_metrics end +---@private +---@return table settings The settings of the rich text, they are created based on the root node on the GUI scene function M:_create_settings() local root_size = gui.get_size(self.root) local scale = gui.get_scale(self.root) diff --git a/druid/druid.lua b/druid/druid.lua index 5865bcd..05b56ac 100644 --- a/druid/druid.lua +++ b/druid/druid.lua @@ -11,6 +11,7 @@ local default_style = require("druid.styles.default.style") ---@class druid local M = {} + ---Create a new Druid instance for creating GUI components. ---@param context table The Druid context. Usually, this is the self of the gui_script. It is passed into all Druid callbacks. ---@param style table|nil The Druid style table to override style parameters for this Druid instance. diff --git a/druid/extended/container.lua b/druid/extended/container.lua index 6f7f852..46024c7 100644 --- a/druid/extended/container.lua +++ b/druid/extended/container.lua @@ -30,24 +30,25 @@ local CORNER_PIVOTS = { ---@field DRAGGABLE_CORNER_SIZE vector3 Size of box node for debug draggable corners ---@field DRAGGABLE_CORNER_COLOR vector4 Color of debug draggable corners +---The component used for managing the size and positions with other containers relations to create a adaptable layouts ---@class druid.container: druid.component ----@field node node ----@field druid druid.instance ----@field node_offset vector4 ----@field origin_size vector3 ----@field size vector3 ----@field origin_position vector3 ----@field position vector3 ----@field pivot_offset vector3 ----@field center_offset vector3 ----@field mode string ----@field fit_size vector3 ----@field min_size_x number|nil ----@field min_size_y number|nil ----@field on_size_changed event fun(self: druid.container, size: vector3) ----@field _parent_container druid.container ----@field _containers table ----@field _draggable_corners table +---@field node node The gui node +---@field druid druid.instance The druid instance +---@field node_offset vector4 The node offset +---@field origin_size vector3 The origin size +---@field size vector3 The current size +---@field origin_position vector3 The origin position +---@field position vector3 The current position +---@field pivot_offset vector3 The pivot offset +---@field center_offset vector3 The center offset +---@field mode string The layout mode +---@field fit_size vector3 The fit size +---@field min_size_x number|nil The minimum size x +---@field min_size_y number|nil The minimum size y +---@field on_size_changed event fun(self: druid.container, size: vector3) The event triggered when the size changes +---@field _parent_container druid.container The parent container +---@field _containers table The containers +---@field _draggable_corners table The draggable corners local M = component.create("container") @@ -106,6 +107,7 @@ function M:on_remove() end +---Refresh the origins of the container, origins is the size and position of the container when it was created function M:refresh_origins() self.origin_size = gui.get_size(self.node) self.origin_position = gui.get_position(self.node) @@ -113,7 +115,8 @@ function M:refresh_origins() end ----@param pivot constant +---Set the pivot of the container +---@param pivot constant The pivot to set function M:set_pivot(pivot) gui.set_pivot(self.node, pivot) self.pivot_offset = helper.get_pivot_offset(pivot) @@ -121,7 +124,8 @@ function M:set_pivot(pivot) end ----@param style druid.container.style +---Set the style of the container +---@param style druid.container.style The style to set function M:on_style_change(style) self.style = { DRAGGABLE_CORNER_SIZE = style.DRAGGABLE_CORNER_SIZE or vmath.vector3(24, 24, 0), @@ -131,8 +135,8 @@ end ---Set new size of layout node ----@param width number|nil ----@param height number|nil +---@param width number|nil The width to set +---@param height number|nil The height to set ---@param anchor_pivot constant|nil If set will keep the corner possition relative to the new size ---@return druid.container Container function M:set_size(width, height, anchor_pivot) @@ -174,13 +178,16 @@ function M:set_size(width, height, anchor_pivot) end +---Get the position of the container +---@return vector3 position The position of the container function M:get_position() return self._position end ----@param pos_x number ----@param pos_y number +---Set the position of the container +---@param pos_x number The x position to set +---@param pos_y number The y position to set function M:set_position(pos_x, pos_y) if self._position.x == pos_x and self._position.y == pos_y then return @@ -192,23 +199,23 @@ function M:set_position(pos_x, pos_y) end ----Get current size of layout node ----@return vector3 size +---Get the current size of the layout node +---@return vector3 size The current size of the layout node function M:get_size() return vmath.vector3(self.size) end ----Get current scale of layout node ----@return vector3 scale +---Get the current scale of the layout node +---@return vector3 scale The current scale of the layout node function M:get_scale() return helper.get_scene_scale(self.node, true) --[[@as vector3]] end ---Set size for layout node to fit inside it ----@param target_size vector3 ----@return druid.container Container +---@param target_size vector3 The target size to fit into +---@return druid.container self Current container instance function M:fit_into_size(target_size) self.fit_size = target_size self:refresh() @@ -218,7 +225,7 @@ end ---Set current size for layout node to fit inside it ----@return druid.container Container +---@return druid.container self Current container instance function M:fit_into_window() return self:fit_into_size(vmath.vector3(gui.get_width(), gui.get_height(), 0)) end @@ -440,7 +447,7 @@ function M:update_child_containers() end ----@return druid.container Container +---@return druid.container self Current container instance function M:create_draggable_corners() self:clear_draggable_corners() @@ -470,7 +477,7 @@ function M:create_draggable_corners() end ----@return druid.container Container +---@return druid.container self Current container instance function M:clear_draggable_corners() for index = 1, #self._draggable_corners do local drag_component = self._draggable_corners[index] @@ -523,7 +530,7 @@ end ---Set node for layout node to fit inside it. Pass nil to reset ---@param node string|node The node_id or gui.get_node(node_id) ----@return druid.container Layout +---@return druid.container self Current container instance function M:fit_into_node(node) self._fit_node = self:get_node(node) self:refresh_scale() @@ -531,8 +538,10 @@ function M:fit_into_node(node) end ----@param min_size_x number|nil ----@param min_size_y number|nil +---Set the minimum size of the container +---@param min_size_x number|nil The minimum size x +---@param min_size_y number|nil The minimum size y +---@return druid.container self Current container instance function M:set_min_size(min_size_x, min_size_y) self.min_size_x = min_size_x or self.min_size_x self.min_size_y = min_size_y or self.min_size_y diff --git a/druid/extended/data_list.lua b/druid/extended/data_list.lua index a41b1b7..795ac6a 100644 --- a/druid/extended/data_list.lua +++ b/druid/extended/data_list.lua @@ -3,25 +3,26 @@ local helper = require("druid.helper") local component = require("druid.component") local event = require("event.event") +---The component used for managing a list of data with a scrollable view, used to manage huge list data and render only visible elements ---@class druid.data_list: druid.component ----@field scroll druid.scroll ----@field grid druid.grid ----@field on_scroll_progress_change event ----@field on_element_add event ----@field on_element_remove event ----@field top_index number ----@field last_index number ----@field scroll_progress number ----@field private _create_function function ----@field private _is_use_cache boolean ----@field private _cache table ----@field private _data table ----@field private _data_visual table +---@field scroll druid.scroll The scroll instance for Data List component +---@field grid druid.grid The StaticGrid or DynamicGrid instance for Data List component +---@field on_scroll_progress_change event The event triggered when the scroll progress changes +---@field on_element_add event The event triggered when a new element is added +---@field on_element_remove event The event triggered when an element is removed +---@field top_index number The top index of the visible elements +---@field last_index number The last index of the visible elements +---@field scroll_progress number The scroll progress +---@field private _create_function function The create function callback(self, data, index, data_list). Function should return (node, [component]) +---@field private _is_use_cache boolean Use cache version of DataList. Requires make setup of components in on_element_add callback and clean in on_element_remove +---@field private _cache table The cache table +---@field private _data table The data table +---@field private _data_visual table The data visual table local M = component.create("data_list") ---@param scroll druid.scroll The Scroll instance for Data List component ----@param grid druid.grid The StaticGrid} or @{DynamicGrid instance for Data List component +---@param grid druid.grid The StaticGrid instance for Data List component ---@param create_function function The create function callback(self, data, index, data_list). Function should return (node, [component]) function M:init(scroll, grid, create_function) self.scroll = scroll @@ -56,9 +57,9 @@ function M:on_remove() end ----Set refresh function for DataList component ----@param is_use_cache boolean Use cache version of DataList. Requires make setup of components in on_element_add callback and clean in on_element_remove ----@return druid.data_list Current DataList instance +---Set use cache version of DataList. Requires make setup of components in on_element_add callback and clean in on_element_remove +---@param is_use_cache boolean Use cache version of DataList +---@return druid.data_list self Current DataList instance function M:set_use_cache(is_use_cache) self._is_use_cache = is_use_cache return self @@ -67,7 +68,7 @@ end ---Set new data set for DataList component ---@param data table The new data array ----@return druid.data_list Current DataList instance +---@return druid.data_list self Current DataList instance function M:set_data(data) self._data = data or {} self:_refresh() @@ -77,50 +78,62 @@ end ---Return current data from DataList component ----@return table The current data array +---@return table data The current data array function M:get_data() return self._data end ----Add element to DataList. Currenly untested ----@param data table ----@param index number|nil +---Add element to DataList +---@param data table The data to add +---@param index number|nil The index to add the data at ---@param shift_policy number|nil The constant from const.SHIFT.* +---@return druid.data_list self Current DataList instance function M:add(data, index, shift_policy) index = index or #self._data + 1 shift_policy = shift_policy or const.SHIFT.RIGHT helper.insert_with_shift(self._data, data, index, shift_policy) self:_refresh() + + return self end ----Remove element from DataList. Currenly untested ----@param index number|nil +---Remove element from DataList +---@param index number|nil The index to remove the data at ---@param shift_policy number|nil The constant from const.SHIFT.* +---@return druid.data_list self Current DataList instance function M:remove(index, shift_policy) helper.remove_with_shift(self._data, index, shift_policy) self:_refresh() + + return self end ----Remove element from DataList by data value. Currenly untested ----@param data table +---Remove element from DataList by data value +---@param data table The data to remove ---@param shift_policy number|nil The constant from const.SHIFT.* +---@return druid.data_list self Current DataList instance function M:remove_by_data(data, shift_policy) local index = helper.contains(self._data, data) if index then helper.remove_with_shift(self._data, index, shift_policy) self:_refresh() end + + return self end ---Clear the DataList and refresh visuals +---@return druid.data_list self Current DataList instance function M:clear() self._data = {} self:_refresh() + + return self end @@ -151,7 +164,7 @@ end ---Return all currenly created components in DataList ----@return druid.component[] List of created nodes +---@return druid.component[] components List of created components function M:get_created_components() local components = {} @@ -164,7 +177,7 @@ end ---Instant scroll to element with passed index ----@param index number +---@param index number The index to scroll to function M:scroll_to_index(index) local pos = self.grid:get_pos(index) self.scroll:scroll_to(pos) @@ -172,7 +185,7 @@ end ---Add element at passed index using cache or create new ----@param index number +---@param index number The index to add the element at ---@private function M:_add_at(index) if self._data_visual[index] then @@ -205,7 +218,7 @@ end ---Remove element from passed index and add it to cache if applicable ----@param index number +---@param index number The index to remove the element at ---@private function M:_remove_at(index) self.grid:remove(index, const.SHIFT.NO_SHIFT) diff --git a/druid/extended/hotkey.lua b/druid/extended/hotkey.lua index d32419c..27db333 100644 --- a/druid/extended/hotkey.lua +++ b/druid/extended/hotkey.lua @@ -5,12 +5,13 @@ local component = require("druid.component") ---@class druid.hotkey.style ---@field MODIFICATORS string[]|hash[] The list of action_id as hotkey modificators +---The component used for managing hotkeys and trigger callbacks when hotkeys are pressed ---@class druid.hotkey: druid.component ----@field on_hotkey_pressed event ----@field on_hotkey_released event ----@field style druid.hotkey.style ----@field private _hotkeys table ----@field private _modificators table +---@field on_hotkey_pressed event fun(self, context, callback_argument) The event triggered when a hotkey is pressed +---@field on_hotkey_released event fun(self, context, callback_argument) The event triggered when a hotkey is released +---@field style druid.hotkey.style The style of the hotkey component +---@field private _hotkeys table The list of hotkeys +---@field private _modificators table The list of modificators local M = component.create("hotkey") @@ -51,7 +52,7 @@ end ---Add hotkey for component callback ---@param keys string[]|hash[]|string|hash that have to be pressed before key pressed to activate ---@param callback_argument any|nil The argument to pass into the callback function ----@return druid.hotkey Current instance +---@return druid.hotkey self Current instance function M:add_hotkey(keys, callback_argument) keys = keys or {} if type(keys) == "string" then @@ -109,9 +110,9 @@ function M:on_focus_gained() end ----@param action_id hash|nil ----@param action action ----@return boolean +---@param action_id hash|nil The action id +---@param action action The action +---@return boolean is_consume True if the action is consumed function M:on_input(action_id, action) if not action_id then return false @@ -167,8 +168,8 @@ end ---If true, the callback will be triggered on action.repeated ----@param is_enabled_repeated bool The flag value ----@return druid.hotkey +---@param is_enabled_repeated boolean The flag value +---@return druid.hotkey self Current instance function M:set_repeat(is_enabled_repeated) self._is_process_repeated = is_enabled_repeated return self diff --git a/druid/extended/input.lua b/druid/extended/input.lua index 46cb305..3a521fd 100755 --- a/druid/extended/input.lua +++ b/druid/extended/input.lua @@ -13,16 +13,17 @@ local utf8 = utf8 or utf8_lua ---@field on_unselect fun(self: druid.input, button_node: node) Callback on input field unselecting ---@field on_input_wrong fun(self: druid.input, button_node: node) Callback on wrong user input +---The component used for managing input fields in basic way ---@class druid.input: druid.component ----@field on_input_select event fun(self: druid.input, input: druid.input) ----@field on_input_unselect event fun(self: druid.input, text: string, input: druid.input) ----@field on_input_text event fun(self: druid.input) ----@field on_input_empty event fun(self: druid.input) ----@field on_input_full event fun(self: druid.input) ----@field on_input_wrong event fun(self: druid.input) ----@field on_select_cursor_change event fun(self: druid.input, cursor_index: number, start_index: number, end_index: number) ----@field style table ----@field text druid.text +---@field on_input_select event fun(self: druid.input, input: druid.input) The event triggered when the input field is selected +---@field on_input_unselect event fun(self: druid.input, text: string, input: druid.input) The event triggered when the input field is unselected +---@field on_input_text event fun(self: druid.input) The event triggered when the input field is changed +---@field on_input_empty event fun(self: druid.input) The event triggered when the input field is empty +---@field on_input_full event fun(self: druid.input) The event triggered when the input field is full +---@field on_input_wrong event fun(self: druid.input) The event triggered when the input field is wrong +---@field on_select_cursor_change event fun(self: druid.input, cursor_index: number, start_index: number, end_index: number) The event triggered when the cursor index is changed +---@field style druid.input.style The style of the input component +---@field text druid.text The text component local M = component.create("input") M.ALLOWED_ACTIONS = { @@ -126,6 +127,9 @@ function M:on_style_change(style) end +---@param action_id hash|nil The action id +---@param action action The action +---@return boolean is_consume True if the action is consumed function M:on_input(action_id, action) if not (action_id == nil or M.ALLOWED_ACTIONS[action_id]) then return false @@ -242,9 +246,10 @@ function M:get_text_selected() return utf8.sub(self.value, self.start_index + 1, self.end_index) end + ---Replace selected text with new text ---@param text string The text to replace selected text ----@return string New input text +---@return string new_text New input text function M:get_text_selected_replaced(text) local left_part = utf8.sub(self.value, 1, self.start_index) local right_part = utf8.sub(self.value, self.end_index + 1, utf8.len(self.value)) @@ -350,7 +355,7 @@ end ---Return current input field text ----@return string The current input field text +---@return string text The current input field text function M:get_text() if self.marked_value ~= "" then return self.value .. self.marked_value @@ -363,7 +368,7 @@ end ---Set maximum length for input field. -- Pass nil to make input field unliminted (by default) ---@param max_length number Maximum length for input text field ----@return druid.input Current input instance +---@return druid.input self Current input instance function M:set_max_length(max_length) self.max_length = max_length return self @@ -374,7 +379,7 @@ end -- See: https://defold.com/ref/stable/string/ -- ex: [%a%d] for alpha and numeric ---@param characters string Regulax exp. for validate user input ----@return druid.input Current input instance +---@return druid.input self Current input instance function M:set_allowed_characters(characters) self.allowed_characters = characters return self @@ -382,7 +387,7 @@ end ---Reset current input selection and return previous value ----@return druid.input Current input instance +---@return druid.input self Current input instance function M:reset_changes() self:set_text(self.previous_value) self:unselect() @@ -394,7 +399,7 @@ end ---@param cursor_index number|nil Cursor index for cursor position, if nil - will be set to the end of the text ---@param start_index number|nil Start index for cursor position, if nil - will be set to the end of the text ---@param end_index number|nil End index for cursor position, if nil - will be set to the start_index ----@return druid.input Current input instance +---@return druid.input self Current input instance function M:select_cursor(cursor_index, start_index, end_index) local len = utf8.len(self.value) @@ -416,6 +421,7 @@ end ---@param delta number side for cursor position, -1 for left, 1 for right ---@param is_add_to_selection boolean (Shift key) ---@param is_move_to_end boolean (Ctrl key) +---@return druid.input self Current input instance function M:move_selection(delta, is_add_to_selection, is_move_to_end) local len = utf8.len(self.value) local cursor_index = self.cursor_index diff --git a/druid/extended/lang_text.lua b/druid/extended/lang_text.lua index 940bb61..7af5dec 100755 --- a/druid/extended/lang_text.lua +++ b/druid/extended/lang_text.lua @@ -2,12 +2,13 @@ local event = require("event.event") local component = require("druid.component") local settings = require("druid.system.settings") +---The component used for displaying localized text, can automatically update text when locale is changed ---@class druid.lang_text: druid.component ----@field text druid.text ----@field node node ----@field on_change event ----@field private last_locale_args table ----@field private last_locale string +---@field text druid.text The text component +---@field node node The node of the text component +---@field on_change event The event triggered when the text is changed +---@field private last_locale_args table The last locale arguments +---@field private last_locale string The last locale local M = component.create("lang_text") @@ -38,7 +39,7 @@ end ---Setup raw text to lang_text component ---@param text string Text for text node ----@return druid.lang_text Current instance +---@return druid.lang_text self Current instance function M:set_to(text) self.last_locale = nil self.text:set_text(text) @@ -50,7 +51,7 @@ end ---Setup raw text to lang_text component ---@param text string Text for text node ----@return druid.lang_text Current instance +---@return druid.lang_text self Current instance function M:set_text(text) return self:set_to(text) end @@ -59,7 +60,7 @@ end ---Translate the text by locale_id ---@param locale_id string Locale id ---@param ... string Optional params for string.format ----@return druid.lang_text Current instance +---@return druid.lang_text self Current instance function M:translate(locale_id, ...) self.last_locale_args = { ... } self.last_locale = locale_id or self.last_locale @@ -71,7 +72,7 @@ end ---Format string with new text params on localized text ---@param ... string Optional params for string.format ----@return druid.lang_text Current instance +---@return druid.lang_text self Current instance function M:format(...) self.last_locale_args = { ... } self.text:set_text(settings.get_text(self.last_locale, ...) or "") diff --git a/druid/extended/layout.lua b/druid/extended/layout.lua index 057e451..f4faaa4 100644 --- a/druid/extended/layout.lua +++ b/druid/extended/layout.lua @@ -19,18 +19,19 @@ local component = require("druid.component") ---@field nodes_height table ---@field rows druid.layout.row_data[]> +---The component used for managing the layout of nodes, placing them inside the node size with respect to the size and pivot of each node ---@class druid.layout: druid.component ----@field node node +---@field node node The node to manage the layout of ---@field rows_data druid.layout.rows_data Last calculated rows data ---@field is_dirty boolean ----@field entities node[] ----@field margin {x: number, y: number} ----@field padding vector4 ----@field type string ----@field is_resize_width boolean ----@field is_resize_height boolean ----@field is_justify boolean ----@field on_size_changed event.on_size_changed +---@field entities node[] The entities to manage the layout of +---@field margin {x: number, y: number} The margin of the layout +---@field padding vector4 The padding of the layout +---@field type string The type of the layout +---@field is_resize_width boolean True if the layout should resize the width of the node +---@field is_resize_height boolean True if the layout should resize the height of the node +---@field is_justify boolean True if the layout should justify the nodes +---@field on_size_changed event.on_size_changed The event triggered when the size of the layout is changed local M = component.create("layout") @@ -68,11 +69,15 @@ function M:update() end +---@return node[] entities The entities to manage the layout of function M:get_entities() return self.entities end +---@param node node The node to set the index of +---@param index number The index to set the node to +---@return druid.layout self for chaining function M:set_node_index(node, index) for i = 1, #self.entities do if self.entities[i] == node then @@ -81,12 +86,15 @@ function M:set_node_index(node, index) break end end + + return self end ----@param margin_x number|nil ----@param margin_y number|nil ----@return druid.layout +---Set the margin of the layout +---@param margin_x number|nil The margin x +---@param margin_y number|nil The margin y +---@return druid.layout self Current layout instance function M:set_margin(margin_x, margin_y) self.margin.x = margin_x or self.margin.x self.margin.y = margin_y or self.margin.y @@ -96,11 +104,11 @@ function M:set_margin(margin_x, margin_y) end ----@param padding_x number|nil ----@param padding_y number|nil ----@param padding_z number|nil ----@param padding_w number|nil ----@return druid.layout +---@param padding_x number|nil The padding x +---@param padding_y number|nil The padding y +---@param padding_z number|nil The padding z +---@param padding_w number|nil The padding w +---@return druid.layout self Current layout instance function M:set_padding(padding_x, padding_y, padding_z, padding_w) self.padding.x = padding_x or self.padding.x self.padding.y = padding_y or self.padding.y @@ -112,7 +120,7 @@ function M:set_padding(padding_x, padding_y, padding_z, padding_w) end ----@return druid.layout +---@return druid.layout self Current layout instance function M:set_dirty() self.is_dirty = true @@ -121,7 +129,7 @@ end ---@param is_justify boolean ----@return druid.layout +---@return druid.layout self Current layout instance function M:set_justify(is_justify) self.is_justify = is_justify self.is_dirty = true @@ -131,7 +139,7 @@ end ---@param type string The layout type: "horizontal", "vertical", "horizontal_wrap" ----@return druid.layout +---@return druid.layout self Current layout instance function M:set_type(type) self.type = type self.is_dirty = true @@ -142,7 +150,7 @@ end ---@param is_hug_width boolean ---@param is_hug_height boolean ----@return druid.layout +---@return druid.layout self Current layout instance function M:set_hug_content(is_hug_width, is_hug_height) self.is_resize_width = is_hug_width or false self.is_resize_height = is_hug_height or false @@ -154,7 +162,7 @@ end ---Add node to layout ---@param node_or_node_id node|string node_or_node_id ----@return druid.layout +---@return druid.layout self Current layout instance function M:add(node_or_node_id) -- Acquire node from entity or by id local node = node_or_node_id @@ -207,7 +215,7 @@ function M:get_content_size() end ----@return druid.layout +---@return druid.layout self Current layout instance function M:refresh_layout() local layout_node = self.node @@ -349,7 +357,7 @@ function M:refresh_layout() end ----@return druid.layout +---@return druid.layout self Current layout instance function M:clear_layout() for index = #self.entities, 1, -1 do self.entities[index] = nil @@ -362,7 +370,8 @@ end ---@param node node ----@return number, number +---@return number width The width of the node +---@return number height The height of the node function M:get_node_size(node) if not gui.is_enabled(node, false) then return 0, 0 diff --git a/druid/extended/progress.lua b/druid/extended/progress.lua index 6d21157..3a43dfe 100644 --- a/druid/extended/progress.lua +++ b/druid/extended/progress.lua @@ -1,5 +1,4 @@ local event = require("event.event") -local const = require("druid.const") local helper = require("druid.helper") local component = require("druid.component") @@ -7,6 +6,7 @@ local component = require("druid.component") ---@field SPEED number|nil Progress bas fill rate. More -> faster. Default: 5 ---@field MIN_DELTA number|nil Minimum step to fill progress bar. Default: 0.005 +---The component used to manage a node as a progress bar, changing the size and scale of the node ---@class druid.progress: druid.component ---@field node node ---@field on_change event @@ -17,10 +17,10 @@ local M = component.create("progress") ---@param node string|node Node name or GUI Node itself. ----@param key string Progress bar direction: const.SIDE.X or const.SIDE.Y +---@param key string Progress bar direction: "x" or "y" ---@param init_value number|nil Initial value of progress bar. Default: 1 function M:init(node, key, init_value) - assert(key == const.SIDE.X or const.SIDE.Y, "Progress bar key should be 'x' or 'y'") + assert(key == "x" or key == "y", "Progress bar key should be 'x' or 'y'") self.key = key self.prop = hash("scale." .. self.key) @@ -85,27 +85,37 @@ function M:update(dt) end ----Fill a progress bar and stop progress animation +---Fill the progress bar +---@return druid.progress self Current progress instance function M:fill() self:_set_bar_to(1, true) + + return self end ----Empty a progress bar +---Empty the progress bar +---@return druid.progress self Current progress instance function M:empty() self:_set_bar_to(0, true) + + return self end ---Instant fill progress bar to value ---@param to number Progress bar value, from 0 to 1 +---@return druid.progress self Current progress instance function M:set_to(to) to = helper.clamp(to, 0, 1) self:_set_bar_to(to) + + return self end ----Return current progress bar value +---Return the current value of the progress bar +---@return number value The current value of the progress bar function M:get() return self.last_value end @@ -114,15 +124,19 @@ end ---Set points on progress bar to fire the callback ---@param steps number[] Array of progress bar values ---@param callback function Callback on intersect step value +---@return druid.progress self Current progress instance function M:set_steps(steps, callback) self.steps = steps self.step_callback = callback + + return self end ---Start animation of a progress bar ---@param to number value between 0..1 ---@param callback function|nil Callback on animation ends +---@return druid.progress self Current progress instance function M:to(to, callback) to = helper.clamp(to, 0, 1) -- cause of float error @@ -135,20 +149,26 @@ function M:to(to, callback) callback(self:get_context(), to) end end + + return self end ---Set progress bar max node size ---@param max_size vector3 The new node maximum (full) size ----@return druid.progress Progress +---@return druid.progress self Current progress instance function M:set_max_size(max_size) self.max_size[self.key] = max_size[self.key] self:set_to(self.last_value) + return self end ---@private +---@param from number The start value +---@param to number The end value +---@param exactly number|nil The exact value function M:_check_steps(from, to, exactly) if not self.steps then return @@ -172,9 +192,10 @@ end ---@private +---@param set_to number The value to set the progress bar to function M:_set_bar_to(set_to, is_silent) local prev_value = self.last_value - local other_side = self.key == const.SIDE.X and const.SIDE.Y or const.SIDE.X + local other_side = self.key == "x" and "y" or "x" self.last_value = set_to local total_width = set_to * self.max_size[self.key] @@ -206,8 +227,9 @@ function M:_set_bar_to(set_to, is_silent) self.on_change:trigger(self:get_context(), self.last_value) end end + + return self end - return M diff --git a/druid/extended/slider.lua b/druid/extended/slider.lua index 871e019..67521f9 100644 --- a/druid/extended/slider.lua +++ b/druid/extended/slider.lua @@ -3,24 +3,25 @@ local helper = require("druid.helper") local const = require("druid.const") local component = require("druid.component") +---The component to make a draggable node over a line with a progress report ---@class druid.slider: druid.component ----@field node node ----@field on_change_value event ----@field style table ----@field private start_pos vector3 ----@field private pos vector3 ----@field private target_pos vector3 ----@field private end_pos vector3 ----@field private dist vector3 ----@field private is_drag boolean ----@field private value number ----@field private steps number[] +---@field node node The node to manage the slider +---@field on_change_value event The event triggered when the slider value changes +---@field style table The style of the slider +---@field private start_pos vector3 The start position of the slider +---@field private pos vector3 The current position of the slider +---@field private target_pos vector3 The target position of the slider +---@field private end_pos vector3 The end position of the slider +---@field private dist vector3 The distance between the start and end positions of the slider +---@field private is_drag boolean True if the slider is being dragged +---@field private value number The current value of the slider +---@field private steps number[] The steps of the slider local M = component.create("slider", const.PRIORITY_INPUT_HIGH) ---The Slider constructor ----@param node node Gui pin node ----@param end_pos vector3 The end position of slider +---@param node node GUI node to drag as a slider +---@param end_pos vector3 The end position of slider, should be on the same axis as the node ---@param callback function|nil On slider change callback function M:init(node, end_pos, callback) self.node = self:get_node(node) @@ -61,6 +62,9 @@ function M:on_window_resized() end +---@param action_id number The action id +---@param action action The action table +---@return boolean is_consumed True if the input was consumed function M:on_input(action_id, action) if action_id ~= const.ACTION_TOUCH then return false @@ -148,6 +152,7 @@ end ---Set value for slider ---@param value number Value from 0 to 1 ---@param is_silent boolean|nil Don't trigger event if true +---@return druid.slider self Current slider instance function M:set(value, is_silent) value = helper.clamp(value, 0, 1) self:_set_position(value) @@ -155,13 +160,15 @@ function M:set(value, is_silent) if not is_silent then self:_on_change_value() end + + return self end ---Set slider steps. Pin node will ---apply closest step position ---@param steps number[] Array of steps ----@return druid.slider Slider +---@return druid.slider self Current slider instance function M:set_steps(steps) self.steps = steps return self @@ -173,7 +180,7 @@ end ---move at this position and node drag will start. ---This function require the Defold version 1.3.0+ ---@param input_node node|string|nil ----@return druid.slider Slider +---@return druid.slider self Current slider instance function M:set_input_node(input_node) if not input_node then self._input_node = nil @@ -186,14 +193,17 @@ end ---Set Slider input enabled or disabled ----@param is_enabled boolean +---@param is_enabled boolean True if slider is enabled +---@return druid.slider self Current slider instance function M:set_enabled(is_enabled) self._is_enabled = is_enabled + + return self end ---Check if Slider component is enabled ----@return boolean +---@return boolean is_enabled True if slider is enabled function M:is_enabled() return self._is_enabled end diff --git a/druid/extended/swipe.lua b/druid/extended/swipe.lua index 50a70dd..0a3aa73 100644 --- a/druid/extended/swipe.lua +++ b/druid/extended/swipe.lua @@ -8,16 +8,17 @@ local component = require("druid.component") ---@field SWIPE_THRESHOLD number|nil Minimum distance for swipe trigger. Default: 50 ---@field SWIPE_TRIGGER_ON_MOVE boolean|nil If true, trigger on swipe moving, not only release action. Default: false +---The component to manage swipe events over a node ---@class druid.swipe: druid.component ----@field node node ----@field on_swipe event function(side, dist, dt), side - "left", "right", "up", "down" ----@field style table ----@field click_zone node ----@field private _trigger_on_move boolean ----@field private _swipe_start_time number ----@field private _start_pos vector3 ----@field private _is_enabled boolean ----@field private _is_mobile boolean +---@field node node The node to manage the swipe +---@field on_swipe event fun(context, side, dist, dt) The event triggered when a swipe is detected +---@field style druid.swipe.style The style of the swipe +---@field click_zone node The click zone of the swipe +---@field private _trigger_on_move boolean True if the swipe should trigger on move +---@field private _swipe_start_time number The time the swipe started +---@field private _start_pos vector3 The start position of the swipe +---@field private _is_enabled boolean True if the swipe is enabled +---@field private _is_mobile boolean True if the swipe is on a mobile device local M = component.create("swipe") @@ -55,8 +56,9 @@ function M:on_style_change(style) end ----@param action_id hash ----@param action action +---@param action_id hash The action id +---@param action action The action table +---@return boolean is_consumed True if the input was consumed function M:on_input(action_id, action) if action_id ~= const.ACTION_TOUCH then return false @@ -93,8 +95,7 @@ function M:on_input_interrupt() end ----Strict swipe click area. Useful for ----restrict events outside stencil node +---Set the click zone for the swipe, useful for restricting events outside stencil node ---@param zone node|string|nil Gui node function M:set_click_zone(zone) if not zone then @@ -107,7 +108,7 @@ end ---Start swipe event ----@param action action +---@param action action The action table function M:_start_swipe(action) self._swipe_start_time = socket.gettime() self._start_pos.x = action.x diff --git a/druid/extended/timer.lua b/druid/extended/timer.lua index 9472836..557c8e3 100644 --- a/druid/extended/timer.lua +++ b/druid/extended/timer.lua @@ -2,15 +2,16 @@ local event = require("event.event") local helper = require("druid.helper") local component = require("druid.component") +---The component that handles a text to display a seconds timer ---@class druid.timer: druid.component ----@field on_tick event ----@field on_set_enabled event ----@field on_timer_end event ----@field node node ----@field from number ----@field target number ----@field value number ----@field is_on boolean|nil +---@field on_tick event fun(context, value) The event triggered when the timer ticks +---@field on_set_enabled event fun(context, is_on) The event triggered when the timer is enabled +---@field on_timer_end event fun(context) The event triggered when the timer ends +---@field node node The node to display the timer +---@field from number The start time of the timer +---@field target number The target time of the timer +---@field value number The current value of the timer +---@field is_on boolean|nil True if the timer is on local M = component.create("timer") @@ -69,8 +70,9 @@ function M:on_layout_change() end +---Set the timer to a specific value ---@param set_to number Value in seconds ----@return druid.timer self +---@return druid.timer self Current timer instance function M:set_to(set_to) self.last_value = set_to gui.set_text(self.node, self:_second_string_min(set_to)) @@ -79,8 +81,9 @@ function M:set_to(set_to) end +---Set the timer to a specific value ---@param is_on boolean|nil Timer enable state ----@return druid.timer self +---@return druid.timer self Current timer instance function M:set_state(is_on) self.is_on = is_on self.on_set_enabled:trigger(self:get_context(), is_on) @@ -89,9 +92,10 @@ function M:set_state(is_on) end +---Set the timer interval ---@param from number Start time in seconds ---@param to number Target time in seconds ----@return druid.timer self +---@return druid.timer self Current timer instance function M:set_interval(from, to) self.from = from self.value = from @@ -104,6 +108,9 @@ function M:set_interval(from, to) end +---@private +---@param sec number Seconds to convert +---@return string The formatted time string function M:_second_string_min(sec) local mins = math.floor(sec / 60) local seconds = math.floor(sec - mins * 60) diff --git a/druid/helper.lua b/druid/helper.lua index 0bb079c..28d60cc 100644 --- a/druid/helper.lua +++ b/druid/helper.lua @@ -553,7 +553,7 @@ function M.get_full_position(node, root) end ----@class druid.animation_data +---@class druid.system.animation_data ---@field frames table> List of frames with uv coordinates and size ---@field width number Width of the animation ---@field height number Height of the animation @@ -564,7 +564,7 @@ end ---@param node node ---@param atlas_path string Path to the atlas ----@return druid.animation_data +---@return druid.system.animation_data function M.get_animation_data_from_node(node, atlas_path) local atlas_data = resource.get_atlas(atlas_path) local tex_info = resource.get_texture_info(atlas_data.texture) diff --git a/druid/system/druid_instance.lua b/druid/system/druid_instance.lua index 3b8295d..5757f56 100755 --- a/druid/system/druid_instance.lua +++ b/druid/system/druid_instance.lua @@ -1,12 +1,12 @@ -- Hello, Defolder! Wish you a good day! -local event = require("event.event") local events = require("event.events") local const = require("druid.const") local helper = require("druid.helper") local settings = require("druid.system.settings") local druid_component = require("druid.component") +---The Druid Factory used to create components ---@class druid.instance ---@field components_all druid.component[] All created components ---@field components_interest table All components sorted by interest @@ -202,18 +202,15 @@ function M.create_druid_instance(context, style) events.subscribe("druid.window_event", self.on_window_event, self) events.subscribe("druid.language_change", self.on_language_change, self) - -- And we can rid of several bindings by this? - --self.on_node_size_changed = event.create() - return self end ---Create new Druid component instance ---@generic T: druid.component ----@param component T ----@vararg any ----@return T +---@param component T The component class to create +---@vararg any Additional arguments to pass to the component's init function +---@return T instance The new ready to use component function M:new(component, ...) local instance = create(self, component) @@ -251,7 +248,7 @@ end -- Component `on_remove` function will be invoked, if exist. ---@generic T: druid.component ---@param component T Component instance ----@return boolean True if component was removed +---@return boolean is_removed True if component was removed function M:remove(component) if self._is_late_remove_enabled then table.insert(self._late_remove, component) @@ -300,7 +297,7 @@ end ---Get a context of Druid instance (usually a self of gui script) ---@package ----@return any +---@return any context The Druid context function M:get_context() return self._context end @@ -308,7 +305,7 @@ end ---Get a style of Druid instance ---@package ----@return table +---@return table style The Druid style table function M:get_style() return self._style end @@ -350,7 +347,7 @@ end ---Call this in gui_script on_input function. ---@param action_id hash Action_id from on_input ---@param action table Action from on_input ----@return boolean The boolean value is input was consumed +---@return boolean is_input_consumed The boolean value is input was consumed function M:on_input(action_id, action) self._is_late_remove_enabled = true @@ -402,6 +399,8 @@ function M:on_message(message_id, message, sender) end +---Called when the window event occurs +---@param window_event number The window event function M:on_window_event(window_event) if window_event == window.WINDOW_EVENT_FOCUS_LOST then local components = self.components_interest[const.ON_FOCUS_LOST] @@ -438,7 +437,7 @@ end ---If whitelist is not empty and component not contains in this list, ---component will be not processed on input step ---@param whitelist_components table|druid.component[] The array of component to whitelist ----@return druid.instance +---@return druid.instance self The Druid instance function M:set_whitelist(whitelist_components) if whitelist_components and whitelist_components._component then whitelist_components = { whitelist_components } @@ -458,7 +457,7 @@ end ---If blacklist is not empty and component contains in this list, ---component will be not processed on input step DruidInstance ---@param blacklist_components table|druid.component[] The array of component to blacklist ----@return druid.instance +---@return druid.instance self The Druid instance function M:set_blacklist(blacklist_components) if blacklist_components and blacklist_components._component then blacklist_components = { blacklist_components } @@ -490,11 +489,11 @@ end ---Create new Druid widget instance ---@generic T: druid.component ----@param widget T +---@param widget T The widget class to create ---@param template string|nil The template name used by widget ---@param nodes table|node|nil The nodes table from gui.clone_tree or prefab node to use for clone ----@vararg any ----@return T +---@vararg any Additional arguments to pass to the widget's init function +---@return T widget The new ready to use widget function M:new_widget(widget, template, nodes, ...) local instance = create_widget(self, widget) @@ -521,7 +520,7 @@ local button = require("druid.base.button") ---@param callback function|event|nil Button callback ---@param params any|nil Button callback params ---@param anim_node node|string|nil Button anim node (node, if not provided) ----@return druid.button Button component +---@return druid.button button The new button component function M:new_button(node, callback, params, anim_node) return self:new(button, node, callback, params, anim_node) end @@ -530,7 +529,7 @@ end local blocker = require("druid.base.blocker") ---Create Blocker component ---@param node string|node The node_id or gui.get_node(node_id) ----@return druid.blocker component Blocker component +---@return druid.blocker blocker The new blocker component function M:new_blocker(node) return self:new(blocker, node) end @@ -540,7 +539,7 @@ local back_handler = require("druid.base.back_handler") ---Create BackHandler component ---@param callback function|nil The callback(self, custom_args) to call on back event ---@param params any|nil Callback argument ----@return druid.back_handler component BackHandler component +---@return druid.back_handler back_handler The new back handler component function M:new_back_handler(callback, params) return self:new(back_handler, callback, params) end @@ -551,7 +550,7 @@ local hover = require("druid.base.hover") ---@param node string|node The node_id or gui.get_node(node_id) ---@param on_hover_callback function|nil Hover callback ---@param on_mouse_hover_callback function|nil Mouse hover callback ----@return druid.hover component Hover component +---@return druid.hover hover The new hover component function M:new_hover(node, on_hover_callback, on_mouse_hover_callback) return self:new(hover, node, on_hover_callback, on_mouse_hover_callback) end @@ -562,7 +561,7 @@ local text = require("druid.base.text") ---@param node string|node The node_id or gui.get_node(node_id) ---@param value string|nil Initial text. Default value is node text from GUI scene. ---@param adjust_type string|nil Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference ----@return druid.text component Text component +---@return druid.text text The new text component function M:new_text(node, value, adjust_type) return self:new(text, node, value, adjust_type) end @@ -573,7 +572,7 @@ local static_grid = require("druid.base.static_grid") ---@param parent_node string|node The node_id or gui.get_node(node_id). Parent of all Grid items. ---@param item string|node Item prefab. Required to get grid's item size. Can be adjusted separately. ---@param in_row number|nil How many nodes in row can be placed ----@return druid.grid component Grid component +---@return druid.grid grid The new grid component function M:new_grid(parent_node, item, in_row) return self:new(static_grid, parent_node, item, in_row) end @@ -583,7 +582,7 @@ local scroll = require("druid.base.scroll") ---Create Scroll component ---@param view_node string|node The node_id or gui.get_node(node_id). Will used as user input node. ---@param content_node string|node The node_id or gui.get_node(node_id). Will used as scrollable node inside view_node. ----@return druid.scroll component Scroll component +---@return druid.scroll scroll The new scroll component function M:new_scroll(view_node, content_node) return self:new(scroll, view_node, content_node) end @@ -593,7 +592,7 @@ local drag = require("druid.base.drag") ---Create Drag component ---@param node string|node The node_id or gui.get_node(node_id). Will used as user input node. ---@param on_drag_callback function|nil Callback for on_drag_event(self, dx, dy) ----@return druid.drag component Drag component +---@return druid.drag drag The new drag component function M:new_drag(node, on_drag_callback) return self:new(drag, node, on_drag_callback) end @@ -603,7 +602,7 @@ local swipe = require("druid.extended.swipe") ---Create Swipe component ---@param node string|node The node_id or gui.get_node(node_id). Will used as user input node. ---@param on_swipe_callback function|nil Swipe callback for on_swipe_end event ----@return druid.swipe component Swipe component +---@return druid.swipe swipe The new swipe component function M:new_swipe(node, on_swipe_callback) return self:new(swipe, node, on_swipe_callback) end @@ -614,7 +613,7 @@ local lang_text = require("druid.extended.lang_text") ---@param node string|node The_node id or gui.get_node(node_id) ---@param locale_id string|nil Default locale id or text from node as default ---@param adjust_type string|nil Adjust type for text node. Default: const.TEXT_ADJUST.DOWNSCALE ----@return druid.lang_text component LangText component +---@return druid.lang_text lang_text The new lang text component function M:new_lang_text(node, locale_id, adjust_type) return self:new(lang_text, node, locale_id, adjust_type) end @@ -625,7 +624,7 @@ local slider = require("druid.extended.slider") ---@param pin_node string|node The_node id or gui.get_node(node_id). ---@param end_pos vector3 The end position of slider ---@param callback function|nil On slider change callback ----@return druid.slider component Slider component +---@return druid.slider slider The new slider component function M:new_slider(pin_node, end_pos, callback) return self:new(slider, pin_node, end_pos, callback) end @@ -636,7 +635,7 @@ local input = require("druid.extended.input") ---@param click_node string|node Button node to enabled input component ---@param text_node string|node|druid.text Text node what will be changed on user input ---@param keyboard_type number|nil Gui keyboard type for input field ----@return druid.input component Input component +---@return druid.input input The new input component function M:new_input(click_node, text_node, keyboard_type) return self:new(input, click_node, text_node, keyboard_type) end @@ -647,7 +646,7 @@ local data_list = require("druid.extended.data_list") ---@param druid_scroll druid.scroll The Scroll instance for Data List component ---@param druid_grid druid.grid The Grid instance for Data List component ---@param create_function function The create function callback(self, data, index, data_list). Function should return (node, [component]) ----@return druid.data_list component DataList component +---@return druid.data_list data_list The new data list component function M:new_data_list(druid_scroll, druid_grid, create_function) return self:new(data_list, druid_scroll, druid_grid, create_function) end @@ -659,7 +658,7 @@ local timer_component = require("druid.extended.timer") ---@param seconds_from number|nil Start timer value in seconds ---@param seconds_to number|nil End timer value in seconds ---@param callback function|nil Function on timer end ----@return druid.timer component Timer component +---@return druid.timer timer The new timer component function M:new_timer(node, seconds_from, seconds_to, callback) return self:new(timer_component, node, seconds_from, seconds_to, callback) end @@ -670,7 +669,7 @@ local progress = require("druid.extended.progress") ---@param node string|node Progress bar fill node or node name ---@param key string Progress bar direction: const.SIDE.X or const.SIDE.Y ---@param init_value number|nil Initial value of progress bar. Default: 1 ----@return druid.progress component Progress component +---@return druid.progress progress The new progress component function M:new_progress(node, key, init_value) return self:new(progress, node, key, init_value) end @@ -680,7 +679,7 @@ local layout = require("druid.extended.layout") ---Create Layout component ---@param node string|node The_node id or gui.get_node(node_id). ---@param mode string|nil vertical|horizontal|horizontal_wrap. Default: horizontal ----@return druid.layout component Layout component +---@return druid.layout layout The new layout component function M:new_layout(node, mode) return self:new(layout, node, mode) end @@ -691,7 +690,7 @@ local container = require("druid.extended.container") ---@param node string|node The_node id or gui.get_node(node_id). ---@param mode string|nil Layout mode ---@param callback fun(self: druid.container, size: vector3)|nil Callback on size changed ----@return druid.container container component +---@return druid.container container The new container component function M:new_container(node, mode, callback) return self:new(container, node, mode, callback) end @@ -702,7 +701,7 @@ local hotkey = require("druid.extended.hotkey") ---@param keys_array string|string[] Keys for trigger action. Should contains one action key and any amount of modificator keys ---@param callback function|event|nil The callback function ---@param callback_argument any|nil The argument to pass into the callback function ----@return druid.hotkey component Hotkey component +---@return druid.hotkey hotkey The new hotkey component function M:new_hotkey(keys_array, callback, callback_argument) return self:new(hotkey, keys_array, callback, callback_argument) end @@ -712,7 +711,7 @@ local rich_text = require("druid.custom.rich_text.rich_text") ---Create RichText component. ---@param text_node string|node The text node to make Rich Text ---@param value string|nil The initial text value. Default will be gui.get_text(text_node) ----@return druid.rich_text component RichText component +---@return druid.rich_text rich_text The new rich text component function M:new_rich_text(text_node, value) return self:new(rich_text, text_node, value) end @@ -723,7 +722,7 @@ local rich_input = require("druid.custom.rich_input.rich_input") -- As a template please check rich_input.gui layout. ---@param template string The template string name ---@param nodes table|nil Nodes table from gui.clone_tree ----@return druid.rich_input component RichInput component +---@return druid.rich_input rich_input The new rich input component function M:new_rich_input(template, nodes) return self:new(rich_input, template, nodes) end