Module Scroll
Component to handle scroll content.
# Overview #
The Scroll component is designed to handle scrollable content and consists of two nodes: the scroll parent and the scroll input.
The scroll input represents the user input zone and remains static.
The scroll parent is the movable part of the scroll and changes its position.
The initial scroll size can be set by adjusting the size of the scroll parent. If the size of the scroll parent is smaller than the scroll input size, scrolling is not available.
# Notes #
• By default, the scroll style includes inertia and extra size for a stretching effect. These settings can be adjusted using the scroll style settings. For more details, refer to the scroll style settings.
• "Points of interest" can be set up for the scroll. The scroll will always be centered on the closest point of interest. This feature allows creating a slider without inertia and with points of interest on each scroll element.
• The scroll content size can be adjusted using the scroll:set_size(node_size) method. This method sets a new size for the _content node.
• Inertial scrolling mode can be enabled or disabled using the scroll:set_inert(state) method.
• The extra stretch size can be adjusted using the scroll:set_extra_stretch_size method.
• Multitouch is required for scrolling. The scroll component correctly handles touch ID swaps while dragging the scroll.
Functions
bind_grid(self, grid) | Bind the grid component (Static or Dynamic) to recalculate scroll size on grid changes |
get_percent(self) | Return current scroll progress status. |
get_scroll_size(self) | Return vector of scroll size with width and height. |
init(self, view_node, content_node) | Scroll constructor |
is_inert(self) | Return if scroll have inertion. |
is_node_in_view(self, node) | Check node if it visible now on scroll. |
scroll_to(self, point[, is_instant]) | Start scroll to target point. |
scroll_to_index(self, index[, skip_cb]) | Scroll to item in scroll by point index. |
scroll_to_percent(self, percent[, is_instant]) | Start scroll to target scroll percent |
set_click_zone(self, node) | Strict drag scroll area. |
set_extra_stretch_size(self[, stretch_size=0]) | Set extra size for scroll stretching. |
set_horizontal_scroll(self, state) | Lock or unlock horizontal scroll |
set_inert(self, state) | Enable or disable scroll inert. |
set_points(self, points) | Set points of interest. |
set_size(self, size, offset) | Set scroll content size. |
set_vertical_scroll(self, state) | Lock or unlock vertical scroll |
Tables
style | Component style params. |
Fields
available_pos | Available position for content node: (min_x, max_y, max_x, min_y) |
available_size | Size of available positions: (width, height, 0) |
content_node | Scroll content node |
drag | Drag Druid component |
inertion | Current inert speed |
is_animate | Flag, if scroll now animating by gui.animate |
is_inert | Flag, if scroll now moving by inertion |
on_point_scroll | On scroll_to_index function callback(self, index, point) |
on_scroll | On scroll move callback(self, position) |
on_scroll_to | On scroll_to function callback(self, target, is_instant) |
position | Current scroll posisition |
selected | Current index of points of interests |
target_position | Current scroll target position |
view_node | Scroll view node |
Functions
- bind_grid(self, grid)
-
Bind the grid component (Static or Dynamic) to recalculate
scroll size on grid changes
Parameters:
- self Scroll Scroll
- grid StaticGrid or DynamicGrid Druid grid component
Returns:
-
druid.scroll
Current scroll instance
- get_percent(self)
-
Return current scroll progress status.
Values will be in [0..1] interval
Parameters:
- self Scroll Scroll
Returns:
-
vector3
New vector with scroll progress values
- get_scroll_size(self)
-
Return vector of scroll size with width and height.
Parameters:
- self Scroll Scroll
Returns:
-
vector3
Available scroll size
- init(self, view_node, content_node)
-
Scroll constructor
Parameters:
- is_inert(self)
-
Return if scroll have inertion.
Parameters:
- self Scroll Scroll
Returns:
-
bool
If scroll have inertion
- is_node_in_view(self, node)
-
Check node if it visible now on scroll.
Extra border is not affected. Return true for elements in extra scroll zone
Parameters:
- self Scroll Scroll
- node node The node to check
Returns:
-
boolean
True if node in visible scroll area
- scroll_to(self, point[, is_instant])
-
Start scroll to target point.
Parameters:
- self Scroll Scroll
- point vector3 Target point
- is_instant bool Instant scroll flag (optional)
Usage:
scroll:scroll_to(vmath.vector3(0, 50, 0))
scroll:scroll_to(vmath.vector3(0), true)
- scroll_to_index(self, index[, skip_cb])
-
Scroll to item in scroll by point index.
Parameters:
- self Scroll Scroll
- index number Point index
- skip_cb bool If true, skip the point callback (optional)
- scroll_to_percent(self, percent[, is_instant])
-
Start scroll to target scroll percent
Parameters:
- self Scroll Scroll
- percent vector3 target percent
- is_instant bool instant scroll flag (optional)
Usage:
scroll:scroll_to_percent(vmath.vector3(0.5, 0, 0))
- set_click_zone(self, node)
-
Strict drag scroll area. Useful for
restrict events outside stencil node
Parameters:
- self Drag
- node node Gui node
- set_extra_stretch_size(self[, stretch_size=0])
-
Set extra size for scroll stretching.
Set 0 to disable stretching effect
Parameters:
- self Scroll Scroll
- stretch_size number Size in pixels of additional scroll area (default 0)
Returns:
-
druid.scroll
Current scroll instance
- set_horizontal_scroll(self, state)
-
Lock or unlock horizontal scroll
Parameters:
- self Scroll Scroll
- state bool True, if horizontal scroll is enabled
Returns:
-
druid.scroll
Current scroll instance
- set_inert(self, state)
-
Enable or disable scroll inert.
If disabled, scroll through points (if exist)
If no points, just simple drag without inertion
Parameters:
- self Scroll Scroll
- state bool Inert scroll state
Returns:
-
druid.scroll
Current scroll instance
- set_points(self, points)
-
Set points of interest.
Scroll will always centered on closer points
Parameters:
Returns:
-
druid.scroll
Current scroll instance
- set_size(self, size, offset)
-
Set scroll content size.
It will change content gui node size
Parameters:
- self Scroll Scroll
- size vector3 The new size for content node
- offset vector3 Offset value to set, where content is starts
Returns:
-
druid.scroll
Current scroll instance
- set_vertical_scroll(self, state)
-
Lock or unlock vertical scroll
Parameters:
- self Scroll Scroll
- state bool True, if vertical scroll is enabled
Returns:
-
druid.scroll
Current scroll instance
Tables
- style
-
Component style params.
You can override this component styles params in druid styles table
or create your own style
Fields:
- FRICT number Multiplier for free inertion (default 0)
- FRICT_HOLD number Multiplier for inertion, while touching (default 0)
- INERT_THRESHOLD number Scroll speed to stop inertion (default 3)
- INERT_SPEED number Multiplier for inertion speed (default 30)
- POINTS_DEADZONE number Speed to check points of interests in no_inertion mode (default 20)
- BACK_SPEED number Scroll back returning lerp speed (default 0.35)
- ANIM_SPEED number Scroll gui.animation speed for scroll_to function (default 0.2)
- EXTRA_STRETCH_SIZE number extra size in pixels outside of scroll (stretch effect) (default 0)
- SMALL_CONTENT_SCROLL bool If true, content node with size less than view node size can be scrolled (default false)
- WHEEL_SCROLL_SPEED bool The scroll speed via mouse wheel scroll or touchpad. Set to 0 to disable wheel scrolling (default 0)
- WHEEL_SCROLL_INVERTED bool If true, invert direction for touchpad and mouse wheel scroll (default false)
- WHEEL_SCROLL_BY_INERTION bool If true, wheel will add inertion to scroll. Direct set position otherwise. (default false)
Fields
- available_pos
-
Available position for content node: (min_x, max_y, max_x, min_y)
- available_pos vector4
- available_size
-
Size of available positions: (width, height, 0)
- available_size vector3
- content_node
-
Scroll content node
- content_node node
- drag
-
Drag Druid component
- drag Drag Drag
- inertion
-
Current inert speed
- inertion vector3
- is_animate
-
Flag, if scroll now animating by gui.animate
- is_animate bool
- is_inert
-
Flag, if scroll now moving by inertion
- is_inert bool
- on_point_scroll
-
On scroll_to_index function callback(self, index, point)
- on_point_scroll DruidEvent DruidEvent
- on_scroll
-
On scroll move callback(self, position)
- on_scroll DruidEvent DruidEvent
- on_scroll_to
-
On scroll_to function callback(self, target, is_instant)
- on_scroll_to DruidEvent DruidEvent
- position
-
Current scroll posisition
- position vector3
- selected
-
Current index of points of interests
- selected number (optional)
- target_position
-
Current scroll target position
- target_position vector3
- view_node
-
Scroll view node
- view_node node