Update annotations: scroll, hover and drag

druid/base/scroll.lua

@@ -5,29 +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
+-- @tfield druid_event on_scroll(self, position)
+
+--- 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)
+
+--- 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")
@@ -66,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
@@ -76,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
@@ -96,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)
@@ -130,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
@@ -144,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)
@@ -181,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
@@ -204,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(
@@ -223,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)
 
@@ -235,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()
 
@@ -249,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
@@ -260,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()
 
@@ -281,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)
@@ -307,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
@@ -318,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
@@ -331,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)
 
@@ -356,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
@@ -397,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
@@ -422,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
@@ -433,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)
@@ -452,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
@@ -504,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
@@ -522,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
@@ -543,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
 
@@ -554,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
@@ -562,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))