imgui-rs/imgui/src/list_clipper.rs

use std::marker::PhantomData;

use crate::sys;
use crate::Ui;

/// Used to render only the visible items when displaying a
/// long list of items in a scrollable area.
///
/// For example, you can have a huge list of checkboxes.
/// Without the clipper you have to call `ui.checkbox(...)`
/// for every one, even if 99% of of them are not visible in
/// the current frame. Using the `ListClipper`, you can only
/// call `ui.checkbox(...)` for the currently visible items.
///
/// Note the efficiency of list clipper relies on the height
/// of each item being cheaply calculated. The current rust
/// bindings only works with a fixed height for all items.
pub struct ListClipper {
    items_count: i32,
    items_height: f32,
}

impl ListClipper {
    /// Begins configuring a list clipper.
    pub const fn new(items_count: i32) -> Self {
        ListClipper {
            items_count,
            items_height: -1.0,
        }
    }

    /// Manually set item height. If not set, the height of the first item is used for all subsequent rows.
    pub const fn items_height(mut self, items_height: f32) -> Self {
        self.items_height = items_height;
        self
    }

    pub fn begin(self, ui: &Ui) -> ListClipperToken<'_> {
        let list_clipper = unsafe {
            let list_clipper = sys::ImGuiListClipper_ImGuiListClipper();
            sys::ImGuiListClipper_Begin(list_clipper, self.items_count, self.items_height);
            list_clipper
        };
        ListClipperToken::new(ui, list_clipper)
    }
}

/// List clipper is a mechanism to efficiently implement scrolling of
/// large lists with random access.
///
/// For example you have a list of 1 million buttons, and the list
/// clipper will help you only draw the ones which are visible.
pub struct ListClipperToken<'ui> {
    list_clipper: *mut sys::ImGuiListClipper,
    _phantom: PhantomData<&'ui Ui>,

    /// In upstream imgui < 1.87, calling step too many times will
    /// cause a segfault due to null pointer. So we keep track of this
    /// and panic instead.
    ///
    /// Fixed in https://github.com/ocornut/imgui/commit/dca527b which
    /// will likely be part of imgui 1.88 - at which point this can be
    /// removed.
    consumed_workaround: bool,
}

impl<'ui> ListClipperToken<'ui> {
    fn new(_: &Ui, list_clipper: *mut sys::ImGuiListClipper) -> Self {
        Self {
            list_clipper,
            _phantom: PhantomData,
            consumed_workaround: false,
        }
    }

    /// Progress the list clipper.
    ///
    /// If this returns returns `true` then the you can loop between
    /// between `clipper.display_start() .. clipper.display_end()`.
    /// If this returns false, you must stop calling this method.
    ///
    /// Calling step again after it returns `false` will cause imgui
    /// to abort. This mirrors the C++ interface.
    ///
    /// It is recommended to use the iterator interface!
    pub fn step(&mut self) -> bool {
        let is_imgui_1_88_or_higher = false;
        if is_imgui_1_88_or_higher {
            unsafe { sys::ImGuiListClipper_Step(self.list_clipper) }
        } else {
            if self.consumed_workaround {
                panic!("ListClipperToken::step called after it has previously returned false");
            }
            let ret = unsafe { sys::ImGuiListClipper_Step(self.list_clipper) };
            if !ret {
                self.consumed_workaround = true;
            }
            ret
        }
    }

    /// This is automatically called back the final call to
    /// `step`. You can call it sooner but typically not needed.
    pub fn end(&mut self) {
        unsafe {
            sys::ImGuiListClipper_End(self.list_clipper);
        }
    }

    /// First item to call, updated each call to `step`
    pub fn display_start(&self) -> i32 {
        unsafe { (*self.list_clipper).DisplayStart }
    }

    /// End of items to call (exclusive), updated each call to `step`
    pub fn display_end(&self) -> i32 {
        unsafe { (*self.list_clipper).DisplayEnd }
    }

    /// Get an iterator which outputs all visible indexes. This is the
    /// recommended way of using the clipper.
    pub fn iter(self) -> ListClipperIterator<'ui> {
        ListClipperIterator::new(self)
    }
}

impl<'ui> Drop for ListClipperToken<'ui> {
    fn drop(&mut self) {
        unsafe {
            sys::ImGuiListClipper_destroy(self.list_clipper);
        };
    }
}

pub struct ListClipperIterator<'ui> {
    list_clipper: ListClipperToken<'ui>,
    exhausted: bool,
    last_value: Option<i32>,
}

impl<'ui> ListClipperIterator<'ui> {
    fn new(list_clipper: ListClipperToken<'ui>) -> Self {
        Self {
            list_clipper,
            exhausted: false,
            last_value: None,
        }
    }
}

impl Iterator for ListClipperIterator<'_> {
    type Item = i32;

    fn next(&mut self) -> Option<Self::Item> {
        if let Some(lv) = self.last_value {
            // Currently iterating a chunk (returning all values
            // between display_start and display_end)
            let next_value = lv + 1;

            if lv >= self.list_clipper.display_end() - 1 {
                // If we reach the end of the current chunk, clear
                // last_value so we call step below
                self.last_value = None;
            } else {
                // Otherwise just increment it
                self.last_value = Some(next_value);
            }
        }

        if let Some(lv) = self.last_value {
            // Next item within current step's chunk
            Some(lv)
        } else {
            // Start iterating a new chunk

            if self.exhausted {
                // If the clipper is exhausted, don't call step again!
                None
            } else {
                // Advance the clipper
                let ret = self.list_clipper.step();
                if !ret {
                    self.exhausted = true;
                    None
                } else {
                    // Setup iteration for this step's chunk
                    let start = self.list_clipper.display_start();
                    let end = self.list_clipper.display_end();

                    if start == end {
                        // Somewhat special case: if a single item, we
                        // don't store the last_value so we call
                        // step() again next iteration
                        self.last_value = None;
                    } else {
                        self.last_value = Some(start);
                    }
                    Some(start)
                }
            }
        }
    }
}

#[test]
fn cpp_style_usage() {
    // Setup
    let (_guard, mut ctx) = crate::test::test_ctx_initialized();
    let ui = ctx.frame();

    let _window = ui
        .window("Example")
        .position([0.0, 0.0], crate::Condition::Always)
        .size([100.0, 800.0], crate::Condition::Always)
        .begin();

    // Create clipper
    let clip = ListClipper::new(1000);
    let mut tok = clip.begin(ui);

    let mut ticks = 0;

    while dbg!(tok.step()) {
        for row_num in dbg!(tok.display_start())..dbg!(tok.display_end()) {
            dbg!(row_num);
            ui.text("...");
            ticks += 1;
        }
    }

    // Check it's called an expected amount of time (only the ones
    // visible in given sized window)
    assert_eq!(ticks, 44);

    // Calling end multiple times is fine albeit redundant
    tok.end();
    tok.end();
    tok.end();
    tok.end();
    tok.end();
    tok.end();
}

#[test]
fn iterator_usage() {
    // Setup
    let (_guard, mut ctx) = crate::test::test_ctx_initialized();
    let ui = ctx.frame();

    let _window = ui
        .window("Example")
        .position([0.0, 0.0], crate::Condition::Always)
        .size([100.0, 800.0], crate::Condition::Always)
        .begin();

    // Create clipper
    let clip = ListClipper::new(1000);

    let mut ticks = 0;

    let tok = clip.begin(ui);
    for row_num in tok.iter() {
        dbg!(row_num);
        ui.text("...");
        ticks += 1;
    }

    // Should be consistent with size in `cpp_style_usage`
    assert_eq!(ticks, 44);
}