Struct Controller 

pub struct Controller<K> { /* private fields */ }

A framework-neutral controller that wraps a virtualizer::Virtualizer and provides common adapter workflows (anchoring, tween-driven scrolling).

This type does not hold any UI objects. Adapters drive it by calling:

• on_viewport_size / on_scroll when UI events occur
• tick(now_ms) each frame/timer tick (for tween scrolling and is_scrolling debouncing)

For UI scroll containers (e.g. DOM), you can use the returned offset from tick() to set the real scroll position, while keeping the virtualizer state in sync.

Typical integration loop

• On UI scroll events: call on_scroll(offset, now_ms) (cancels any active tween).
• On UI resize/layout: call on_viewport_size(main).
• Each frame/timer: call tick(now_ms); if it returns Some(offset), apply it to the real UI.

Implementations

impl<K: VirtualizerKey> Controller<K>

pub fn new(options: VirtualizerOptions<K>) -> Self

Examples found in repository

examples/controller_tween.rs (line 11)

fn main() {
    // Example: TanStack-like controller driving tween scrolling without holding any UI objects.
    //
    // An adapter would:
    // - start a tween (e.g. in response to "scroll to index" command)
    // - call tick(now_ms) in a frame loop / timer
    // - apply the returned offset to the real scroll container (if any)
    // - render using the virtualizer state
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new(10_000, |_| 1));
    c.virtualizer_mut().set_viewport_size(20);
    c.virtualizer_mut().set_scroll_offset(0);

    let target = c.start_tween_to_index(
        2_000,
        virtualizer::Align::Center,
        0,
        240,
        Easing::SmoothStep,
    );
    println!("target_offset={target}");

    let mut now_ms = 0u64;
    loop {
        now_ms += 16;
        if let Some(off) = c.tick(now_ms) {
            if now_ms.is_multiple_of(80) {
                println!(
                    "t={now_ms} off={off} visible={:?}",
                    c.virtualizer().visible_range()
                );
            }
        } else {
            break;
        }
    }

    println!(
        "done: off={} range={:?}",
        c.virtualizer().scroll_offset(),
        c.virtualizer().virtual_range()
    );
}

examples/anchor_prepend.rs (lines 10-14)

fn main() {
    // Example: preserve visual scroll position across "prepend" (chat/timeline load older messages).
    //
    // The adapter flow is typically:
    // 1) capture an anchor (key + offset_in_viewport) before data changes
    // 2) apply data changes (count/key mapping)
    // 3) apply the anchor to adjust scroll_offset so the same item stays in the same place
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new_with_key(
        100,
        |_| 1,
        |i| 1000u64 + i as u64,
    ));
    c.virtualizer_mut().set_viewport_and_scroll_clamped(10, 50);

    let anchor = c
        .capture_first_visible_anchor()
        .expect("visible range must not be empty");
    println!(
        "before prepend: off={} anchor={anchor:?}",
        c.virtualizer().scroll_offset()
    );

    // Prepend 10 items; old items shift by +10 indexes.
    c.virtualizer_mut().set_count(110);
    c.virtualizer_mut().set_get_item_key(|i| {
        if i < 10 {
            2000u64 + i as u64
        } else {
            1000u64 + (i - 10) as u64
        }
    });
    // Note: `set_count` and `set_get_item_key` rebuild per-index sizes. In real apps, call
    // `sync_item_keys()` when your underlying dataset is reordered while `count` stays the same.

    // Provide a key -> index mapping for the current dataset (owned by your adapter).
    let ok = c.apply_anchor(&anchor, |k| {
        if (1000..1100).contains(k) {
            Some((*k as usize - 1000) + 10)
        } else if (2000..2010).contains(k) {
            Some(*k as usize - 2000)
        } else {
            None
        }
    });

    println!(
        "after prepend: ok={ok} off={}",
        c.virtualizer().scroll_offset()
    );
}

pub fn from_virtualizer(v: Virtualizer<K>) -> Self

pub fn virtualizer(&self) -> &Virtualizer<K>

Examples found in repository

examples/controller_tween.rs (line 31)

