simvx.core.ui.virtual_scroll

VirtualScrollContainer – only renders visible items for large lists.

Items are provided via a data source callback. Only items within the visible viewport range are instantiated and laid out, enabling efficient handling of thousands of items.

Module Contents

Classes

VirtualScrollContainer

ScrollContainer that only renders visible items.

Data

log
__all__

API

simvx.core.ui.virtual_scroll.log

‘getLogger(…)’

simvx.core.ui.virtual_scroll.__all__

[‘VirtualScrollContainer’]

class simvx.core.ui.virtual_scroll.VirtualScrollContainer(item_height: float = 24.0, show_scrollbar: bool = False, **kwargs)

Bases: simvx.core.ui.containers.Container

ScrollContainer that only renders visible items.

Items are provided via a data source callback. Only items within the visible viewport range are instantiated and laid out. Off-screen items are recycled to minimize allocation.

Set show_scrollbar = True to display a vertical scrollbar thumb when content overflows (default False).

Example: vs = VirtualScrollContainer(item_height=24.0, show_scrollbar=True) vs.size = Vec2(300, 400)

def make_label(index, recycled):
    from simvx.core.ui.widgets import Label
    lbl = recycled or Label()
    lbl.text = f"Item {index}"
    return lbl

vs.set_data_source(10000, make_label)

Initialization

scrollbar_colour

‘ThemeColour(…)’

scrollbar_track_colour

‘ThemeColour(…)’

set_data_source(count: int, factory: collections.abc.Callable[[int, simvx.core.ui.core.Control | None], simvx.core.ui.core.Control], data_fn: collections.abc.Callable[[int], Any] | None = None)

Configure the virtual list.

Args: count: Total number of items. factory: Creates/updates a Control for item at index. Signature: fn(index, existing_or_None) -> Control data_fn: Optional callback returning data for item at index.

update_item_count(count: int)

Update total item count and refresh visible items.

property total_height: float

Total content height based on item count and row height.

property visible_range: tuple[int, int]

Return (first_visible_index, last_visible_index_exclusive).

scroll_to(offset: float)

Scroll to absolute pixel offset.

scroll_to_index(index: int)

Scroll so the item at index is at the top of the viewport.

on_scroll(delta: float)

Handle scroll wheel input (positive delta = scroll down).

draw(renderer)

separation

‘Property(…)’

ready()

add_child(node)

remove_child(node)

mark_layout_dirty()

process(dt: float)

size_x

‘Property(…)’

size_y

‘Property(…)’

property size: simvx.core.math.types.Vec2

touch_mode: str

‘mouse’

property theme: simvx.core.ui.types.Theme | None

property mouse_over: bool

property focused: bool

property disabled: bool

get_theme() → simvx.core.ui.types.Theme

queue_redraw()

get_minimum_size() → simvx.core.math.types.Vec2

get_rect() → tuple[float, float, float, float]

get_global_rect() → tuple[float, float, float, float]

is_point_inside(point) → bool

set_anchor_preset(preset: simvx.core.ui.enums.AnchorPreset)

set_focus()

grab_focus()

release_focus()

has_focus() → bool

focus_next_control()

focus_previous_control()

grab_mouse()

release_mouse()

set_drag_preview(control: simvx.core.ui.core.Control)

draw_popup(renderer)

is_popup_point_inside(point) → bool

popup_input(event)

dismiss_popup()

z_index

‘Property(…)’

z_as_relative

‘Property(…)’

render_layer

‘Property(…)’

set_render_layer(index: int, enabled: bool = True) → None

is_on_render_layer(index: int) → bool

property absolute_z_index: int

property position: simvx.core.math.types.Vec2

property rotation: float

property rotation_degrees: float

property scale: simvx.core.math.types.Vec2

property world_position: simvx.core.math.types.Vec2

property world_rotation: float

property world_scale: simvx.core.math.types.Vec2

property forward: simvx.core.math.types.Vec2

property right: simvx.core.math.types.Vec2

translate(offset: tuple[float, float] | numpy.ndarray)

rotate(radians: float)

rotate_deg(degrees: float)

look_at(target: tuple[float, float] | numpy.ndarray)

transform_points(points: list[simvx.core.math.types.Vec2]) → list[simvx.core.math.types.Vec2]

draw_polygon(renderer, points: list[simvx.core.math.types.Vec2], closed=True, colour=None)

wrap_screen(margin: float = 20)

strict_errors: ClassVar[bool]

True

script_error_raised

‘Signal(…)’

classmethod __init_subclass__(**kwargs)

property name: str

property process_mode: simvx.core.descriptors.ProcessMode

reset_error() → None

reparent(new_parent: simvx.core.node.Node)

get_node(path: str) → simvx.core.node.Node

find_child(name: str, recursive: bool = False) → simvx.core.node.Node | None

find(node_type: type, recursive: bool = True) → simvx.core.node.Node | None

find_all(node_type: type, recursive: bool = True) → list

property path: str

add_to_group(group: str)

remove_from_group(group: str)

is_in_group(group: str) → bool

enter_tree() → None

exit_tree() → None

physics_process(dt: float) → None

input_event(event: simvx.core.events.InputEvent) → None

input(event: simvx.core.events.TreeInputEvent) → None

unhandled_input(event: simvx.core.events.TreeInputEvent) → None

start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle

stop_coroutine(gen_or_handle)

clear_children()

destroy()

property app

property tree: simvx.core.scene_tree.SceneTree

get_tree() → simvx.core.scene_tree.SceneTree

__getitem__(key: str)

classmethod get_properties() → dict[str, simvx.core.descriptors.Property]

__repr__()