Scrollbar¶

Documentation for std-library/nodes/components/scrollbar.ksp

Import¶

import "_IVLS/std-library/nodes/components/scrollbar.ksp"

Node: `Stl.Scrollbar`¶

Uses: Init

API¶

Nodes¶

Name	Description
`node Stl.Scrollbar`	Base node providing core scrollbar logic and the thumb-update subroutine.
`node Stl.Scrollbar.Template(#name#, #orientation#, #xy_pad#, #thumb_label#, #visible_items#, #total_items#)` (Template)	Scrollbar template for creating named, independently-configured scrollbar instan...

Defines¶

Name	Description
`define STL.UI_CALLBACKS += #name#.cb.scrollbar`	Registers the scrollbar pad drag callback with the UI callback system.
`define STL.UI_CALLBACKS += #name#.cb.page_back`	Registers the page-back button callback with the UI callback system.
`define STL.UI_CALLBACKS += #name#.cb.page_forward`	Registers the page-forward button callback with the UI callback system.

Const Blocks¶

Name	Description
`const orient`	Scrollbar orientation constants.

Properties¶

Name	Description
`property #name#.index`	Property for the visible item index, accounting for scroll stride.
`property #name#.internal`	Core state property for the raw internal scroll position (0 to `max_position`).

Functions¶

Name	Description
`#name#.evaluate_block_region()`	Configures the invisible blocker button to prevent unintended clicks outside the...
`#name#.force_update()`	Updates scrollbar state and unconditionally triggers the response callback.
`#name#.get_scroll_index() -> i`	Converts the internal scroll position to a visible item index.
`#name#.recalc()`	Recalculates `num_positions` and `max_position` from visible items, total items,...
`#name#.render_scroll_button(ui_id, visible)`	Override hook for page button visibility based on whether the scrollbar is neede...
`#name#.render_scroll_thumb(ui_id, visible)`	Override hook for thumb visibility based on whether the scrollbar is needed.
`#name#.response(val)`	Override hook called when the scroll position changes.
`#name#.update()`	Recalculates scrollbar state, updates the UI, and fires `response` if the positi...
`scrollbars.update_thumb(thumb, xy, orientation, pos, max_pos, num_pos)`	Updates scrollbar thumb position and size for a given scroll state.
`uicb.#name#.cb.page_back(ui_id, n)`	Callback invoked when the user clicks the page-back button.
`uicb.#name#.cb.page_forward(ui_id, n)`	Callback invoked when the user clicks the page-forward button.
`uicb.#name#.cb.scrollbar(ui_id, n)`	Callback invoked when the user drags the scrollbar XY pad.

Stl.Scrollbar¶

`node Stl.Scrollbar`¶

Callbacks: Init

Base node providing core scrollbar logic and the thumb-update subroutine.

`const orient`¶

Scrollbar orientation constants.

`scrollbars.update_thumb(thumb, xy, orientation, pos, max_pos, num_pos)`¶

Updates scrollbar thumb position and size for a given scroll state.

Parameter	Type	Description
`thumb`	int	UI control ID for the thumb label
`xy`	int	UI control ID for the scrollbar track/pad
`orientation`	int	orientation constant (`scroll.orient.VERTICAL` or `scroll.orient.HORIZONTAL`)
`pos`	int	current scroll position
`max_pos`	int	maximum valid scroll position
`num_pos`	int	total number of scroll positions

Side effects:

Name	Type	Purpose
`updthb.thumb`	int	Resolved UI ID of the thumb control
`updthb.xy`	int	Resolved UI ID of the track/pad control
`updthb.orientation`	int	Orientation constant for subroutine
`updthb.pos`	int	Current position for subroutine
`updthb.max_pos`	int	Maximum position for subroutine
`updthb.num_pos`	int	Total positions for subroutine

`node Stl.Scrollbar.Template(#name#, #orientation#, #xy_pad#, #thumb_label#, #visible_items#, #total_items#)`¶

Callbacks: Init, PostInit, Reload

Scrollbar template for creating named, independently-configured scrollbar instances bound to specific UI controls.

Parameter	Description
`#name#`	instance identifier used as family namespace
`#orientation#`	`scroll.orient.VERTICAL` or `scroll.orient.HORIZONTAL`
`#xy_pad#`	UI XY pad control for the scrollbar track
`#thumb_label#`	UI label control for the draggable thumb
`#visible_items#`	number of items visible in the viewport
`#total_items#`	total number of items in the scrollable content

`property #name#.index`¶

Property for the visible item index, accounting for scroll stride.

Side effects:

Sets #name#.internal property (triggers full update chain)
Calls #name#._update_cursor()
get() -> result
set(index)

`property #name#.internal`¶

Core state property for the raw internal scroll position (0 to max_position).

Side effects:

Writes to #name#.position
Calls #name#.recalc()
Calls #name#._update_thumb()
Calls #name#.response() if position changed
get() -> result
set(pos)

`#name#.update()`¶

Recalculates scrollbar state, updates the UI, and fires response if the position changed.

Side effects:

Calls #name#.recalc()
Clamps #name#.position to valid range
Calls #name#._update_thumb()
Calls #name#._update_cursor()
Calls #name#.response() if position changed

`#name#.force_update()`¶

Updates scrollbar state and unconditionally triggers the response callback.

Side effects:

Calls #name#.update()
Calls #name#.response() regardless of whether position changed

`#name#.get_scroll_index() -> i`¶

Converts the internal scroll position to a visible item index.