fn main() {
    // Example: TanStack-like controller driving tween scrolling without holding any UI objects.
    //
    // An adapter would:
    // - start a tween (e.g. in response to "scroll to index" command)
    // - call tick(now_ms) in a frame loop / timer
    // - apply the returned offset to the real scroll container (if any)
    // - render using the virtualizer state
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new(10_000, |_| 1));
    c.virtualizer_mut().set_viewport_size(20);
    c.virtualizer_mut().set_scroll_offset(0);

    let target = c.start_tween_to_index(
        2_000,
        virtualizer::Align::Center,
        0,
        240,
        Easing::SmoothStep,
    );
    println!("target_offset={target}");

    let mut now_ms = 0u64;
    loop {
        now_ms += 16;
        if let Some(off) = c.tick(now_ms) {
            if now_ms.is_multiple_of(80) {
                println!(
                    "t={now_ms} off={off} visible={:?}",
                    c.virtualizer().visible_range()
                );
            }
        } else {
            break;
        }
    }

    println!(
        "done: off={} range={:?}",
        c.virtualizer().scroll_offset(),
        c.virtualizer().virtual_range()
    );
}

examples/anchor_prepend.rs (line 22)

fn main() {
    // Example: preserve visual scroll position across "prepend" (chat/timeline load older messages).
    //
    // The adapter flow is typically:
    // 1) capture an anchor (key + offset_in_viewport) before data changes
    // 2) apply data changes (count/key mapping)
    // 3) apply the anchor to adjust scroll_offset so the same item stays in the same place
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new_with_key(
        100,
        |_| 1,
        |i| 1000u64 + i as u64,
    ));
    c.virtualizer_mut().set_viewport_and_scroll_clamped(10, 50);

    let anchor = c
        .capture_first_visible_anchor()
        .expect("visible range must not be empty");
    println!(
        "before prepend: off={} anchor={anchor:?}",
        c.virtualizer().scroll_offset()
    );

    // Prepend 10 items; old items shift by +10 indexes.
    c.virtualizer_mut().set_count(110);
    c.virtualizer_mut().set_get_item_key(|i| {
        if i < 10 {
            2000u64 + i as u64
        } else {
            1000u64 + (i - 10) as u64
        }
    });
    // Note: `set_count` and `set_get_item_key` rebuild per-index sizes. In real apps, call
    // `sync_item_keys()` when your underlying dataset is reordered while `count` stays the same.

    // Provide a key -> index mapping for the current dataset (owned by your adapter).
    let ok = c.apply_anchor(&anchor, |k| {
        if (1000..1100).contains(k) {
            Some((*k as usize - 1000) + 10)
        } else if (2000..2010).contains(k) {
            Some(*k as usize - 2000)
        } else {
            None
        }
    });

    println!(
        "after prepend: ok={ok} off={}",
        c.virtualizer().scroll_offset()
    );
}

pub fn virtualizer_mut(&mut self) -> &mut Virtualizer<K>

Examples found in repository

examples/controller_tween.rs (line 12)

fn main() {
    // Example: TanStack-like controller driving tween scrolling without holding any UI objects.
    //
    // An adapter would:
    // - start a tween (e.g. in response to "scroll to index" command)
    // - call tick(now_ms) in a frame loop / timer
    // - apply the returned offset to the real scroll container (if any)
    // - render using the virtualizer state
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new(10_000, |_| 1));
    c.virtualizer_mut().set_viewport_size(20);
    c.virtualizer_mut().set_scroll_offset(0);

    let target = c.start_tween_to_index(
        2_000,
        virtualizer::Align::Center,
        0,
        240,
        Easing::SmoothStep,
    );
    println!("target_offset={target}");

    let mut now_ms = 0u64;
    loop {
        now_ms += 16;
        if let Some(off) = c.tick(now_ms) {
            if now_ms.is_multiple_of(80) {
                println!(
                    "t={now_ms} off={off} visible={:?}",
                    c.virtualizer().visible_range()
                );
            }
        } else {
            break;
        }
    }

    println!(
        "done: off={} range={:?}",
        c.virtualizer().scroll_offset(),
        c.virtualizer().virtual_range()
    );
}

examples/anchor_prepend.rs (line 15)

