From 248b9c30f92527b9ab1cc4c16652bbf441966746 Mon Sep 17 00:00:00 2001 From: Insality Date: Sun, 11 Oct 2020 23:53:30 +0300 Subject: [PATCH] Update annotations: scroll, static_grid, events, druid_instance --- druid/base/scroll.lua | 8 +- druid/base/static_grid.lua | 123 +++++++++++++---------- druid/const.lua | 3 +- druid/event.lua | 34 +++---- druid/system/druid_instance.lua | 171 ++++++++++++++++---------------- 5 files changed, 181 insertions(+), 158 deletions(-) diff --git a/druid/base/scroll.lua b/druid/base/scroll.lua index 3646984..7f76bb6 100644 --- a/druid/base/scroll.lua +++ b/druid/base/scroll.lua @@ -10,14 +10,14 @@ -- @alias druid.scroll ---- On scroll move callback --- @tfield druid_event on_scroll(self, position) +--- 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 --- @tfield druid_event on_point_scroll(self, index, point) +--- On scroll_to_index function callback(self, index, point) +-- @tfield druid_event on_point_scroll --- Scroll view node -- @tfield node view_node diff --git a/druid/base/static_grid.lua b/druid/base/static_grid.lua index 05e06c9..7e2e7dd 100644 --- a/druid/base/static_grid.lua +++ b/druid/base/static_grid.lua @@ -1,26 +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") @@ -31,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 = {} @@ -62,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 @@ -78,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 @@ -94,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 @@ -108,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 @@ -154,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 @@ -170,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, @@ -187,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)) @@ -201,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 @@ -213,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 @@ -224,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), @@ -244,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) @@ -255,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 @@ -271,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 @@ -300,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/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/system/druid_instance.lua b/druid/system/druid_instance.lua index a2b8898..407acce 100644 --- a/druid/system/druid_instance.lua +++ b/druid/system/druid_instance.lua @@ -7,7 +7,8 @@ -- end -- -- Learn Druid instance function here --- @module druid_instance +-- @module DruidInstance +-- @alias druid_instance -- @see Button -- @see Blocker -- @see BackHandler @@ -16,7 +17,7 @@ -- @see druid.lang_text -- @see druid.timer -- @see druid.progress --- @see druid.static_grid +-- @see StaticGrid -- @see druid.dynamic_grid -- @see Scroll -- @see druid.slider @@ -53,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) @@ -142,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 @@ -161,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 @@ -177,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 @@ -195,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 @@ -238,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) @@ -249,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 @@ -277,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 @@ -303,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() @@ -314,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() @@ -325,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() @@ -338,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() @@ -347,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 DruidInstanceInstance