Update annotations P.1

druid/base/scroll.lua

@@ -39,13 +39,13 @@
 
 
 --- On scroll move callback(self, position)
--- @tfield DruidEvent on_scroll @{DruidEvent}
+-- @tfield DruidEvent on_scroll DruidEvent
 
 --- On scroll_to function callback(self, target, is_instant)
--- @tfield DruidEvent on_scroll_to @{DruidEvent}
+-- @tfield DruidEvent on_scroll_to DruidEvent
 
 --- On scroll_to_index function callback(self, index, point)
--- @tfield DruidEvent on_point_scroll @{DruidEvent}
+-- @tfield DruidEvent on_point_scroll DruidEvent
 
 --- Scroll view node
 -- @tfield node view_node
@@ -75,7 +75,7 @@
 -- @tfield vector3 available_size
 
 --- Drag Druid component
--- @tfield Drag drag @{Drag}
+-- @tfield Drag drag Drag
 
 --- Current index of points of interests
 -- @tfield number|nil selected
@@ -90,7 +90,16 @@ local const = require("druid.const")
 local helper = require("druid.helper")
 local component = require("druid.component")
 
-local Scroll = component.create("scroll")
+---@class druid.scroll: druid.base_component
+---@field on_scroll druid.event
+---@field on_scroll_to druid.event
+---@field on_point_scroll druid.event
+---@field view_node node
+---@field view_border vector4
+---@field content_node node
+---@field view_size vector3
+---@field position vector3
+local M = component.create("scroll")
 
 
 local function inverse_lerp(min, max, current)
@@ -138,7 +147,7 @@ end
 -- @tfield boolean|nil WHEEL_SCROLL_SPEED The scroll speed via mouse wheel scroll or touchpad. Set to 0 to disable wheel scrolling. Default: 0
 -- @tfield boolean|nil WHEEL_SCROLL_INVERTED If true, invert direction for touchpad and mouse wheel scroll. Default: false
 -- @tfield boolean|nil WHEEL_SCROLL_BY_INERTION If true, wheel will add inertion to scroll. Direct set position otherwise.. Default: false
-function Scroll.on_style_change(self, style)
+function M:on_style_change(style)
 	self.style = {}
 	self.style.EXTRA_STRETCH_SIZE = style.EXTRA_STRETCH_SIZE or 0
 	self.style.ANIM_SPEED = style.ANIM_SPEED or 0.2
@@ -161,11 +170,11 @@ function Scroll.on_style_change(self, style)
 end
 
 
---- The @{Scroll} constructor
--- @tparam Scroll self @{Scroll}
+--- The Scroll constructor
+-- @tparam Scroll self Scroll
 -- @tparam string|node view_node GUI view scroll node
 -- @tparam string|node content_node GUI content scroll node
-function Scroll.init(self, view_node, content_node)
+function M:init(view_node, content_node)
 	self.druid = self:get_druid()
 
 	self.view_node = self:get_node(view_node)
@@ -203,7 +212,7 @@ function Scroll.init(self, view_node, content_node)
 end
 
 
-function Scroll.on_late_init(self)
+function M:on_late_init()
 	if not self.click_zone and const.IS_STENCIL_CHECK then
 		local stencil_node = helper.get_closest_stencil_node(self.node)
 		if stencil_node then
@@ -213,12 +222,12 @@ function Scroll.on_late_init(self)
 end
 
 
-function Scroll.on_layout_change(self)
+function M:on_layout_change()
 	gui.set_position(self.content_node, self.position)
 end
 
 
-function Scroll.update(self, dt)
+function M:update(dt)
 	if self.is_animate then
 		self.position.x = gui.get(self.content_node, "position.x")
 		self.position.y = gui.get(self.content_node, "position.y")
@@ -233,23 +242,23 @@ function Scroll.update(self, dt)
 end
 
 
-function Scroll.on_input(self, action_id, action)
+function M:on_input(action_id, action)
 	return self:_process_scroll_wheel(action_id, action)
 end
 
 
-function Scroll.on_remove(self)
+function M:on_remove()
 	self:bind_grid(nil)
 end
 
 
 --- Start scroll to target point.
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam vector3 point Target point
 -- @tparam boolean|nil 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(self, point, is_instant)