Returns: i — item index (#name#.position multiplied by #name#.options.scroll_stride)

Side effects:

None

`#name#.evaluate_block_region()`¶

Configures the invisible blocker button to prevent unintended clicks outside the scrollbar pad area.

Side effects:

Modifies #name#.Unclick UI properties (hide, x, y, width, height)

`#name#.recalc()`¶

Recalculates num_positions and max_position from visible items, total items, and stride.

Side effects:

Writes to #name#.num_positions
Writes to #name#.max_position
Calls #name#.render_scroll_thumb() with visibility state
Calls #name#.render_scroll_button() for page-back and page-forward widgets

`#name#.response(val)`¶

Override hook called when the scroll position changes.

Parameter	Type	Description
`val`	int	new scroll index (visible item index, not internal position)

Side effects:

None (default implementation prints a diagnostic message)

`define STL.UI_CALLBACKS += #name#.cb.scrollbar`¶

Registers the scrollbar pad drag callback with the UI callback system.

Side effects:

Appends #name#.cb.scrollbar to STL.UI_CALLBACKS define list

`uicb.#name#.cb.scrollbar(ui_id, n)`¶

Callback invoked when the user drags the scrollbar XY pad.

Parameter	Type	Description
`ui_id`	int	UI control ID that triggered the callback
`n`	int	callback event index

Side effects:

Reads cursor value from #xy_pad# via get_control_par_real_arr()
Writes to ~#name#.cursor_val
Sets #name#.internal (triggers full update chain)

`define STL.UI_CALLBACKS += #name#.cb.page_back`¶

Registers the page-back button callback with the UI callback system.

Side effects:

Appends #name#.cb.page_back to STL.UI_CALLBACKS define list

`uicb.#name#.cb.page_back(ui_id, n)`¶

Callback invoked when the user clicks the page-back button.

Parameter	Type	Description
`ui_id`	int	UI control ID that triggered the callback
`n`	int	callback event index

Side effects:

Sets #name#.internal to #name#.position - 1 (triggers full update chain)

`define STL.UI_CALLBACKS += #name#.cb.page_forward`¶

Registers the page-forward button callback with the UI callback system.

Side effects:

Appends #name#.cb.page_forward to STL.UI_CALLBACKS define list

`uicb.#name#.cb.page_forward(ui_id, n)`¶

Callback invoked when the user clicks the page-forward button.

Parameter	Type	Description
`ui_id`	int	UI control ID that triggered the callback
`n`	int	callback event index

Side effects:

Sets #name#.internal to #name#.position + 1 (triggers full update chain)

`#name#.render_scroll_thumb(ui_id, visible)`¶

Override hook for thumb visibility based on whether the scrollbar is needed.

Parameter	Type	Description
`ui_id`	int	UI control ID of the thumb element
`visible`	int	`TRUE` if scrollbar is needed, `FALSE` otherwise

Side effects:

Sets ui_id -> hide property

`#name#.render_scroll_button(ui_id, visible)`¶

Override hook for page button visibility based on whether the scrollbar is needed.

Parameter	Type	Description
`ui_id`	int	UI control ID of the page button
`visible`	int	`TRUE` if scrollbar is needed, `FALSE` otherwise

Side effects:

Sets ui_id -> hide property

Example¶

// TODO: Add usage example

Scrollbar¶

Import¶

Node: Stl.Scrollbar¶

API¶

Nodes¶

Defines¶

Const Blocks¶

Properties¶

Functions¶

Stl.Scrollbar¶

node Stl.Scrollbar¶

const orient¶

scrollbars.update_thumb(thumb, xy, orientation, pos, max_pos, num_pos)¶

node Stl.Scrollbar.Template(#name#, #orientation#, #xy_pad#, #thumb_label#, #visible_items#, #total_items#)¶

property #name#.index¶

property #name#.internal¶

#name#.update()¶

#name#.force_update()¶

#name#.get_scroll_index() -> i¶

#name#.evaluate_block_region()¶

#name#.recalc()¶

#name#.response(val)¶

define STL.UI_CALLBACKS += #name#.cb.scrollbar¶

uicb.#name#.cb.scrollbar(ui_id, n)¶

define STL.UI_CALLBACKS += #name#.cb.page_back¶

uicb.#name#.cb.page_back(ui_id, n)¶

define STL.UI_CALLBACKS += #name#.cb.page_forward¶

uicb.#name#.cb.page_forward(ui_id, n)¶

#name#.render_scroll_thumb(ui_id, visible)¶

#name#.render_scroll_button(ui_id, visible)¶

Example¶

See Also¶

Node: `Stl.Scrollbar`¶

`node Stl.Scrollbar`¶

`const orient`¶

`scrollbars.update_thumb(thumb, xy, orientation, pos, max_pos, num_pos)`¶

`node Stl.Scrollbar.Template(#name#, #orientation#, #xy_pad#, #thumb_label#, #visible_items#, #total_items#)`¶

`property #name#.index`¶

`property #name#.internal`¶

`#name#.update()`¶

`#name#.force_update()`¶

`#name#.get_scroll_index() -> i`¶

`#name#.evaluate_block_region()`¶

`#name#.recalc()`¶

`#name#.response(val)`¶

`define STL.UI_CALLBACKS += #name#.cb.scrollbar`¶

`uicb.#name#.cb.scrollbar(ui_id, n)`¶

`define STL.UI_CALLBACKS += #name#.cb.page_back`¶

`uicb.#name#.cb.page_back(ui_id, n)`¶

`define STL.UI_CALLBACKS += #name#.cb.page_forward`¶

`uicb.#name#.cb.page_forward(ui_id, n)`¶

`#name#.render_scroll_thumb(ui_id, visible)`¶

`#name#.render_scroll_button(ui_id, visible)`¶