Update annotations: scroll, static_grid, events, druid_instance

This commit is contained in:
Insality 2020-10-11 23:53:30 +03:00
parent 082aa454c6
commit 248b9c30f9
5 changed files with 181 additions and 158 deletions

View File

@ -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

View File

@ -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

View File

@ -1,6 +1,7 @@
--- Druid constants
-- @local
-- @module const
-- @module DruidConst
-- @alias druid_const
local M = {}

View File

@ -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

View File

@ -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