diff --git a/annotations.lua b/annotations.lua index ff99324..f39db15 100644 --- a/annotations.lua +++ b/annotations.lua @@ -1,12 +1,5 @@ ---@class druid ----@field dynamic_grid druid.dynamic_grid Submodule ---@field helper druid.helper Submodule ----@field input druid.input Submodule ----@field lang_text druid.lang_text Submodule ----@field progress druid.progress Submodule ----@field radio_group druid.radio_group Submodule ----@field slider druid.slider Submodule ----@field timer druid.timer Submodule ---@field new fun(context:table, style:table):druid_instance Create Druid instance. ---@field on_language_change fun() Druid on language change. ---@field on_language_change fun() Callback on global language change event. @@ -111,33 +104,26 @@ ---@field DRAG_DEADZONE field Distance in pixels to start dragging ---@class druid.dynamic_grid : druid.base_component ----@field Events druid.dynamic_grid.Events Component events ----@field Fields druid.dynamic_grid.Fields Component fields ----@field DynamicGrid:_get_side_vector fun(side:unknown, is_forward:unknown) Return side vector to correct node shifting ----@field add fun(node:node, index:number, is_shift_left:bool) Add new node to the grid ----@field clear fun():druid.dynamic_grid Clear grid nodes array. ----@field get_all_pos fun():vector3[] Return array of all node positions ----@field get_index_by_node fun(node:node):number Return grid index by node ----@field get_pos fun(index:number, node:node):vector3 Return pos for grid node index ----@field get_size fun():vector3 Return grid content size ----@field init fun(parent:node) Component init function ----@field remove fun(index:number, is_shift_left:bool) Remove the item from the grid. ----@field set_position_function fun(callback:function):druid.dynamic_grid Change set position function for grid nodes. - ----@class druid.dynamic_grid.Events ----@field on_add_item field On item add callback ----@field on_change_items field On item add or remove callback ----@field on_clear field On grid clear callback ----@field on_remove_item field On item remove callback ----@field on_update_positions field On update item positions callback - ----@class druid.dynamic_grid.Fields ----@field border field The size of item content ----@field first_index field The first index of node in grid ----@field last_index field The last index of node in grid ----@field node_size field Item size ----@field nodes field List of all grid nodes ----@field parent field Parent gui node +---@field first_index number The first index of node in grid +---@field last_index number The last index of node in grid +---@field node_size vector3 Item size +---@field nodes node[] List of all grid nodes +---@field on_add_item druid_event On item add callback(self, node, index) +---@field on_change_items druid_event On item add or remove callback(self, index) +---@field on_clear druid_event On grid clear callback(self) +---@field on_remove_item druid_event On item remove callback(self, index) +---@field on_update_positions druid_event On update item positions callback(self) +---@field parent node Parent gui node +---@field _get_side_vector fun(self:unknown, side:unknown, is_forward:unknown) Return side vector to correct node shifting +---@field add fun(self:druid.dynamic_grid, node:node, index:number, is_shift_left:bool) Add new node to the grid +---@field clear fun(self:druid.dynamic_grid):druid.dynamic_grid Clear grid nodes array. +---@field get_all_pos fun(self:druid.dynamic_grid):vector3[] Return array of all node positions +---@field get_index_by_node fun(self:druid.dynamic_grid, node:node):number Return grid index by node +---@field get_pos fun(self:druid.dynamic_grid, index:number, node:node, origin_index:number):vector3 Return pos for grid node index +---@field get_size fun(self:druid.dynamic_grid, border:vector3):vector3 Return grid content size +---@field init fun(self:druid.dynamic_grid, parent:node) Component init function +---@field remove fun(self:druid.dynamic_grid, index:number, is_shift_left:bool) Remove the item from the grid. +---@field set_position_function fun(self:druid.dynamic_grid, callback:function):druid.dynamic_grid Change set position function for grid nodes. ---@class druid.helper ---@field centrate_icon_with_text fun(icon_node:box, text_node:text, margin:number) Center two nodes. @@ -158,33 +144,26 @@ ---@field set_mouse_hover fun(self:druid.hover, state:bool) Set mouse hover state ---@class druid.input : druid.base_component ----@field Events druid.input.Events Component events ----@field Fields druid.input.Fields Component fields ----@field Style druid.input.Style Component style params. ----@field get_text fun():string Return current input field text ----@field reset_changes fun() Reset current input selection and return previous value ----@field set_allowerd_characters fun(characters:string):druid.input Set allowed charaters for input field. ----@field set_max_length fun(max_length:number):druid.input Set maximum length for input field. ----@field set_text fun(input_text:string) Set text for input field +---@field allowerd_characters string Pattern matching for user input +---@field button druid.button Button component +---@field is_empty bool Is current input is empty now +---@field is_selected bool Is current input selected now +---@field max_length number Max length for input text +---@field on_input_empty druid_event On input field text change to empty string callback(self, input_text) +---@field on_input_full druid_event On input field text change to max length string callback(self, input_text) +---@field on_input_select druid_event On input field select callback(self, button_node) +---@field on_input_text druid_event On input field text change callback(self, input_text) +---@field on_input_unselect druid_event On input field unselect callback(self, button_node) +---@field on_input_wrong druid_event On trying user input with not allowed character callback(self, params, button_instance) +---@field style druid.input.style Component style params. +---@field text druid.text Text component +---@field get_text fun(self:druid.input):string Return current input field text +---@field reset_changes fun(self:druid.input) Reset current input selection and return previous value +---@field set_allowed_characters fun(self:druid.input, characters:string):druid.input Set allowed charaters for input field. +---@field set_max_length fun(self:druid.input, max_length:number):druid.input Set maximum length for input field. +---@field set_text fun(self:druid.input, input_text:string) Set text for input field ----@class druid.input.Events ----@field on_input_empty field (self, input_text) On input field text change to empty string callback ----@field on_input_full field (self, input_text) On input field text change to max length string callback ----@field on_input_select field (self, button_node) On input field select callback ----@field on_input_text field (self, input_text) On input field text change callback ----@field on_input_unselect field (self, button_node) On input field unselect callback ----@field on_input_wrong field (self, params, button_instance) On trying user input with not allowed character callback - ----@class druid.input.Fields ----@field allowerd_characters field Pattern matching for user input ----@field button field Button component ----@field is_empty field Is current input is empty now ----@field is_selected field Is current input selected now ----@field keyboard_type field Gui keyboard type for input field ----@field max_length field Max length for input text ----@field text field Text component - ----@class druid.input.Style +---@class druid.input.style ---@field IS_LONGTAP_ERASE field Is long tap will erase current input data ---@field MASK_DEFAULT_CHAR field Default character mask for password input ---@field button_style field Custom button style for input node @@ -193,57 +172,36 @@ ---@field on_unselect field (self, button_node) Callback on input field unselecting ---@class druid.lang_text : druid.base_component ----@field Events druid.lang_text.Events Component events ----@field Fields druid.lang_text.Fields Component fields ----@field init fun(node:node, locale_id:string, no_adjust:bool) Component init function ----@field set_to fun(text:string) Setup raw text to lang_text component ----@field translate fun(locale_id:string) Translate the text by locale_id - ----@class druid.lang_text.Events ----@field on_change field On change text callback - ----@class druid.lang_text.Fields ----@field text field The text component +---@field on_change druid_event On change text callback +---@field init fun(self:druid.lang_text, node:node, locale_id:string, no_adjust:bool) Component init function +---@field set_to fun(self:druid.lang_text, text:string) Setup raw text to lang_text component +---@field translate fun(self:druid.lang_text, locale_id:string) Translate the text by locale_id ---@class druid.progress : druid.base_component ----@field Events druid.progress.Events Component events ----@field Fields druid.progress.Fields Component fields ----@field Style druid.progress.Style Component style params. ----@field empty fun() Empty a progress bar ----@field fill fun() Fill a progress bar and stop progress animation ----@field get fun() Return current progress bar value ----@field init fun(node:string|node, key:string, init_value:number) Component init function ----@field set_steps fun(steps:number[], callback:function) Set points on progress bar to fire the callback ----@field set_to fun(to:number) Instant fill progress bar to value ----@field to fun(to:number, callback:function) Start animation of a progress bar +---@field key string The progress bar direction +---@field max_size number Maximum size of progress bar +---@field node node Progress bar fill node +---@field on_change druid_event On progress bar change callback(self, new_value) +---@field scale vector3 Current progress bar scale +---@field size vector3 Current progress bar size +---@field style druid.progress.style Component style params. +---@field empty fun(self:druid.progress) Empty a progress bar +---@field fill fun(self:druid.progress) Fill a progress bar and stop progress animation +---@field get fun(self:druid.progress) Return current progress bar value +---@field init fun(self:druid.progress, node:string|node, key:string, init_value:number) Component init function +---@field set_steps fun(self:druid.progress, steps:number[], callback:function) Set points on progress bar to fire the callback +---@field set_to fun(self:druid.progress, to:number) Instant fill progress bar to value +---@field to fun(self:druid.progress, to:number, callback:function) Start animation of a progress bar ----@class druid.progress.Events ----@field on_change field On progress bar change callback - ----@class druid.progress.Fields ----@field key field The progress bar direction ----@field max_size field Maximum size of progress bar ----@field node field Progress bar fill node ----@field scale field Current progress bar scale ----@field size field Current progress bar size ----@field slice field Progress bar slice9 settings - ----@class druid.progress.Style +---@class druid.progress.style ---@field MIN_DELTA field Minimum step to fill progress bar ---@field SPEED field Progress bas fill rate. More -> faster ---@class druid.radio_group : druid.base_component ----@field Events druid.radio_group.Events Component events ----@field Fields druid.radio_group.Fields Component fields ----@field get_state fun():number Return radio group state ----@field init fun(node:node[], callback:function, click:node[]) Component init function ----@field set_state fun(index:number) Set radio group state - ----@class druid.radio_group.Events ----@field on_radio_click field On any checkbox click - ----@class druid.radio_group.Fields ----@field checkboxes field Array of checkbox components +---@field on_radio_click druid_event On any checkbox click +---@field get_state fun(self:druid.radio_group):number Return radio group state +---@field init fun(self:druid.radio_group, nodes:node[], callback:function, click_nodes:node[]) Component init function +---@field set_state fun(self:druid.radio_group, index:number) Set radio group state ---@class druid.scroll : druid.base_component ---@field available_pos vector4 Available position for content node: (min_x, max_y, max_x, min_y) @@ -288,24 +246,17 @@ ---@field SMALL_CONTENT_SCROLL field If true, content node with size less than view node size can be scrolled ---@class druid.slider : druid.base_component ----@field Events druid.slider.Events Component events ----@field Fields druid.slider.Fields Component fields ----@field init fun(node:node, end_pos:vector3, callback:function) Component init function ----@field set fun(value:number, is_silent:bool) Set value for slider ----@field set_steps fun(steps:number[]) Set slider steps. - ----@class druid.slider.Events ----@field on_change_value field On change value callback - ----@class druid.slider.Fields ----@field dist field Length between start and end position ----@field end_pos field End pin node position ----@field is_drag field Current drag state ----@field node field Slider pin node ----@field pos field Current pin node position ----@field start_pos field Start pin node position ----@field target_pos field Targer pin node position ----@field value field Current slider value +---@field dist number Length between start and end position +---@field end_pos vector3 End pin node position +---@field is_drag bool Current drag state +---@field node node Slider pin node +---@field on_change_value druid_event On change value callback(self, value) +---@field pos vector3 Current pin node position +---@field start_pos vector3 Start pin node position +---@field target_pos vector3 Targer pin node position +---@field init fun(self:druid.slider, node:node, end_pos:vector3, callback:function) Component init function +---@field set fun(self:druid.slider, value:number, is_silent:bool) Set value for slider +---@field set_steps fun(self:druid.slider, steps:number[]) Set slider steps. ---@class druid.static_grid : druid.base_component ---@field anchor vector3 Item anchor @@ -364,23 +315,16 @@ ---@field set_to fun(self:druid.text, set_to:string) Set text to text field ---@class druid.timer : druid.base_component ----@field Events druid.timer.Events Component events ----@field Fields druid.timer.Fields Component fields ----@field init fun(node:node, seconds_from:number, seconds_to:number, callback:function) Component init function ----@field set_interval fun(from:number, to:number) Set time interval ----@field set_state fun(is_on:bool) Called when update ----@field set_to fun(set_to:number) Set text to text field - ----@class druid.timer.Events ----@field on_set_enabled field On timer change enabled state callback ----@field on_tick field On timer tick callback. Fire every second ----@field on_timer_end field On timer end callback - ----@class druid.timer.Fields ----@field from field Initial timer value ----@field node field Trigger node ----@field target field Target timer value ----@field value field Current timer value +---@field from number Initial timer value +---@field node node Trigger node +---@field on_set_enabled druid_event On timer change enabled state callback(self, is_enabled) +---@field on_tick druid_event On timer tick. +---@field on_timer_end druid_event On timer end callback +---@field target number Target timer value +---@field init fun(self:druid.timer, node:node, seconds_from:number, seconds_to:number, callback:function) Component init function +---@field set_interval fun(self:druid.timer, from:number, to:number) Set time interval +---@field set_state fun(self:druid.timer, is_on:bool) Called when update +---@field set_to fun(self:druid.timer, set_to:number) Set text to text field ---@class druid_event ---@field clear fun(self:druid_event) Clear the all event handlers diff --git a/druid/extended/dynamic_grid.lua b/druid/extended/dynamic_grid.lua index 8e88ce5..efa6f0a 100644 --- a/druid/extended/dynamic_grid.lua +++ b/druid/extended/dynamic_grid.lua @@ -1,24 +1,41 @@ --- Component to handle placing components in row --- @module druid.dynamic_grid +-- @module DynamicGrid -- @within BaseComponent -- @alias druid.dynamic_grid ---- Component events --- @table Events --- @tfield druid_event on_add_item On item add callback --- @tfield druid_event on_remove_item On item remove callback --- @tfield druid_event on_change_items On item add or remove callback --- @tfield druid_event on_clear On grid clear callback --- @tfield druid_event on_update_positions On update item positions callback +--- On item add callback(self, node, index) +-- @tfield druid_event on_add_item + +--- On item remove callback(self, index) +-- @tfield druid_event on_remove_item + +--- On item add or remove callback(self, index) +-- @tfield druid_event on_change_items + +--- On grid clear callback(self) +-- @tfield druid_event on_clear + +--- On update item positions callback(self) +-- @tfield druid_event on_update_positions + +--- Parent gui node +-- @tfield node parent + +--- List of all grid nodes +-- @tfield node[] nodes + +--- The first index of node in grid +-- @tfield number first_index + +--- The last index of node in grid +-- @tfield number last_index + +--- Item size +-- @tfield vector3 node_size + +--- The size of item content +-- @tfield vector4 border ---- Component fields --- @table Fields --- @tfield node parent Parent gui node --- @tfield node[] nodes List of all grid nodes --- @tfield number first_index The first index of node in grid --- @tfield number last_index The last index of node in grid --- @tfield vector3 node_size Item size --- @tfield vector4 border The size of item content local const = require("druid.const") local Event = require("druid.event") @@ -44,9 +61,9 @@ local AVAILABLE_PIVOTS = { --- Component init function --- @function dynamic_grid:init +-- @tparam DynamicGrid self -- @tparam node parent The gui node parent, where items will be placed -function DynamicGrid:init(parent) +function DynamicGrid.init(self, parent) self.parent = self:get_node(parent) local parent_pivot = gui.get_pivot(self.parent) @@ -69,17 +86,18 @@ function DynamicGrid:init(parent) end -function DynamicGrid:on_layout_change() +function DynamicGrid.on_layout_change(self) self:_update(true) end --- Return pos for grid node index --- @function dynamic_grid:get_pos +-- @tparam DynamicGrid self -- @tparam number index The grid element index -- @tparam node node The node to be placed +-- @tparam[opt] number origin_index Index of nearby node -- @treturn vector3 Node position -function DynamicGrid:get_pos(index, node, origin_index) +function DynamicGrid.get_pos(self, index, node, origin_index) local origin_node = self.nodes[origin_index] -- If anchor node is not exist, check around nodes @@ -115,11 +133,11 @@ end --- Add new node to the grid --- @function dynamic_grid:add +-- @tparam DynamicGrid self -- @tparam node node Gui node -- @tparam[opt] number index The node position. By default add as last node -- @tparam[opt=false] bool is_shift_left If true, shift all nodes to the left, otherwise shift nodes to the right -function DynamicGrid:add(node, index, is_shift_left) +function DynamicGrid.add(self, node, index, is_shift_left) local delta = is_shift_left and -1 or 1 -- By default add node at end @@ -157,10 +175,10 @@ end --- Remove the item from the grid. Note that gui node will be not deleted --- @function dynamic_grid:remove +-- @tparam DynamicGrid self -- @tparam number index The grid node index to remove -- @tparam[opt=false] bool is_shift_left If true, shift all nodes to the left, otherwise shift nodes to the right -function DynamicGrid:remove(index, is_shift_left) +function DynamicGrid.remove(self, index, is_shift_left) local delta = is_shift_left and -1 or 1 assert(self.nodes[index], "No grid item at given index " .. index) @@ -180,15 +198,16 @@ function DynamicGrid:remove(index, is_shift_left) -- Sync grid data self:_update() - self.on_add_item:trigger(self:get_context(), index) + self.on_remove_item:trigger(self:get_context(), index) self.on_change_items:trigger(self:get_context(), index) end --- Return grid content size --- @function dynamic_grid:get_size +-- @tparam DynamicGrid self +-- @tparam vector3 border -- @treturn vector3 The grid content size -function DynamicGrid:get_size(border) +function DynamicGrid.get_size(self, border) border = border or self.border return vmath.vector3( border.z - border.x, @@ -198,10 +217,10 @@ end --- Return grid index by node --- @function dynamic_grid:get_index_by_node +-- @tparam DynamicGrid self -- @tparam node node The gui node in the grid -- @treturn number The node index -function DynamicGrid:get_index_by_node(node) +function DynamicGrid.get_index_by_node(self, node) for index, node_info in pairs(self.nodes) do if node == node_info.node then return index @@ -213,9 +232,9 @@ end --- Return array of all node positions --- @function dynamic_grid:get_all_pos +-- @tparam DynamicGrid self -- @treturn vector3[] All grid node positions -function DynamicGrid:get_all_pos() +function DynamicGrid.get_all_pos(self) local result = {} for i, node in pairs(self.nodes) do table.insert(result, gui.get_position(node)) @@ -227,10 +246,10 @@ end --- Change set position function for grid nodes. It will call on -- update poses on grid elements. Default: gui.set_position --- @function dynamic_grid:set_position_function +-- @tparam DynamicGrid self -- @tparam function callback Function on node set position -- @treturn druid.dynamic_grid Current grid instance -function DynamicGrid:set_position_function(callback) +function DynamicGrid.set_position_function(self, callback) self._set_position_function = callback or gui.set_position return self end @@ -238,16 +257,19 @@ end --- Clear grid nodes array. GUI nodes will be not deleted! -- If you want to delete GUI nodes, use dynamic_grid.nodes array before grid:clear --- @function dynamic_grid:clear +-- @tparam DynamicGrid self -- @treturn druid.dynamic_grid Current grid instance -function DynamicGrid:clear() +function DynamicGrid.clear(self) self.nodes = {} self:_update() + + self.on_clear:trigger(self:get_context()) + return self end -function DynamicGrid:_add_node(node, index, origin_index) +function DynamicGrid._add_node(self, node, index, origin_index) self.nodes[index] = { node = node, pos = self:get_pos(index, node, origin_index), @@ -262,10 +284,10 @@ end --- Update grid inner state --- @function dynamic_grid:_update +-- @tparam DynamicGrid self -- @tparam bool is_instant If true, node position update instantly, otherwise with set_position_function callback -- @local -function DynamicGrid:_update(is_instant) +function DynamicGrid._update(self, is_instant) self:_update_indexes() self:_update_borders() self:_update_pos(is_instant) @@ -273,9 +295,9 @@ end --- Update first and last indexes of grid nodes --- @function dynamic_grid:_update_indexes +-- @tparam DynamicGrid self -- @local -function DynamicGrid:_update_indexes() +function DynamicGrid._update_indexes(self) self.first_index = nil self.last_index = nil for index in pairs(self.nodes) do @@ -289,9 +311,9 @@ end --- Update grid content borders, recalculate min and max values --- @function dynamic_grid:_update_borders +-- @tparam DynamicGrid self -- @local -function DynamicGrid:_update_borders() +function DynamicGrid._update_borders(self) if not self.first_index then self.border = vmath.vector4(0) return @@ -318,10 +340,10 @@ end --- Update grid nodes position --- @function dynamic_grid:_update_indexes +-- @tparam DynamicGrid self -- @tparam bool is_instant If true, node position update instantly, otherwise with set_position_function callback -- @local -function DynamicGrid:_update_pos(is_instant) +function DynamicGrid._update_pos(self, is_instant) local offset = self:_get_zero_offset() for index, node in pairs(self.nodes) do @@ -336,7 +358,7 @@ function DynamicGrid:_update_pos(is_instant) end -function DynamicGrid:_get_next_node_pos(origin_node_index, new_node, place_side) +function DynamicGrid._get_next_node_pos(self, origin_node_index, new_node, place_side) local node = self.nodes[origin_node_index] local new_node_size = self:_get_node_size(new_node) @@ -355,17 +377,17 @@ function DynamicGrid:_get_next_node_pos(origin_node_index, new_node, place_side) end -function DynamicGrid:_get_node_size(node) +function DynamicGrid._get_node_size(self, node) return vmath.mul_per_elem(gui.get_size(node), gui.get_scale(node)) end --- Return elements offset for correct posing nodes. Correct posing at -- parent pivot node (0:0) with adjusting of node sizes and anchoring --- @function dynamic_grid:_get_zero_offset +-- @tparam DynamicGrid self -- @treturn vector3 The offset vector -- @local -function DynamicGrid:_get_zero_offset() +function DynamicGrid._get_zero_offset(self) -- zero offset: center pos - border size * anchor return vmath.vector3( -((self.border.x + self.border.z)/2 + (self.border.z - self.border.x) * self.pivot.x), @@ -375,7 +397,7 @@ end --- Return side vector to correct node shifting -function DynamicGrid:_get_side_vector(side, is_forward) +function DynamicGrid._get_side_vector(self, side, is_forward) if side == const.SIDE.X then return is_forward and SIDE_VECTORS.RIGHT or SIDE_VECTORS.LEFT end diff --git a/druid/extended/input.lua b/druid/extended/input.lua index 0bc783c..0ea8db5 100644 --- a/druid/extended/input.lua +++ b/druid/extended/input.lua @@ -1,28 +1,49 @@ --- Druid input text component. -- Carry on user text input -- @author Part of code from Britzl gooey input component --- @module druid.input +-- @module Input -- @within BaseComponent -- @alias druid.input ---- Component events --- @table Events --- @tfield druid_event on_input_select (self, button_node) On input field select callback --- @tfield druid_event on_input_unselect (self, button_node) On input field unselect callback --- @tfield druid_event on_input_text (self, input_text) On input field text change callback --- @tfield druid_event on_input_empty (self, input_text) On input field text change to empty string callback --- @tfield druid_event on_input_full (self, input_text) On input field text change to max length string callback --- @tfield druid_event on_input_wrong (self, params, button_instance) On trying user input with not allowed character callback +--- On input field select callback(self, button_node) +-- @tfield druid_event on_input_select + +--- On input field unselect callback(self, button_node) +-- @tfield druid_event on_input_unselect + +--- On input field text change callback(self, input_text) +-- @tfield druid_event on_input_text + +--- On input field text change to empty string callback(self, input_text) +-- @tfield druid_event on_input_empty + +--- On input field text change to max length string callback(self, input_text) +-- @tfield druid_event on_input_full + +--- On trying user input with not allowed character callback(self, params, button_instance) +-- @tfield druid_event on_input_wrong + +--- Text component +-- @tfield druid.text text + +--- Button component +-- @tfield druid.button button + +--- Is current input selected now +-- @tfield bool is_selected + +--- Is current input is empty now +-- @tfield bool is_empty + +--- Max length for input text +-- @tfield[opt] number max_length + +--- Pattern matching for user input +-- @tfield[opt] string allowerd_characters + +--- Gui keyboard type for input field +-- @tfield number keyboard_type ---- Component fields --- @table Fields --- @tfield druid.text text Text component --- @tfield druid.button button Button component --- @tfield bool is_selected Is current input selected now --- @tfield bool is_empty Is current input is empty now --- @tfield[opt] number max_length Max length for input text --- @tfield[opt] string allowerd_characters Pattern matching for user input --- @tfield number keyboard_type Gui keyboard type for input field local Event = require("druid.event") local const = require("druid.const") @@ -92,14 +113,14 @@ end --- Component style params. -- You can override this component styles params in druid styles table -- or create your own style --- @table Style +-- @table style -- @tfield[opt=false] bool IS_LONGTAP_ERASE Is long tap will erase current input data -- @tfield[opt=*] string MASK_DEFAULT_CHAR Default character mask for password input -- @tfield function on_select (self, button_node) Callback on input field selecting -- @tfield function on_unselect (self, button_node) Callback on input field unselecting -- @tfield function on_input_wrong (self, button_node) Callback on wrong user input -- @tfield table button_style Custom button style for input node -function Input:on_style_change(style) +function Input.on_style_change(self, style) self.style = {} self.style.IS_LONGTAP_ERASE = style.IS_LONGTAP_ERASE or false @@ -117,7 +138,7 @@ function Input:on_style_change(style) end -function Input:init(click_node, text_node, keyboard_type) +function Input.init(self, click_node, text_node, keyboard_type) self.druid = self:get_druid(self) self.text = self.druid:new_text(text_node) @@ -151,7 +172,7 @@ function Input:init(click_node, text_node, keyboard_type) end -function Input:on_input(action_id, action) +function Input.on_input(self, action_id, action) if self.selected then local input_text = nil if action_id == const.ACTION_TEXT then @@ -215,20 +236,20 @@ function Input:on_input(action_id, action) end -function Input:on_focus_lost() +function Input.on_focus_lost(self) unselect(self) end -function Input:on_input_interrupt() +function Input.on_input_interrupt(self) -- unselect(self) end --- Set text for input field --- @function input:set_text +-- @tparam Input self -- @tparam string input_text The string to apply for input field -function Input:set_text(input_text) +function Input.set_text(self, input_text) -- Case when update with marked text if input_text then self.value = input_text @@ -273,19 +294,19 @@ end --- Return current input field text --- @function input:get_text +-- @tparam Input self -- @treturn string The current input field text -function Input:get_text() +function Input.get_text(self) return self.value .. self.marked_value end --- Set maximum length for input field. -- Pass nil to make input field unliminted (by default) --- @function input:set_max_length +-- @tparam Input self -- @tparam number max_length Maximum length for input text field -- @treturn druid.input Current input instance -function Input:set_max_length(max_length) +function Input.set_max_length(self, max_length) self.max_length = max_length return self end @@ -294,18 +315,18 @@ end --- Set allowed charaters for input field. -- See: https://defold.com/ref/stable/string/ -- ex: [%a%d] for alpha and numeric --- @function input:set_allowerd_characters +-- @tparam Input self -- @tparam string characters Regulax exp. for validate user input -- @treturn druid.input Current input instance -function Input:set_allowed_characters(characters) +function Input.set_allowed_characters(self, characters) self.allowed_characters = characters return self end --- Reset current input selection and return previous value --- @function input:reset_changes -function Input:reset_changes() +-- @tparam Input self +function Input.reset_changes(self) self:set_text(self.previous_value) unselect(self) end diff --git a/druid/extended/lang_text.lua b/druid/extended/lang_text.lua index 04f82ef..b51992c 100644 --- a/druid/extended/lang_text.lua +++ b/druid/extended/lang_text.lua @@ -1,16 +1,15 @@ --- Component to handle all GUI texts -- Good working with localization system --- @module druid.lang_text +-- @module LangText -- @within BaseComponent -- @alias druid.lang_text ---- Component events --- @table Events --- @tfield druid_event on_change On change text callback +--- On change text callback +-- @tfield druid_event on_change + +--- The text component +-- @tfield Text text ---- Component fields --- @table Fields --- @tfield druid.text text The text component local Event = require("druid.event") local const = require("druid.const") @@ -21,11 +20,11 @@ local LangText = component.create("lang_text", { const.ON_LANGUAGE_CHANGE }) --- Component init function --- @function lang_text:init +-- @tparam LangText self -- @tparam node node The text node -- @tparam string locale_id Default locale id -- @tparam bool no_adjust If true, will not correct text size -function LangText:init(node, locale_id, no_adjust) +function LangText.init(self, node, locale_id, no_adjust) self.druid = self:get_druid() self.text = self.druid:new_text(node, locale_id, no_adjust) self.last_locale_args = {} @@ -38,7 +37,7 @@ function LangText:init(node, locale_id, no_adjust) end -function LangText:on_language_change() +function LangText.on_language_change(self) if self.last_locale then self:translate(self.last_locale, unpack(self.last_locale_args)) end @@ -46,9 +45,9 @@ end --- Setup raw text to lang_text component --- @function lang_text:set_to +-- @tparam LangText self -- @tparam string text Text for text node -function LangText:set_to(text) +function LangText.set_to(self, text) self.last_locale = false self.text:set_to(text) self.on_change:trigger() @@ -56,9 +55,9 @@ end --- Translate the text by locale_id --- @function lang_text:translate +-- @tparam LangText self -- @tparam string locale_id Locale id -function LangText:translate(locale_id, ...) +function LangText.translate(self, locale_id, ...) self.last_locale_args = {...} self.last_locale = locale_id or self.last_locale self.text:set_to(settings.get_text(self.last_locale, ...)) diff --git a/druid/extended/progress.lua b/druid/extended/progress.lua index 87171fe..fb257e1 100644 --- a/druid/extended/progress.lua +++ b/druid/extended/progress.lua @@ -1,21 +1,30 @@ --- Basic progress bar component. -- For correct progress bar init it should be in max size from gui --- @module druid.progress +-- @module Progress -- @within BaseComponent -- @alias druid.progress ---- Component events --- @table Events --- @tfield druid_event on_change On progress bar change callback +--- On progress bar change callback(self, new_value) +-- @tfield druid_event on_change + +--- Progress bar fill node +-- @tfield node node + +--- The progress bar direction +-- @tfield string key + +--- Current progress bar scale +-- @tfield vector3 scale + +--- Current progress bar size +-- @tfield vector3 size + +--- Maximum size of progress bar +-- @tfield number max_size + +--- Progress bar slice9 settings +-- @tfield vector4 slice ---- Component fields --- @table Fields --- @tfield node node Progress bar fill node --- @tfield string key The progress bar direction --- @tfield vector3 scale Current progress bar scale --- @tfield vector3 size Current progress bar size --- @tfield number max_size Maximum size of progress bar --- @tfield vector4 slice Progress bar slice9 settings local Event = require("druid.event") local const = require("druid.const") @@ -70,10 +79,10 @@ end --- Component style params. -- You can override this component styles params in druid styles table -- or create your own style --- @table Style +-- @table style -- @tfield[opt=5] number SPEED Progress bas fill rate. More -> faster -- @tfield[opt=0.005] number MIN_DELTA Minimum step to fill progress bar -function Progress:on_style_change(style) +function Progress.on_style_change(self, style) self.style = {} self.style.SPEED = style.SPEED or 5 self.style.MIN_DELTA = style.MIN_DELTA or 0.005 @@ -81,11 +90,11 @@ end --- Component init function --- @function progress:init +-- @tparam Progress self -- @tparam string|node node Progress bar fill node or node name -- @tparam string key Progress bar direction: const.SIDE.X or const.SIDE.Y -- @tparam[opt=1] number init_value Initial value of progress bar -function Progress:init(node, key, init_value) +function Progress.init(self, node, key, init_value) assert(key == const.SIDE.X or const.SIDE.Y, "Progress bar key should be 'x' or 'y'") self.prop = hash("scale."..key) @@ -108,12 +117,12 @@ function Progress:init(node, key, init_value) end -function Progress:on_layout_change() +function Progress.on_layout_change(self) self:set_to(self.last_value) end -function Progress:update(dt) +function Progress.update(self, dt) if self.target then local prev_value = self.last_value local step = math.abs(self.last_value - self.target) * (self.style.SPEED*dt) @@ -134,50 +143,50 @@ end --- Fill a progress bar and stop progress animation --- @function progress:fill -function Progress:fill() +-- @tparam Progress self +function Progress.fill(self) set_bar_to(self, 1, true) end --- Empty a progress bar --- @function progress:empty -function Progress:empty() +-- @tparam Progress self +function Progress.empty(self) set_bar_to(self, 0, true) end --- Instant fill progress bar to value --- @function progress:set_to +-- @tparam Progress self -- @tparam number to Progress bar value, from 0 to 1 -function Progress:set_to(to) +function Progress.set_to(self, to) set_bar_to(self, to) end --- Return current progress bar value --- @function progress:get -function Progress:get() +-- @tparam Progress self +function Progress.get(self) return self.last_value end --- Set points on progress bar to fire the callback --- @function progress:set_steps +-- @tparam Progress self -- @tparam number[] steps Array of progress bar values -- @tparam function callback Callback on intersect step value -- @usage progress:set_steps({0, 0.3, 0.6, 1}, function(self, step) end) -function Progress:set_steps(steps, callback) +function Progress.set_steps(self, steps, callback) self.steps = steps self.step_callback = callback end --- Start animation of a progress bar --- @function progress:to +-- @tparam Progress self -- @tparam number to value between 0..1 -- @tparam[opt] function callback Callback on animation ends -function Progress:to(to, callback) +function Progress.to(self, to, callback) to = helper.clamp(to, 0, 1) -- cause of float error local value = helper.round(to, 5) diff --git a/druid/extended/radio_group.lua b/druid/extended/radio_group.lua index c5345dd..9bdbd9c 100644 --- a/druid/extended/radio_group.lua +++ b/druid/extended/radio_group.lua @@ -1,15 +1,14 @@ --- Radio group module --- @module druid.radio_group +-- @module RadioGroup -- @within BaseComponent -- @alias druid.radio_group ---- Component events --- @table Events --- @tfield druid_event on_radio_click On any checkbox click +--- On any checkbox click +-- @tfield druid_event on_radio_click + +--- Array of checkbox components +-- @tfield Checkbox[] checkboxes ---- Component fields --- @table Fields --- @tfield table checkboxes Array of checkbox components local Event = require("druid.event") local component = require("druid.component") @@ -27,11 +26,11 @@ end --- Component init function --- @function radio_group:init --- @tparam node[] node Array of gui node +-- @tparam RadioGroup self +-- @tparam node[] nodes Array of gui node -- @tparam function callback Radio callback --- @tparam[opt=node] node[] click node Array of trigger nodes, by default equals to nodes -function RadioGroup:init(nodes, callback, click_nodes) +-- @tparam[opt=node] node[] click_nodes Array of trigger nodes, by default equals to nodes +function RadioGroup.init(self, nodes, callback, click_nodes) self.druid = self:get_druid() self.checkboxes = {} @@ -49,17 +48,17 @@ end --- Set radio group state --- @function radio_group:set_state +-- @tparam RadioGroup self -- @tparam number index Index in radio group -function RadioGroup:set_state(index) +function RadioGroup.set_state(self, index) on_checkbox_click(self, index) end --- Return radio group state --- @function radio_group:get_state +-- @tparam RadioGroup self -- @treturn number Index in radio group -function RadioGroup:get_state() +function RadioGroup.get_state(self) local result = -1 for i = 1, #self.checkboxes do diff --git a/druid/extended/slider.lua b/druid/extended/slider.lua index 30ccaf6..e890a5e 100644 --- a/druid/extended/slider.lua +++ b/druid/extended/slider.lua @@ -1,22 +1,35 @@ --- Druid slider component --- @module druid.slider +-- @module Slider -- @within BaseComponent -- @alias druid.slider ---- Component events --- @table Events --- @tfield druid_event on_change_value On change value callback +--- On change value callback(self, value) +-- @tfield druid_event on_change_value + +--- Slider pin node +-- @tfield node node + +--- Start pin node position +-- @tfield vector3 start_pos + +--- Current pin node position +-- @tfield vector3 pos + +--- Targer pin node position +-- @tfield vector3 target_pos + +--- End pin node position +-- @tfield vector3 end_pos + +--- Length between start and end position +-- @tfield number dist + +--- Current drag state +-- @tfield bool is_drag + +--- Current slider value +-- @tfield number value ---- Component fields --- @table Fields --- @tfield node node Slider pin node --- @tfield vector3 start_pos Start pin node position --- @tfield vector3 pos Current pin node position --- @tfield vector3 target_pos Targer pin node position --- @tfield vector3 end_pos End pin node position --- @tfield number dist Length between start and end position --- @tfield bool is_drag Current drag state --- @tfield number value Current slider value local Event = require("druid.event") @@ -39,11 +52,11 @@ end --- Component init function --- @function slider:init +-- @tparam Slider self -- @tparam node node Gui pin node -- @tparam vector3 end_pos The end position of slider -- @tparam[opt] function callback On slider change callback -function Slider:init(node, end_pos, callback) +function Slider.init(self, node, end_pos, callback) self.node = self:get_node(node) self.start_pos = gui.get_position(self.node) @@ -61,12 +74,12 @@ function Slider:init(node, end_pos, callback) end -function Slider:on_layout_change() +function Slider.on_layout_change(self, ) self:set(self.value, true) end -function Slider:on_input(action_id, action) +function Slider.on_input(self, action_id, action) if action_id ~= const.ACTION_TOUCH then return false end @@ -132,10 +145,10 @@ end --- Set value for slider --- @function slider:set +-- @tparam Slider self -- @tparam number value Value from 0 to 1 -- @tparam[opt] bool is_silent Don't trigger event if true -function Slider:set(value, is_silent) +function Slider.set(self, value, is_silent) value = helper.clamp(value, 0, 1) set_position(self, value) self.value = value @@ -147,10 +160,10 @@ end --- Set slider steps. Pin node will -- apply closest step position --- @function slider:set_steps +-- @tparam Slider self -- @tparam number[] steps Array of steps -- @usage slider:set_steps({0, 0.2, 0.6, 1}) -function Slider:set_steps(steps) +function Slider.set_steps(self, steps) self.steps = steps end diff --git a/druid/extended/timer.lua b/druid/extended/timer.lua index 7f50cf7..5ae1ba8 100644 --- a/druid/extended/timer.lua +++ b/druid/extended/timer.lua @@ -1,22 +1,31 @@ --- Component to handle GUI timers. -- Timer updating by game delta time. If game is not focused - -- timer will be not updated. --- @module druid.timer +-- @module Timer -- @within BaseComponent -- @alias druid.timer ---- Component events --- @table Events --- @tfield druid_event on_tick On timer tick callback. Fire every second --- @tfield druid_event on_set_enabled On timer change enabled state callback --- @tfield druid_event on_timer_end On timer end callback +--- On timer tick. Fire every second callback(self, value) +-- @tfield druid_event on_tick + +--- On timer change enabled state callback(self, is_enabled) +-- @tfield druid_event on_set_enabled + +--- On timer end callback +-- @tfield druid_event on_timer_end(self, Timer) + +--- Trigger node +-- @tfield node node + +--- Initial timer value +-- @tfield number from + +--- Target timer value +-- @tfield number target + +--- Current timer value +-- @tfield number value ---- Component fields --- @table Fields --- @tfield node node Trigger node --- @tfield number from Initial timer value --- @tfield number target Target timer value --- @tfield number value Current timer value local Event = require("druid.event") local const = require("druid.const") @@ -28,12 +37,12 @@ local Timer = component.create("timer", { const.ON_UPDATE }) --- Component init function --- @function timer:init +-- @tparam Timer self -- @tparam node node Gui text node -- @tparam number seconds_from Start timer value in seconds -- @tparam[opt=0] number seconds_to End timer value in seconds -- @tparam[opt] function callback Function on timer end -function Timer:init(node, seconds_from, seconds_to, callback) +function Timer.init(self, node, seconds_from, seconds_to, callback) self.node = self:get_node(node) seconds_from = math.max(seconds_from, 0) seconds_to = math.max(seconds_to or 0, 0) @@ -54,7 +63,7 @@ function Timer:init(node, seconds_from, seconds_to, callback) end -function Timer:update(dt) +function Timer.update(self, dt) if not self.is_on then return end @@ -77,18 +86,18 @@ function Timer:update(dt) end --- Set text to text field --- @function timer:set_to +-- @tparam Timer self -- @tparam number set_to Value in seconds -function Timer:set_to(set_to) +function Timer.set_to(self, set_to) self.last_value = set_to gui.set_text(self.node, formats.second_string_min(set_to)) end --- Called when update --- @function timer:set_state +-- @tparam Timer self -- @tparam bool is_on Timer enable state -function Timer:set_state(is_on) +function Timer.set_state(self, is_on) self.is_on = is_on self.on_set_enabled:trigger(self:get_context(), is_on) @@ -96,10 +105,10 @@ end --- Set time interval --- @function timer:set_interval +-- @tparam Timer self -- @tparam number from Start time in seconds -- @tparam number to Target time in seconds -function Timer:set_interval(from, to) +function Timer.set_interval(self, from, to) self.from = from self.value = from self.temp = 0 diff --git a/druid/system/druid_instance.lua b/druid/system/druid_instance.lua index f4994e6..a5f6562 100644 --- a/druid/system/druid_instance.lua +++ b/druid/system/druid_instance.lua @@ -12,18 +12,18 @@ -- @see Button -- @see Blocker -- @see BackHandler --- @see druid.input +-- @see Input -- @see Text --- @see druid.lang_text --- @see druid.timer --- @see druid.progress +-- @see LangText +-- @see Timer +-- @see Progress -- @see StaticGrid --- @see druid.dynamic_grid +-- @see DynamicGrid -- @see Scroll --- @see druid.slider +-- @see Slider -- @see Checkbox -- @see CheckboxGroup --- @see druid.radio_group +-- @see RadioGroup -- @see Swipe -- @see Drag -- @see Hover