fn main() {
    // Example: preserve visual scroll position across "prepend" (chat/timeline load older messages).
    //
    // The adapter flow is typically:
    // 1) capture an anchor (key + offset_in_viewport) before data changes
    // 2) apply data changes (count/key mapping)
    // 3) apply the anchor to adjust scroll_offset so the same item stays in the same place
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new_with_key(
        100,
        |_| 1,
        |i| 1000u64 + i as u64,
    ));
    c.virtualizer_mut().set_viewport_and_scroll_clamped(10, 50);

    let anchor = c
        .capture_first_visible_anchor()
        .expect("visible range must not be empty");
    println!(
        "before prepend: off={} anchor={anchor:?}",
        c.virtualizer().scroll_offset()
    );

    // Prepend 10 items; old items shift by +10 indexes.
    c.virtualizer_mut().set_count(110);
    c.virtualizer_mut().set_get_item_key(|i| {
        if i < 10 {
            2000u64 + i as u64
        } else {
            1000u64 + (i - 10) as u64
        }
    });
    // Note: `set_count` and `set_get_item_key` rebuild per-index sizes. In real apps, call
    // `sync_item_keys()` when your underlying dataset is reordered while `count` stays the same.

    // Provide a key -> index mapping for the current dataset (owned by your adapter).
    let ok = c.apply_anchor(&anchor, |k| {
        if (1000..1100).contains(k) {
            Some((*k as usize - 1000) + 10)
        } else if (2000..2010).contains(k) {
            Some(*k as usize - 2000)
        } else {
            None
        }
    });

    println!(
        "after prepend: ok={ok} off={}",
        c.virtualizer().scroll_offset()
    );
}

pub fn into_virtualizer(self) -> Virtualizer<K>

pub fn is_animating(&self) -> bool

pub fn cancel_animation(&mut self)

pub fn on_viewport_size(&mut self, viewport_main: u32)

pub fn on_scroll(&mut self, scroll_offset: u64, now_ms: u64)

Call this when the UI reports a scroll offset change (e.g. user wheel/drag).

This cancels any active tween.

pub fn tick(&mut self, now_ms: u64) -> Option<u64>

Advances the controller.

• If a tween is active, updates scroll_offset and returns the new offset.
• Otherwise, runs is_scrolling debouncing and returns None.

Examples found in repository

examples/controller_tween.rs (line 27)

fn main() {
    // Example: TanStack-like controller driving tween scrolling without holding any UI objects.
    //
    // An adapter would:
    // - start a tween (e.g. in response to "scroll to index" command)
    // - call tick(now_ms) in a frame loop / timer
    // - apply the returned offset to the real scroll container (if any)
    // - render using the virtualizer state
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new(10_000, |_| 1));
    c.virtualizer_mut().set_viewport_size(20);
    c.virtualizer_mut().set_scroll_offset(0);

    let target = c.start_tween_to_index(
        2_000,
        virtualizer::Align::Center,
        0,
        240,
        Easing::SmoothStep,
    );
    println!("target_offset={target}");

    let mut now_ms = 0u64;
    loop {
        now_ms += 16;
        if let Some(off) = c.tick(now_ms) {
            if now_ms.is_multiple_of(80) {
                println!(
                    "t={now_ms} off={off} visible={:?}",
                    c.virtualizer().visible_range()
                );
            }
        } else {
            break;
        }
    }

    println!(
        "done: off={} range={:?}",
        c.virtualizer().scroll_offset(),
        c.virtualizer().virtual_range()
    );
}

pub fn scroll_to_index( &mut self, index: usize, align: Align, now_ms: u64, ) -> u64

Computes and applies a scroll-to-index immediately (no animation).

Returns the applied (clamped) offset.

pub fn scroll_to_offset(&mut self, offset: u64, now_ms: u64) -> u64

Applies a scroll-to-offset immediately (no animation).

Returns the applied (clamped) offset.

pub fn start_tween_to_index( &mut self, index: usize, align: Align, now_ms: u64, duration_ms: u64, easing: Easing, ) -> u64

Starts a tween to an index (adapter-driven).

Returns the clamped target offset.

Examples found in repository

examples/controller_tween.rs (lines 15-21)

fn main() {
    // Example: TanStack-like controller driving tween scrolling without holding any UI objects.
    //
    // An adapter would:
    // - start a tween (e.g. in response to "scroll to index" command)
    // - call tick(now_ms) in a frame loop / timer
    // - apply the returned offset to the real scroll container (if any)
    // - render using the virtualizer state
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new(10_000, |_| 1));
    c.virtualizer_mut().set_viewport_size(20);
    c.virtualizer_mut().set_scroll_offset(0);

    let target = c.start_tween_to_index(
        2_000,
        virtualizer::Align::Center,
        0,
        240,
        Easing::SmoothStep,
    );
    println!("target_offset={target}");

    let mut now_ms = 0u64;
    loop {
        now_ms += 16;
        if let Some(off) = c.tick(now_ms) {
            if now_ms.is_multiple_of(80) {
                println!(
                    "t={now_ms} off={off} visible={:?}",
                    c.virtualizer().visible_range()
                );
            }
        } else {
            break;
        }
    }

    println!(
        "done: off={} range={:?}",
        c.virtualizer().scroll_offset(),
        c.virtualizer().virtual_range()
    );
}

