1//! A list element that can be used to render a large number of differently sized elements
2//! efficiently. Clients of this API need to ensure that elements outside of the scrolled
3//! area do not change their height for this element to function correctly. If your elements
4//! do change height, notify the list element via [`ListState::splice`] or [`ListState::reset`].
5//! In order to minimize re-renders, this element's state is stored intrusively
6//! on your own views, so that your code can coordinate directly with the list element's cached state.
7//!
8//! If all of your elements are the same height, see [`UniformList`] for a simpler API
9
10use crate::{
11 AnyElement, App, AvailableSpace, Bounds, ContentMask, DispatchPhase, Edges, Element, EntityId,
12 FocusHandle, GlobalElementId, Hitbox, HitboxBehavior, InspectorElementId, IntoElement,
13 Overflow, Pixels, Point, ScrollDelta, ScrollWheelEvent, Size, Style, StyleRefinement, Styled,
14 Window, point, px, size,
15};
16use collections::VecDeque;
17use refineable::Refineable as _;
18use std::{cell::RefCell, ops::Range, rc::Rc};
19use sum_tree::{Bias, SumTree};
20
21/// Construct a new list element
22pub fn list(state: ListState) -> List {
23 List {
24 state,
25 style: StyleRefinement::default(),
26 sizing_behavior: ListSizingBehavior::default(),
27 }
28}
29
30/// A list element
31pub struct List {
32 state: ListState,
33 style: StyleRefinement,
34 sizing_behavior: ListSizingBehavior,
35}
36
37impl List {
38 /// Set the sizing behavior for the list.
39 pub fn with_sizing_behavior(mut self, behavior: ListSizingBehavior) -> Self {
40 self.sizing_behavior = behavior;
41 self
42 }
43}
44
45/// The list state that views must hold on behalf of the list element.
46#[derive(Clone)]
47pub struct ListState(Rc<RefCell<StateInner>>);
48
49impl std::fmt::Debug for ListState {
50 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
51 f.write_str("ListState")
52 }
53}
54
55struct StateInner {
56 last_layout_bounds: Option<Bounds<Pixels>>,
57 last_padding: Option<Edges<Pixels>>,
58 render_item: Box<dyn FnMut(usize, &mut Window, &mut App) -> AnyElement>,
59 items: SumTree<ListItem>,
60 logical_scroll_top: Option<ListOffset>,
61 alignment: ListAlignment,
62 overdraw: Pixels,
63 reset: bool,
64 #[allow(clippy::type_complexity)]
65 scroll_handler: Option<Box<dyn FnMut(&ListScrollEvent, &mut Window, &mut App)>>,
66 scrollbar_drag_start_height: Option<Pixels>,
67}
68
69/// Whether the list is scrolling from top to bottom or bottom to top.
70#[derive(Clone, Copy, Debug, Eq, PartialEq)]
71pub enum ListAlignment {
72 /// The list is scrolling from top to bottom, like most lists.
73 Top,
74 /// The list is scrolling from bottom to top, like a chat log.
75 Bottom,
76}
77
78/// A scroll event that has been converted to be in terms of the list's items.
79pub struct ListScrollEvent {
80 /// The range of items currently visible in the list, after applying the scroll event.
81 pub visible_range: Range<usize>,
82
83 /// The number of items that are currently visible in the list, after applying the scroll event.
84 pub count: usize,
85
86 /// Whether the list has been scrolled.
87 pub is_scrolled: bool,
88}
89
90/// The sizing behavior to apply during layout.
91#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
92pub enum ListSizingBehavior {
93 /// The list should calculate its size based on the size of its items.
94 Infer,
95 /// The list should not calculate a fixed size.
96 #[default]
97 Auto,
98}
99
100/// The horizontal sizing behavior to apply during layout.
101#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
102pub enum ListHorizontalSizingBehavior {
103 /// List items' width can never exceed the width of the list.
104 #[default]
105 FitList,
106 /// List items' width may go over the width of the list, if any item is wider.
107 Unconstrained,
108}
109
110struct LayoutItemsResponse {
111 max_item_width: Pixels,
112 scroll_top: ListOffset,
113 item_layouts: VecDeque<ItemLayout>,
114}
115
116struct ItemLayout {
117 index: usize,
118 element: AnyElement,
119 size: Size<Pixels>,
120}
121
122/// Frame state used by the [List] element after layout.
123pub struct ListPrepaintState {
124 hitbox: Hitbox,
125 layout: LayoutItemsResponse,
126}
127
128#[derive(Clone)]
129enum ListItem {
130 Unmeasured {
131 focus_handle: Option<FocusHandle>,
132 },
133 Measured {
134 size: Size<Pixels>,
135 focus_handle: Option<FocusHandle>,
136 },
137}
138
139impl ListItem {
140 fn size(&self) -> Option<Size<Pixels>> {
141 if let ListItem::Measured { size, .. } = self {
142 Some(*size)
143 } else {
144 None
145 }
146 }
147
148 fn focus_handle(&self) -> Option<FocusHandle> {
149 match self {
150 ListItem::Unmeasured { focus_handle } | ListItem::Measured { focus_handle, .. } => {
151 focus_handle.clone()
152 }
153 }
154 }
155
156 fn contains_focused(&self, window: &Window, cx: &App) -> bool {
157 match self {
158 ListItem::Unmeasured { focus_handle } | ListItem::Measured { focus_handle, .. } => {
159 focus_handle
160 .as_ref()
161 .is_some_and(|handle| handle.contains_focused(window, cx))
162 }
163 }
164 }
165}
166
167#[derive(Clone, Debug, Default, PartialEq)]
168struct ListItemSummary {
169 count: usize,
170 rendered_count: usize,
171 unrendered_count: usize,
172 height: Pixels,
173 has_focus_handles: bool,
174}
175
176#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
177struct Count(usize);
178
179#[derive(Clone, Debug, Default)]
180struct Height(Pixels);
181
182impl ListState {
183 /// Construct a new list state, for storage on a view.
184 ///
185 /// The overdraw parameter controls how much extra space is rendered
186 /// above and below the visible area. Elements within this area will
187 /// be measured even though they are not visible. This can help ensure
188 /// that the list doesn't flicker or pop in when scrolling.
189 pub fn new<R>(
190 item_count: usize,
191 alignment: ListAlignment,
192 overdraw: Pixels,
193 render_item: R,
194 ) -> Self
195 where
196 R: 'static + FnMut(usize, &mut Window, &mut App) -> AnyElement,
197 {
198 let this = Self(Rc::new(RefCell::new(StateInner {
199 last_layout_bounds: None,
200 last_padding: None,
201 render_item: Box::new(render_item),
202 items: SumTree::default(),
203 logical_scroll_top: None,
204 alignment,
205 overdraw,
206 scroll_handler: None,
207 reset: false,
208 scrollbar_drag_start_height: None,
209 })));
210 this.splice(0..0, item_count);
211 this
212 }
213
214 /// Reset this instantiation of the list state.
215 ///
216 /// Note that this will cause scroll events to be dropped until the next paint.
217 pub fn reset(&self, element_count: usize) {
218 let old_count = {
219 let state = &mut *self.0.borrow_mut();
220 state.reset = true;
221 state.logical_scroll_top = None;
222 state.scrollbar_drag_start_height = None;
223 state.items.summary().count
224 };
225
226 self.splice(0..old_count, element_count);
227 }
228
229 /// The number of items in this list.
230 pub fn item_count(&self) -> usize {
231 self.0.borrow().items.summary().count
232 }
233
234 /// Inform the list state that the items in `old_range` have been replaced
235 /// by `count` new items that must be recalculated.
236 pub fn splice(&self, old_range: Range<usize>, count: usize) {
237 self.splice_focusable(old_range, (0..count).map(|_| None))
238 }
239
240 /// Register with the list state that the items in `old_range` have been replaced
241 /// by new items. As opposed to [`splice`], this method allows an iterator of optional focus handles
242 /// to be supplied to properly integrate with items in the list that can be focused. If a focused item
243 /// is scrolled out of view, the list will continue to render it to allow keyboard interaction.
244 pub fn splice_focusable(
245 &self,
246 old_range: Range<usize>,
247 focus_handles: impl IntoIterator<Item = Option<FocusHandle>>,
248 ) {
249 let state = &mut *self.0.borrow_mut();
250
251 let mut old_items = state.items.cursor::<Count>(&());
252 let mut new_items = old_items.slice(&Count(old_range.start), Bias::Right);
253 old_items.seek_forward(&Count(old_range.end), Bias::Right);
254
255 let mut spliced_count = 0;
256 new_items.extend(
257 focus_handles.into_iter().map(|focus_handle| {
258 spliced_count += 1;
259 ListItem::Unmeasured { focus_handle }
260 }),
261 &(),
262 );
263 new_items.append(old_items.suffix(), &());
264 drop(old_items);
265 state.items = new_items;
266
267 if let Some(ListOffset {
268 item_ix,
269 offset_in_item,
270 }) = state.logical_scroll_top.as_mut()
271 {
272 if old_range.contains(item_ix) {
273 *item_ix = old_range.start;
274 *offset_in_item = px(0.);
275 } else if old_range.end <= *item_ix {
276 *item_ix = *item_ix - (old_range.end - old_range.start) + spliced_count;
277 }
278 }
279 }
280
281 /// Set a handler that will be called when the list is scrolled.
282 pub fn set_scroll_handler(
283 &self,
284 handler: impl FnMut(&ListScrollEvent, &mut Window, &mut App) + 'static,
285 ) {
286 self.0.borrow_mut().scroll_handler = Some(Box::new(handler))
287 }
288
289 /// Get the current scroll offset, in terms of the list's items.
290 pub fn logical_scroll_top(&self) -> ListOffset {
291 self.0.borrow().logical_scroll_top()
292 }
293
294 /// Scroll the list by the given offset
295 pub fn scroll_by(&self, distance: Pixels) {
296 if distance == px(0.) {
297 return;
298 }
299
300 let current_offset = self.logical_scroll_top();
301 let state = &mut *self.0.borrow_mut();
302 let mut cursor = state.items.cursor::<ListItemSummary>(&());
303 cursor.seek(&Count(current_offset.item_ix), Bias::Right);
304
305 let start_pixel_offset = cursor.start().height + current_offset.offset_in_item;
306 let new_pixel_offset = (start_pixel_offset + distance).max(px(0.));
307 if new_pixel_offset > start_pixel_offset {
308 cursor.seek_forward(&Height(new_pixel_offset), Bias::Right);
309 } else {
310 cursor.seek(&Height(new_pixel_offset), Bias::Right);
311 }
312
313 state.logical_scroll_top = Some(ListOffset {
314 item_ix: cursor.start().count,
315 offset_in_item: new_pixel_offset - cursor.start().height,
316 });
317 }
318
319 /// Scroll the list to the given offset
320 pub fn scroll_to(&self, mut scroll_top: ListOffset) {
321 let state = &mut *self.0.borrow_mut();
322 let item_count = state.items.summary().count;
323 if scroll_top.item_ix >= item_count {
324 scroll_top.item_ix = item_count;
325 scroll_top.offset_in_item = px(0.);
326 }
327
328 state.logical_scroll_top = Some(scroll_top);
329 }
330
331 /// Scroll the list to the given item, such that the item is fully visible.
332 pub fn scroll_to_reveal_item(&self, ix: usize) {
333 let state = &mut *self.0.borrow_mut();
334
335 let mut scroll_top = state.logical_scroll_top();
336 let height = state
337 .last_layout_bounds
338 .map_or(px(0.), |bounds| bounds.size.height);
339 let padding = state.last_padding.unwrap_or_default();
340
341 if ix <= scroll_top.item_ix {
342 scroll_top.item_ix = ix;
343 scroll_top.offset_in_item = px(0.);
344 } else {
345 let mut cursor = state.items.cursor::<ListItemSummary>(&());
346 cursor.seek(&Count(ix + 1), Bias::Right);
347 let bottom = cursor.start().height + padding.top;
348 let goal_top = px(0.).max(bottom - height + padding.bottom);
349
350 cursor.seek(&Height(goal_top), Bias::Left);
351 let start_ix = cursor.start().count;
352 let start_item_top = cursor.start().height;
353
354 if start_ix >= scroll_top.item_ix {
355 scroll_top.item_ix = start_ix;
356 scroll_top.offset_in_item = goal_top - start_item_top;
357 }
358 }
359
360 state.logical_scroll_top = Some(scroll_top);
361 }
362
363 /// Get the bounds for the given item in window coordinates, if it's
364 /// been rendered.
365 pub fn bounds_for_item(&self, ix: usize) -> Option<Bounds<Pixels>> {
366 let state = &*self.0.borrow();
367
368 let bounds = state.last_layout_bounds.unwrap_or_default();
369 let scroll_top = state.logical_scroll_top();
370 if ix < scroll_top.item_ix {
371 return None;
372 }
373
374 let mut cursor = state.items.cursor::<(Count, Height)>(&());
375 cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
376
377 let scroll_top = cursor.start().1.0 + scroll_top.offset_in_item;
378
379 cursor.seek_forward(&Count(ix), Bias::Right);
380 if let Some(&ListItem::Measured { size, .. }) = cursor.item() {
381 let &(Count(count), Height(top)) = cursor.start();
382 if count == ix {
383 let top = bounds.top() + top - scroll_top;
384 return Some(Bounds::from_corners(
385 point(bounds.left(), top),
386 point(bounds.right(), top + size.height),
387 ));
388 }
389 }
390 None
391 }
392
393 /// Call this method when the user starts dragging the scrollbar.
394 ///
395 /// This will prevent the height reported to the scrollbar from changing during the drag
396 /// as items in the overdraw get measured, and help offset scroll position changes accordingly.
397 pub fn scrollbar_drag_started(&self) {
398 let mut state = self.0.borrow_mut();
399 state.scrollbar_drag_start_height = Some(state.items.summary().height);
400 }
401
402 /// Called when the user stops dragging the scrollbar.
403 ///
404 /// See `scrollbar_drag_started`.
405 pub fn scrollbar_drag_ended(&self) {
406 self.0.borrow_mut().scrollbar_drag_start_height.take();
407 }
408
409 /// Set the offset from the scrollbar
410 pub fn set_offset_from_scrollbar(&self, point: Point<Pixels>) {
411 self.0.borrow_mut().set_offset_from_scrollbar(point);
412 }
413
414 /// Returns the maximum scroll offset according to the items we have measured.
415 /// This value remains constant while dragging to prevent the scrollbar from moving away unexpectedly.
416 pub fn max_offset_for_scrollbar(&self) -> Size<Pixels> {
417 let state = self.0.borrow();
418 let bounds = state.last_layout_bounds.unwrap_or_default();
419
420 let height = state
421 .scrollbar_drag_start_height
422 .unwrap_or_else(|| state.items.summary().height);
423
424 Size::new(Pixels::ZERO, Pixels::ZERO.max(height - bounds.size.height))
425 }
426
427 /// Returns the current scroll offset adjusted for the scrollbar
428 pub fn scroll_px_offset_for_scrollbar(&self) -> Point<Pixels> {
429 let state = &self.0.borrow();
430 let logical_scroll_top = state.logical_scroll_top();
431
432 let mut cursor = state.items.cursor::<ListItemSummary>(&());
433 let summary: ListItemSummary =
434 cursor.summary(&Count(logical_scroll_top.item_ix), Bias::Right);
435 let content_height = state.items.summary().height;
436 let drag_offset =
437 // if dragging the scrollbar, we want to offset the point if the height changed
438 content_height - state.scrollbar_drag_start_height.unwrap_or(content_height);
439 let offset = summary.height + logical_scroll_top.offset_in_item - drag_offset;
440
441 Point::new(px(0.), -offset)
442 }
443
444 /// Return the bounds of the viewport in pixels.
445 pub fn viewport_bounds(&self) -> Bounds<Pixels> {
446 self.0.borrow().last_layout_bounds.unwrap_or_default()
447 }
448}
449
450impl StateInner {
451 fn visible_range(&self, height: Pixels, scroll_top: &ListOffset) -> Range<usize> {
452 let mut cursor = self.items.cursor::<ListItemSummary>(&());
453 cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
454 let start_y = cursor.start().height + scroll_top.offset_in_item;
455 cursor.seek_forward(&Height(start_y + height), Bias::Left);
456 scroll_top.item_ix..cursor.start().count + 1
457 }
458
459 fn scroll(
460 &mut self,
461 scroll_top: &ListOffset,
462 height: Pixels,
463 delta: Point<Pixels>,
464 current_view: EntityId,
465 window: &mut Window,
466 cx: &mut App,
467 ) {
468 // Drop scroll events after a reset, since we can't calculate
469 // the new logical scroll top without the item heights
470 if self.reset {
471 return;
472 }
473
474 let padding = self.last_padding.unwrap_or_default();
475 let scroll_max =
476 (self.items.summary().height + padding.top + padding.bottom - height).max(px(0.));
477 let new_scroll_top = (self.scroll_top(scroll_top) - delta.y)
478 .max(px(0.))
479 .min(scroll_max);
480
481 if self.alignment == ListAlignment::Bottom && new_scroll_top == scroll_max {
482 self.logical_scroll_top = None;
483 } else {
484 let mut cursor = self.items.cursor::<ListItemSummary>(&());
485 cursor.seek(&Height(new_scroll_top), Bias::Right);
486 let item_ix = cursor.start().count;
487 let offset_in_item = new_scroll_top - cursor.start().height;
488 self.logical_scroll_top = Some(ListOffset {
489 item_ix,
490 offset_in_item,
491 });
492 }
493
494 if self.scroll_handler.is_some() {
495 let visible_range = self.visible_range(height, scroll_top);
496 self.scroll_handler.as_mut().unwrap()(
497 &ListScrollEvent {
498 visible_range,
499 count: self.items.summary().count,
500 is_scrolled: self.logical_scroll_top.is_some(),
501 },
502 window,
503 cx,
504 );
505 }
506
507 cx.notify(current_view);
508 }
509
510 fn logical_scroll_top(&self) -> ListOffset {
511 self.logical_scroll_top
512 .unwrap_or_else(|| match self.alignment {
513 ListAlignment::Top => ListOffset {
514 item_ix: 0,
515 offset_in_item: px(0.),
516 },
517 ListAlignment::Bottom => ListOffset {
518 item_ix: self.items.summary().count,
519 offset_in_item: px(0.),
520 },
521 })
522 }
523
524 fn scroll_top(&self, logical_scroll_top: &ListOffset) -> Pixels {
525 let mut cursor = self.items.cursor::<ListItemSummary>(&());
526 cursor.seek(&Count(logical_scroll_top.item_ix), Bias::Right);
527 cursor.start().height + logical_scroll_top.offset_in_item
528 }
529
530 fn layout_items(
531 &mut self,
532 available_width: Option<Pixels>,
533 available_height: Pixels,
534 padding: &Edges<Pixels>,
535 window: &mut Window,
536 cx: &mut App,
537 ) -> LayoutItemsResponse {
538 let old_items = self.items.clone();
539 let mut measured_items = VecDeque::new();
540 let mut item_layouts = VecDeque::new();
541 let mut rendered_height = padding.top;
542 let mut max_item_width = px(0.);
543 let mut scroll_top = self.logical_scroll_top();
544 let mut rendered_focused_item = false;
545
546 let available_item_space = size(
547 available_width.map_or(AvailableSpace::MinContent, |width| {
548 AvailableSpace::Definite(width)
549 }),
550 AvailableSpace::MinContent,
551 );
552
553 let mut cursor = old_items.cursor::<Count>(&());
554
555 // Render items after the scroll top, including those in the trailing overdraw
556 cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
557 for (ix, item) in cursor.by_ref().enumerate() {
558 let visible_height = rendered_height - scroll_top.offset_in_item;
559 if visible_height >= available_height + self.overdraw {
560 break;
561 }
562
563 // Use the previously cached height and focus handle if available
564 let mut size = item.size();
565
566 // If we're within the visible area or the height wasn't cached, render and measure the item's element
567 if visible_height < available_height || size.is_none() {
568 let item_index = scroll_top.item_ix + ix;
569 let mut element = (self.render_item)(item_index, window, cx);
570 let element_size = element.layout_as_root(available_item_space, window, cx);
571 size = Some(element_size);
572 if visible_height < available_height {
573 item_layouts.push_back(ItemLayout {
574 index: item_index,
575 element,
576 size: element_size,
577 });
578 if item.contains_focused(window, cx) {
579 rendered_focused_item = true;
580 }
581 }
582 }
583
584 let size = size.unwrap();
585 rendered_height += size.height;
586 max_item_width = max_item_width.max(size.width);
587 measured_items.push_back(ListItem::Measured {
588 size,
589 focus_handle: item.focus_handle(),
590 });
591 }
592 rendered_height += padding.bottom;
593
594 // Prepare to start walking upward from the item at the scroll top.
595 cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
596
597 // If the rendered items do not fill the visible region, then adjust
598 // the scroll top upward.
599 if rendered_height - scroll_top.offset_in_item < available_height {
600 while rendered_height < available_height {
601 cursor.prev();
602 if let Some(item) = cursor.item() {
603 let item_index = cursor.start().0;
604 let mut element = (self.render_item)(item_index, window, cx);
605 let element_size = element.layout_as_root(available_item_space, window, cx);
606 let focus_handle = item.focus_handle();
607 rendered_height += element_size.height;
608 measured_items.push_front(ListItem::Measured {
609 size: element_size,
610 focus_handle,
611 });
612 item_layouts.push_front(ItemLayout {
613 index: item_index,
614 element,
615 size: element_size,
616 });
617 if item.contains_focused(window, cx) {
618 rendered_focused_item = true;
619 }
620 } else {
621 break;
622 }
623 }
624
625 scroll_top = ListOffset {
626 item_ix: cursor.start().0,
627 offset_in_item: rendered_height - available_height,
628 };
629
630 match self.alignment {
631 ListAlignment::Top => {
632 scroll_top.offset_in_item = scroll_top.offset_in_item.max(px(0.));
633 self.logical_scroll_top = Some(scroll_top);
634 }
635 ListAlignment::Bottom => {
636 scroll_top = ListOffset {
637 item_ix: cursor.start().0,
638 offset_in_item: rendered_height - available_height,
639 };
640 self.logical_scroll_top = None;
641 }
642 };
643 }
644
645 // Measure items in the leading overdraw
646 let mut leading_overdraw = scroll_top.offset_in_item;
647 while leading_overdraw < self.overdraw {
648 cursor.prev();
649 if let Some(item) = cursor.item() {
650 let size = if let ListItem::Measured { size, .. } = item {
651 *size
652 } else {
653 let mut element = (self.render_item)(cursor.start().0, window, cx);
654 element.layout_as_root(available_item_space, window, cx)
655 };
656
657 leading_overdraw += size.height;
658 measured_items.push_front(ListItem::Measured {
659 size,
660 focus_handle: item.focus_handle(),
661 });
662 } else {
663 break;
664 }
665 }
666
667 let measured_range = cursor.start().0..(cursor.start().0 + measured_items.len());
668 let mut cursor = old_items.cursor::<Count>(&());
669 let mut new_items = cursor.slice(&Count(measured_range.start), Bias::Right);
670 new_items.extend(measured_items, &());
671 cursor.seek(&Count(measured_range.end), Bias::Right);
672 new_items.append(cursor.suffix(), &());
673 self.items = new_items;
674
675 // If none of the visible items are focused, check if an off-screen item is focused
676 // and include it to be rendered after the visible items so keyboard interaction continues
677 // to work for it.
678 if !rendered_focused_item {
679 let mut cursor = self
680 .items
681 .filter::<_, Count>(&(), |summary| summary.has_focus_handles);
682 cursor.next();
683 while let Some(item) = cursor.item() {
684 if item.contains_focused(window, cx) {
685 let item_index = cursor.start().0;
686 let mut element = (self.render_item)(cursor.start().0, window, cx);
687 let size = element.layout_as_root(available_item_space, window, cx);
688 item_layouts.push_back(ItemLayout {
689 index: item_index,
690 element,
691 size,
692 });
693 break;
694 }
695 cursor.next();
696 }
697 }
698
699 LayoutItemsResponse {
700 max_item_width,
701 scroll_top,
702 item_layouts,
703 }
704 }
705
706 fn prepaint_items(
707 &mut self,
708 bounds: Bounds<Pixels>,
709 padding: Edges<Pixels>,
710 autoscroll: bool,
711 window: &mut Window,
712 cx: &mut App,
713 ) -> Result<LayoutItemsResponse, ListOffset> {
714 window.transact(|window| {
715 let mut layout_response = self.layout_items(
716 Some(bounds.size.width),
717 bounds.size.height,
718 &padding,
719 window,
720 cx,
721 );
722
723 // Avoid honoring autoscroll requests from elements other than our children.
724 window.take_autoscroll();
725
726 // Only paint the visible items, if there is actually any space for them (taking padding into account)
727 if bounds.size.height > padding.top + padding.bottom {
728 let mut item_origin = bounds.origin + Point::new(px(0.), padding.top);
729 item_origin.y -= layout_response.scroll_top.offset_in_item;
730 for item in &mut layout_response.item_layouts {
731 window.with_content_mask(Some(ContentMask { bounds }), |window| {
732 item.element.prepaint_at(item_origin, window, cx);
733 });
734
735 if let Some(autoscroll_bounds) = window.take_autoscroll() {
736 if autoscroll {
737 if autoscroll_bounds.top() < bounds.top() {
738 return Err(ListOffset {
739 item_ix: item.index,
740 offset_in_item: autoscroll_bounds.top() - item_origin.y,
741 });
742 } else if autoscroll_bounds.bottom() > bounds.bottom() {
743 let mut cursor = self.items.cursor::<Count>(&());
744 cursor.seek(&Count(item.index), Bias::Right);
745 let mut height = bounds.size.height - padding.top - padding.bottom;
746
747 // Account for the height of the element down until the autoscroll bottom.
748 height -= autoscroll_bounds.bottom() - item_origin.y;
749
750 // Keep decreasing the scroll top until we fill all the available space.
751 while height > Pixels::ZERO {
752 cursor.prev();
753 let Some(item) = cursor.item() else { break };
754
755 let size = item.size().unwrap_or_else(|| {
756 let mut item =
757 (self.render_item)(cursor.start().0, window, cx);
758 let item_available_size = size(
759 bounds.size.width.into(),
760 AvailableSpace::MinContent,
761 );
762 item.layout_as_root(item_available_size, window, cx)
763 });
764 height -= size.height;
765 }
766
767 return Err(ListOffset {
768 item_ix: cursor.start().0,
769 offset_in_item: if height < Pixels::ZERO {
770 -height
771 } else {
772 Pixels::ZERO
773 },
774 });
775 }
776 }
777 }
778
779 item_origin.y += item.size.height;
780 }
781 } else {
782 layout_response.item_layouts.clear();
783 }
784
785 Ok(layout_response)
786 })
787 }
788
789 // Scrollbar support
790
791 fn set_offset_from_scrollbar(&mut self, point: Point<Pixels>) {
792 let Some(bounds) = self.last_layout_bounds else {
793 return;
794 };
795 let height = bounds.size.height;
796
797 let padding = self.last_padding.unwrap_or_default();
798 let content_height = self.items.summary().height;
799 let scroll_max = (content_height + padding.top + padding.bottom - height).max(px(0.));
800 let drag_offset =
801 // if dragging the scrollbar, we want to offset the point if the height changed
802 content_height - self.scrollbar_drag_start_height.unwrap_or(content_height);
803 let new_scroll_top = (point.y - drag_offset).abs().max(px(0.)).min(scroll_max);
804
805 if self.alignment == ListAlignment::Bottom && new_scroll_top == scroll_max {
806 self.logical_scroll_top = None;
807 } else {
808 let mut cursor = self.items.cursor::<ListItemSummary>(&());
809 cursor.seek(&Height(new_scroll_top), Bias::Right);
810
811 let item_ix = cursor.start().count;
812 let offset_in_item = new_scroll_top - cursor.start().height;
813 self.logical_scroll_top = Some(ListOffset {
814 item_ix,
815 offset_in_item,
816 });
817 }
818 }
819}
820
821impl std::fmt::Debug for ListItem {
822 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
823 match self {
824 Self::Unmeasured { .. } => write!(f, "Unrendered"),
825 Self::Measured { size, .. } => f.debug_struct("Rendered").field("size", size).finish(),
826 }
827 }
828}
829
830/// An offset into the list's items, in terms of the item index and the number
831/// of pixels off the top left of the item.
832#[derive(Debug, Clone, Copy, Default)]
833pub struct ListOffset {
834 /// The index of an item in the list
835 pub item_ix: usize,
836 /// The number of pixels to offset from the item index.
837 pub offset_in_item: Pixels,
838}
839
840impl Element for List {
841 type RequestLayoutState = ();
842 type PrepaintState = ListPrepaintState;
843
844 fn id(&self) -> Option<crate::ElementId> {
845 None
846 }
847
848 fn source_location(&self) -> Option<&'static core::panic::Location<'static>> {
849 None
850 }
851
852 fn request_layout(
853 &mut self,
854 _id: Option<&GlobalElementId>,
855 _inspector_id: Option<&InspectorElementId>,
856 window: &mut Window,
857 cx: &mut App,
858 ) -> (crate::LayoutId, Self::RequestLayoutState) {
859 let layout_id = match self.sizing_behavior {
860 ListSizingBehavior::Infer => {
861 let mut style = Style::default();
862 style.overflow.y = Overflow::Scroll;
863 style.refine(&self.style);
864 window.with_text_style(style.text_style().cloned(), |window| {
865 let state = &mut *self.state.0.borrow_mut();
866
867 let available_height = if let Some(last_bounds) = state.last_layout_bounds {
868 last_bounds.size.height
869 } else {
870 // If we don't have the last layout bounds (first render),
871 // we might just use the overdraw value as the available height to layout enough items.
872 state.overdraw
873 };
874 let padding = style.padding.to_pixels(
875 state.last_layout_bounds.unwrap_or_default().size.into(),
876 window.rem_size(),
877 );
878
879 let layout_response =
880 state.layout_items(None, available_height, &padding, window, cx);
881 let max_element_width = layout_response.max_item_width;
882
883 let summary = state.items.summary();
884 let total_height = summary.height;
885
886 window.request_measured_layout(
887 style,
888 move |known_dimensions, available_space, _window, _cx| {
889 let width =
890 known_dimensions
891 .width
892 .unwrap_or(match available_space.width {
893 AvailableSpace::Definite(x) => x,
894 AvailableSpace::MinContent | AvailableSpace::MaxContent => {
895 max_element_width
896 }
897 });
898 let height = match available_space.height {
899 AvailableSpace::Definite(height) => total_height.min(height),
900 AvailableSpace::MinContent | AvailableSpace::MaxContent => {
901 total_height
902 }
903 };
904 size(width, height)
905 },
906 )
907 })
908 }
909 ListSizingBehavior::Auto => {
910 let mut style = Style::default();
911 style.refine(&self.style);
912 window.with_text_style(style.text_style().cloned(), |window| {
913 window.request_layout(style, None, cx)
914 })
915 }
916 };
917 (layout_id, ())
918 }
919
920 fn prepaint(
921 &mut self,
922 _id: Option<&GlobalElementId>,
923 _inspector_id: Option<&InspectorElementId>,
924 bounds: Bounds<Pixels>,
925 _: &mut Self::RequestLayoutState,
926 window: &mut Window,
927 cx: &mut App,
928 ) -> ListPrepaintState {
929 let state = &mut *self.state.0.borrow_mut();
930 state.reset = false;
931
932 let mut style = Style::default();
933 style.refine(&self.style);
934
935 let hitbox = window.insert_hitbox(bounds, HitboxBehavior::Normal);
936
937 // If the width of the list has changed, invalidate all cached item heights
938 if state.last_layout_bounds.map_or(true, |last_bounds| {
939 last_bounds.size.width != bounds.size.width
940 }) {
941 let new_items = SumTree::from_iter(
942 state.items.iter().map(|item| ListItem::Unmeasured {
943 focus_handle: item.focus_handle(),
944 }),
945 &(),
946 );
947
948 state.items = new_items;
949 }
950
951 let padding = style
952 .padding
953 .to_pixels(bounds.size.into(), window.rem_size());
954 let layout = match state.prepaint_items(bounds, padding, true, window, cx) {
955 Ok(layout) => layout,
956 Err(autoscroll_request) => {
957 state.logical_scroll_top = Some(autoscroll_request);
958 state
959 .prepaint_items(bounds, padding, false, window, cx)
960 .unwrap()
961 }
962 };
963
964 state.last_layout_bounds = Some(bounds);
965 state.last_padding = Some(padding);
966 ListPrepaintState { hitbox, layout }
967 }
968
969 fn paint(
970 &mut self,
971 _id: Option<&GlobalElementId>,
972 _inspector_id: Option<&InspectorElementId>,
973 bounds: Bounds<crate::Pixels>,
974 _: &mut Self::RequestLayoutState,
975 prepaint: &mut Self::PrepaintState,
976 window: &mut Window,
977 cx: &mut App,
978 ) {
979 let current_view = window.current_view();
980 window.with_content_mask(Some(ContentMask { bounds }), |window| {
981 for item in &mut prepaint.layout.item_layouts {
982 item.element.paint(window, cx);
983 }
984 });
985
986 let list_state = self.state.clone();
987 let height = bounds.size.height;
988 let scroll_top = prepaint.layout.scroll_top;
989 let hitbox_id = prepaint.hitbox.id;
990 let mut accumulated_scroll_delta = ScrollDelta::default();
991 window.on_mouse_event(move |event: &ScrollWheelEvent, phase, window, cx| {
992 if phase == DispatchPhase::Bubble && hitbox_id.should_handle_scroll(window) {
993 accumulated_scroll_delta = accumulated_scroll_delta.coalesce(event.delta);
994 let pixel_delta = accumulated_scroll_delta.pixel_delta(px(20.));
995 list_state.0.borrow_mut().scroll(
996 &scroll_top,
997 height,
998 pixel_delta,
999 current_view,
1000 window,
1001 cx,
1002 )
1003 }
1004 });
1005 }
1006}
1007
1008impl IntoElement for List {
1009 type Element = Self;
1010
1011 fn into_element(self) -> Self::Element {
1012 self
1013 }
1014}
1015
1016impl Styled for List {
1017 fn style(&mut self) -> &mut StyleRefinement {
1018 &mut self.style
1019 }
1020}
1021
1022impl sum_tree::Item for ListItem {
1023 type Summary = ListItemSummary;
1024
1025 fn summary(&self, _: &()) -> Self::Summary {
1026 match self {
1027 ListItem::Unmeasured { focus_handle } => ListItemSummary {
1028 count: 1,
1029 rendered_count: 0,
1030 unrendered_count: 1,
1031 height: px(0.),
1032 has_focus_handles: focus_handle.is_some(),
1033 },
1034 ListItem::Measured {
1035 size, focus_handle, ..
1036 } => ListItemSummary {
1037 count: 1,
1038 rendered_count: 1,
1039 unrendered_count: 0,
1040 height: size.height,
1041 has_focus_handles: focus_handle.is_some(),
1042 },
1043 }
1044 }
1045}
1046
1047impl sum_tree::Summary for ListItemSummary {
1048 type Context = ();
1049
1050 fn zero(_cx: &()) -> Self {
1051 Default::default()
1052 }
1053
1054 fn add_summary(&mut self, summary: &Self, _: &()) {
1055 self.count += summary.count;
1056 self.rendered_count += summary.rendered_count;
1057 self.unrendered_count += summary.unrendered_count;
1058 self.height += summary.height;
1059 self.has_focus_handles |= summary.has_focus_handles;
1060 }
1061}
1062
1063impl<'a> sum_tree::Dimension<'a, ListItemSummary> for Count {
1064 fn zero(_cx: &()) -> Self {
1065 Default::default()
1066 }
1067
1068 fn add_summary(&mut self, summary: &'a ListItemSummary, _: &()) {
1069 self.0 += summary.count;
1070 }
1071}
1072
1073impl<'a> sum_tree::Dimension<'a, ListItemSummary> for Height {
1074 fn zero(_cx: &()) -> Self {
1075 Default::default()
1076 }
1077
1078 fn add_summary(&mut self, summary: &'a ListItemSummary, _: &()) {
1079 self.0 += summary.height;
1080 }
1081}
1082
1083impl sum_tree::SeekTarget<'_, ListItemSummary, ListItemSummary> for Count {
1084 fn cmp(&self, other: &ListItemSummary, _: &()) -> std::cmp::Ordering {
1085 self.0.partial_cmp(&other.count).unwrap()
1086 }
1087}
1088
1089impl sum_tree::SeekTarget<'_, ListItemSummary, ListItemSummary> for Height {
1090 fn cmp(&self, other: &ListItemSummary, _: &()) -> std::cmp::Ordering {
1091 self.0.partial_cmp(&other.height).unwrap()
1092 }
1093}
1094
1095#[cfg(test)]
1096mod test {
1097
1098 use gpui::{ScrollDelta, ScrollWheelEvent};
1099
1100 use crate::{self as gpui, TestAppContext};
1101
1102 #[gpui::test]
1103 fn test_reset_after_paint_before_scroll(cx: &mut TestAppContext) {
1104 use crate::{
1105 AppContext, Context, Element, IntoElement, ListState, Render, Styled, Window, div,
1106 list, point, px, size,
1107 };
1108
1109 let cx = cx.add_empty_window();
1110
1111 let state = ListState::new(5, crate::ListAlignment::Top, px(10.), |_, _, _| {
1112 div().h(px(10.)).w_full().into_any()
1113 });
1114
1115 // Ensure that the list is scrolled to the top
1116 state.scroll_to(gpui::ListOffset {
1117 item_ix: 0,
1118 offset_in_item: px(0.0),
1119 });
1120
1121 struct TestView(ListState);
1122 impl Render for TestView {
1123 fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1124 list(self.0.clone()).w_full().h_full()
1125 }
1126 }
1127
1128 // Paint
1129 cx.draw(point(px(0.), px(0.)), size(px(100.), px(20.)), |_, cx| {
1130 cx.new(|_| TestView(state.clone()))
1131 });
1132
1133 // Reset
1134 state.reset(5);
1135
1136 // And then receive a scroll event _before_ the next paint
1137 cx.simulate_event(ScrollWheelEvent {
1138 position: point(px(1.), px(1.)),
1139 delta: ScrollDelta::Pixels(point(px(0.), px(-500.))),
1140 ..Default::default()
1141 });
1142
1143 // Scroll position should stay at the top of the list
1144 assert_eq!(state.logical_scroll_top().item_ix, 0);
1145 assert_eq!(state.logical_scroll_top().offset_in_item, px(0.));
1146 }
1147
1148 #[gpui::test]
1149 fn test_scroll_by_positive_and_negative_distance(cx: &mut TestAppContext) {
1150 use crate::{
1151 AppContext, Context, Element, IntoElement, ListState, Render, Styled, Window, div,
1152 list, point, px, size,
1153 };
1154
1155 let cx = cx.add_empty_window();
1156
1157 let state = ListState::new(5, crate::ListAlignment::Top, px(10.), |_, _, _| {
1158 div().h(px(20.)).w_full().into_any()
1159 });
1160
1161 struct TestView(ListState);
1162 impl Render for TestView {
1163 fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1164 list(self.0.clone()).w_full().h_full()
1165 }
1166 }
1167
1168 // Paint
1169 cx.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, cx| {
1170 cx.new(|_| TestView(state.clone()))
1171 });
1172
1173 // Test positive distance: start at item 1, move down 30px
1174 state.scroll_by(px(30.));
1175
1176 // Should move to item 2
1177 let offset = state.logical_scroll_top();
1178 assert_eq!(offset.item_ix, 1);
1179 assert_eq!(offset.offset_in_item, px(10.));
1180
1181 // Test negative distance: start at item 2, move up 30px
1182 state.scroll_by(px(-30.));
1183
1184 // Should move back to item 1
1185 let offset = state.logical_scroll_top();
1186 assert_eq!(offset.item_ix, 0);
1187 assert_eq!(offset.offset_in_item, px(0.));
1188
1189 // Test zero distance
1190 state.scroll_by(px(0.));
1191 let offset = state.logical_scroll_top();
1192 assert_eq!(offset.item_ix, 0);
1193 assert_eq!(offset.offset_in_item, px(0.));
1194 }
1195}