diff --git a/annotations.lua b/annotations.lua new file mode 100644 index 0000000..f39db15 --- /dev/null +++ b/annotations.lua @@ -0,0 +1,371 @@ +---@class druid +---@field helper druid.helper 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. +---@field on_layout_change fun() Callback on global layout change event. +---@field on_window_callback fun(event:string) Callback on global window event. +---@field register fun(name:string, module:table) Register external druid component. +---@field set_default_style fun(style:table) Set new default style. +---@field set_sound_function fun(callback:function) Set sound function. +---@field set_text_function fun(callback:function) Set text function Druid locale component will call this function to get translated text. + +---@class druid.back_handler : druid.base_component +---@field on_back druid_event On back handler callback(self, params) +---@field init fun(self:druid.back_handler, callback:callback, params:any) Component init function +---@field on_input fun(self:druid.back_handler, action_id:string, action:table) Input handler for component + +---@class druid.base_component +---@field get_context fun(self:druid.base_component):table Get current component context +---@field get_druid fun(self:druid.base_component):Druid Return druid with context of calling component. +---@field get_name fun(self:druid.base_component):string Return component name +---@field get_node fun(self:druid.base_component, node_or_name:string|node):node Get node for component by name. +---@field get_parent_component fun(self:druid.base_component):druid.base_component|nil Return the parent for current component +---@field increase_input_priority fun(self:druid.base_component) Increase input priority in current input stack +---@field reset_input_priority fun(self:druid.base_component) Reset input priority in current input stack +---@field set_input_enabled fun(self:druid.base_component, state:bool):druid.base_component Set component input state. +---@field set_nodes fun(self:druid.base_component, nodes:table) Set current component nodes +---@field set_style fun(self:druid.base_component, druid_style:table) Set current component style table. +---@field set_template fun(self:druid.base_component, template:string) Set current component template name +---@field setup_component fun(self:druid.base_component, druid_instance:table, context:table, style:table):component Setup component context and his style table + +---@class druid.blocker : druid.base_component +---@field init fun(self:druid.blocker, node:node) Component init function +---@field is_enabled fun(self:druid.blocker):bool Return blocked enabled state +---@field set_enabled fun(self:druid.blocker, state:bool) Set enabled blocker component state + +---@class druid.button : druid.base_component +---@field anim_node node Animation node +---@field hover druid.hover Druid hover logic component +---@field node node Trigger node +---@field on_click druid_event On release button callback(self, params, button_instance) +---@field on_click_outside druid_event On click outside of button(self, params, button_instance) +---@field on_double_click druid_event On double tap button callback(self, params, button_instance, click_amount) +---@field on_hold_callback druid_event On button hold before long_click callback(self, params, button_instance, time) +---@field on_long_click druid_event On long tap button callback(self, params, button_instance, time) +---@field on_repeated_click druid_event On repeated action button callback(self, params, button_instance, click_amount) +---@field params any Params to click callbacks +---@field pos vector3 Initial pos of anim_node +---@field start_pos vector3 Initial pos of anim_node +---@field start_scale vector3 Initial scale of anim_node +---@field style druid.button.style Component style params. +---@field get_key_trigger fun(self:druid.button):hash Get key-code to trigger this button +---@field init fun(self:druid.button, node:node, callback:function, params:table, anim_node:node) Component init function +---@field is_enabled fun(self:druid.button):bool Return button enabled state +---@field set_click_zone fun(self:druid.button, zone:node):druid.button Strict button click area. +---@field set_enabled fun(self:druid.button, state:bool):druid.button Set enabled button component state +---@field set_key_trigger fun(self:druid.button, key:hash):druid.button Set key-code to trigger this button + +---@class druid.button.style +---@field AUTOHOLD_TRIGGER field Maximum hold time to trigger button release while holding +---@field DOUBLETAP_TIME field Time between double taps +---@field LONGTAP_TIME field Minimum time to trigger on_hold_callback +---@field on_click field (self, node) +---@field on_click_disabled field (self, node) +---@field on_hover field (self, node, hover_state) +---@field on_mouse_hover field (self, node, hover_state) +---@field on_set_enabled field (self, node, enabled_state) + +---@class druid.checkbox : druid.base_component +---@field click_node node Button trigger node +---@field node node Visual node +---@field on_change_state druid_event On change state callback(self, state) +---@field style druid.checkbox.style Component style params. +---@field get_state fun(self:druid.checkbox):bool Return checkbox state +---@field init fun(self:druid.checkbox, node:node, callback:function, click_node:node) Component init function +---@field set_state fun(self:druid.checkbox, state:bool, is_silent:bool) Set checkbox state + +---@class druid.checkbox.style +---@field on_change_state field (self, node, state) + +---@class druid.checkbox_group : druid.base_component +---@field on_checkbox_click druid_event On any checkbox click callback(self, index) +---@field get_state fun(self:druid.checkbox_group):bool[] Return checkbox group state +---@field init fun(self:druid.checkbox_group, nodes:node[], callback:function, click_nodes:node[]) Component init function +---@field set_state fun(self:druid.checkbox_group, indexes:bool[]) Set checkbox group state + +---@class druid.drag : druid.base_component +---@field can_x bool Is drag component process vertical dragging. +---@field can_y bool Is drag component process horizontal. +---@field is_drag bool Is component now dragging +---@field is_touch bool Is component now touching +---@field on_drag druid_event on drag progress callback(self, dx, dy) +---@field on_drag_end druid_event Event on drag end callback(self) +---@field on_drag_start druid_event Event on drag start callback(self) +---@field on_touch_end druid_event Event on touch end callback(self) +---@field on_touch_start druid_event Event on touch start callback(self) +---@field style druid.drag.style Component style params. +---@field x number Current touch x position +---@field y number Current touch y position +---@field init fun(self:druid.drag, node:node, on_drag_callback:function) Drag component constructor +---@field set_click_zone fun(self:druid.drag, zone:node) Strict drag click area. + +---@class druid.drag.style +---@field DRAG_DEADZONE field Distance in pixels to start dragging + +---@class druid.dynamic_grid : druid.base_component +---@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. +---@field centrate_text_with_icon fun(text_node:text, icon_node:box, margin:number) Center two nodes. +---@field deprecated fun(message:string) Show deprecated message. +---@field get_border fun(): Distance from node to size border +---@field get_pivot_offset fun(pivot:gui.pivot):vector3 Get node offset for given gui pivot +---@field is_enabled fun(node:node):bool Check if node is enabled in gui hierarchy. +---@field is_web fun() Check if device is HTML5 + +---@class druid.hover : druid.base_component +---@field on_hover druid_event On hover callback(self, state) +---@field init fun(self:druid.hover, node:node, on_hover_callback:function) Component init function +---@field is_enabled fun(self:druid.hover):bool Return current hover enabled state +---@field set_click_zone fun(self:druid.hover, zone:node) Strict hover click area. +---@field set_enabled fun(self:druid.hover, state:bool) Set enable state of hover component. +---@field set_hover fun(self:druid.hover, state:bool) Set hover state +---@field set_mouse_hover fun(self:druid.hover, state:bool) Set mouse hover state + +---@class druid.input : druid.base_component +---@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.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 +---@field on_input_wrong field (self, button_node) Callback on wrong user input +---@field on_select field (self, button_node) Callback on input field selecting +---@field on_unselect field (self, button_node) Callback on input field unselecting + +---@class druid.lang_text : druid.base_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 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.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 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) +---@field available_size vector3 Size of available positions: (width, height, 0) +---@field content_node node Scroll content node +---@field drag Drag Drag Druid component +---@field inertion vector3 Current inert speed +---@field is_inert bool Flag, if scroll now moving by inertion +---@field on_point_scroll druid_event On scroll_to_index function callback(self, index, point) +---@field on_scroll druid_event On scroll move callback(self, position) +---@field on_scroll_to druid_event On scroll_to function callback(self, target, is_instant) +---@field position vector3 Current scroll posisition +---@field selected number Current index of points of interests +---@field style druid.scroll.style Component style params. +---@field target_position vector3 Current scroll target position +---@field view_node node Scroll view node +---@field _cancel_animate fun(self:unknown) Cancel animation on other animation or input touch +---@field bind_grid fun(self:druid.scroll, grid:StaticGrid|DynamicGrid):druid.scroll Bind the grid component (Static or Dynamic) to recalculate scroll size on grid changes +---@field get_percent fun(self:druid.scroll):vector3 Return current scroll progress status. +---@field get_scroll_size fun(self:druid.scroll):vector3 Return vector of scroll size with width and height. +---@field init fun(self:druid.scroll, view_node:node, content_node:node) Scroll constructor +---@field is_inert fun(self:druid.scroll):bool Return if scroll have inertion. +---@field scroll_to fun(self:druid.scroll, point:vector3, is_instant:bool) Start scroll to target point. +---@field scroll_to_index fun(self:druid.scroll, index:number, skip_cb:bool) Scroll to item in scroll by point index. +---@field scroll_to_percent fun(self:druid.scroll, percent:vector3, is_instant:bool) Start scroll to target scroll percent +---@field set_extra_stretch_size fun(self:druid.scroll, stretch_size:number):druid.scroll Set extra size for scroll stretching. +---@field set_horizontal_scroll fun(self:druid.scroll, state:bool):druid.scroll Lock or unlock horizontal scroll +---@field set_inert fun(self:druid.scroll, state:bool):druid.scroll Enable or disable scroll inert. +---@field set_points fun(self:druid.scroll, points:table):druid.scroll Set points of interest. +---@field set_size fun(self:druid.scroll, size:vector3):druid.scroll Set scroll content size. +---@field set_vertical_scroll fun(self:druid.scroll, state:bool):druid.scroll Lock or unlock vertical scroll + +---@class druid.scroll.style +---@field ANIM_SPEED field Scroll gui.animation speed for scroll_to function +---@field BACK_SPEED field Scroll back returning lerp speed +---@field EXTRA_STRETCH_SIZE field extra size in pixels outside of scroll (stretch effect) +---@field FRICT field Multiplier for free inertion +---@field FRICT_HOLD field Multiplier for inertion, while touching +---@field INERT_SPEED field Multiplier for inertion speed +---@field INERT_THRESHOLD field Scroll speed to stop inertion +---@field POINTS_DEADZONE field Speed to check points of interests in no_inertion mode +---@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 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 +---@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 add fun(self:druid.static_grid, item:node, index:number) Add new item to the grid +---@field clear fun(self:druid.static_grid):druid.static_grid Clear grid nodes array. +---@field get_all_pos fun(self:druid.static_grid):vector3[] Return array of all node positions +---@field get_index fun(self:druid.static_grid, pos:vector3):number Return index for grid pos +---@field get_index_by_node fun(self:druid.static_grid, node:node):number Return grid index by node +---@field get_pos fun(self:druid.static_grid, index:number):vector3 Return pos for grid node index +---@field get_size fun(self:druid.static_grid):vector3 Return grid content size +---@field init fun(self:druid.static_grid, parent:node, element:node, in_row:number) Component init function +---@field remove fun(self:druid.static_grid, index:number, is_shift_nodes:bool) Remove the item from the grid. +---@field set_anchor fun(self:druid.static_grid, anchor:vector3) Set grid anchor. +---@field set_position_function fun(self:druid.static_grid, callback:function):druid.static_grid Change set position function for grid nodes. + +---@class druid.swipe : druid.base_component +---@field click_zone node Restriction zone +---@field node node Swipe node +---@field style druid.swipe.style Component style params. +---@field init fun(self:druid.swipe, node:node, on_swipe_callback:function) Component init function +---@field set_click_zone fun(self:druid.swipe, zone:node) Strict swipe click area. + +---@class druid.swipe.style +---@field SWIPE_THRESHOLD field Minimum distance for swipe trigger +---@field SWIPE_TIME field Maximum time for swipe trigger +---@field SWIPE_TRIGGER_ON_MOVE field If true, trigger on swipe moving, not only release action + +---@class druid.text : druid.base_component +---@field is_no_adjust bool Current text size adjust settings +---@field node node Text node +---@field on_set_pivot druid_event On change pivot callback(self, pivot) +---@field on_set_text druid_event On set text callback(self, text) +---@field on_update_text_scale druid_event On adjust text size callback(self, new_scale) +---@field pos vector3 Current text position +---@field scale vector3 Current text node scale +---@field start_scale vector3 Initial text node scale +---@field start_size vector3 Initial text node size +---@field text_area vector3 Current text node available are +---@field get_text_width fun(self:druid.text, text:string) Calculate text width with font with respect to trailing space +---@field init fun(self:druid.text, node:node, value:string, no_adjust:bool) Component init function +---@field is_multiline fun(self:druid.text):bool Return true, if text with line break +---@field set_alpha fun(self:druid.text, alpha:number) Set alpha +---@field set_color fun(self:druid.text, color:vector4) Set color +---@field set_pivot fun(self:druid.text, pivot:gui.pivot) Set text pivot. +---@field set_scale fun(self:druid.text, scale:vector3) Set scale +---@field set_to fun(self:druid.text, set_to:string) Set text to text field + +---@class druid.timer : druid.base_component +---@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 +---@field initialize fun(self:druid_event, initial_callback:function) Event constructur +---@field is_exist fun(self:druid_event):bool Return true, if event have at lease one handler +---@field subscribe fun(self:druid_event, callback:function) Subscribe callback on event +---@field trigger fun(self:druid_event, ...:any) Trigger the event and call all subscribed callbacks +---@field unsubscribe fun(self:druid_event, callback:function) Unsubscribe callback on event + +---@class druid_instance +---@field create fun(self:druid_instance, component:Component, ...:args) Create new druid component +---@field final fun(self:druid_instance) Call on final function on gui_script. +---@field initialize fun(self:druid_instance, context:table, style:table) Druid class constructor +---@field new_back_handler fun(self:druid_instance, ...:args):Component Create back_handler basic component +---@field new_blocker fun(self:druid_instance, ...:args):Component Create blocker basic component +---@field new_button fun(self:druid_instance, ...:args):Component Create button basic component +---@field new_checkbox fun(self:druid_instance, ...:args):Component Create checkbox component +---@field new_checkbox_group fun(self:druid_instance, ...:args):Component Create checkbox_group component +---@field new_drag fun(self:druid_instance, ...:args):Componetn Create drag basic component +---@field new_dynamic_grid fun(self:druid_instance, ...:args):Component Create dynamic grid component +---@field new_grid fun(self:druid_instance, ...:args):Component Create grid basic component Deprecated +---@field new_hover fun(self:druid_instance, ...:args):Component Create hover basic component +---@field new_input fun(self:druid_instance, ...:args):Component Create input component +---@field new_lang_text fun(self:druid_instance, ...:args):Component Create lang_text component +---@field new_progress fun(self:druid_instance, ...:args):Component Create progress component +---@field new_radio_group fun(self:druid_instance, ...:args):Component Create radio_group component +---@field new_scroll fun(self:druid_instance, ...:args):Component Create scroll basic component +---@field new_slider fun(self:druid_instance, ...:args):Component Create slider component +---@field new_static_grid fun(self:druid_instance, ...:args):Component Create static grid basic component +---@field new_swipe fun(self:druid_instance, ...:args):Component Create swipe basic component +---@field new_text fun(self:druid_instance, ...:args):Component Create text basic component +---@field new_timer fun(self:druid_instance, ...:args):Component Create timer component +---@field on_focus_gained fun(self:druid_instance) Druid on focus gained interest function. +---@field on_focus_lost fun(self:druid_instance) Druid on focus lost interest function. +---@field on_input fun(self:druid_instance, action_id:hash, action:table) Druid on_input function +---@field on_layout_change fun(self:druid_instance) Druid on layout change function. +---@field on_message fun(self:druid_instance, message_id:hash, message:table, sender:hash) Druid on_message function +---@field remove fun(self:druid_instance, component:Component) Remove component from druid instance. +---@field update fun(self:druid_instance, dt:number) Druid update function + +---@class helper +---@field is_mobile fun() Check if device is mobile (Android or iOS) + + diff --git a/config.ld b/config.ld index 273a754..7448c16 100644 --- a/config.ld +++ b/config.ld @@ -11,7 +11,6 @@ package='druid' sort=false dir='./docs' style='!fixed' -format='discount' -topics={"./docs_md", "README.md"} +topics={} use_markdown_titles=true no_space_before_args=true \ No newline at end of file diff --git a/druid/base/back_handler.lua b/druid/base/back_handler.lua index daabd9a..d6711df 100644 --- a/druid/base/back_handler.lua +++ b/druid/base/back_handler.lua @@ -1,13 +1,14 @@ --- Component to handle back key (android, backspace) --- @module druid.back_handler +-- @module BackHandler +-- @within BaseComponent +-- @alias druid.back_handler ---- Component events --- @table Events --- @tfield druid_event on_back On back handler callback +--- On back handler callback(self, params) +-- @tfield druid_event on_back + +--- Params to back callback +-- @tfield any params ---- Component fields --- @table Fields --- @tfield any params Params to click callbacks local Event = require("druid.event") local const = require("druid.const") @@ -17,21 +18,20 @@ local BackHandler = component.create("back_handler", { const.ON_INPUT }) --- Component init function --- @function back_handler:init +-- @tparam BackHandler self -- @tparam callback callback On back button --- @tparam[opt] params Callback argument -function BackHandler:init(callback, params) +-- @tparam[opt] any params Callback argument +function BackHandler.init(self, callback, params) self.params = params - self.on_back = Event(callback) end --- Input handler for component --- @function back_handler:on_input +-- @tparam BackHandler self -- @tparam string action_id on_input action id -- @tparam table action on_input action -function BackHandler:on_input(action_id, action) +function BackHandler.on_input(self, action_id, action) if not action[const.RELEASED] then return false end diff --git a/druid/base/blocker.lua b/druid/base/blocker.lua index 4f36ae8..1017db9 100644 --- a/druid/base/blocker.lua +++ b/druid/base/blocker.lua @@ -1,16 +1,12 @@ --- Component to block input on specify zone by node --- @module druid.blocker +-- @module Blocker +-- @within BaseComponent +-- @alias druid.blocker ---- Component events --- @table Events --- @tfield druid_event on_click On release button callback --- @tfield druid_event on_enable_change On enable/disable callback +---Trigger node +-- @tfield node node ---- Component fields --- @table Fields --- @tfield node node Trigger node -local Event = require("druid.event") local const = require("druid.const") local component = require("druid.component") @@ -18,17 +14,14 @@ local Blocker = component.create("blocker", { const.ON_INPUT }) --- Component init function --- @function blocker:init +-- @tparam Blocker self -- @tparam node node Gui node -function Blocker:init(node) +function Blocker.init(self, node) self.node = self:get_node(node) - - self.on_click = Event() - self.on_enable_change = Event() end -function Blocker:on_input(action_id, action) +function Blocker.on_input(self, action_id, action) if action_id ~= const.ACTION_TOUCH and action_id ~= const.ACTION_MULTITOUCH and action_id ~= nil then @@ -48,17 +41,17 @@ end --- Set enabled blocker component state --- @function blocker:set_enabled +-- @tparam Blocker self -- @tparam bool state Enabled state -function Blocker:set_enabled(state) +function Blocker.set_enabled(self, state) gui.set_enabled(self.node, state) end --- Return blocked enabled state --- @function blocker:is_enabled +-- @tparam Blocker self -- @treturn bool True, if blocker is enabled -function Blocker:is_enabled(state) +function Blocker.is_enabled(self) return gui.is_enabled(self.node) end diff --git a/druid/base/button.lua b/druid/base/button.lua index e1ac309..3f25c4e 100644 --- a/druid/base/button.lua +++ b/druid/base/button.lua @@ -1,25 +1,50 @@ --- Component to handle basic GUI button --- @module druid.button +-- @module Button +-- @within BaseComponent +-- @alias druid.button ---- Component events --- @table Events --- @tfield druid_event on_click (self, params, button_instance) On release button callback --- @tfield druid_event on_repeated_click (self, params, button_instance, click_amount) On repeated action button callback --- @tfield druid_event on_long_click (self, params, button_instance, time) On long tap button callback --- @tfield druid_event on_double_click (self, params, button_instance, click_amount) On double tap button callback --- @tfield druid_event on_hold_callback (self, params, button_instance, time) On button hold before long_click callback --- @tfield druid_event on_click_outside (self, params, button_instance) On click outside of button +--- On release button callback(self, params, button_instance) +-- @tfield druid_event on_click + +--- On repeated action button callback(self, params, button_instance, click_amount) +-- @tfield druid_event on_repeated_click + +---On long tap button callback(self, params, button_instance, time) +-- @tfield druid_event on_long_click + +---On double tap button callback(self, params, button_instance, click_amount) +-- @tfield druid_event on_double_click + +---On button hold before long_click callback(self, params, button_instance, time) +-- @tfield druid_event on_hold_callback + +---On click outside of button(self, params, button_instance) +-- @tfield druid_event on_click_outside + +---Trigger node +-- @tfield node node + +---Animation node +-- @tfield[opt=node] node anim_node + +---Initial scale of anim_node +-- @tfield vector3 start_scale + +---Initial pos of anim_node +-- @tfield vector3 start_pos + +---Initial pos of anim_node +-- @tfield vector3 pos + +---Params to click callbacks +-- @tfield any params + +---Druid hover logic component +-- @tfield druid.hover hover + +---Restriction zone +-- @tfield[opt] node click_zone ---- Component fields --- @table Fields --- @tfield node node Trigger node --- @tfield[opt=node] node anim_node Animation node --- @tfield vector3 start_scale Initial scale of anim_node --- @tfield vector3 start_pos Initial pos of anim_node --- @tfield vector3 pos Initial pos of anim_node --- @tfield any params Params to click callbacks --- @tfield druid.hover hover Druid hover logic component --- @tfield[opt] node click_zone Restriction zone local Event = require("druid.event") local const = require("druid.const") @@ -132,7 +157,7 @@ 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=0.4] number LONGTAP_TIME Minimum time to trigger on_hold_callback -- @tfield[opt=0.8] number AUTOHOLD_TRIGGER Maximum hold time to trigger button release while holding -- @tfield[opt=0.4] number DOUBLETAP_TIME Time between double taps @@ -141,7 +166,7 @@ end -- @tfield function on_hover (self, node, hover_state) -- @tfield function on_mouse_hover (self, node, hover_state) -- @tfield function on_set_enabled (self, node, enabled_state) -function Button:on_style_change(style) +function Button.on_style_change(self, style) self.style = {} self.style.LONGTAP_TIME = style.LONGTAP_TIME or 0.4 self.style.AUTOHOLD_TRIGGER = style.AUTOHOLD_TRIGGER or 0.8 @@ -156,12 +181,12 @@ end --- Component init function --- @function button:init +-- @tparam Button self -- @tparam node node Gui node -- @tparam function callback Button callback -- @tparam[opt] table params Button callback params -- @tparam[opt] node anim_node Button anim node (node, if not provided) -function Button:init(node, callback, params, anim_node) +function Button.init(self, node, callback, params, anim_node) self.druid = self:get_druid() self.node = self:get_node(node) @@ -188,7 +213,7 @@ function Button:init(node, callback, params, anim_node) end -function Button:on_input(action_id, action) +function Button.on_input(self, action_id, action) if not is_input_match(self, action_id) then return false end @@ -257,16 +282,16 @@ function Button:on_input(action_id, action) end -function Button:on_input_interrupt() +function Button.on_input_interrupt(self) self.can_action = false end --- Set enabled button component state --- @function button:set_enabled +-- @tparam Button self -- @tparam bool state Enabled state --- @treturn druid.button Current button instance -function Button:set_enabled(state) +-- @treturn Button Current button instance +function Button.set_enabled(self, state) self.disabled = not state self.hover:set_enabled(state) self.style.on_set_enabled(self, self.node, state) @@ -276,19 +301,19 @@ end --- Return button enabled state --- @function button:is_enabled +-- @tparam Button self -- @treturn bool True, if button is enabled -function Button:is_enabled() +function Button.is_enabled(self) return not self.disabled end --- Strict button click area. Useful for -- no click events outside stencil node --- @function button:set_click_zone +-- @tparam Button self -- @tparam node zone Gui node --- @treturn druid.button Current button instance -function Button:set_click_zone(zone) +-- @treturn Button Current button instance +function Button.set_click_zone(self, zone) self.click_zone = self:get_node(zone) self.hover:set_click_zone(zone) @@ -297,10 +322,10 @@ end --- Set key-code to trigger this button --- @function button:set_key_trigger +-- @tparam Button self -- @tparam hash key The action_id of the key --- @treturn druid.button Current button instance -function Button:set_key_trigger(key) +-- @treturn Button Current button instance +function Button.set_key_trigger(self, key) self.key_trigger = hash(key) return self @@ -308,9 +333,9 @@ end --- Get key-code to trigger this button --- @function button:get_key_trigger +-- @tparam Button self -- @treturn hash The action_id of the key -function Button:get_key_trigger() +function Button.get_key_trigger(self) return self.key_trigger end diff --git a/druid/base/drag.lua b/druid/base/drag.lua index bef0b7a..2eef901 100644 --- a/druid/base/drag.lua +++ b/druid/base/drag.lua @@ -2,25 +2,46 @@ -- Drag have correct handling for multitouch and swap -- touched while dragging. Drag will be processed even -- the cursor is outside of node, if drag is already started --- @module druid.drag +-- @module Drag +-- @within BaseComponent +-- @alias druid.drag ---- Component events --- @table Events --- @tfield druid_event on_touch_start (self) Event on touch start --- @tfield druid_event on_touch_end (self) Event on touch end --- @tfield druid_event on_drag_start (self) Event on drag start --- @tfield druid_event on_drag (self, dx, dy) Event on drag progress --- @tfield druid_event on_drag_end (self) Event on drag end +--- Event on touch start callback(self) +-- @tfield druid_event on_touch_start + +--- Event on touch end callback(self) +-- @tfield druid_event on_touch_end + +--- Event on drag start callback(self) +-- @tfield druid_event on_drag_start + +--- on drag progress callback(self, dx, dy) +-- @tfield druid_event on_drag Event + +--- Event on drag end callback(self) +-- @tfield druid_event on_drag_end + +--- Is component now touching +-- @tfield bool is_touch + +--- Is component now dragging +-- @tfield bool is_drag + +--- Is drag component process vertical dragging. Default - true +-- @tfield bool can_x + +--- Is drag component process horizontal. Default - true +-- @tfield bool can_y + +--- Current touch x position +-- @tfield number x + +--- Current touch y position +-- @tfield number y + +--- Touch start position +-- @tfield vector3 touch_start_pos ---- Components fields --- @table Fields --- @tfield bool is_touch Is component now touching --- @tfield bool is_drag Is component now dragging --- @tfield bool can_x Is drag component process vertical dragging. Default - true --- @tfield bool can_y Is drag component process horizontal. Default - true --- @tfield number x Current touch x position --- @tfield number y Current touch y position --- @tfield vector3 touch_start_pos Touch start position local Event = require("druid.event") local const = require("druid.const") @@ -127,19 +148,19 @@ 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=10] number DRAG_DEADZONE Distance in pixels to start dragging -function Drag:on_style_change(style) +function Drag.on_style_change(self, style) self.style = {} self.style.DRAG_DEADZONE = style.DRAG_DEADZONE or 10 end --- Drag component constructor +-- @tparam Drag self -- @tparam node node GUI node to detect dragging -- @tparam function on_drag_callback Callback for on_drag_event(self, dx, dy) --- @function drag:init -function Drag:init(node, on_drag_callback) +function Drag.init(self, node, on_drag_callback) self.node = self:get_node(node) self.dx = 0 @@ -163,14 +184,14 @@ function Drag:init(node, on_drag_callback) end -function Drag:on_input_interrupt() +function Drag.on_input_interrupt(self) if self.is_drag or self.is_touch then end_touch(self) end end -function Drag:on_input(action_id, action) +function Drag.on_input(self, action_id, action) if action_id ~= const.ACTION_TOUCH and action_id ~= const.ACTION_MULTITOUCH then return false end @@ -241,9 +262,9 @@ end --- Strict drag click area. Useful for -- restrict events outside stencil node --- @function drag:set_click_zone +-- @tparam Drag self -- @tparam node zone Gui node -function Drag:set_click_zone(zone) +function Drag.set_click_zone(self, zone) self.click_zone = self:get_node(zone) end diff --git a/druid/base/hover.lua b/druid/base/hover.lua index 221c7b6..4d61461 100644 --- a/druid/base/hover.lua +++ b/druid/base/hover.lua @@ -1,10 +1,14 @@ --- Component to handle hover node interaction --- @module druid.hover +-- @module Hover +-- @within BaseComponent +-- @alias druid.hover + +--- On hover callback(self, state) +-- @tfield druid_event on_hover + +--- On mouse hover callback(self, state) +-- @tfield druid_event on_mouse_hover ---- Component events --- @table Events --- @tfield druid_event on_hover On hover callback (Touch pressed) --- @tfield druid_event on_mouse_hover On mouse hover callback (Touch over without action_id) local Event = require("druid.event") local const = require("druid.const") @@ -15,10 +19,10 @@ local Hover = component.create("hover", { const.ON_INPUT }) --- Component init function --- @function hover:init +-- @tparam Hover self -- @tparam node node Gui node -- @tparam function on_hover_callback Hover callback -function Hover:init(node, on_hover_callback) +function Hover.init(self, node, on_hover_callback) self.node = self:get_node(node) self._is_hovered = false @@ -31,7 +35,7 @@ function Hover:init(node, on_hover_callback) end -function Hover:on_input(action_id, action) +function Hover.on_input(self, action_id, action) if action_id ~= const.ACTION_TOUCH and action_id ~= nil then return false end @@ -64,15 +68,15 @@ function Hover:on_input(action_id, action) end -function Hover:on_input_interrupt() +function Hover.on_input_interrupt(self) self:set_hover(false) end --- Set hover state --- @function hover:set_hover +-- @tparam Hover self -- @tparam bool state The hover state -function Hover:set_hover(state) +function Hover.set_hover(self, state) if self._is_hovered ~= state then self._is_hovered = state self.on_hover:trigger(self:get_context(), state) @@ -80,9 +84,9 @@ function Hover:set_hover(state) end --- Set mouse hover state --- @function hover:set_mouse_hover +-- @tparam Hover self -- @tparam bool state The mouse hover state -function Hover:set_mouse_hover(state) +function Hover.set_mouse_hover(self, state) if self._is_mouse_hovered ~= state then self._is_mouse_hovered = state self.on_mouse_hover:trigger(self:get_context(), state) @@ -92,9 +96,9 @@ end --- Strict hover click area. Useful for -- no click events outside stencil node --- @function hover:set_click_zone +-- @tparam Hover self -- @tparam node zone Gui node -function Hover:set_click_zone(zone) +function Hover.set_click_zone(self, zone) self.click_zone = self:get_node(zone) end @@ -102,9 +106,9 @@ end --- Set enable state of hover component. -- If hover is not enabled, it will not generate -- any hover events --- @function hover:set_enabled +-- @tparam Hover self -- @tparam bool state The hover enabled state -function Hover:set_enabled(state) +function Hover.set_enabled(self, state) self._is_enabled = state if not state then @@ -119,9 +123,9 @@ end --- Return current hover enabled state --- @function hover:is_enabled +-- @tparam Hover self -- @treturn bool The hover enabled state -function Hover:is_enabled() +function Hover.is_enabled(self) return self._is_enabled end diff --git a/druid/base/scroll.lua b/druid/base/scroll.lua index bd7139a..7f76bb6 100644 --- a/druid/base/scroll.lua +++ b/druid/base/scroll.lua @@ -5,27 +5,53 @@ -- Setup initial scroll size by changing scroll parent size. If scroll parent -- size will be less than scroll_input size, no scroll is available. For scroll -- parent size should be more than input size --- @module druid.scroll +-- @module Scroll +-- @within BaseComponent +-- @alias druid.scroll ---- Component events --- @table Events --- @tfield druid_event on_scroll On scroll move callback --- @tfield druid_event on_scroll_to On scroll_to function callback --- @tfield druid_event on_point_scroll On scroll_to_index function callback ---- Component fields --- @table Fields --- @tfield node view_node Scroll view node --- @tfield node content_node Scroll content node --- @tfield bool is_inert Flag, if scroll now moving by inertion --- @tfield vector3 inertion Current inert speed --- @tfield vector3 position Current scroll posisition --- @tfield vector3 target_position Current scroll target position --- @tfield vector4 available_pos Available position for content node: (min_x, max_y, max_x, min_y) --- @tfield vector3 available_size Size of available positions: (width, height, 0) --- @tfield druid.drag drag Drag component --- @tfield[opt] selected Current index of points of interests --- @tfield bool is_animate Flag, if scroll now animating by gui.animate +--- On scroll move callback(self, position) +-- @tfield druid_event on_scroll + +--- On scroll_to function callback(self, target, is_instant) +-- @tfield druid_event on_scroll_to + +--- On scroll_to_index function callback(self, index, point) +-- @tfield druid_event on_point_scroll + +--- Scroll view node +-- @tfield node view_node + +--- Scroll content node +-- @tfield node content_node + +--- Flag, if scroll now moving by inertion +-- @tfield bool is_inert + +--- Current inert speed +-- @tfield vector3 inertion + +--- Current scroll posisition +-- @tfield vector3 position + +--- Current scroll target position +-- @tfield vector3 target_position + +--- Available position for content node: (min_x, max_y, max_x, min_y) +-- @tfield vector4 available_pos + +--- Size of available positions: (width, height, 0) +-- @tfield vector3 available_size + +--- Drag Druid component +-- @tfield Drag drag + +--- Current index of points of interests +-- @tfield[opt] number selected + +--- Flag, if scroll now animating by gui.animate +-- @tfield bool is_animate + local Event = require("druid.event") local const = require("druid.const") @@ -64,7 +90,7 @@ 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=0] number FRICT Multiplier for free inertion -- @tfield[opt=0] number FRICT_HOLD Multiplier for inertion, while touching -- @tfield[opt=3] number INERT_THRESHOLD Scroll speed to stop inertion @@ -74,7 +100,7 @@ end -- @tfield[opt=0.2] number ANIM_SPEED Scroll gui.animation speed for scroll_to function -- @tfield[opt=0] number EXTRA_STRETCH_SIZE extra size in pixels outside of scroll (stretch effect) -- @tfield[opt=false] bool SMALL_CONTENT_SCROLL If true, content node with size less than view node size can be scrolled -function Scroll:on_style_change(style) +function Scroll.on_style_change(self, style) self.style = {} self.style.EXTRA_STRETCH_SIZE = style.EXTRA_STRETCH_SIZE or 0 self.style.ANIM_SPEED = style.ANIM_SPEED or 0.2 @@ -94,11 +120,11 @@ function Scroll:on_style_change(style) end ---- Scroll constructor. --- @function scroll:init +--- Scroll constructor +-- @tparam Scroll self -- @tparam node view_node GUI view scroll node -- @tparam node content_node GUI content scroll node -function Scroll:init(view_node, content_node) +function Scroll.init(self, view_node, content_node) self.druid = self:get_druid() self.view_node = self:get_node(view_node) @@ -128,12 +154,12 @@ function Scroll:init(view_node, content_node) end -function Scroll:on_layout_change() +function Scroll.on_layout_change(self) gui.set_position(self.content_node, self.position) end -function Scroll:update(dt) +function Scroll.update(self, dt) if self.drag.is_drag then self:_update_hand_scroll(dt) else @@ -142,18 +168,18 @@ function Scroll:update(dt) end -function Scroll:on_remove() +function Scroll.on_remove(self) self:bind_grid(nil) end --- Start scroll to target point. --- @function scroll:scroll_to --- @tparam point vector3 Target point +-- @tparam Scroll self +-- @tparam vector3 point Target point -- @tparam[opt] bool is_instant Instant scroll flag -- @usage scroll:scroll_to(vmath.vector3(0, 50, 0)) -- @usage scroll:scroll_to(vmath.vector3(0), true) -function Scroll:scroll_to(point, is_instant) +function Scroll.scroll_to(self, point, is_instant) local b = self.available_pos local target = vmath.vector3(-point.x, -point.y, 0) target.x = helper.clamp(target.x, b.x, b.z) @@ -179,10 +205,10 @@ end --- Scroll to item in scroll by point index. --- @function scroll:scroll_to_index +-- @tparam Scroll self -- @tparam number index Point index -- @tparam[opt] bool skip_cb If true, skip the point callback -function Scroll:scroll_to_index(index, skip_cb) +function Scroll.scroll_to_index(self, index, skip_cb) if not self.points then return end @@ -202,11 +228,11 @@ end --- Start scroll to target scroll percent --- @function scroll:scroll_to_percent --- @tparam point vector3 target percent +-- @tparam Scroll self +-- @tparam vector3 percent target percent -- @tparam[opt] bool is_instant instant scroll flag -- @usage scroll:scroll_to_percent(vmath.vector3(0.5, 0, 0)) -function Scroll:scroll_to_percent(percent, is_instant) +function Scroll.scroll_to_percent(self, percent, is_instant) local border = self.available_pos local pos = vmath.vector3( @@ -221,9 +247,9 @@ end --- Return current scroll progress status. -- Values will be in [0..1] interval --- @function scroll:get_percent +-- @tparam Scroll self -- @treturn vector3 New vector with scroll progress values -function Scroll:get_percent() +function Scroll.get_percent(self) local x_perc = 1 - inverse_lerp(self.available_pos.x, self.available_pos.z, self.position.x) local y_perc = inverse_lerp(self.available_pos.w, self.available_pos.y, self.position.y) @@ -233,10 +259,10 @@ end --- Set scroll content size. -- It will change content gui node size --- @function scroll:set_size +-- @tparam Scroll self -- @tparam vector3 size The new size for content node -- @treturn druid.scroll Current scroll instance -function Scroll:set_size(size) +function Scroll.set_size(self, size) gui.set_size(self.content_node, size) self:_update_size() @@ -247,10 +273,10 @@ end --- Enable or disable scroll inert. -- If disabled, scroll through points (if exist) -- If no points, just simple drag without inertion --- @function scroll:set_inert +-- @tparam Scroll self -- @tparam bool state Inert scroll state -- @treturn druid.scroll Current scroll instance -function Scroll:set_inert(state) +function Scroll.set_inert(self, state) self._is_inert = state return self @@ -258,19 +284,19 @@ end --- Return if scroll have inertion. --- @function scroll:is_inert +-- @tparam Scroll self -- @treturn bool If scroll have inertion -function Scroll:is_inert() +function Scroll.is_inert(self) return self._is_inert end --- Set extra size for scroll stretching. -- Set 0 to disable stretching effect --- @function scroll:set_extra_stretch_size +-- @tparam Scroll self -- @tparam[opt=0] number stretch_size Size in pixels of additional scroll area -- @treturn druid.scroll Current scroll instance -function Scroll:set_extra_stretch_size(stretch_size) +function Scroll.set_extra_stretch_size(self, stretch_size) self.style.EXTRA_STRETCH_SIZE = stretch_size or 0 self:_update_size() @@ -279,19 +305,19 @@ end --- Return vector of scroll size with width and height. --- @function scroll:get_scroll_size +-- @tparam Scroll self -- @treturn vector3 Available scroll size -function Scroll:get_scroll_size() +function Scroll.get_scroll_size(self) return self.available_size end --- Set points of interest. -- Scroll will always centered on closer points --- @function scroll:set_points +-- @tparam Scroll self -- @tparam table points Array of vector3 points -- @treturn druid.scroll Current scroll instance -function Scroll:set_points(points) +function Scroll.set_points(self, points) self.points = points table.sort(self.points, function(a, b) @@ -305,10 +331,10 @@ end --- Lock or unlock horizontal scroll --- @function scroll:set_horizontal_scroll +-- @tparam Scroll self -- @tparam bool state True, if horizontal scroll is enabled -- @treturn druid.scroll Current scroll instance -function Scroll:set_horizontal_scroll(state) +function Scroll.set_horizontal_scroll(self, state) self._is_horizontal_scroll = state self.drag.can_x = self.available_size.x > 0 and state return self @@ -316,10 +342,10 @@ end --- Lock or unlock vertical scroll --- @function scroll:set_vertical_scroll +-- @tparam Scroll self -- @tparam bool state True, if vertical scroll is enabled -- @treturn druid.scroll Current scroll instance -function Scroll:set_vertical_scroll(state) +function Scroll.set_vertical_scroll(self, state) self._is_vertical_scroll = state self.drag.can_y = self.available_size.y > 0 and state return self @@ -329,10 +355,10 @@ end --- Bind the grid component (Static or Dynamic) to recalculate -- scroll size on grid changes --- @function scroll:bind_grid --- @tparam druid.static_grid|druid.dynamic_grid Druid grid component +-- @tparam Scroll self +-- @tparam StaticGrid|DynamicGrid grid Druid grid component -- @treturn druid.scroll Current scroll instance -function Scroll:bind_grid(grid) +function Scroll.bind_grid(self, grid) if self._grid_on_change then self._grid_on_change:unsubscribe(self._grid_on_change_callback) @@ -354,7 +380,7 @@ function Scroll:bind_grid(grid) end -function Scroll:_on_scroll_drag(dx, dy) +function Scroll._on_scroll_drag(self, dx, dy) local t = self.target_position local b = self.available_pos local eb = self.available_pos_extra @@ -395,7 +421,7 @@ function Scroll:_on_scroll_drag(dx, dy) end -function Scroll:_check_soft_zone() +function Scroll._check_soft_zone(self) local target = self.target_position local border = self.available_pos local speed = self.style.BACK_SPEED @@ -420,7 +446,7 @@ end --- Cancel animation on other animation or input touch -function Scroll:_cancel_animate() +function Scroll._cancel_animate(self) if self.is_animate then self.target_position = gui.get_position(self.content_node) self.position.x = self.target_position.x @@ -431,7 +457,7 @@ function Scroll:_cancel_animate() end -function Scroll:_set_scroll_position(position) +function Scroll._set_scroll_position(self, position) local available_extra = self.available_pos_extra position.x = helper.clamp(position.x, available_extra.x, available_extra.z) position.y = helper.clamp(position.y, available_extra.w, available_extra.y) @@ -450,7 +476,7 @@ end -- if no inert, scroll to next point by scroll direction -- if inert, find next point by scroll director -- @local -function Scroll:_check_points() +function Scroll._check_points(self) if not self.points then return end @@ -502,7 +528,7 @@ function Scroll:_check_points() end -function Scroll:_check_threshold() +function Scroll._check_threshold(self) local is_stopped = false if self.inertion.x ~= 0 and math.abs(self.inertion.x) < self.style.INERT_THRESHOLD then @@ -520,7 +546,7 @@ function Scroll:_check_threshold() end -function Scroll:_update_free_scroll(dt) +function Scroll._update_free_scroll(self, dt) local target = self.target_position if self._is_inert and (self.inertion.x ~= 0 or self.inertion.y ~= 0) then @@ -541,7 +567,7 @@ function Scroll:_update_free_scroll(dt) end -function Scroll:_update_hand_scroll(dt) +function Scroll._update_hand_scroll(self, dt) local dx = self.target_position.x - self.position.x local dy = self.target_position.y - self.position.y @@ -552,7 +578,7 @@ function Scroll:_update_hand_scroll(dt) end -function Scroll:_on_touch_start() +function Scroll._on_touch_start(self) self.inertion.x = 0 self.inertion.y = 0 self.target_position.x = self.position.x @@ -560,12 +586,12 @@ function Scroll:_on_touch_start() end -function Scroll:_on_touch_end() +function Scroll._on_touch_end(self) self:_check_threshold() end -function Scroll:_update_size() +function Scroll._update_size(self) local view_border = helper.get_border(self.view_node) local view_size = vmath.mul_per_elem(gui.get_size(self.view_node), gui.get_scale(self.view_node)) diff --git a/druid/base/static_grid.lua b/druid/base/static_grid.lua index 2dd9a42..7e2e7dd 100644 --- a/druid/base/static_grid.lua +++ b/druid/base/static_grid.lua @@ -1,24 +1,45 @@ --- Component to handle placing components by row and columns. -- Grid can anchor your elements, get content size and other --- @module druid.static_grid +-- @module StaticGrid +-- @within BaseComponent +-- @alias druid.static_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 anchor +-- @tfield vector3 anchor + +--- 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 anchor Item anchor --- @tfield vector3 node_size Item size --- @tfield vector4 border The size of item content local const = require("druid.const") local Event = require("druid.event") @@ -29,11 +50,11 @@ local StaticGrid = component.create("static_grid", { const.ON_LAYOUT_CHANGE }) --- Component init function --- @function static_grid:init +-- @tparam StaticGrid self -- @tparam node parent The gui node parent, where items will be placed -- @tparam node element Element prefab. Need to get it size -- @tparam[opt=1] number in_row How many nodes in row can be placed -function StaticGrid:init(parent, element, in_row) +function StaticGrid.init(self, parent, element, in_row) self.parent = self:get_node(parent) self.nodes = {} @@ -60,10 +81,10 @@ end local _temp_pos = vmath.vector3(0) --- Return pos for grid node index --- @function static_grid:get_pos +-- @tparam StaticGrid self -- @tparam number index The grid element index -- @treturn vector3 Node position -function StaticGrid:get_pos(index) +function StaticGrid.get_pos(self, index) local row = math.ceil(index / self.in_row) - 1 local col = (index - row * self.in_row) - 1 @@ -76,10 +97,10 @@ end --- Return index for grid pos --- @function static_grid:get_index +-- @tparam StaticGrid self -- @tparam vector3 pos The node position in the grid -- @treturn number The node index -function StaticGrid:get_index(pos) +function StaticGrid.get_index(self, pos) local col = pos.x / self.node_size.x + 1 local row = -pos.y / self.node_size.y @@ -92,10 +113,10 @@ end --- Return grid index by node --- @function static_grid:get_index_by_node +-- @tparam StaticGrid self -- @tparam node node The gui node in the grid -- @treturn number The node index -function StaticGrid:get_index_by_node(node) +function StaticGrid.get_index_by_node(self, node) for index, grid_node in pairs(self.nodes) do if node == grid_node then return index @@ -106,25 +127,25 @@ function StaticGrid:get_index_by_node(node) end -function StaticGrid:on_layout_change() +function StaticGrid.on_layout_change(self) self:_update(true) end --- Set grid anchor. Default anchor is equal to anchor of grid parent node --- @function static_grid:set_anchor +-- @tparam StaticGrid self -- @tparam vector3 anchor Anchor -function StaticGrid:set_anchor(anchor) +function StaticGrid.set_anchor(self, anchor) self.anchor = anchor self:_update() end --- Add new item to the grid --- @function static_grid:add +-- @tparam StaticGrid self -- @tparam node item Gui node -- @tparam[opt] number index The item position. By default add as last item -function StaticGrid:add(item, index) +function StaticGrid.add(self, item, index) index = index or ((self.last_index or 0) + 1) if self.nodes[index] then @@ -152,10 +173,10 @@ end --- Remove the item from the grid. Note that gui node will be not deleted --- @function static_grid:remove +-- @tparam StaticGrid self -- @tparam number index The grid node index to remove -- @tparam bool is_shift_nodes If true, will shift nodes left after index -function StaticGrid:remove(index, is_shift_nodes) +function StaticGrid.remove(self, index, is_shift_nodes) assert(self.nodes[index], "No grid item at given index " .. index) self.nodes[index] = nil @@ -168,15 +189,15 @@ function StaticGrid:remove(index, is_shift_nodes) 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 static_grid:get_size +-- @tparam StaticGrid self -- @treturn vector3 The grid content size -function StaticGrid:get_size() +function StaticGrid.get_size(self) return vmath.vector3( self.border.z - self.border.x, self.border.y - self.border.w, @@ -185,9 +206,9 @@ end --- Return array of all node positions --- @function static_grid:get_all_pos +-- @tparam StaticGrid self -- @treturn vector3[] All grid node positions -function StaticGrid:get_all_pos() +function StaticGrid.get_all_pos(self) local result = {} for i, node in pairs(self.nodes) do table.insert(result, gui.get_position(node)) @@ -199,10 +220,10 @@ end --- Change set position function for grid nodes. It will call on -- update poses on grid elements. Default: gui.set_position --- @function static_grid:set_position_function +-- @tparam StaticGrid self -- @tparam function callback Function on node set position -- @treturn druid.static_grid Current grid instance -function StaticGrid:set_position_function(callback) +function StaticGrid.set_position_function(self, callback) self._set_position_function = callback or gui.set_position return self @@ -211,9 +232,9 @@ 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 --- @function static_grid:clear +-- @tparam StaticGrid self -- @treturn druid.static_grid Current grid instance -function StaticGrid:clear() +function StaticGrid.clear(self) self.border.x = 0 self.border.y = 0 self.border.w = 0 @@ -222,16 +243,18 @@ function StaticGrid:clear() self.nodes = {} self:_update() + self.on_clear:trigger(self:get_context()) + return self end --- Return elements offset for correct posing nodes. Correct posing at -- parent pivot node (0:0) with adjusting of node sizes and anchoring --- @function static_grid:_get_zero_offset +-- @tparam StaticGrid self -- @treturn vector3 The offset vector -- @local -function StaticGrid:_get_zero_offset() +function StaticGrid._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), @@ -242,10 +265,10 @@ end --- Update grid inner state --- @function static_grid:_update +-- @tparam StaticGrid self -- @tparam bool is_instant If true, node position update instantly, otherwise with set_position_function callback -- @local -function StaticGrid:_update(is_instant) +function StaticGrid._update(self, is_instant) self:_update_indexes() self:_update_borders() self:_update_pos(is_instant) @@ -253,9 +276,9 @@ end --- Update first and last indexes of grid nodes --- @function static_grid:_update_indexes +-- @tparam StaticGrid self -- @local -function StaticGrid:_update_indexes() +function StaticGrid._update_indexes(self) self.first_index = nil self.last_index = nil for index in pairs(self.nodes) do @@ -269,9 +292,9 @@ end --- Update grid content borders, recalculate min and max values --- @function static_grid:_update_borders +-- @tparam StaticGrid self -- @local -function StaticGrid:_update_borders() +function StaticGrid._update_borders(self) if not self.first_index then self.border = vmath.vector4(0) return @@ -298,10 +321,10 @@ end --- Update grid nodes position --- @function static_grid:_update_indexes +-- @tparam StaticGrid self -- @tparam bool is_instant If true, node position update instantly, otherwise with set_position_function callback -- @local -function StaticGrid:_update_pos(is_instant) +function StaticGrid._update_pos(self, is_instant) local zero_offset = self:_get_zero_offset() for i, node in pairs(self.nodes) do diff --git a/druid/base/swipe.lua b/druid/base/swipe.lua index 09a9eae..f248e64 100644 --- a/druid/base/swipe.lua +++ b/druid/base/swipe.lua @@ -1,16 +1,19 @@ --- Component to handle swipe gestures on node. -- Swipe will be triggered, if swipe was started and -- ended on one node --- @module druid.swipe +-- @module Swipe +-- @within BaseComponent +-- @alias druid.swipe ---- Components fields --- @table Fields --- @tparam node node Swipe node --- @tparam[opt] node click_zone Restriction zone +--- Swipe node +-- @tparam node node + +--- Restriction zone +-- @tparam[opt] node click_zone + +--- Trigger on swipe event(self, swipe_side, dist, delta_time +-- @tfield druid_event on_swipe) ---- Component events --- @table Events --- @tfield druid_event on_swipe Trigger on swipe event local Event = require("druid.event") local const = require("druid.const") @@ -65,11 +68,11 @@ 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=0.4] number SWIPE_TIME Maximum time for swipe trigger -- @tfield[opt=50] number SWIPE_THRESHOLD Minimum distance for swipe trigger -- @tfield[opt=false] bool SWIPE_TRIGGER_ON_MOVE If true, trigger on swipe moving, not only release action -function Swipe:on_style_change(style) +function Swipe.on_style_change(self, style) self.style = {} self.style.SWIPE_TIME = style.SWIPE_TIME or 0.4 self.style.SWIPE_THRESHOLD = style.SWIPE_THRESHOLD or 50 @@ -78,10 +81,10 @@ end --- Component init function --- @function swipe:init +-- @tparam Swipe self -- @tparam node node Gui node -- @tparam function on_swipe_callback Swipe callback for on_swipe_end event -function Swipe:init(node, on_swipe_callback) +function Swipe.init(self, node, on_swipe_callback) self._trigger_on_move = self.style.SWIPE_TRIGGER_ON_MOVE self.node = self:get_node(node) @@ -93,7 +96,7 @@ function Swipe:init(node, on_swipe_callback) end -function Swipe:on_input(action_id, action) +function Swipe.on_input(self, action_id, action) if action_id ~= const.ACTION_TOUCH then return false end @@ -126,16 +129,16 @@ function Swipe:on_input(action_id, action) end -function Swipe:on_input_interrupt() +function Swipe.on_input_interrupt(self) reset_swipe(self) end --- Strict swipe click area. Useful for -- restrict events outside stencil node --- @function swipe:set_click_zone +-- @tparam Swipe self -- @tparam node zone Gui node -function Swipe:set_click_zone(zone) +function Swipe.set_click_zone(self, zone) self.click_zone = self:get_node(zone) end diff --git a/druid/base/text.lua b/druid/base/text.lua index c5018cd..ff29f19 100644 --- a/druid/base/text.lua +++ b/druid/base/text.lua @@ -1,24 +1,43 @@ --- Component to handle all GUI texts. -- Druid text can adjust itself for text node size -- Text will never will be outside of his text size (even multiline) --- @module druid.text +-- @module Text +-- @within BaseComponent +-- @alias druid.text ---- Component events --- @table Events --- @tfield druid_event on_set_text On set text callback --- @tfield druid_event on_update_text_scale On adjust text size callback --- @tfield druid_event on_set_pivot On change pivot callback +--- On set text callback(self, text) +-- @tfield druid_event on_set_text + +--- On adjust text size callback(self, new_scale) +-- @tfield druid_event on_update_text_scale + +--- On change pivot callback(self, pivot) +-- @tfield druid_event on_set_pivot + +--- Text node +-- @tfield node node + +--- Current text position +-- @tfield vector3 pos + +--- Initial text node scale +-- @tfield vector3 start_scale + +--- Current text node scale +-- @tfield vector3 scale + +--- Initial text node size +-- @tfield vector3 start_size + +--- Current text node available are +-- @tfield vector3 text_area + +--- Current text size adjust settings +-- @tfield bool is_no_adjust + +--- Current text color +-- @tfield vector3 color ---- Component fields --- @table Fields --- @tfield node node Text node --- @tfield vector3 pos Current text position --- @tfield vector3 start_scale Initial text node scale --- @tfield vector3 scale Current text node scale --- @tfield vector3 start_size Initial text node size --- @tfield vector3 text_area Current text node available are --- @tfield bool is_no_adjust Current text size adjust settings --- @tfield vector3 color Current text color local Event = require("druid.event") local const = require("druid.const") @@ -77,11 +96,11 @@ end --- Component init function --- @function text:init +-- @tparam Text self -- @tparam node node Gui text node -- @tparam[opt] string value Initial text. Default value is node text from GUI scene. -- @tparam[opt] bool no_adjust If true, text will be not auto-adjust size -function Text:init(node, value, no_adjust) +function Text.init(self, node, value, no_adjust) self.node = self:get_node(node) self.pos = gui.get_position(self.node) @@ -107,15 +126,15 @@ function Text:init(node, value, no_adjust) end -function Text:on_layout_change() +function Text.on_layout_change(self) self:set_to(self.last_value) end --- Calculate text width with font with respect to trailing space --- @function text:get_text_width +-- @tparam Text self -- @tparam[opt] string text -function Text:get_text_width(text) +function Text.get_text_width(self, text) text = text or self.last_value local font = gui.get_font(self.node) local scale = gui.get_scale(self.node) @@ -134,9 +153,9 @@ end --- Set text to text field --- @function text:set_to +-- @tparam Text self -- @tparam string set_to Text for node -function Text:set_to(set_to) +function Text.set_to(self, set_to) self.last_value = set_to gui.set_text(self.node, set_to) @@ -149,27 +168,27 @@ end --- Set color --- @function text:set_color +-- @tparam Text self -- @tparam vector4 color Color for node -function Text:set_color(color) +function Text.set_color(self, color) self.color = color gui.set_color(self.node, color) end --- Set alpha --- @function text:set_alpha +-- @tparam Text self -- @tparam number alpha Alpha for node -function Text:set_alpha(alpha) +function Text.set_alpha(self, alpha) self.color.w = alpha gui.set_color(self.node, self.color) end --- Set scale --- @function text:set_scale +-- @tparam Text self -- @tparam vector3 scale Scale for node -function Text:set_scale(scale) +function Text.set_scale(self, scale) self.last_scale = scale gui.set_scale(self.node, scale) end @@ -177,9 +196,9 @@ end --- Set text pivot. Text will re-anchor inside -- his text area --- @function text:set_pivot +-- @tparam Text self -- @tparam gui.pivot pivot Gui pivot constant -function Text:set_pivot(pivot) +function Text.set_pivot(self, pivot) local prev_pivot = gui.get_pivot(self.node) local prev_offset = const.PIVOTS[prev_pivot] @@ -200,9 +219,9 @@ end --- Return true, if text with line break --- @function text:is_multiline +-- @tparam Text self -- @treturn bool Is text node with line break -function Text:is_multiline() +function Text.is_multiline(self) return gui.get_line_break(self.node) end diff --git a/druid/component.lua b/druid/component.lua index c58d0c4..f735edf 100644 --- a/druid/component.lua +++ b/druid/component.lua @@ -1,20 +1,20 @@ --- Basic class for all Druid components. -- To create you component, use `component.create` --- @module component +-- @module BaseComponent +-- @alias druid.base_component local const = require("druid.const") local class = require("druid.system.middleclass") --- @classmod Component -local Component = class("druid.component") +local BaseComponent = class("druid.component") --- Set current component style table. --- Invoke `on_style_change` on component, if exist. Component should handle +-- Invoke `on_style_change` on component, if exist. BaseComponent should handle -- their style changing and store all style params --- @function component:set_style --- @tparam table style Druid style module -function Component:set_style(druid_style) +-- @tparam BaseComponent self +-- @tparam table druid_style Druid style module +function BaseComponent.set_style(self, druid_style) self._meta.style = druid_style or const.EMPTY_TABLE local component_style = self._meta.style[self._component.name] or const.EMPTY_TABLE @@ -25,39 +25,39 @@ end --- Set current component template name --- @function component:set_template --- @tparam string template Component template name -function Component:set_template(template) +-- @tparam BaseComponent self +-- @tparam string template BaseComponent template name +function BaseComponent.set_template(self, template) self._meta.template = template end --- Set current component nodes --- @function component:set_nodes --- @tparam table nodes Component nodes table -function Component:set_nodes(nodes) +-- @tparam BaseComponent self +-- @tparam table nodes BaseComponent nodes table +function BaseComponent.set_nodes(self, nodes) self._meta.nodes = nodes end --- Get current component context --- @function component:get_context --- @treturn table Component context -function Component:get_context(context) +-- @tparam BaseComponent self +-- @treturn table BaseComponent context +function BaseComponent.get_context(self) return self._meta.context end --- Increase input priority in current input stack --- @function component:increase_input_priority -function Component:increase_input_priority() +-- @tparam BaseComponent self +function BaseComponent.increase_input_priority(self) self._meta.increased_input_priority = true end --- Reset input priority in current input stack --- @function component:reset_input_priority -function Component:reset_input_priority() +-- @tparam BaseComponent self +function BaseComponent.reset_input_priority(self) self._meta.increased_input_priority = false end @@ -66,10 +66,10 @@ end -- If component has nodes, node_or_name should be string -- It auto pick node by template name or from nodes by clone_tree -- if they was setup via component:set_nodes, component:set_template --- @function component:get_node +-- @tparam BaseComponent self -- @tparam string|node node_or_name Node name or node itself -- @treturn node Gui node -function Component:get_node(node_or_name) +function BaseComponent.get_node(self, node_or_name) local template_name = self:__get_template() or const.EMPTY_STRING local nodes = self:__get_nodes() @@ -94,28 +94,28 @@ end --- Return druid with context of calling component. -- Use it to create component inside of other components. --- @function component:get_druid +-- @tparam BaseComponent self -- @treturn Druid Druid instance with component context -function Component:get_druid() +function BaseComponent.get_druid(self) local context = { _context = self } return setmetatable(context, { __index = self._meta.druid }) end --- Return component name --- @function component:get_name +-- @tparam BaseComponent self -- @treturn string The component name -function Component:get_name() +function BaseComponent.get_name(self) return self._component.name end --- Set component input state. By default it enabled -- You can disable any input of component by this function --- @function component:set_input_enabled +-- @tparam BaseComponent self -- @tparam bool state The component input state --- @treturn Component Component itself -function Component:set_input_enabled(state) +-- @treturn BaseComponent BaseComponent itself +function BaseComponent.set_input_enabled(self, state) self._meta.input_enabled = state for index = 1, #self._meta.children do @@ -127,12 +127,12 @@ end --- Return the parent for current component --- @function component:get_parent_component --- @treturn Component|nil The druid component instance or nil -function Component:get_parent_component() +-- @tparam BaseComponent self +-- @treturn druid.base_component|nil The druid component instance or nil +function BaseComponent.get_parent_component(self) local context = self:get_context() - if context.isInstanceOf and context:isInstanceOf(Component) then + if context.isInstanceOf and context:isInstanceOf(BaseComponent) then return context end @@ -141,12 +141,12 @@ end --- Setup component context and his style table --- @function component:setup_component --- @tparam druid_instance table The parent druid instance --- @tparam context table Druid context. Usually it is self of script --- @tparam style table Druid style module --- @treturn component Component itself -function Component:setup_component(druid_instance, context, style) +-- @tparam BaseComponent self +-- @tparam table druid_instance The parent druid instance +-- @tparam table context Druid context. Usually it is self of script +-- @tparam table style Druid style module +-- @treturn component BaseComponent itself +function BaseComponent.setup_component(self, druid_instance, context, style) self._meta = { template = nil, context = nil, @@ -171,12 +171,12 @@ end --- Basic constructor of component. It will call automaticaly --- by `Component.static.create` --- @function component:initialize --- @tparam string name Component name +-- by `BaseComponent.static.create` +-- @tparam BaseComponent self +-- @tparam string name BaseComponent name -- @tparam[opt={}] table interest List of component's interest -- @local -function Component:initialize(name, interest) +function BaseComponent.initialize(self, name, interest) interest = interest or {} self._component = { @@ -186,55 +186,61 @@ function Component:initialize(name, interest) end -function Component:__tostring() +function BaseComponent.__tostring(self) return self._component.name end --- Set current component context --- @function component:__set_context +-- @tparam BaseComponent self -- @tparam table context Druid context. Usually it is self of script -function Component:__set_context(context) +-- @local +function BaseComponent.__set_context(self, context) self._meta.context = context end --- Get current component interests --- @function component:__get_interests +-- @tparam BaseComponent self -- @treturn table List of component interests -function Component:__get_interests() +-- @local +function BaseComponent.__get_interests(self) return self._component.interest end --- Get current component template name --- @function component:__get_template --- @treturn string Component template name -function Component:__get_template() +-- @tparam BaseComponent self +-- @treturn string BaseComponent template name +-- @local +function BaseComponent.__get_template(self) return self._meta.template end --- Get current component nodes --- @function component:__get_nodes --- @treturn table Component nodes table -function Component:__get_nodes() +-- @tparam BaseComponent self +-- @treturn table BaseComponent nodes table +-- @local +function BaseComponent.__get_nodes(self) return self._meta.nodes end --- Add child to component children list --- @function component:__add_children +-- @tparam BaseComponent self -- @tparam component children The druid component instance -function Component:__add_children(children) +-- @local +function BaseComponent.__add_children(self, children) table.insert(self._meta.children, children) end --- Remove child from component children list --- @function component:__remove_children +-- @tparam BaseComponent self -- @tparam component children The druid component instance -function Component:__remove_children(children) +-- @local +function BaseComponent.__remove_children(self, children) for i = #self._meta.children, 1, -1 do if self._meta.children[i] == children then table.remove(self._meta.children, i) @@ -245,19 +251,19 @@ end --- Create new component. It will inheritance from basic -- druid component. --- @function Component.create --- @tparam string name Component name +-- @tparam string name BaseComponent name -- @tparam[opt={}] table interest List of component's interest -function Component.static.create(name, interest) +-- @local +function BaseComponent.static.create(name, interest) -- Yea, inheritance here - local new_class = class(name, Component) + local new_class = class(name, BaseComponent) new_class.initialize = function(self) - Component.initialize(self, name, interest) + BaseComponent.initialize(self, name, interest) end return new_class end -return Component +return BaseComponent diff --git a/druid/const.lua b/druid/const.lua index 3437fe4..a16499e 100644 --- a/druid/const.lua +++ b/druid/const.lua @@ -1,6 +1,7 @@ --- Druid constants -- @local --- @module const +-- @module DruidConst +-- @alias druid_const local M = {} diff --git a/druid/event.lua b/druid/event.lua index a8ada46..0e9f624 100644 --- a/druid/event.lua +++ b/druid/event.lua @@ -1,16 +1,16 @@ --- Lua event small library --- @module druid_event +-- @module DruidEvent +-- @alias druid_event local class = require("druid.system.middleclass") --- @class DruidEvent -local Event = class("druid.event") +local DruidEvent = class("druid.event") --- Event constructur --- @function Event +-- @tparam DruidEvent self -- @tparam function initial_callback Subscribe the callback on new event, if callback exist -function Event:initialize(initial_callback) +function DruidEvent.initialize(self, initial_callback) self._callbacks = {} if initial_callback then @@ -20,9 +20,9 @@ end --- Subscribe callback on event --- @function event:subscribe +-- @tparam DruidEvent self -- @tparam function callback Callback itself -function Event:subscribe(callback) +function DruidEvent.subscribe(self, callback) assert(type(self) == "table", "You should subscribe to event with : syntax") assert(type(callback) == "function", "Callback should be function") @@ -33,9 +33,9 @@ end --- Unsubscribe callback on event --- @function event:unsubscribe +-- @tparam DruidEvent self -- @tparam function callback Callback itself -function Event:unsubscribe(callback) +function DruidEvent.unsubscribe(self, callback) for i = 1, #self._callbacks do if self._callbacks[i] == callback then table.remove(self._callbacks, i) @@ -46,28 +46,28 @@ end --- Return true, if event have at lease one handler --- @function event:is_exist +-- @tparam DruidEvent self -- @treturn bool True if event have handlers -function Event:is_exist() +function DruidEvent.is_exist(self) return #self._callbacks > 0 end --- Clear the all event handlers --- @function event:clear -function Event:clear() +-- @tparam DruidEvent self +function DruidEvent.clear(self) self._callbacks = {} end --- Trigger the event and call all subscribed callbacks --- @function event:trigger --- @param ... All event params -function Event:trigger(...) +-- @tparam DruidEvent self +-- @tparam any ... All event params +function DruidEvent.trigger(self, ...) for i = 1, #self._callbacks do self._callbacks[i](...) end end -return Event +return DruidEvent diff --git a/druid/extended/checkbox.lua b/druid/extended/checkbox.lua index bfe7c6e..24b5e56 100644 --- a/druid/extended/checkbox.lua +++ b/druid/extended/checkbox.lua @@ -1,15 +1,20 @@ --- Druid checkbox component --- @module druid.checkbox +-- @module Checkbox +-- @within BaseComponent +-- @alias druid.checkbox ---- Component events --- @table Events --- @tfield druid_event on_change_state On change state callback +--- On change state callback(self, state) +-- @tfield druid_event on_change_state + +--- Visual node +-- @tfield node node + +--- Button trigger node +-- @tfield[opt=node] node click_node + +--- Button component from click_node +-- @tfield Button button ---- Component fields --- @table Fields --- @tfield node node Visual node --- @tfield[opt=node] node click_node Button trigger node --- @tfield druid.button button Button component from click_node local const = require("druid.const") local Event = require("druid.event") @@ -26,9 +31,9 @@ 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 function on_change_state (self, node, state) -function Checkbox:on_style_change(style) +function Checkbox.on_style_change(self, style) self.style = {} self.style.on_change_state = style.on_change_state or function(_, node, state) @@ -38,11 +43,11 @@ end --- Component init function --- @function checkbox:init +-- @tparam Checkbox self -- @tparam node node Gui node -- @tparam function callback Checkbox callback --- @tparam[opt=node] node click node Trigger node, by default equals to node -function Checkbox:init(node, callback, click_node) +-- @tparam[opt=node] node click_node Trigger node, by default equals to node +function Checkbox.init(self, node, callback, click_node) self.druid = self:get_druid() self.node = self:get_node(node) self.click_node = self:get_node(click_node) @@ -54,16 +59,16 @@ function Checkbox:init(node, callback, click_node) end -function Checkbox:on_layout_change() +function Checkbox.on_layout_change(self) self:set_state(self.state, true) end --- Set checkbox state --- @function checkbox:set_state +-- @tparam Checkbox self -- @tparam bool state Checkbox state -- @tparam bool is_silent Don't trigger on_change_state if true -function Checkbox:set_state(state, is_silent) +function Checkbox.set_state(self, state, is_silent) self.state = state self.style.on_change_state(self, self.node, state) @@ -74,9 +79,9 @@ end --- Return checkbox state --- @function checkbox:get_state +-- @tparam Checkbox self -- @treturn bool Checkbox state -function Checkbox:get_state() +function Checkbox.get_state(self) return self.state end diff --git a/druid/extended/checkbox_group.lua b/druid/extended/checkbox_group.lua index 376c712..a801a89 100644 --- a/druid/extended/checkbox_group.lua +++ b/druid/extended/checkbox_group.lua @@ -1,13 +1,14 @@ --- Checkbox group module --- @module druid.checkbox_group +-- @module CheckboxGroup +-- @within BaseComponent +-- @alias druid.checkbox_group ---- Component events --- @table Events --- @tfield druid_event on_checkbox_click On any checkbox click +--- On any checkbox click callback(self, index) +-- @tfield druid_event on_checkbox_click + +--- Array of checkbox components +-- @tfield table checkboxes ---- Component fields --- @table Fields --- @tfield table checkboxes Array of checkbox components local Event = require("druid.event") local component = require("druid.component") @@ -16,11 +17,11 @@ local CheckboxGroup = component.create("checkbox_group") --- Component init function --- @function checkbox_group:init --- @tparam node[] node Array of gui node +-- @tparam CheckboxGroup self +-- @tparam node[] nodes Array of gui node -- @tparam function callback Checkbox callback --- @tparam[opt=node] node[] click node Array of trigger nodes, by default equals to nodes -function CheckboxGroup:init(nodes, callback, click_nodes) +-- @tparam[opt=node] node[] click_nodes Array of trigger nodes, by default equals to nodes +function CheckboxGroup.init(self, nodes, callback, click_nodes) self.druid = self:get_druid() self.checkboxes = {} @@ -38,9 +39,9 @@ end --- Set checkbox group state --- @function checkbox_group:set_state +-- @tparam CheckboxGroup self -- @tparam bool[] indexes Array of checkbox state -function CheckboxGroup:set_state(indexes) +function CheckboxGroup.set_state(self, indexes) for i = 1, #indexes do if self.checkboxes[i] then self.checkboxes[i]:set_state(indexes[i], true) @@ -50,9 +51,9 @@ end --- Return checkbox group state --- @function checkbox_group:get_state +-- @tparam CheckboxGroup self -- @treturn bool[] Array if checkboxes state -function CheckboxGroup:get_state() +function CheckboxGroup.get_state(self) local result = {} for i = 1, #self.checkboxes do diff --git a/druid/extended/dynamic_grid.lua b/druid/extended/dynamic_grid.lua index e009459..efa6f0a 100644 --- a/druid/extended/dynamic_grid.lua +++ b/druid/extended/dynamic_grid.lua @@ -1,22 +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") @@ -42,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) @@ -67,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 @@ -113,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 @@ -155,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) @@ -178,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, @@ -196,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 @@ -211,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)) @@ -225,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 @@ -236,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), @@ -260,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) @@ -271,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 @@ -287,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 @@ -316,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 @@ -334,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) @@ -353,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), @@ -373,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 b70608c..0ea8db5 100644 --- a/druid/extended/input.lua +++ b/druid/extended/input.lua @@ -1,26 +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") @@ -90,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 @@ -115,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) @@ -149,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 @@ -213,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 @@ -271,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 @@ -292,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 61d345f..b51992c 100644 --- a/druid/extended/lang_text.lua +++ b/druid/extended/lang_text.lua @@ -1,14 +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") @@ -19,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 = {} @@ -36,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 @@ -44,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() @@ -54,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 2a343ba..fb257e1 100644 --- a/druid/extended/progress.lua +++ b/druid/extended/progress.lua @@ -1,19 +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") @@ -68,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 @@ -79,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) @@ -106,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) @@ -132,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 75be888..9bdbd9c 100644 --- a/druid/extended/radio_group.lua +++ b/druid/extended/radio_group.lua @@ -1,13 +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") @@ -25,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 = {} @@ -47,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 2661927..e890a5e 100644 --- a/druid/extended/slider.lua +++ b/druid/extended/slider.lua @@ -1,20 +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") @@ -37,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) @@ -59,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 @@ -130,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 @@ -145,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 34b6b98..5ae1ba8 100644 --- a/druid/extended/timer.lua +++ b/druid/extended/timer.lua @@ -1,20 +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") @@ -26,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) @@ -52,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 @@ -75,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) @@ -94,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 e8f4cd9..a5f6562 100644 --- a/druid/system/druid_instance.lua +++ b/druid/system/druid_instance.lua @@ -7,24 +7,26 @@ -- end -- -- Learn Druid instance function here --- @module druid_instance --- @see druid.button --- @see druid.blocker --- @see druid.back_handler --- @see druid.input --- @see druid.text --- @see druid.lang_text --- @see druid.timer --- @see druid.progress --- @see druid.static_grid --- @see druid.dynamic_grid --- @see druid.scroll --- @see druid.slider --- @see druid.checkbox --- @see druid.checkbox_group --- @see druid.radio_group --- @see druid.swipe --- @see druid.drag +-- @module DruidInstance +-- @alias druid_instance +-- @see Button +-- @see Blocker +-- @see BackHandler +-- @see Input +-- @see Text +-- @see LangText +-- @see Timer +-- @see Progress +-- @see StaticGrid +-- @see DynamicGrid +-- @see Scroll +-- @see Slider +-- @see Checkbox +-- @see CheckboxGroup +-- @see RadioGroup +-- @see Swipe +-- @see Drag +-- @see Hover local const = require("druid.const") local helper = require("druid.helper") @@ -52,8 +54,8 @@ local radio_group = require("druid.extended.radio_group") local slider = require("druid.extended.slider") local timer = require("druid.extended.timer") --- @classmod Druid -local Druid = class("druid.druid_instance") + +local DruidInstance = class("druid.druid_instance") local function input_init(self) @@ -141,10 +143,10 @@ end --- Druid class constructor --- @function druid:initialize --- @tparam context table Druid context. Usually it is self of script --- @tparam style table Druid style module -function Druid:initialize(context, style) +-- @tparam DruidInstance self +-- @tparam table context Druid context. Usually it is self of script +-- @tparam table style Druid style module +function DruidInstance.initialize(self, context, style) self._context = context self._style = style or settings.default_style self._deleted = false @@ -160,10 +162,10 @@ end --- Create new druid component --- @function druid:create +-- @tparam DruidInstance self -- @tparam Component component Component module -- @tparam args ... Other component params to pass it to component:init function -function Druid:create(component, ...) +function DruidInstance.create(self, component, ...) local instance = create(self, component) if instance.init then @@ -176,8 +178,8 @@ end --- Call on final function on gui_script. It will call on_remove -- on all druid components --- @function druid:final -function Druid:final() +-- @tparam DruidInstance self +function DruidInstance.final(self) local components = self.components[const.ALL] for i = #components, 1, -1 do @@ -194,9 +196,9 @@ end --- Remove component from druid instance. -- Component `on_remove` function will be invoked, if exist. --- @function druid:remove +-- @tparam DruidInstance self -- @tparam Component component Component instance -function Druid:remove(component) +function DruidInstance.remove(self, component) if self._is_input_processing then table.insert(self._late_remove, component) return @@ -237,9 +239,9 @@ end --- Druid update function --- @function druid:update +-- @tparam DruidInstance self -- @tparam number dt Delta time -function Druid:update(dt) +function DruidInstance.update(self, dt) local components = self.components[const.ON_UPDATE] for i = 1, #components do components[i]:update(dt) @@ -248,10 +250,10 @@ end --- Druid on_input function --- @function druid:on_input +-- @tparam DruidInstance self -- @tparam hash action_id Action_id from on_input -- @tparam table action Action from on_input -function Druid:on_input(action_id, action) +function DruidInstance.on_input(self, action_id, action) self._is_input_processing = true local is_input_consumed = false @@ -276,11 +278,11 @@ end --- Druid on_message function --- @function druid:on_message +-- @tparam DruidInstance self -- @tparam hash message_id Message_id from on_message -- @tparam table message Message from on_message -- @tparam hash sender Sender from on_message -function Druid:on_message(message_id, message, sender) +function DruidInstance.on_message(self, message_id, message, sender) local specific_ui_message = const.SPECIFIC_UI_MESSAGES[message_id] if specific_ui_message then @@ -302,8 +304,8 @@ end --- Druid on focus lost interest function. -- This one called by on_window_callback by global window listener --- @function druid:on_focus_lost -function Druid:on_focus_lost() +-- @tparam DruidInstance self +function DruidInstance.on_focus_lost(self) local components = self.components[const.ON_FOCUS_LOST] for i = 1, #components do components[i]:on_focus_lost() @@ -313,8 +315,8 @@ end --- Druid on focus gained interest function. -- This one called by on_window_callback by global window listener --- @function druid:on_focus_gained -function Druid:on_focus_gained() +-- @tparam DruidInstance self +function DruidInstance.on_focus_gained(self) local components = self.components[const.ON_FOCUS_GAINED] for i = 1, #components do components[i]:on_focus_gained() @@ -324,8 +326,8 @@ end --- Druid on layout change function. -- Called on update gui layout --- @function druid:on_layout_change -function Druid:on_layout_change() +-- @tparam DruidInstance self +function DruidInstance.on_layout_change(self) local components = self.components[const.ON_LAYOUT_CHANGE] for i = 1, #components do components[i]:on_layout_change() @@ -337,7 +339,7 @@ end -- This one called by global gruid.on_language_change, but can be -- call manualy to update all translations -- @function druid.on_language_change -function Druid:on_language_change() +function DruidInstance.on_language_change(self) local components = self.components[const.ON_LANGUAGE_CHANGE] for i = 1, #components do components[i]:on_language_change() @@ -346,185 +348,185 @@ end --- Create button basic component --- @function druid:new_button +-- @tparam DruidInstance self -- @tparam args ... button init args -- @treturn Component button component -function Druid:new_button(...) - return Druid.create(self, button, ...) +function DruidInstance.new_button(self, ...) + return DruidInstance.create(self, button, ...) end --- Create blocker basic component --- @function druid:new_blocker +-- @tparam DruidInstance self -- @tparam args ... blocker init args -- @treturn Component blocker component -function Druid:new_blocker(...) - return Druid.create(self, blocker, ...) +function DruidInstance.new_blocker(self, ...) + return DruidInstance.create(self, blocker, ...) end --- Create back_handler basic component --- @function druid:new_back_handler +-- @tparam DruidInstance self -- @tparam args ... back_handler init args -- @treturn Component back_handler component -function Druid:new_back_handler(...) - return Druid.create(self, back_handler, ...) +function DruidInstance.new_back_handler(self, ...) + return DruidInstance.create(self, back_handler, ...) end --- Create hover basic component --- @function druid:new_hover +-- @tparam DruidInstance self -- @tparam args ... hover init args -- @treturn Component hover component -function Druid:new_hover(...) - return Druid.create(self, hover, ...) +function DruidInstance.new_hover(self, ...) + return DruidInstance.create(self, hover, ...) end --- Create text basic component --- @function druid:new_text +-- @tparam DruidInstance self -- @tparam args ... text init args -- @treturn Component text component -function Druid:new_text(...) - return Druid.create(self, text, ...) +function DruidInstance.new_text(self, ...) + return DruidInstance.create(self, text, ...) end --- Create grid basic component -- Deprecated --- @function druid:new_grid +-- @tparam DruidInstance self -- @tparam args ... grid init args -- @treturn Component grid component -function Druid:new_grid(...) +function DruidInstance.new_grid(self, ...) helper.deprecated("The druid:new_grid is deprecated. Please use druid:new_static_grid instead") - return Druid.create(self, static_grid, ...) + return DruidInstance.create(self, static_grid, ...) end --- Create static grid basic component --- @function druid:new_static_grid +-- @tparam DruidInstance self -- @tparam args ... grid init args -- @treturn Component grid component -function Druid:new_static_grid(...) - return Druid.create(self, static_grid, ...) +function DruidInstance.new_static_grid(self, ...) + return DruidInstance.create(self, static_grid, ...) end --- Create scroll basic component --- @function druid:new_scroll +-- @tparam DruidInstance self -- @tparam args ... scroll init args -- @treturn Component scroll component -function Druid:new_scroll(...) - return Druid.create(self, scroll, ...) +function DruidInstance.new_scroll(self, ...) + return DruidInstance.create(self, scroll, ...) end --- Create swipe basic component --- @function druid:new_swipe +-- @tparam DruidInstance self -- @tparam args ... swipe init args -- @treturn Component swipe component -function Druid:new_swipe(...) - return Druid.create(self, swipe, ...) +function DruidInstance.new_swipe(self, ...) + return DruidInstance.create(self, swipe, ...) end --- Create drag basic component --- @function druid:new_drag +-- @tparam DruidInstance self -- @tparam args ... drag init args -- @treturn Componetn drag component -function Druid:new_drag(...) - return Druid.create(self, drag, ...) +function DruidInstance.new_drag(self, ...) + return DruidInstance.create(self, drag, ...) end --- Create dynamic grid component --- @function druid:new_dynamic_grid +-- @tparam DruidInstance self -- @tparam args ... grid init args -- @treturn Component grid component -function Druid:new_dynamic_grid(...) +function DruidInstance.new_dynamic_grid(self, ...) -- return helper.extended_component("dynamic_grid") - return Druid.create(self, dynamic_grid, ...) + return DruidInstance.create(self, dynamic_grid, ...) end --- Create lang_text component --- @function druid:new_lang_text +-- @tparam DruidInstance self -- @tparam args ... lang_text init args -- @treturn Component lang_text component -function Druid:new_lang_text(...) +function DruidInstance.new_lang_text(self, ...) -- return helper.extended_component("lang_text") - return Druid.create(self, lang_text, ...) + return DruidInstance.create(self, lang_text, ...) end --- Create slider component --- @function druid:new_slider +-- @tparam DruidInstance self -- @tparam args ... slider init args -- @treturn Component slider component -function Druid:new_slider(...) +function DruidInstance.new_slider(self, ...) -- return helper.extended_component("slider") - return Druid.create(self, slider, ...) + return DruidInstance.create(self, slider, ...) end --- Create checkbox component --- @function druid:new_checkbox +-- @tparam DruidInstance self -- @tparam args ... checkbox init args -- @treturn Component checkbox component -function Druid:new_checkbox(...) +function DruidInstance.new_checkbox(self, ...) -- return helper.extended_component("checkbox") - return Druid.create(self, checkbox, ...) + return DruidInstance.create(self, checkbox, ...) end --- Create input component --- @function druid:new_input +-- @tparam DruidInstance self -- @tparam args ... input init args -- @treturn Component input component -function Druid:new_input(...) +function DruidInstance.new_input(self, ...) -- return helper.extended_component("input") - return Druid.create(self, input, ...) + return DruidInstance.create(self, input, ...) end --- Create checkbox_group component --- @function druid:new_checkbox_group +-- @tparam DruidInstance self -- @tparam args ... checkbox_group init args -- @treturn Component checkbox_group component -function Druid:new_checkbox_group(...) +function DruidInstance.new_checkbox_group(self, ...) -- return helper.extended_component("checkbox_group") - return Druid.create(self, checkbox_group, ...) + return DruidInstance.create(self, checkbox_group, ...) end --- Create radio_group component --- @function druid:new_radio_group +-- @tparam DruidInstance self -- @tparam args ... radio_group init args -- @treturn Component radio_group component -function Druid:new_radio_group(...) +function DruidInstance.new_radio_group(self, ...) -- return helper.extended_component("radio_group") - return Druid.create(self, radio_group, ...) + return DruidInstance.create(self, radio_group, ...) end --- Create timer component --- @function druid:new_timer +-- @tparam DruidInstance self -- @tparam args ... timer init args -- @treturn Component timer component -function Druid:new_timer(...) +function DruidInstance.new_timer(self, ...) -- return helper.extended_component("timer") - return Druid.create(self, timer, ...) + return DruidInstance.create(self, timer, ...) end --- Create progress component --- @function druid:new_progress +-- @tparam DruidInstance self -- @tparam args ... progress init args -- @treturn Component progress component -function Druid:new_progress(...) +function DruidInstance.new_progress(self, ...) -- return helper.extended_component("progress") - return Druid.create(self, progress, ...) + return DruidInstance.create(self, progress, ...) end -return Druid +return DruidInstance diff --git a/settings_deployer b/settings_deployer index de288e7..91665ba 100644 --- a/settings_deployer +++ b/settings_deployer @@ -1,2 +1,4 @@ #!/bin/bash use_latest_bob=false +enable_incremental_version=true +bob_sha="173:fe2b689302e79b7cf8c0bc7d934f23587b268c8a"