pub fn start_tween_to_offset( &mut self, offset: u64, now_ms: u64, duration_ms: u64, easing: Easing, ) -> u64

Starts a tween to an offset (adapter-driven).

Returns the clamped target offset.

pub fn capture_first_visible_anchor(&self) -> Option<ScrollAnchor<K>>

Examples found in repository

examples/anchor_prepend.rs (line 18)

fn main() {
    // Example: preserve visual scroll position across "prepend" (chat/timeline load older messages).
    //
    // The adapter flow is typically:
    // 1) capture an anchor (key + offset_in_viewport) before data changes
    // 2) apply data changes (count/key mapping)
    // 3) apply the anchor to adjust scroll_offset so the same item stays in the same place
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new_with_key(
        100,
        |_| 1,
        |i| 1000u64 + i as u64,
    ));
    c.virtualizer_mut().set_viewport_and_scroll_clamped(10, 50);

    let anchor = c
        .capture_first_visible_anchor()
        .expect("visible range must not be empty");
    println!(
        "before prepend: off={} anchor={anchor:?}",
        c.virtualizer().scroll_offset()
    );

    // Prepend 10 items; old items shift by +10 indexes.
    c.virtualizer_mut().set_count(110);
    c.virtualizer_mut().set_get_item_key(|i| {
        if i < 10 {
            2000u64 + i as u64
        } else {
            1000u64 + (i - 10) as u64
        }
    });
    // Note: `set_count` and `set_get_item_key` rebuild per-index sizes. In real apps, call
    // `sync_item_keys()` when your underlying dataset is reordered while `count` stays the same.

    // Provide a key -> index mapping for the current dataset (owned by your adapter).
    let ok = c.apply_anchor(&anchor, |k| {
        if (1000..1100).contains(k) {
            Some((*k as usize - 1000) + 10)
        } else if (2000..2010).contains(k) {
            Some(*k as usize - 2000)
        } else {
            None
        }
    });

    println!(
        "after prepend: ok={ok} off={}",
        c.virtualizer().scroll_offset()
    );
}

pub fn capture_anchor_at_offset_in_viewport( &self, offset_in_viewport: u64, ) -> Option<ScrollAnchor<K>>

Captures an anchor for the item at a given offset in the viewport.

For example, offset_in_viewport = 0 anchors the item at the top of the viewport.

pub fn apply_anchor( &mut self, anchor: &ScrollAnchor<K>, key_to_index: impl FnMut(&K) -> Option<usize>, ) -> bool

Applies a previously captured anchor by adjusting the scroll offset.

This cancels any active tween.

Examples found in repository

examples/anchor_prepend.rs (lines 38-46)

fn main() {
    // Example: preserve visual scroll position across "prepend" (chat/timeline load older messages).
    //
    // The adapter flow is typically:
    // 1) capture an anchor (key + offset_in_viewport) before data changes
    // 2) apply data changes (count/key mapping)
    // 3) apply the anchor to adjust scroll_offset so the same item stays in the same place
    let mut c = Controller::new(virtualizer::VirtualizerOptions::new_with_key(
        100,
        |_| 1,
        |i| 1000u64 + i as u64,
    ));
    c.virtualizer_mut().set_viewport_and_scroll_clamped(10, 50);

    let anchor = c
        .capture_first_visible_anchor()
        .expect("visible range must not be empty");
    println!(
        "before prepend: off={} anchor={anchor:?}",
        c.virtualizer().scroll_offset()
    );

    // Prepend 10 items; old items shift by +10 indexes.
    c.virtualizer_mut().set_count(110);
    c.virtualizer_mut().set_get_item_key(|i| {
        if i < 10 {
            2000u64 + i as u64
        } else {
            1000u64 + (i - 10) as u64
        }
    });
    // Note: `set_count` and `set_get_item_key` rebuild per-index sizes. In real apps, call
    // `sync_item_keys()` when your underlying dataset is reordered while `count` stays the same.

    // Provide a key -> index mapping for the current dataset (owned by your adapter).
    let ok = c.apply_anchor(&anchor, |k| {
        if (1000..1100).contains(k) {
            Some((*k as usize - 1000) + 10)
        } else if (2000..2010).contains(k) {
            Some(*k as usize - 2000)
        } else {
            None
        }
    });

    println!(
        "after prepend: ok={ok} off={}",
        c.virtualizer().scroll_offset()
    );
}

Trait Implementations

impl<K: Clone> Clone for Controller<K>

fn clone(&self) -> Controller<K>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K: Debug> Debug for Controller<K>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.