`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¶

API¶

simvx.core.ui.virtual_scroll.__all__¶: [‘VirtualScrollContainer’]

class simvx.core.ui.virtual_scroll.VirtualScrollContainer(item_height: float = 24.0, **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.

Example: vs = VirtualScrollContainer(item_height=24.0) 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

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).

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¶

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

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.core.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(…)’

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 global_position: simvx.core.math.types.Vec2¶

property global_rotation: float¶

property global_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, color=None)¶

wrap_screen(margin: float = 20)¶

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) → 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¶

draw(renderer) → 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)¶

destroy()¶

queue_free¶: None

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]¶

get_settings¶: None

__repr__()¶