//! A list element that can be used to render a large number of differently sized elements//! efficiently. Clients of this API need to ensure that elements outside of the scrolled//! area do not change their height for this element to function correctly. If your elements//! do change height, notify the list element via [`ListState::splice`] or [`ListState::reset`].//! In order to minimize re-renders, this element's state is stored intrusively//! on your own views, so that your code can coordinate directly with the list element's cached state.//!//! If all of your elements are the same height, see [`crate::UniformList`] for a simpler API use crate::{    AnyElement, App, AvailableSpace, Bounds, ContentMask, DispatchPhase, Edges, Element, EntityId,    FocusHandle, GlobalElementId, Hitbox, HitboxBehavior, InspectorElementId, IntoElement,    Overflow, Pixels, Point, ScrollDelta, ScrollWheelEvent, Size, Style, StyleRefinement, Styled,    Window, point, px, size,};use collections::VecDeque;use refineable::Refineable as _;use std::{cell::RefCell, ops::Range, rc::Rc};use sum_tree::{Bias, Dimensions, SumTree}; type RenderItemFn = dyn FnMut(usize, &mut Window, &mut App) -> AnyElement + 'static; /// Construct a new list elementpub fn list(    state: ListState,    render_item: impl FnMut(usize, &mut Window, &mut App) -> AnyElement + 'static,) -> List {    List {        state,        render_item: Box::new(render_item),        style: StyleRefinement::default(),        sizing_behavior: ListSizingBehavior::default(),    }} /// A list elementpub struct List {    state: ListState,    render_item: Box<RenderItemFn>,    style: StyleRefinement,    sizing_behavior: ListSizingBehavior,} impl List {    /// Set the sizing behavior for the list.    pub fn with_sizing_behavior(mut self, behavior: ListSizingBehavior) -> Self {        self.sizing_behavior = behavior;        self    }} /// The list state that views must hold on behalf of the list element.#[derive(Clone)]pub struct ListState(Rc<RefCell<StateInner>>); impl std::fmt::Debug for ListState {    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {        f.write_str("ListState")    }} struct StateInner {    last_layout_bounds: Option<Bounds<Pixels>>,    last_padding: Option<Edges<Pixels>>,    items: SumTree<ListItem>,    logical_scroll_top: Option<ListOffset>,    alignment: ListAlignment,    overdraw: Pixels,    reset: bool,    #[allow(clippy::type_complexity)]    scroll_handler: Option<Box<dyn FnMut(&ListScrollEvent, &mut Window, &mut App)>>,    scrollbar_drag_start_height: Option<Pixels>,    measuring_behavior: ListMeasuringBehavior,    pending_scroll: Option<PendingScrollFraction>,} /// Keeps track of a fractional scroll position within an item for restoration/// after remeasurement.struct PendingScrollFraction {    /// The index of the item to scroll within.    item_ix: usize,    /// Fractional offset (0.0 to 1.0) within the item's height.    fraction: f32,} /// Whether the list is scrolling from top to bottom or bottom to top.#[derive(Clone, Copy, Debug, Eq, PartialEq)]pub enum ListAlignment {    /// The list is scrolling from top to bottom, like most lists.    Top,    /// The list is scrolling from bottom to top, like a chat log.    Bottom,} /// A scroll event that has been converted to be in terms of the list's items.pub struct ListScrollEvent {    /// The range of items currently visible in the list, after applying the scroll event.    pub visible_range: Range<usize>,     /// The number of items that are currently visible in the list, after applying the scroll event.    pub count: usize,     /// Whether the list has been scrolled.    pub is_scrolled: bool,} /// The sizing behavior to apply during layout.#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]pub enum ListSizingBehavior {    /// The list should calculate its size based on the size of its items.    Infer,    /// The list should not calculate a fixed size.    #[default]    Auto,} /// The measuring behavior to apply during layout.#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]pub enum ListMeasuringBehavior {    /// Measure all items in the list.    /// Note: This can be expensive for the first frame in a large list.    Measure(bool),    /// Only measure visible items    #[default]    Visible,} impl ListMeasuringBehavior {    fn reset(&mut self) {        match self {            ListMeasuringBehavior::Measure(has_measured) => *has_measured = false,            ListMeasuringBehavior::Visible => {}        }    }} /// The horizontal sizing behavior to apply during layout.#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]pub enum ListHorizontalSizingBehavior {    /// List items' width can never exceed the width of the list.    #[default]    FitList,    /// List items' width may go over the width of the list, if any item is wider.    Unconstrained,} struct LayoutItemsResponse {    max_item_width: Pixels,    scroll_top: ListOffset,    item_layouts: VecDeque<ItemLayout>,} struct ItemLayout {    index: usize,    element: AnyElement,    size: Size<Pixels>,} /// Frame state used by the [List] element after layout.pub struct ListPrepaintState {    hitbox: Hitbox,    layout: LayoutItemsResponse,} #[derive(Clone)]enum ListItem {    Unmeasured {        focus_handle: Option<FocusHandle>,    },    Measured {        size: Size<Pixels>,        focus_handle: Option<FocusHandle>,    },} impl ListItem {    fn size(&self) -> Option<Size<Pixels>> {        if let ListItem::Measured { size, .. } = self {            Some(*size)        } else {            None        }    }     fn focus_handle(&self) -> Option<FocusHandle> {        match self {            ListItem::Unmeasured { focus_handle } | ListItem::Measured { focus_handle, .. } => {                focus_handle.clone()            }        }    }     fn contains_focused(&self, window: &Window, cx: &App) -> bool {        match self {            ListItem::Unmeasured { focus_handle } | ListItem::Measured { focus_handle, .. } => {                focus_handle                    .as_ref()                    .is_some_and(|handle| handle.contains_focused(window, cx))            }        }    }} #[derive(Clone, Debug, Default, PartialEq)]struct ListItemSummary {    count: usize,    rendered_count: usize,    unrendered_count: usize,    height: Pixels,    has_focus_handles: bool,} #[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]struct Count(usize); #[derive(Clone, Debug, Default)]struct Height(Pixels); impl ListState {    /// Construct a new list state, for storage on a view.    ///    /// The overdraw parameter controls how much extra space is rendered    /// above and below the visible area. Elements within this area will    /// be measured even though they are not visible. This can help ensure    /// that the list doesn't flicker or pop in when scrolling.    pub fn new(item_count: usize, alignment: ListAlignment, overdraw: Pixels) -> Self {        let this = Self(Rc::new(RefCell::new(StateInner {            last_layout_bounds: None,            last_padding: None,            items: SumTree::default(),            logical_scroll_top: None,            alignment,            overdraw,            scroll_handler: None,            reset: false,            scrollbar_drag_start_height: None,            measuring_behavior: ListMeasuringBehavior::default(),            pending_scroll: None,        })));        this.splice(0..0, item_count);        this    }     /// Set the list to measure all items in the list in the first layout phase.    ///    /// This is useful for ensuring that the scrollbar size is correct instead of based on only rendered elements.    pub fn measure_all(self) -> Self {        self.0.borrow_mut().measuring_behavior = ListMeasuringBehavior::Measure(false);        self    }     /// Reset this instantiation of the list state.    ///    /// Note that this will cause scroll events to be dropped until the next paint.    pub fn reset(&self, element_count: usize) {        let old_count = {            let state = &mut *self.0.borrow_mut();            state.reset = true;            state.measuring_behavior.reset();            state.logical_scroll_top = None;            state.scrollbar_drag_start_height = None;            state.items.summary().count        };         self.splice(0..old_count, element_count);    }     /// Remeasure all items while preserving proportional scroll position.    ///    /// Use this when item heights may have changed (e.g., font size changes)    /// but the number and identity of items remains the same.    pub fn remeasure(&self) {        let state = &mut *self.0.borrow_mut();         let new_items = state.items.iter().map(|item| ListItem::Unmeasured {            focus_handle: item.focus_handle(),        });         // If there's a `logical_scroll_top`, we need to keep track of it as a        // `PendingScrollFraction`, so we can later preserve that scroll        // position proportionally to the item, in case the item's height        // changes.        if let Some(scroll_top) = state.logical_scroll_top {            let mut cursor = state.items.cursor::<Count>(());            cursor.seek(&Count(scroll_top.item_ix), Bias::Right);             if let Some(item) = cursor.item() {                if let Some(size) = item.size() {                    let fraction = if size.height.0 > 0.0 {                        (scroll_top.offset_in_item.0 / size.height.0).clamp(0.0, 1.0)                    } else {                        0.0                    };                     state.pending_scroll = Some(PendingScrollFraction {                        item_ix: scroll_top.item_ix,                        fraction,                    });                }            }        }         state.items = SumTree::from_iter(new_items, ());        state.measuring_behavior.reset();    }     /// The number of items in this list.    pub fn item_count(&self) -> usize {        self.0.borrow().items.summary().count    }     /// Inform the list state that the items in `old_range` have been replaced    /// by `count` new items that must be recalculated.    pub fn splice(&self, old_range: Range<usize>, count: usize) {        self.splice_focusable(old_range, (0..count).map(|_| None))    }     /// Register with the list state that the items in `old_range` have been replaced    /// by new items. As opposed to [`Self::splice`], this method allows an iterator of optional focus handles    /// to be supplied to properly integrate with items in the list that can be focused. If a focused item    /// is scrolled out of view, the list will continue to render it to allow keyboard interaction.    pub fn splice_focusable(        &self,        old_range: Range<usize>,        focus_handles: impl IntoIterator<Item = Option<FocusHandle>>,    ) {        let state = &mut *self.0.borrow_mut();         let mut old_items = state.items.cursor::<Count>(());        let mut new_items = old_items.slice(&Count(old_range.start), Bias::Right);        old_items.seek_forward(&Count(old_range.end), Bias::Right);         let mut spliced_count = 0;        new_items.extend(            focus_handles.into_iter().map(|focus_handle| {                spliced_count += 1;                ListItem::Unmeasured { focus_handle }            }),            (),        );        new_items.append(old_items.suffix(), ());        drop(old_items);        state.items = new_items;         if let Some(ListOffset {            item_ix,            offset_in_item,        }) = state.logical_scroll_top.as_mut()        {            if old_range.contains(item_ix) {                *item_ix = old_range.start;                *offset_in_item = px(0.);            } else if old_range.end <= *item_ix {                *item_ix = *item_ix - (old_range.end - old_range.start) + spliced_count;            }        }    }     /// Set a handler that will be called when the list is scrolled.    pub fn set_scroll_handler(        &self,        handler: impl FnMut(&ListScrollEvent, &mut Window, &mut App) + 'static,    ) {        self.0.borrow_mut().scroll_handler = Some(Box::new(handler))    }     /// Get the current scroll offset, in terms of the list's items.    pub fn logical_scroll_top(&self) -> ListOffset {        self.0.borrow().logical_scroll_top()    }     /// Scroll the list by the given offset    pub fn scroll_by(&self, distance: Pixels) {        if distance == px(0.) {            return;        }         let current_offset = self.logical_scroll_top();        let state = &mut *self.0.borrow_mut();        let mut cursor = state.items.cursor::<ListItemSummary>(());        cursor.seek(&Count(current_offset.item_ix), Bias::Right);         let start_pixel_offset = cursor.start().height + current_offset.offset_in_item;        let new_pixel_offset = (start_pixel_offset + distance).max(px(0.));        if new_pixel_offset > start_pixel_offset {            cursor.seek_forward(&Height(new_pixel_offset), Bias::Right);        } else {            cursor.seek(&Height(new_pixel_offset), Bias::Right);        }         state.logical_scroll_top = Some(ListOffset {            item_ix: cursor.start().count,            offset_in_item: new_pixel_offset - cursor.start().height,        });    }     /// Scroll the list to the given offset    pub fn scroll_to(&self, mut scroll_top: ListOffset) {        let state = &mut *self.0.borrow_mut();        let item_count = state.items.summary().count;        if scroll_top.item_ix >= item_count {            scroll_top.item_ix = item_count;            scroll_top.offset_in_item = px(0.);        }         state.logical_scroll_top = Some(scroll_top);    }     /// Scroll the list to the given item, such that the item is fully visible.    pub fn scroll_to_reveal_item(&self, ix: usize) {        let state = &mut *self.0.borrow_mut();         let mut scroll_top = state.logical_scroll_top();        let height = state            .last_layout_bounds            .map_or(px(0.), |bounds| bounds.size.height);        let padding = state.last_padding.unwrap_or_default();         if ix <= scroll_top.item_ix {            scroll_top.item_ix = ix;            scroll_top.offset_in_item = px(0.);        } else {            let mut cursor = state.items.cursor::<ListItemSummary>(());            cursor.seek(&Count(ix + 1), Bias::Right);            let bottom = cursor.start().height + padding.top;            let goal_top = px(0.).max(bottom - height + padding.bottom);             cursor.seek(&Height(goal_top), Bias::Left);            let start_ix = cursor.start().count;            let start_item_top = cursor.start().height;             if start_ix >= scroll_top.item_ix {                scroll_top.item_ix = start_ix;                scroll_top.offset_in_item = goal_top - start_item_top;            }        }         state.logical_scroll_top = Some(scroll_top);    }     /// Get the bounds for the given item in window coordinates, if it's    /// been rendered.    pub fn bounds_for_item(&self, ix: usize) -> Option<Bounds<Pixels>> {        let state = &*self.0.borrow();         let bounds = state.last_layout_bounds.unwrap_or_default();        let scroll_top = state.logical_scroll_top();        if ix < scroll_top.item_ix {            return None;        }         let mut cursor = state.items.cursor::<Dimensions<Count, Height>>(());        cursor.seek(&Count(scroll_top.item_ix), Bias::Right);         let scroll_top = cursor.start().1.0 + scroll_top.offset_in_item;         cursor.seek_forward(&Count(ix), Bias::Right);        if let Some(&ListItem::Measured { size, .. }) = cursor.item() {            let &Dimensions(Count(count), Height(top), _) = cursor.start();            if count == ix {                let top = bounds.top() + top - scroll_top;                return Some(Bounds::from_corners(                    point(bounds.left(), top),                    point(bounds.right(), top + size.height),                ));            }        }        None    }     /// Call this method when the user starts dragging the scrollbar.    ///    /// This will prevent the height reported to the scrollbar from changing during the drag    /// as items in the overdraw get measured, and help offset scroll position changes accordingly.    pub fn scrollbar_drag_started(&self) {        let mut state = self.0.borrow_mut();        state.scrollbar_drag_start_height = Some(state.items.summary().height);    }     /// Called when the user stops dragging the scrollbar.    ///    /// See `scrollbar_drag_started`.    pub fn scrollbar_drag_ended(&self) {        self.0.borrow_mut().scrollbar_drag_start_height.take();    }     /// Set the offset from the scrollbar    pub fn set_offset_from_scrollbar(&self, point: Point<Pixels>) {        self.0.borrow_mut().set_offset_from_scrollbar(point);    }     /// Returns the maximum scroll offset according to the items we have measured.    /// This value remains constant while dragging to prevent the scrollbar from moving away unexpectedly.    pub fn max_offset_for_scrollbar(&self) -> Point<Pixels> {        let state = self.0.borrow();        let bounds = state.last_layout_bounds.unwrap_or_default();         let height = state            .scrollbar_drag_start_height            .unwrap_or_else(|| state.items.summary().height);

Lines 1–500 of 1452. Load more