+function M:scroll_to(point, is_instant)
 	local b = self.available_pos
 	local target = vmath.vector3(
 		self._is_horizontal_scroll and -point.x or self.target_position.x,
@@ -278,10 +287,10 @@ end
 
 
 --- Scroll to item in scroll by point index.
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam number index Point index
 -- @tparam boolean|nil skip_cb If true, skip the point callback
-function Scroll.scroll_to_index(self, index, skip_cb)
+function M:scroll_to_index(index, skip_cb)
 	if not self.points then
 		return
 	end
@@ -301,11 +310,11 @@ end
 
 
 --- Start scroll to target scroll percent
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam vector3 percent target percent
 -- @tparam boolean|nil is_instant instant scroll flag
 -- @usage scroll:scroll_to_percent(vmath.vector3(0.5, 0, 0))
-function Scroll.scroll_to_percent(self, percent, is_instant)
+function M:scroll_to_percent(percent, is_instant)
 	local border = self.available_pos
 
 	local pos = vmath.vector3(
@@ -327,9 +336,9 @@ end
 
 --- Return current scroll progress status.
 -- Values will be in [0..1] interval
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @treturn vector3 New vector with scroll progress values
-function Scroll.get_percent(self)
+function M:get_percent()
 	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)
 
@@ -339,11 +348,11 @@ end
 
 --- Set scroll content size.
 -- It will change content gui node size
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam vector3 size The new size for content node
 -- @tparam vector3|nil offset Offset value to set, where content is starts
 -- @treturn druid.scroll Current scroll instance
-function Scroll.set_size(self, size, offset)
+function M:set_size(size, offset)
 	if offset then
 		self._offset = offset
 	end
@@ -355,10 +364,10 @@ end
 
 
 --- Set new scroll view size in case the node size was changed.
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam vector3 size The new size for view node
 -- @treturn druid.scroll Current scroll instance
-function Scroll.set_view_size(self, size)
+function M:set_view_size(size)
 	gui.set_size(self.view_node, size)
 	self.view_size = size
 	self.view_border = helper.get_border(self.view_node)
@@ -369,8 +378,8 @@ end
 
 
 --- Refresh scroll view size
--- @tparam Scroll self @{Scroll}
-function Scroll.update_view_size(self)
+-- @tparam Scroll self Scroll
+function M:update_view_size()
 	self.view_size = helper.get_scaled_size(self.view_node)
 	self.view_border = helper.get_border(self.view_node)
 	self:_update_size()
@@ -382,10 +391,10 @@ end
 --- Enable or disable scroll inert.
 -- If disabled, scroll through points (if exist)
 -- If no points, just simple drag without inertion
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam boolean|nil state Inert scroll state
 -- @treturn druid.scroll Current scroll instance
-function Scroll.set_inert(self, state)
+function M:set_inert(state)
 	self._is_inert = state
 
 	return self
@@ -393,19 +402,19 @@ end
 
 
 --- Return if scroll have inertion.
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @treturn boolean @If scroll have inertion
-function Scroll.is_inert(self)
+function M:is_inert()
 	return self._is_inert
 end
 
 
 --- Set extra size for scroll stretching.
 -- Set 0 to disable stretching effect
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam number|nil stretch_size Size in pixels of additional scroll area
 -- @treturn druid.scroll Current scroll instance
-function Scroll.set_extra_stretch_size(self, stretch_size)
+function M:set_extra_stretch_size(stretch_size)
 	self.style.EXTRA_STRETCH_SIZE = stretch_size or 0
 	self:_update_size()
 
@@ -414,19 +423,19 @@ end
 
 
 --- Return vector of scroll size with width and height.
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @treturn vector3 Available scroll size
-function Scroll.get_scroll_size(self)
+function M:get_scroll_size()
 	return self.available_size
 end
 
 
 --- Set points of interest.
 -- Scroll will always centered on closer points
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam table points Array of vector3 points
 -- @treturn druid.scroll Current scroll instance
-function Scroll.set_points(self, points)
+function M:set_points(points)
 	self.points = points
 
 	table.sort(self.points, function(a, b)
@@ -440,10 +449,10 @@ end
 
 
 --- Lock or unlock horizontal scroll
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam boolean|nil state True, if horizontal scroll is enabled
 -- @treturn druid.scroll Current scroll instance
-function Scroll.set_horizontal_scroll(self, state)
+function M:set_horizontal_scroll(state)
 	self._is_horizontal_scroll = state
 	self.drag.can_x = self.available_size.x > 0 and state
 	return self
@@ -451,10 +460,10 @@ end
 
 
 --- Lock or unlock vertical scroll
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam boolean|nil state True, if vertical scroll is enabled
 -- @treturn druid.scroll Current scroll instance
-function Scroll.set_vertical_scroll(self, state)
+function M:set_vertical_scroll(state)
 	self._is_vertical_scroll = state
 	self.drag.can_y = self.available_size.y > 0 and state
 	return self
@@ -463,10 +472,10 @@ end
 
 --- Check node if it visible now on scroll.
 -- Extra border is not affected. Return true for elements in extra scroll zone
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam node node The node to check
 -- @treturn boolean True if node in visible scroll area
-function Scroll.is_node_in_view(self, node)
+function M:is_node_in_view(node)
 	local node_offset_for_view = gui.get_position(node)
 	local parent = gui.get_parent(node)
 	local is_parent_of_view = false
@@ -504,10 +513,10 @@ end
 
 --- Bind the grid component (Static or Dynamic) to recalculate
 -- scroll size on grid changes
--- @tparam Scroll self @{Scroll}
+-- @tparam Scroll self Scroll
 -- @tparam StaticGrid grid Druid grid component
 -- @treturn druid.scroll Current scroll instance
-function Scroll.bind_grid(self, grid)
+function M:bind_grid(grid)
 	if self._grid_on_change then
 		self._grid_on_change:unsubscribe(self._grid_on_change_callback)
 
@@ -535,12 +544,12 @@ end
 -- restrict events outside stencil node
 -- @tparam Drag self
 -- @tparam node|string node Gui node
-function Scroll.set_click_zone(self, node)
+function M:set_click_zone(node)
 	self.drag:set_click_zone(node)
 end
 
 
-function Scroll._on_scroll_drag(self, dx, dy)
+function M:_on_scroll_drag(dx, dy)
 	local t = self.target_position
 	local b = self.available_pos
 	local eb = self.available_pos_extra
@@ -581,7 +590,7 @@ function Scroll._on_scroll_drag(self, dx, dy)
 end
 
 
-function Scroll._check_soft_zone(self)
+function M:_check_soft_zone()
 	local target = self.target_position
 	local border = self.available_pos
 	local speed = self.style.BACK_SPEED
@@ -610,7 +619,7 @@ end
 
 
 -- Cancel animation on other animation or input touch
-function Scroll._cancel_animate(self)
+function M:_cancel_animate()
 	self.inertion.x = 0
 	self.inertion.y = 0
 
@@ -624,7 +633,7 @@ function Scroll._cancel_animate(self)
 end
 
 
-function Scroll._set_scroll_position(self, position_x, position_y)
+function M:_set_scroll_position(position_x, position_y)
 	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)
@@ -643,7 +652,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(self)
+function M:_check_points()
 	if not self.points then
 		return
 	end
@@ -699,7 +708,7 @@ function Scroll._check_points(self)
 end
 
 
-function Scroll._check_threshold(self)
+function M:_check_threshold()
 	local is_stopped = false
 
 	if self.drag.can_x and math.abs(self.inertion.x) < self.style.INERT_THRESHOLD then
@@ -717,7 +726,7 @@ function Scroll._check_threshold(self)
 end
 
 
-function Scroll._update_free_scroll(self, dt)
+function M:_update_free_scroll(dt)
 	if self.is_animate then
 		return
 	end
@@ -742,7 +751,7 @@ function Scroll._update_free_scroll(self, dt)
 end
 
 
-function Scroll._update_hand_scroll(self, dt)
+function M:_update_hand_scroll(dt)
 	if self.is_animate then
 		self:_cancel_animate()
 	end
@@ -757,7 +766,7 @@ function Scroll._update_hand_scroll(self, dt)
 end
 
 
-function Scroll._on_touch_start(self)
+function M:_on_touch_start()
 	self.inertion.x = 0
 	self.inertion.y = 0
 	self.target_position.x = self.position.x
@@ -765,12 +774,12 @@ function Scroll._on_touch_start(self)
 end
 
 
-function Scroll._on_touch_end(self)
+function M:_on_touch_end()
 	self:_check_threshold()
 end
 
 
-function Scroll._update_size(self)
+function M:_update_size()
 	local content_border = helper.get_border(self.content_node)
 	local content_size = helper.get_scaled_size(self.content_node)
 
@@ -808,7 +817,7 @@ function Scroll._update_size(self)
 end
 
 
-function Scroll._process_scroll_wheel(self, action_id, action)
+function M:_process_scroll_wheel(action_id, action)
 	if not self._is_mouse_hover or self.style.WHEEL_SCROLL_SPEED == 0 then
 		return false
 	end
@@ -845,9 +854,9 @@ function Scroll._process_scroll_wheel(self, action_id, action)
 end
 
 
-function Scroll._on_mouse_hover(self, state)
+function M:_on_mouse_hover(state)
 	self._is_mouse_hover = state
 end
 
 
-return Scroll
+return M