Skip to main content

boltz_gpui/elements/
div.rs

1//! Div is the central, reusable element that most GPUI trees will be built from.
2//! It functions as a container for other elements, and provides a number of
3//! useful features for laying out and styling its children as well as binding
4//! mouse events and action handlers. It is meant to be similar to the HTML `<div>`
5//! element, but for GPUI.
6//!
7//! # Build your own div
8//!
9//! GPUI does not directly provide APIs for stateful, multi step events like `click`
10//! and `drag`. We want GPUI users to be able to build their own abstractions for
11//! their own needs. However, as a UI framework, we're also obliged to provide some
12//! building blocks to make the process of building your own elements easier.
13//! For this we have the [`Interactivity`] and the [`StyleRefinement`] structs, as well
14//! as several associated traits. Together, these provide the full suite of Dom-like events
15//! and Tailwind-like styling that you can use to build your own custom elements. Div is
16//! constructed by combining these two systems into an all-in-one element.
17
18use crate::PinchEvent;
19use crate::{
20    Action, AnyDrag, AnyElement, AnyTooltip, AnyView, App, Bounds, ClickEvent, DispatchPhase,
21    Display, Element, ElementId, Entity, FocusHandle, Global, GlobalElementId, Hitbox,
22    HitboxBehavior, HitboxId, InspectorElementId, IntoElement, IsZero, KeyContext, KeyDownEvent,
23    KeyUpEvent, KeyboardButton, KeyboardClickEvent, LayoutId, ModifiersChangedEvent, MouseButton,
24    MouseClickEvent, MouseDownEvent, MouseMoveEvent, MousePressureEvent, MouseUpEvent, Overflow,
25    ParentElement, Pixels, Point, Render, ScrollWheelEvent, SharedString, Size, Style,
26    StyleRefinement, Styled, Task, TooltipId, Visibility, Window, WindowControlArea, point, px,
27    size,
28};
29use collections::HashMap;
30use gpui_util::ResultExt;
31use refineable::Refineable;
32use smallvec::SmallVec;
33use stacksafe::{StackSafe, stacksafe};
34use std::{
35    any::{Any, TypeId},
36    cell::RefCell,
37    cmp::Ordering,
38    fmt::Debug,
39    marker::PhantomData,
40    mem,
41    rc::Rc,
42    sync::Arc,
43    time::Duration,
44};
45
46use super::ImageCacheProvider;
47
48const DRAG_THRESHOLD: f64 = 2.;
49const TOOLTIP_SHOW_DELAY: Duration = Duration::from_millis(500);
50const HOVERABLE_TOOLTIP_HIDE_DELAY: Duration = Duration::from_millis(500);
51
52/// The styling information for a given group.
53pub struct GroupStyle {
54    /// The identifier for this group.
55    pub group: SharedString,
56
57    /// The specific style refinement that this group would apply
58    /// to its children.
59    pub style: Box<StyleRefinement>,
60}
61
62/// An event for when a drag is moving over this element, with the given state type.
63pub struct DragMoveEvent<T> {
64    /// The mouse move event that triggered this drag move event.
65    pub event: MouseMoveEvent,
66
67    /// The bounds of this element.
68    pub bounds: Bounds<Pixels>,
69    drag: PhantomData<T>,
70    dragged_item: Arc<dyn Any>,
71}
72
73impl<T: 'static> DragMoveEvent<T> {
74    /// Returns the drag state for this event.
75    pub fn drag<'b>(&self, cx: &'b App) -> &'b T {
76        cx.active_drag
77            .as_ref()
78            .and_then(|drag| drag.value.downcast_ref::<T>())
79            .expect("DragMoveEvent is only valid when the stored active drag is of the same type.")
80    }
81
82    /// An item that is about to be dropped.
83    pub fn dragged_item(&self) -> &dyn Any {
84        self.dragged_item.as_ref()
85    }
86}
87
88impl Interactivity {
89    /// Create an `Interactivity`, capturing the caller location in debug mode.
90    #[cfg(any(feature = "inspector", debug_assertions))]
91    #[track_caller]
92    pub fn new() -> Interactivity {
93        Interactivity {
94            source_location: Some(core::panic::Location::caller()),
95            ..Default::default()
96        }
97    }
98
99    /// Create an `Interactivity`, capturing the caller location in debug mode.
100    #[cfg(not(any(feature = "inspector", debug_assertions)))]
101    pub fn new() -> Interactivity {
102        Interactivity::default()
103    }
104
105    /// Gets the source location of construction. Returns `None` when not in debug mode.
106    pub fn source_location(&self) -> Option<&'static std::panic::Location<'static>> {
107        #[cfg(any(feature = "inspector", debug_assertions))]
108        {
109            self.source_location
110        }
111
112        #[cfg(not(any(feature = "inspector", debug_assertions)))]
113        {
114            None
115        }
116    }
117
118    /// Bind the given callback to the mouse down event for the given mouse button, during the bubble phase.
119    /// The imperative API equivalent of [`InteractiveElement::on_mouse_down`].
120    ///
121    /// See [`Context::listener`](crate::Context::listener) to get access to the view state from this callback.
122    pub fn on_mouse_down(
123        &mut self,
124        button: MouseButton,
125        listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
126    ) {
127        self.mouse_down_listeners
128            .push(Box::new(move |event, phase, hitbox, window, cx| {
129                if phase == DispatchPhase::Bubble
130                    && event.button == button
131                    && hitbox.is_hovered(window)
132                {
133                    (listener)(event, window, cx)
134                }
135            }));
136    }
137
138    /// Bind the given callback to the mouse down event for any button, during the capture phase.
139    /// The imperative API equivalent of [`InteractiveElement::capture_any_mouse_down`].
140    ///
141    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
142    pub fn capture_any_mouse_down(
143        &mut self,
144        listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
145    ) {
146        self.mouse_down_listeners
147            .push(Box::new(move |event, phase, hitbox, window, cx| {
148                if phase == DispatchPhase::Capture && hitbox.is_hovered(window) {
149                    (listener)(event, window, cx)
150                }
151            }));
152    }
153
154    /// Bind the given callback to the mouse down event for any button, during the bubble phase.
155    /// The imperative API equivalent to [`InteractiveElement::on_any_mouse_down`].
156    ///
157    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
158    pub fn on_any_mouse_down(
159        &mut self,
160        listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
161    ) {
162        self.mouse_down_listeners
163            .push(Box::new(move |event, phase, hitbox, window, cx| {
164                if phase == DispatchPhase::Bubble && hitbox.is_hovered(window) {
165                    (listener)(event, window, cx)
166                }
167            }));
168    }
169
170    /// Bind the given callback to the mouse pressure event, during the bubble phase
171    /// the imperative API equivalent to [`InteractiveElement::on_mouse_pressure`].
172    ///
173    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
174    pub fn on_mouse_pressure(
175        &mut self,
176        listener: impl Fn(&MousePressureEvent, &mut Window, &mut App) + 'static,
177    ) {
178        self.mouse_pressure_listeners
179            .push(Box::new(move |event, phase, hitbox, window, cx| {
180                if phase == DispatchPhase::Bubble && hitbox.is_hovered(window) {
181                    (listener)(event, window, cx)
182                }
183            }));
184    }
185
186    /// Bind the given callback to the mouse pressure event, during the capture phase
187    /// the imperative API equivalent to [`InteractiveElement::on_mouse_pressure`].
188    ///
189    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
190    pub fn capture_mouse_pressure(
191        &mut self,
192        listener: impl Fn(&MousePressureEvent, &mut Window, &mut App) + 'static,
193    ) {
194        self.mouse_pressure_listeners
195            .push(Box::new(move |event, phase, hitbox, window, cx| {
196                if phase == DispatchPhase::Capture && hitbox.is_hovered(window) {
197                    (listener)(event, window, cx)
198                }
199            }));
200    }
201
202    /// Bind the given callback to the mouse up event for the given button, during the bubble phase.
203    /// The imperative API equivalent to [`InteractiveElement::on_mouse_up`].
204    ///
205    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
206    pub fn on_mouse_up(
207        &mut self,
208        button: MouseButton,
209        listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static,
210    ) {
211        self.mouse_up_listeners
212            .push(Box::new(move |event, phase, hitbox, window, cx| {
213                if phase == DispatchPhase::Bubble
214                    && event.button == button
215                    && hitbox.is_hovered(window)
216                {
217                    (listener)(event, window, cx)
218                }
219            }));
220    }
221
222    /// Bind the given callback to the mouse up event for any button, during the capture phase.
223    /// The imperative API equivalent to [`InteractiveElement::capture_any_mouse_up`].
224    ///
225    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
226    pub fn capture_any_mouse_up(
227        &mut self,
228        listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static,
229    ) {
230        self.mouse_up_listeners
231            .push(Box::new(move |event, phase, hitbox, window, cx| {
232                if phase == DispatchPhase::Capture && hitbox.is_hovered(window) {
233                    (listener)(event, window, cx)
234                }
235            }));
236    }
237
238    /// Bind the given callback to the mouse up event for any button, during the bubble phase.
239    /// The imperative API equivalent to [`Interactivity::on_any_mouse_up`].
240    ///
241    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
242    pub fn on_any_mouse_up(
243        &mut self,
244        listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static,
245    ) {
246        self.mouse_up_listeners
247            .push(Box::new(move |event, phase, hitbox, window, cx| {
248                if phase == DispatchPhase::Bubble && hitbox.is_hovered(window) {
249                    (listener)(event, window, cx)
250                }
251            }));
252    }
253
254    /// Bind the given callback to the mouse down event, on any button, during the capture phase,
255    /// when the mouse is outside of the bounds of this element.
256    /// The imperative API equivalent to [`InteractiveElement::on_mouse_down_out`].
257    ///
258    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
259    pub fn on_mouse_down_out(
260        &mut self,
261        listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
262    ) {
263        self.mouse_down_listeners
264            .push(Box::new(move |event, phase, hitbox, window, cx| {
265                if phase == DispatchPhase::Capture && !hitbox.contains(&window.mouse_position()) {
266                    (listener)(event, window, cx)
267                }
268            }));
269    }
270
271    /// Bind the given callback to the mouse up event, for the given button, during the capture phase,
272    /// when the mouse is outside of the bounds of this element.
273    /// The imperative API equivalent to [`InteractiveElement::on_mouse_up_out`].
274    ///
275    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
276    pub fn on_mouse_up_out(
277        &mut self,
278        button: MouseButton,
279        listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static,
280    ) {
281        self.mouse_up_listeners
282            .push(Box::new(move |event, phase, hitbox, window, cx| {
283                if phase == DispatchPhase::Capture
284                    && event.button == button
285                    && !hitbox.is_hovered(window)
286                {
287                    (listener)(event, window, cx);
288                }
289            }));
290    }
291
292    /// Bind the given callback to the mouse move event, during the bubble phase.
293    /// The imperative API equivalent to [`InteractiveElement::on_mouse_move`].
294    ///
295    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
296    pub fn on_mouse_move(
297        &mut self,
298        listener: impl Fn(&MouseMoveEvent, &mut Window, &mut App) + 'static,
299    ) {
300        self.mouse_move_listeners
301            .push(Box::new(move |event, phase, hitbox, window, cx| {
302                if phase == DispatchPhase::Bubble && hitbox.is_hovered(window) {
303                    (listener)(event, window, cx);
304                }
305            }));
306    }
307
308    /// Bind the given callback to the mouse drag event of the given type. Note that this
309    /// will be called for all move events, inside or outside of this element, as long as the
310    /// drag was started with this element under the mouse. Useful for implementing draggable
311    /// UIs that don't conform to a drag and drop style interaction, like resizing.
312    /// The imperative API equivalent to [`InteractiveElement::on_drag_move`].
313    ///
314    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
315    pub fn on_drag_move<T>(
316        &mut self,
317        listener: impl Fn(&DragMoveEvent<T>, &mut Window, &mut App) + 'static,
318    ) where
319        T: 'static,
320    {
321        self.mouse_move_listeners
322            .push(Box::new(move |event, phase, hitbox, window, cx| {
323                if phase == DispatchPhase::Capture
324                    && let Some(drag) = &cx.active_drag
325                    && drag.value.as_ref().type_id() == TypeId::of::<T>()
326                {
327                    (listener)(
328                        &DragMoveEvent {
329                            event: event.clone(),
330                            bounds: hitbox.bounds,
331                            drag: PhantomData,
332                            dragged_item: Arc::clone(&drag.value),
333                        },
334                        window,
335                        cx,
336                    );
337                }
338            }));
339    }
340
341    /// Bind the given callback to scroll wheel events during the bubble phase.
342    /// The imperative API equivalent to [`InteractiveElement::on_scroll_wheel`].
343    ///
344    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
345    pub fn on_scroll_wheel(
346        &mut self,
347        listener: impl Fn(&ScrollWheelEvent, &mut Window, &mut App) + 'static,
348    ) {
349        self.scroll_wheel_listeners
350            .push(Box::new(move |event, phase, hitbox, window, cx| {
351                if phase == DispatchPhase::Bubble && hitbox.should_handle_scroll(window) {
352                    (listener)(event, window, cx);
353                }
354            }));
355    }
356
357    /// Bind the given callback to pinch gesture events during the bubble phase.
358    ///
359    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
360    pub fn on_pinch(&mut self, listener: impl Fn(&PinchEvent, &mut Window, &mut App) + 'static) {
361        self.pinch_listeners
362            .push(Box::new(move |event, phase, hitbox, window, cx| {
363                if phase == DispatchPhase::Bubble && hitbox.is_hovered(window) {
364                    (listener)(event, window, cx);
365                }
366            }));
367    }
368
369    /// Bind the given callback to pinch gesture events during the capture phase.
370    ///
371    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
372    pub fn capture_pinch(
373        &mut self,
374        listener: impl Fn(&PinchEvent, &mut Window, &mut App) + 'static,
375    ) {
376        self.pinch_listeners
377            .push(Box::new(move |event, phase, _hitbox, window, cx| {
378                if phase == DispatchPhase::Capture {
379                    (listener)(event, window, cx);
380                } else {
381                    cx.propagate();
382                }
383            }));
384    }
385
386    /// Bind the given callback to an action dispatch during the capture phase.
387    /// The imperative API equivalent to [`InteractiveElement::capture_action`].
388    ///
389    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
390    pub fn capture_action<A: Action>(
391        &mut self,
392        listener: impl Fn(&A, &mut Window, &mut App) + 'static,
393    ) {
394        self.action_listeners.push((
395            TypeId::of::<A>(),
396            Box::new(move |action, phase, window, cx| {
397                let action = action.downcast_ref().unwrap();
398                if phase == DispatchPhase::Capture {
399                    (listener)(action, window, cx)
400                } else {
401                    cx.propagate();
402                }
403            }),
404        ));
405    }
406
407    /// Bind the given callback to an action dispatch during the bubble phase.
408    /// The imperative API equivalent to [`InteractiveElement::on_action`].
409    ///
410    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
411    pub fn on_action<A: Action>(&mut self, listener: impl Fn(&A, &mut Window, &mut App) + 'static) {
412        self.action_listeners.push((
413            TypeId::of::<A>(),
414            Box::new(move |action, phase, window, cx| {
415                let action = action.downcast_ref().unwrap();
416                if phase == DispatchPhase::Bubble {
417                    (listener)(action, window, cx)
418                }
419            }),
420        ));
421    }
422
423    /// Bind the given callback to an action dispatch, based on a dynamic action parameter
424    /// instead of a type parameter. Useful for component libraries that want to expose
425    /// action bindings to their users.
426    /// The imperative API equivalent to [`InteractiveElement::on_boxed_action`].
427    ///
428    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
429    pub fn on_boxed_action(
430        &mut self,
431        action: &dyn Action,
432        listener: impl Fn(&dyn Action, &mut Window, &mut App) + 'static,
433    ) {
434        let action = action.boxed_clone();
435        self.action_listeners.push((
436            (*action).type_id(),
437            Box::new(move |_, phase, window, cx| {
438                if phase == DispatchPhase::Bubble {
439                    (listener)(&*action, window, cx)
440                }
441            }),
442        ));
443    }
444
445    /// Bind the given callback to key down events during the bubble phase.
446    /// The imperative API equivalent to [`InteractiveElement::on_key_down`].
447    ///
448    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
449    pub fn on_key_down(
450        &mut self,
451        listener: impl Fn(&KeyDownEvent, &mut Window, &mut App) + 'static,
452    ) {
453        self.key_down_listeners
454            .push(Box::new(move |event, phase, window, cx| {
455                if phase == DispatchPhase::Bubble {
456                    (listener)(event, window, cx)
457                }
458            }));
459    }
460
461    /// Bind the given callback to key down events during the capture phase.
462    /// The imperative API equivalent to [`InteractiveElement::capture_key_down`].
463    ///
464    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
465    pub fn capture_key_down(
466        &mut self,
467        listener: impl Fn(&KeyDownEvent, &mut Window, &mut App) + 'static,
468    ) {
469        self.key_down_listeners
470            .push(Box::new(move |event, phase, window, cx| {
471                if phase == DispatchPhase::Capture {
472                    listener(event, window, cx)
473                }
474            }));
475    }
476
477    /// Bind the given callback to key up events during the bubble phase.
478    /// The imperative API equivalent to [`InteractiveElement::on_key_up`].
479    ///
480    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
481    pub fn on_key_up(&mut self, listener: impl Fn(&KeyUpEvent, &mut Window, &mut App) + 'static) {
482        self.key_up_listeners
483            .push(Box::new(move |event, phase, window, cx| {
484                if phase == DispatchPhase::Bubble {
485                    listener(event, window, cx)
486                }
487            }));
488    }
489
490    /// Bind the given callback to key up events during the capture phase.
491    /// The imperative API equivalent to [`InteractiveElement::on_key_up`].
492    ///
493    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
494    pub fn capture_key_up(
495        &mut self,
496        listener: impl Fn(&KeyUpEvent, &mut Window, &mut App) + 'static,
497    ) {
498        self.key_up_listeners
499            .push(Box::new(move |event, phase, window, cx| {
500                if phase == DispatchPhase::Capture {
501                    listener(event, window, cx)
502                }
503            }));
504    }
505
506    /// Bind the given callback to modifiers changing events.
507    /// The imperative API equivalent to [`InteractiveElement::on_modifiers_changed`].
508    ///
509    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
510    pub fn on_modifiers_changed(
511        &mut self,
512        listener: impl Fn(&ModifiersChangedEvent, &mut Window, &mut App) + 'static,
513    ) {
514        self.modifiers_changed_listeners
515            .push(Box::new(move |event, window, cx| {
516                listener(event, window, cx)
517            }));
518    }
519
520    /// Bind the given callback to drop events of the given type, whether or not the drag started on this element.
521    /// The imperative API equivalent to [`InteractiveElement::on_drop`].
522    ///
523    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
524    pub fn on_drop<T: 'static>(&mut self, listener: impl Fn(&T, &mut Window, &mut App) + 'static) {
525        self.drop_listeners.push((
526            TypeId::of::<T>(),
527            Box::new(move |dragged_value, window, cx| {
528                listener(dragged_value.downcast_ref().unwrap(), window, cx);
529            }),
530        ));
531    }
532
533    /// Use the given predicate to determine whether or not a drop event should be dispatched to this element.
534    /// The imperative API equivalent to [`InteractiveElement::can_drop`].
535    pub fn can_drop(
536        &mut self,
537        predicate: impl Fn(&dyn Any, &mut Window, &mut App) -> bool + 'static,
538    ) {
539        self.can_drop_predicate = Some(Box::new(predicate));
540    }
541
542    /// Bind the given callback to click events of this element.
543    /// The imperative API equivalent to [`StatefulInteractiveElement::on_click`].
544    ///
545    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
546    pub fn on_click(&mut self, listener: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static)
547    where
548        Self: Sized,
549    {
550        self.click_listeners.push(Rc::new(move |event, window, cx| {
551            listener(event, window, cx)
552        }));
553    }
554
555    /// Bind the given callback to non-primary click events of this element.
556    /// The imperative API equivalent to [`StatefulInteractiveElement::on_aux_click`].
557    ///
558    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
559    pub fn on_aux_click(&mut self, listener: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static)
560    where
561        Self: Sized,
562    {
563        self.aux_click_listeners
564            .push(Rc::new(move |event, window, cx| {
565                listener(event, window, cx)
566            }));
567    }
568
569    /// On drag initiation, this callback will be used to create a new view to render the dragged value for a
570    /// drag and drop operation. This API should also be used as the equivalent of 'on drag start' with
571    /// the [`Self::on_drag_move`] API.
572    /// The imperative API equivalent to [`StatefulInteractiveElement::on_drag`].
573    ///
574    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
575    pub fn on_drag<T, W>(
576        &mut self,
577        value: T,
578        constructor: impl Fn(&T, Point<Pixels>, &mut Window, &mut App) -> Entity<W> + 'static,
579    ) where
580        Self: Sized,
581        T: 'static,
582        W: 'static + Render,
583    {
584        debug_assert!(
585            self.drag_listener.is_none(),
586            "calling on_drag more than once on the same element is not supported"
587        );
588        self.drag_listener = Some((
589            Arc::new(value),
590            Box::new(move |value, offset, window, cx| {
591                constructor(value.downcast_ref().unwrap(), offset, window, cx).into()
592            }),
593        ));
594    }
595
596    /// Bind the given callback on the hover start and end events of this element. Note that the boolean
597    /// passed to the callback is true when the hover starts and false when it ends.
598    /// The imperative API equivalent to [`StatefulInteractiveElement::on_hover`].
599    ///
600    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
601    pub fn on_hover(&mut self, listener: impl Fn(&bool, &mut Window, &mut App) + 'static)
602    where
603        Self: Sized,
604    {
605        debug_assert!(
606            self.hover_listener.is_none(),
607            "calling on_hover more than once on the same element is not supported"
608        );
609        self.hover_listener = Some(Box::new(listener));
610    }
611
612    /// Use the given callback to construct a new tooltip view when the mouse hovers over this element.
613    /// The imperative API equivalent to [`StatefulInteractiveElement::tooltip`].
614    pub fn tooltip(&mut self, build_tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static)
615    where
616        Self: Sized,
617    {
618        debug_assert!(
619            self.tooltip_builder.is_none(),
620            "calling tooltip more than once on the same element is not supported"
621        );
622        self.tooltip_builder = Some(TooltipBuilder {
623            build: Rc::new(build_tooltip),
624            hoverable: false,
625        });
626    }
627
628    /// Use the given callback to construct a new tooltip view when the mouse hovers over this element.
629    /// The tooltip itself is also hoverable and won't disappear when the user moves the mouse into
630    /// the tooltip. The imperative API equivalent to [`StatefulInteractiveElement::hoverable_tooltip`].
631    pub fn hoverable_tooltip(
632        &mut self,
633        build_tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static,
634    ) where
635        Self: Sized,
636    {
637        debug_assert!(
638            self.tooltip_builder.is_none(),
639            "calling tooltip more than once on the same element is not supported"
640        );
641        self.tooltip_builder = Some(TooltipBuilder {
642            build: Rc::new(build_tooltip),
643            hoverable: true,
644        });
645    }
646
647    /// Block the mouse from all interactions with elements behind this element's hitbox. Typically
648    /// `block_mouse_except_scroll` should be preferred.
649    ///
650    /// The imperative API equivalent to [`InteractiveElement::occlude`]
651    pub fn occlude_mouse(&mut self) {
652        self.hitbox_behavior = HitboxBehavior::BlockMouse;
653    }
654
655    /// Set the bounds of this element as a window control area for the platform window.
656    /// The imperative API equivalent to [`InteractiveElement::window_control_area`]
657    pub fn window_control_area(&mut self, area: WindowControlArea) {
658        self.window_control = Some(area);
659    }
660
661    /// Block non-scroll mouse interactions with elements behind this element's hitbox.
662    /// The imperative API equivalent to [`InteractiveElement::block_mouse_except_scroll`].
663    ///
664    /// See [`Hitbox::is_hovered`] for details.
665    pub fn block_mouse_except_scroll(&mut self) {
666        self.hitbox_behavior = HitboxBehavior::BlockMouseExceptScroll;
667    }
668
669    fn has_pinch_listeners(&self) -> bool {
670        !self.pinch_listeners.is_empty()
671    }
672}
673
674/// A trait for elements that want to use the standard GPUI event handlers that don't
675/// require any state.
676pub trait InteractiveElement: Sized {
677    /// Retrieve the interactivity state associated with this element
678    fn interactivity(&mut self) -> &mut Interactivity;
679
680    /// Assign this element to a group of elements that can be styled together
681    fn group(mut self, group: impl Into<SharedString>) -> Self {
682        self.interactivity().group = Some(group.into());
683        self
684    }
685
686    /// Assign this element an ID, so that it can be used with interactivity
687    fn id(mut self, id: impl Into<ElementId>) -> Stateful<Self> {
688        self.interactivity().element_id = Some(id.into());
689
690        Stateful { element: self }
691    }
692
693    /// Track the focus state of the given focus handle on this element.
694    /// If the focus handle is focused by the application, this element will
695    /// apply its focused styles.
696    fn track_focus(mut self, focus_handle: &FocusHandle) -> Self {
697        self.interactivity().focusable = true;
698        self.interactivity().tracked_focus_handle = Some(focus_handle.clone());
699        self
700    }
701
702    /// Set whether this element is a tab stop.
703    ///
704    /// When false, the element remains in tab-index order but cannot be reached via keyboard navigation.
705    /// Useful for container elements: focus the container, then call `window.focus_next(cx)` to focus
706    /// the first tab stop inside it while having the container element itself be unreachable via the keyboard.
707    /// Should only be used with `tab_index`.
708    fn tab_stop(mut self, tab_stop: bool) -> Self {
709        self.interactivity().tab_stop = tab_stop;
710        self
711    }
712
713    /// Set index of the tab stop order, and set this node as a tab stop.
714    /// This will default the element to being a tab stop. See [`Self::tab_stop`] for more information.
715    /// This should only be used in conjunction with `tab_group`
716    /// in order to not interfere with the tab index of other elements.
717    fn tab_index(mut self, index: isize) -> Self {
718        self.interactivity().focusable = true;
719        self.interactivity().tab_index = Some(index);
720        self.interactivity().tab_stop = true;
721        self
722    }
723
724    /// Designate this div as a "tab group". Tab groups have their own location in the tab-index order,
725    /// but for children of the tab group, the tab index is reset to 0. This can be useful for swapping
726    /// the order of tab stops within the group, without having to renumber all the tab stops in the whole
727    /// application.
728    fn tab_group(mut self) -> Self {
729        self.interactivity().tab_group = true;
730        if self.interactivity().tab_index.is_none() {
731            self.interactivity().tab_index = Some(0);
732        }
733        self
734    }
735
736    /// Set the keymap context for this element. This will be used to determine
737    /// which action to dispatch from the keymap.
738    fn key_context<C, E>(mut self, key_context: C) -> Self
739    where
740        C: TryInto<KeyContext, Error = E>,
741        E: std::fmt::Display,
742    {
743        if let Some(key_context) = key_context.try_into().log_err() {
744            self.interactivity().key_context = Some(key_context);
745        }
746        self
747    }
748
749    /// Apply the given style to this element when the mouse hovers over it
750    fn hover(mut self, f: impl FnOnce(StyleRefinement) -> StyleRefinement) -> Self {
751        debug_assert!(
752            self.interactivity().hover_style.is_none(),
753            "hover style already set"
754        );
755        self.interactivity().hover_style = Some(Box::new(f(StyleRefinement::default())));
756        self
757    }
758
759    /// Apply the given style to this element when the mouse hovers over a group member
760    fn group_hover(
761        mut self,
762        group_name: impl Into<SharedString>,
763        f: impl FnOnce(StyleRefinement) -> StyleRefinement,
764    ) -> Self {
765        self.interactivity().group_hover_style = Some(GroupStyle {
766            group: group_name.into(),
767            style: Box::new(f(StyleRefinement::default())),
768        });
769        self
770    }
771
772    /// Bind the given callback to the mouse down event for the given mouse button.
773    /// The fluent API equivalent to [`Interactivity::on_mouse_down`].
774    ///
775    /// See [`Context::listener`](crate::Context::listener) to get access to the view state from this callback.
776    fn on_mouse_down(
777        mut self,
778        button: MouseButton,
779        listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
780    ) -> Self {
781        self.interactivity().on_mouse_down(button, listener);
782        self
783    }
784
785    #[cfg(any(test, feature = "test-support"))]
786    /// Set a key that can be used to look up this element's bounds
787    /// in the [`crate::VisualTestContext::debug_bounds`] map
788    /// This is a noop in release builds
789    fn debug_selector(mut self, f: impl FnOnce() -> String) -> Self {
790        self.interactivity().debug_selector = Some(f());
791        self
792    }
793
794    #[cfg(not(any(test, feature = "test-support")))]
795    /// Set a key that can be used to look up this element's bounds
796    /// in the [`crate::VisualTestContext::debug_bounds`] map
797    /// This is a noop in release builds
798    #[inline]
799    fn debug_selector(self, _: impl FnOnce() -> String) -> Self {
800        self
801    }
802
803    /// Bind the given callback to the mouse down event for any button, during the capture phase.
804    /// The fluent API equivalent to [`Interactivity::capture_any_mouse_down`].
805    ///
806    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
807    fn capture_any_mouse_down(
808        mut self,
809        listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
810    ) -> Self {
811        self.interactivity().capture_any_mouse_down(listener);
812        self
813    }
814
815    /// Bind the given callback to the mouse down event for any button, during the capture phase.
816    /// The fluent API equivalent to [`Interactivity::on_any_mouse_down`].
817    ///
818    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
819    fn on_any_mouse_down(
820        mut self,
821        listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
822    ) -> Self {
823        self.interactivity().on_any_mouse_down(listener);
824        self
825    }
826
827    /// Bind the given callback to the mouse up event for the given button, during the bubble phase.
828    /// The fluent API equivalent to [`Interactivity::on_mouse_up`].
829    ///
830    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
831    fn on_mouse_up(
832        mut self,
833        button: MouseButton,
834        listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static,
835    ) -> Self {
836        self.interactivity().on_mouse_up(button, listener);
837        self
838    }
839
840    /// Bind the given callback to the mouse up event for any button, during the capture phase.
841    /// The fluent API equivalent to [`Interactivity::capture_any_mouse_up`].
842    ///
843    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
844    fn capture_any_mouse_up(
845        mut self,
846        listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static,
847    ) -> Self {
848        self.interactivity().capture_any_mouse_up(listener);
849        self
850    }
851
852    /// Bind the given callback to the mouse pressure event, during the bubble phase
853    /// the fluent API equivalent to [`Interactivity::on_mouse_pressure`]
854    ///
855    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
856    fn on_mouse_pressure(
857        mut self,
858        listener: impl Fn(&MousePressureEvent, &mut Window, &mut App) + 'static,
859    ) -> Self {
860        self.interactivity().on_mouse_pressure(listener);
861        self
862    }
863
864    /// Bind the given callback to the mouse pressure event, during the capture phase
865    /// the fluent API equivalent to [`Interactivity::on_mouse_pressure`]
866    ///
867    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
868    fn capture_mouse_pressure(
869        mut self,
870        listener: impl Fn(&MousePressureEvent, &mut Window, &mut App) + 'static,
871    ) -> Self {
872        self.interactivity().capture_mouse_pressure(listener);
873        self
874    }
875
876    /// Bind the given callback to the mouse down event, on any button, during the capture phase,
877    /// when the mouse is outside of the bounds of this element.
878    /// The fluent API equivalent to [`Interactivity::on_mouse_down_out`].
879    ///
880    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
881    fn on_mouse_down_out(
882        mut self,
883        listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
884    ) -> Self {
885        self.interactivity().on_mouse_down_out(listener);
886        self
887    }
888
889    /// Bind the given callback to the mouse up event, for the given button, during the capture phase,
890    /// when the mouse is outside of the bounds of this element.
891    /// The fluent API equivalent to [`Interactivity::on_mouse_up_out`].
892    ///
893    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
894    fn on_mouse_up_out(
895        mut self,
896        button: MouseButton,
897        listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static,
898    ) -> Self {
899        self.interactivity().on_mouse_up_out(button, listener);
900        self
901    }
902
903    /// Bind the given callback to the mouse move event, during the bubble phase.
904    /// The fluent API equivalent to [`Interactivity::on_mouse_move`].
905    ///
906    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
907    fn on_mouse_move(
908        mut self,
909        listener: impl Fn(&MouseMoveEvent, &mut Window, &mut App) + 'static,
910    ) -> Self {
911        self.interactivity().on_mouse_move(listener);
912        self
913    }
914
915    /// Bind the given callback to the mouse drag event of the given type. Note that this
916    /// will be called for all move events, inside or outside of this element, as long as the
917    /// drag was started with this element under the mouse. Useful for implementing draggable
918    /// UIs that don't conform to a drag and drop style interaction, like resizing.
919    /// The fluent API equivalent to [`Interactivity::on_drag_move`].
920    ///
921    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
922    fn on_drag_move<T: 'static>(
923        mut self,
924        listener: impl Fn(&DragMoveEvent<T>, &mut Window, &mut App) + 'static,
925    ) -> Self {
926        self.interactivity().on_drag_move(listener);
927        self
928    }
929
930    /// Bind the given callback to scroll wheel events during the bubble phase.
931    /// The fluent API equivalent to [`Interactivity::on_scroll_wheel`].
932    ///
933    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
934    fn on_scroll_wheel(
935        mut self,
936        listener: impl Fn(&ScrollWheelEvent, &mut Window, &mut App) + 'static,
937    ) -> Self {
938        self.interactivity().on_scroll_wheel(listener);
939        self
940    }
941
942    /// Bind the given callback to pinch gesture events during the bubble phase.
943    /// The fluent API equivalent to [`Interactivity::on_pinch`].
944    ///
945    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
946    fn on_pinch(mut self, listener: impl Fn(&PinchEvent, &mut Window, &mut App) + 'static) -> Self {
947        self.interactivity().on_pinch(listener);
948        self
949    }
950
951    /// Bind the given callback to pinch gesture events during the capture phase.
952    /// The fluent API equivalent to [`Interactivity::capture_pinch`].
953    ///
954    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
955    fn capture_pinch(
956        mut self,
957        listener: impl Fn(&PinchEvent, &mut Window, &mut App) + 'static,
958    ) -> Self {
959        self.interactivity().capture_pinch(listener);
960        self
961    }
962    /// Capture the given action, before normal action dispatch can fire.
963    /// The fluent API equivalent to [`Interactivity::capture_action`].
964    ///
965    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
966    fn capture_action<A: Action>(
967        mut self,
968        listener: impl Fn(&A, &mut Window, &mut App) + 'static,
969    ) -> Self {
970        self.interactivity().capture_action(listener);
971        self
972    }
973
974    /// Bind the given callback to an action dispatch during the bubble phase.
975    /// The fluent API equivalent to [`Interactivity::on_action`].
976    ///
977    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
978    fn on_action<A: Action>(
979        mut self,
980        listener: impl Fn(&A, &mut Window, &mut App) + 'static,
981    ) -> Self {
982        self.interactivity().on_action(listener);
983        self
984    }
985
986    /// Bind the given callback to an action dispatch, based on a dynamic action parameter
987    /// instead of a type parameter. Useful for component libraries that want to expose
988    /// action bindings to their users.
989    /// The fluent API equivalent to [`Interactivity::on_boxed_action`].
990    ///
991    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
992    fn on_boxed_action(
993        mut self,
994        action: &dyn Action,
995        listener: impl Fn(&dyn Action, &mut Window, &mut App) + 'static,
996    ) -> Self {
997        self.interactivity().on_boxed_action(action, listener);
998        self
999    }
1000
1001    /// Bind the given callback to key down events during the bubble phase.
1002    /// The fluent API equivalent to [`Interactivity::on_key_down`].
1003    ///
1004    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1005    fn on_key_down(
1006        mut self,
1007        listener: impl Fn(&KeyDownEvent, &mut Window, &mut App) + 'static,
1008    ) -> Self {
1009        self.interactivity().on_key_down(listener);
1010        self
1011    }
1012
1013    /// Bind the given callback to key down events during the capture phase.
1014    /// The fluent API equivalent to [`Interactivity::capture_key_down`].
1015    ///
1016    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1017    fn capture_key_down(
1018        mut self,
1019        listener: impl Fn(&KeyDownEvent, &mut Window, &mut App) + 'static,
1020    ) -> Self {
1021        self.interactivity().capture_key_down(listener);
1022        self
1023    }
1024
1025    /// Bind the given callback to key up events during the bubble phase.
1026    /// The fluent API equivalent to [`Interactivity::on_key_up`].
1027    ///
1028    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1029    fn on_key_up(
1030        mut self,
1031        listener: impl Fn(&KeyUpEvent, &mut Window, &mut App) + 'static,
1032    ) -> Self {
1033        self.interactivity().on_key_up(listener);
1034        self
1035    }
1036
1037    /// Bind the given callback to key up events during the capture phase.
1038    /// The fluent API equivalent to [`Interactivity::capture_key_up`].
1039    ///
1040    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1041    fn capture_key_up(
1042        mut self,
1043        listener: impl Fn(&KeyUpEvent, &mut Window, &mut App) + 'static,
1044    ) -> Self {
1045        self.interactivity().capture_key_up(listener);
1046        self
1047    }
1048
1049    /// Bind the given callback to modifiers changing events.
1050    /// The fluent API equivalent to [`Interactivity::on_modifiers_changed`].
1051    ///
1052    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1053    fn on_modifiers_changed(
1054        mut self,
1055        listener: impl Fn(&ModifiersChangedEvent, &mut Window, &mut App) + 'static,
1056    ) -> Self {
1057        self.interactivity().on_modifiers_changed(listener);
1058        self
1059    }
1060
1061    /// Apply the given style when the given data type is dragged over this element
1062    fn drag_over<S: 'static>(
1063        mut self,
1064        f: impl 'static + Fn(StyleRefinement, &S, &mut Window, &mut App) -> StyleRefinement,
1065    ) -> Self {
1066        self.interactivity().drag_over_styles.push((
1067            TypeId::of::<S>(),
1068            Box::new(move |currently_dragged: &dyn Any, window, cx| {
1069                f(
1070                    StyleRefinement::default(),
1071                    currently_dragged.downcast_ref::<S>().unwrap(),
1072                    window,
1073                    cx,
1074                )
1075            }),
1076        ));
1077        self
1078    }
1079
1080    /// Apply the given style when the given data type is dragged over this element's group
1081    fn group_drag_over<S: 'static>(
1082        mut self,
1083        group_name: impl Into<SharedString>,
1084        f: impl FnOnce(StyleRefinement) -> StyleRefinement,
1085    ) -> Self {
1086        self.interactivity().group_drag_over_styles.push((
1087            TypeId::of::<S>(),
1088            GroupStyle {
1089                group: group_name.into(),
1090                style: Box::new(f(StyleRefinement::default())),
1091            },
1092        ));
1093        self
1094    }
1095
1096    /// Bind the given callback to drop events of the given type, whether or not the drag started on this element.
1097    /// The fluent API equivalent to [`Interactivity::on_drop`].
1098    ///
1099    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1100    fn on_drop<T: 'static>(
1101        mut self,
1102        listener: impl Fn(&T, &mut Window, &mut App) + 'static,
1103    ) -> Self {
1104        self.interactivity().on_drop(listener);
1105        self
1106    }
1107
1108    /// Use the given predicate to determine whether or not a drop event should be dispatched to this element.
1109    /// The fluent API equivalent to [`Interactivity::can_drop`].
1110    fn can_drop(
1111        mut self,
1112        predicate: impl Fn(&dyn Any, &mut Window, &mut App) -> bool + 'static,
1113    ) -> Self {
1114        self.interactivity().can_drop(predicate);
1115        self
1116    }
1117
1118    /// Block the mouse from all interactions with elements behind this element's hitbox. Typically
1119    /// `block_mouse_except_scroll` should be preferred.
1120    /// The fluent API equivalent to [`Interactivity::occlude_mouse`].
1121    fn occlude(mut self) -> Self {
1122        self.interactivity().occlude_mouse();
1123        self
1124    }
1125
1126    /// Set the bounds of this element as a window control area for the platform window.
1127    /// The fluent API equivalent to [`Interactivity::window_control_area`].
1128    fn window_control_area(mut self, area: WindowControlArea) -> Self {
1129        self.interactivity().window_control_area(area);
1130        self
1131    }
1132
1133    /// Block non-scroll mouse interactions with elements behind this element's hitbox.
1134    /// The fluent API equivalent to [`Interactivity::block_mouse_except_scroll`].
1135    ///
1136    /// See [`Hitbox::is_hovered`] for details.
1137    fn block_mouse_except_scroll(mut self) -> Self {
1138        self.interactivity().block_mouse_except_scroll();
1139        self
1140    }
1141
1142    /// Set the given styles to be applied when this element, specifically, is focused.
1143    /// Requires that the element is focusable. Elements can be made focusable using [`InteractiveElement::track_focus`].
1144    fn focus(mut self, f: impl FnOnce(StyleRefinement) -> StyleRefinement) -> Self
1145    where
1146        Self: Sized,
1147    {
1148        self.interactivity().focus_style = Some(Box::new(f(StyleRefinement::default())));
1149        self
1150    }
1151
1152    /// Set the given styles to be applied when this element is inside another element that is focused.
1153    /// Requires that the element is focusable. Elements can be made focusable using [`InteractiveElement::track_focus`].
1154    fn in_focus(mut self, f: impl FnOnce(StyleRefinement) -> StyleRefinement) -> Self
1155    where
1156        Self: Sized,
1157    {
1158        self.interactivity().in_focus_style = Some(Box::new(f(StyleRefinement::default())));
1159        self
1160    }
1161
1162    /// Set the given styles to be applied when this element is focused via keyboard navigation.
1163    /// This is similar to CSS's `:focus-visible` pseudo-class - it only applies when the element
1164    /// is focused AND the user is navigating via keyboard (not mouse clicks).
1165    /// Requires that the element is focusable. Elements can be made focusable using [`InteractiveElement::track_focus`].
1166    fn focus_visible(mut self, f: impl FnOnce(StyleRefinement) -> StyleRefinement) -> Self
1167    where
1168        Self: Sized,
1169    {
1170        self.interactivity().focus_visible_style = Some(Box::new(f(StyleRefinement::default())));
1171        self
1172    }
1173}
1174
1175/// A trait for elements that want to use the standard GPUI interactivity features
1176/// that require state.
1177pub trait StatefulInteractiveElement: InteractiveElement {
1178    /// Set this element to focusable.
1179    fn focusable(mut self) -> Self {
1180        self.interactivity().focusable = true;
1181        self
1182    }
1183
1184    /// Set the overflow x and y to scroll.
1185    fn overflow_scroll(mut self) -> Self {
1186        self.interactivity().base_style.overflow.x = Some(Overflow::Scroll);
1187        self.interactivity().base_style.overflow.y = Some(Overflow::Scroll);
1188        self
1189    }
1190
1191    /// Set the overflow x to scroll.
1192    fn overflow_x_scroll(mut self) -> Self {
1193        self.interactivity().base_style.overflow.x = Some(Overflow::Scroll);
1194        self
1195    }
1196
1197    /// Set the overflow y to scroll.
1198    fn overflow_y_scroll(mut self) -> Self {
1199        self.interactivity().base_style.overflow.y = Some(Overflow::Scroll);
1200        self
1201    }
1202
1203    /// Track the scroll state of this element with the given handle.
1204    fn track_scroll(mut self, scroll_handle: &ScrollHandle) -> Self {
1205        self.interactivity().tracked_scroll_handle = Some(scroll_handle.clone());
1206        self
1207    }
1208
1209    /// Track the scroll state of this element with the given handle.
1210    fn anchor_scroll(mut self, scroll_anchor: Option<ScrollAnchor>) -> Self {
1211        self.interactivity().scroll_anchor = scroll_anchor;
1212        self
1213    }
1214
1215    /// Set the given styles to be applied when this element is active.
1216    fn active(mut self, f: impl FnOnce(StyleRefinement) -> StyleRefinement) -> Self
1217    where
1218        Self: Sized,
1219    {
1220        self.interactivity().active_style = Some(Box::new(f(StyleRefinement::default())));
1221        self
1222    }
1223
1224    /// Set the given styles to be applied when this element's group is active.
1225    fn group_active(
1226        mut self,
1227        group_name: impl Into<SharedString>,
1228        f: impl FnOnce(StyleRefinement) -> StyleRefinement,
1229    ) -> Self
1230    where
1231        Self: Sized,
1232    {
1233        self.interactivity().group_active_style = Some(GroupStyle {
1234            group: group_name.into(),
1235            style: Box::new(f(StyleRefinement::default())),
1236        });
1237        self
1238    }
1239
1240    /// Bind the given callback to click events of this element.
1241    /// The fluent API equivalent to [`Interactivity::on_click`].
1242    ///
1243    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1244    fn on_click(mut self, listener: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static) -> Self
1245    where
1246        Self: Sized,
1247    {
1248        self.interactivity().on_click(listener);
1249        self
1250    }
1251
1252    /// Bind the given callback to non-primary click events of this element.
1253    /// The fluent API equivalent to [`Interactivity::on_aux_click`].
1254    ///
1255    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1256    fn on_aux_click(
1257        mut self,
1258        listener: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static,
1259    ) -> Self
1260    where
1261        Self: Sized,
1262    {
1263        self.interactivity().on_aux_click(listener);
1264        self
1265    }
1266
1267    /// On drag initiation, this callback will be used to create a new view to render the dragged value for a
1268    /// drag and drop operation. This API should also be used as the equivalent of 'on drag start' with
1269    /// the [`InteractiveElement::on_drag_move`] API.
1270    /// The callback also has access to the offset of triggering click from the origin of parent element.
1271    /// The fluent API equivalent to [`Interactivity::on_drag`].
1272    ///
1273    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1274    fn on_drag<T, W>(
1275        mut self,
1276        value: T,
1277        constructor: impl Fn(&T, Point<Pixels>, &mut Window, &mut App) -> Entity<W> + 'static,
1278    ) -> Self
1279    where
1280        Self: Sized,
1281        T: 'static,
1282        W: 'static + Render,
1283    {
1284        self.interactivity().on_drag(value, constructor);
1285        self
1286    }
1287
1288    /// Bind the given callback on the hover start and end events of this element. Note that the boolean
1289    /// passed to the callback is true when the hover starts and false when it ends.
1290    /// The fluent API equivalent to [`Interactivity::on_hover`].
1291    ///
1292    /// See [`Context::listener`](crate::Context::listener) to get access to a view's state from this callback.
1293    fn on_hover(mut self, listener: impl Fn(&bool, &mut Window, &mut App) + 'static) -> Self
1294    where
1295        Self: Sized,
1296    {
1297        self.interactivity().on_hover(listener);
1298        self
1299    }
1300
1301    /// Use the given callback to construct a new tooltip view when the mouse hovers over this element.
1302    /// The fluent API equivalent to [`Interactivity::tooltip`].
1303    fn tooltip(mut self, build_tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static) -> Self
1304    where
1305        Self: Sized,
1306    {
1307        self.interactivity().tooltip(build_tooltip);
1308        self
1309    }
1310
1311    /// Use the given callback to construct a new tooltip view when the mouse hovers over this element.
1312    /// The tooltip itself is also hoverable and won't disappear when the user moves the mouse into
1313    /// the tooltip. The fluent API equivalent to [`Interactivity::hoverable_tooltip`].
1314    fn hoverable_tooltip(
1315        mut self,
1316        build_tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static,
1317    ) -> Self
1318    where
1319        Self: Sized,
1320    {
1321        self.interactivity().hoverable_tooltip(build_tooltip);
1322        self
1323    }
1324}
1325
1326pub(crate) type MouseDownListener =
1327    Box<dyn Fn(&MouseDownEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static>;
1328pub(crate) type MouseUpListener =
1329    Box<dyn Fn(&MouseUpEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static>;
1330pub(crate) type MousePressureListener =
1331    Box<dyn Fn(&MousePressureEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static>;
1332pub(crate) type MouseMoveListener =
1333    Box<dyn Fn(&MouseMoveEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static>;
1334
1335pub(crate) type ScrollWheelListener =
1336    Box<dyn Fn(&ScrollWheelEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static>;
1337
1338pub(crate) type PinchListener =
1339    Box<dyn Fn(&PinchEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static>;
1340
1341pub(crate) type ClickListener = Rc<dyn Fn(&ClickEvent, &mut Window, &mut App) + 'static>;
1342
1343pub(crate) type DragListener =
1344    Box<dyn Fn(&dyn Any, Point<Pixels>, &mut Window, &mut App) -> AnyView + 'static>;
1345
1346type DropListener = Box<dyn Fn(&dyn Any, &mut Window, &mut App) + 'static>;
1347
1348type CanDropPredicate = Box<dyn Fn(&dyn Any, &mut Window, &mut App) -> bool + 'static>;
1349
1350pub(crate) struct TooltipBuilder {
1351    build: Rc<dyn Fn(&mut Window, &mut App) -> AnyView + 'static>,
1352    hoverable: bool,
1353}
1354
1355pub(crate) type KeyDownListener =
1356    Box<dyn Fn(&KeyDownEvent, DispatchPhase, &mut Window, &mut App) + 'static>;
1357
1358pub(crate) type KeyUpListener =
1359    Box<dyn Fn(&KeyUpEvent, DispatchPhase, &mut Window, &mut App) + 'static>;
1360
1361pub(crate) type ModifiersChangedListener =
1362    Box<dyn Fn(&ModifiersChangedEvent, &mut Window, &mut App) + 'static>;
1363
1364pub(crate) type ActionListener =
1365    Box<dyn Fn(&dyn Any, DispatchPhase, &mut Window, &mut App) + 'static>;
1366
1367/// Construct a new [`Div`] element
1368#[track_caller]
1369pub fn div() -> Div {
1370    Div {
1371        interactivity: Interactivity::new(),
1372        children: SmallVec::default(),
1373        prepaint_listener: None,
1374        image_cache: None,
1375        prepaint_order_fn: None,
1376    }
1377}
1378
1379/// A [`Div`] element, the all-in-one element for building complex UIs in GPUI
1380pub struct Div {
1381    interactivity: Interactivity,
1382    children: SmallVec<[StackSafe<AnyElement>; 2]>,
1383    prepaint_listener: Option<Box<dyn Fn(Vec<Bounds<Pixels>>, &mut Window, &mut App) + 'static>>,
1384    image_cache: Option<Box<dyn ImageCacheProvider>>,
1385    prepaint_order_fn: Option<Box<dyn Fn(&mut Window, &mut App) -> SmallVec<[usize; 8]>>>,
1386}
1387
1388impl Div {
1389    /// Add a listener to be called when the children of this `Div` are prepainted.
1390    /// This allows you to store the [`Bounds`] of the children for later use.
1391    pub fn on_children_prepainted(
1392        mut self,
1393        listener: impl Fn(Vec<Bounds<Pixels>>, &mut Window, &mut App) + 'static,
1394    ) -> Self {
1395        self.prepaint_listener = Some(Box::new(listener));
1396        self
1397    }
1398
1399    /// Add an image cache at the location of this div in the element tree.
1400    pub fn image_cache(mut self, cache: impl ImageCacheProvider) -> Self {
1401        self.image_cache = Some(Box::new(cache));
1402        self
1403    }
1404
1405    /// Specify a function that determines the order in which children are prepainted.
1406    ///
1407    /// The function is called at prepaint time and should return a vector of child indices
1408    /// in the desired prepaint order. Each index should appear exactly once.
1409    ///
1410    /// This is useful when the prepaint of one child affects state that another child reads.
1411    /// For example, in split editor views, the editor with an autoscroll request should
1412    /// be prepainted first so its scroll position update is visible to the other editor.
1413    pub fn with_dynamic_prepaint_order(
1414        mut self,
1415        order_fn: impl Fn(&mut Window, &mut App) -> SmallVec<[usize; 8]> + 'static,
1416    ) -> Self {
1417        self.prepaint_order_fn = Some(Box::new(order_fn));
1418        self
1419    }
1420}
1421
1422/// A frame state for a `Div` element, which contains layout IDs for its children.
1423///
1424/// This struct is used internally by the `Div` element to manage the layout state of its children
1425/// during the UI update cycle. It holds a small vector of `LayoutId` values, each corresponding to
1426/// a child element of the `Div`. These IDs are used to query the layout engine for the computed
1427/// bounds of the children after the layout phase is complete.
1428pub struct DivFrameState {
1429    child_layout_ids: SmallVec<[LayoutId; 2]>,
1430}
1431
1432/// Interactivity state displayed an manipulated in the inspector.
1433#[derive(Clone)]
1434pub struct DivInspectorState {
1435    /// The inspected element's base style. This is used for both inspecting and modifying the
1436    /// state. In the future it will make sense to separate the read and write, possibly tracking
1437    /// the modifications.
1438    #[cfg(any(feature = "inspector", debug_assertions))]
1439    pub base_style: Box<StyleRefinement>,
1440    /// Inspects the bounds of the element.
1441    pub bounds: Bounds<Pixels>,
1442    /// Size of the children of the element, or `bounds.size` if it has no children.
1443    pub content_size: Size<Pixels>,
1444}
1445
1446impl Styled for Div {
1447    fn style(&mut self) -> &mut StyleRefinement {
1448        &mut self.interactivity.base_style
1449    }
1450}
1451
1452impl InteractiveElement for Div {
1453    fn interactivity(&mut self) -> &mut Interactivity {
1454        &mut self.interactivity
1455    }
1456}
1457
1458impl ParentElement for Div {
1459    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
1460        self.children
1461            .extend(elements.into_iter().map(StackSafe::new))
1462    }
1463}
1464
1465impl Element for Div {
1466    type RequestLayoutState = DivFrameState;
1467    type PrepaintState = Option<Hitbox>;
1468
1469    fn id(&self) -> Option<ElementId> {
1470        self.interactivity.element_id.clone()
1471    }
1472
1473    fn source_location(&self) -> Option<&'static std::panic::Location<'static>> {
1474        self.interactivity.source_location()
1475    }
1476
1477    #[stacksafe]
1478    fn request_layout(
1479        &mut self,
1480        global_id: Option<&GlobalElementId>,
1481        inspector_id: Option<&InspectorElementId>,
1482        window: &mut Window,
1483        cx: &mut App,
1484    ) -> (LayoutId, Self::RequestLayoutState) {
1485        let mut child_layout_ids = SmallVec::new();
1486        let image_cache = self
1487            .image_cache
1488            .as_mut()
1489            .map(|provider| provider.provide(window, cx));
1490
1491        let layout_id = window.with_image_cache(image_cache, |window| {
1492            self.interactivity.request_layout(
1493                global_id,
1494                inspector_id,
1495                window,
1496                cx,
1497                |style, window, cx| {
1498                    window.with_text_style(style.text_style().cloned(), |window| {
1499                        child_layout_ids = self
1500                            .children
1501                            .iter_mut()
1502                            .map(|child| child.request_layout(window, cx))
1503                            .collect::<SmallVec<_>>();
1504                        window.request_layout(style, child_layout_ids.iter().copied(), cx)
1505                    })
1506                },
1507            )
1508        });
1509
1510        (layout_id, DivFrameState { child_layout_ids })
1511    }
1512
1513    #[stacksafe]
1514    fn prepaint(
1515        &mut self,
1516        global_id: Option<&GlobalElementId>,
1517        inspector_id: Option<&InspectorElementId>,
1518        bounds: Bounds<Pixels>,
1519        request_layout: &mut Self::RequestLayoutState,
1520        window: &mut Window,
1521        cx: &mut App,
1522    ) -> Option<Hitbox> {
1523        let image_cache = self
1524            .image_cache
1525            .as_mut()
1526            .map(|provider| provider.provide(window, cx));
1527
1528        let has_prepaint_listener = self.prepaint_listener.is_some();
1529        let mut children_bounds = Vec::with_capacity(if has_prepaint_listener {
1530            request_layout.child_layout_ids.len()
1531        } else {
1532            0
1533        });
1534
1535        let mut child_min = point(Pixels::MAX, Pixels::MAX);
1536        let mut child_max = Point::default();
1537        if let Some(handle) = self.interactivity.scroll_anchor.as_ref() {
1538            *handle.last_origin.borrow_mut() = bounds.origin - window.element_offset();
1539        }
1540        let content_size = if request_layout.child_layout_ids.is_empty() {
1541            bounds.size
1542        } else if let Some(scroll_handle) = self.interactivity.tracked_scroll_handle.as_ref() {
1543            let mut state = scroll_handle.0.borrow_mut();
1544            state.child_bounds = Vec::with_capacity(request_layout.child_layout_ids.len());
1545            for child_layout_id in &request_layout.child_layout_ids {
1546                let child_bounds = window.layout_bounds(*child_layout_id);
1547                child_min = child_min.min(&child_bounds.origin);
1548                child_max = child_max.max(&child_bounds.bottom_right());
1549                state.child_bounds.push(child_bounds);
1550            }
1551            (child_max - child_min).into()
1552        } else {
1553            for child_layout_id in &request_layout.child_layout_ids {
1554                let child_bounds = window.layout_bounds(*child_layout_id);
1555                child_min = child_min.min(&child_bounds.origin);
1556                child_max = child_max.max(&child_bounds.bottom_right());
1557
1558                if has_prepaint_listener {
1559                    children_bounds.push(child_bounds);
1560                }
1561            }
1562            (child_max - child_min).into()
1563        };
1564
1565        if let Some(scroll_handle) = self.interactivity.tracked_scroll_handle.as_ref() {
1566            scroll_handle.scroll_to_active_item();
1567        }
1568
1569        self.interactivity.prepaint(
1570            global_id,
1571            inspector_id,
1572            bounds,
1573            content_size,
1574            window,
1575            cx,
1576            |style, scroll_offset, hitbox, window, cx| {
1577                // skip children
1578                if style.display == Display::None {
1579                    return hitbox;
1580                }
1581
1582                window.with_image_cache(image_cache, |window| {
1583                    window.with_element_offset(scroll_offset, |window| {
1584                        if let Some(order_fn) = &self.prepaint_order_fn {
1585                            let order = order_fn(window, cx);
1586                            for idx in order {
1587                                if let Some(child) = self.children.get_mut(idx) {
1588                                    child.prepaint(window, cx);
1589                                }
1590                            }
1591                        } else {
1592                            for child in &mut self.children {
1593                                child.prepaint(window, cx);
1594                            }
1595                        }
1596                    });
1597
1598                    if let Some(listener) = self.prepaint_listener.as_ref() {
1599                        listener(children_bounds, window, cx);
1600                    }
1601                });
1602
1603                hitbox
1604            },
1605        )
1606    }
1607
1608    #[stacksafe]
1609    fn paint(
1610        &mut self,
1611        global_id: Option<&GlobalElementId>,
1612        inspector_id: Option<&InspectorElementId>,
1613        bounds: Bounds<Pixels>,
1614        _request_layout: &mut Self::RequestLayoutState,
1615        hitbox: &mut Option<Hitbox>,
1616        window: &mut Window,
1617        cx: &mut App,
1618    ) {
1619        let image_cache = self
1620            .image_cache
1621            .as_mut()
1622            .map(|provider| provider.provide(window, cx));
1623
1624        window.with_image_cache(image_cache, |window| {
1625            self.interactivity.paint(
1626                global_id,
1627                inspector_id,
1628                bounds,
1629                hitbox.as_ref(),
1630                window,
1631                cx,
1632                |style, window, cx| {
1633                    // skip children
1634                    if style.display == Display::None {
1635                        return;
1636                    }
1637
1638                    for child in &mut self.children {
1639                        child.paint(window, cx);
1640                    }
1641                },
1642            )
1643        });
1644    }
1645}
1646
1647impl IntoElement for Div {
1648    type Element = Self;
1649
1650    fn into_element(self) -> Self::Element {
1651        self
1652    }
1653}
1654
1655/// The interactivity struct. Powers all of the general-purpose
1656/// interactivity in the `Div` element.
1657#[derive(Default)]
1658pub struct Interactivity {
1659    /// The element ID of the element. In id is required to support a stateful subset of the interactivity such as on_click.
1660    pub element_id: Option<ElementId>,
1661    /// Whether the element was clicked. This will only be present after layout.
1662    pub active: Option<bool>,
1663    /// Whether the element was hovered. This will only be present after paint if an hitbox
1664    /// was created for the interactive element.
1665    pub hovered: Option<bool>,
1666    pub(crate) tooltip_id: Option<TooltipId>,
1667    pub(crate) content_size: Size<Pixels>,
1668    pub(crate) key_context: Option<KeyContext>,
1669    pub(crate) focusable: bool,
1670    pub(crate) tracked_focus_handle: Option<FocusHandle>,
1671    pub(crate) tracked_scroll_handle: Option<ScrollHandle>,
1672    pub(crate) scroll_anchor: Option<ScrollAnchor>,
1673    pub(crate) scroll_offset: Option<Rc<RefCell<Point<Pixels>>>>,
1674    pub(crate) group: Option<SharedString>,
1675    /// The base style of the element, before any modifications are applied
1676    /// by focus, active, etc.
1677    pub base_style: Box<StyleRefinement>,
1678    pub(crate) focus_style: Option<Box<StyleRefinement>>,
1679    pub(crate) in_focus_style: Option<Box<StyleRefinement>>,
1680    pub(crate) focus_visible_style: Option<Box<StyleRefinement>>,
1681    pub(crate) hover_style: Option<Box<StyleRefinement>>,
1682    pub(crate) group_hover_style: Option<GroupStyle>,
1683    pub(crate) active_style: Option<Box<StyleRefinement>>,
1684    pub(crate) group_active_style: Option<GroupStyle>,
1685    pub(crate) drag_over_styles: Vec<(
1686        TypeId,
1687        Box<dyn Fn(&dyn Any, &mut Window, &mut App) -> StyleRefinement>,
1688    )>,
1689    pub(crate) group_drag_over_styles: Vec<(TypeId, GroupStyle)>,
1690    pub(crate) mouse_down_listeners: Vec<MouseDownListener>,
1691    pub(crate) mouse_up_listeners: Vec<MouseUpListener>,
1692    pub(crate) mouse_pressure_listeners: Vec<MousePressureListener>,
1693    pub(crate) mouse_move_listeners: Vec<MouseMoveListener>,
1694    pub(crate) scroll_wheel_listeners: Vec<ScrollWheelListener>,
1695    pub(crate) pinch_listeners: Vec<PinchListener>,
1696    pub(crate) key_down_listeners: Vec<KeyDownListener>,
1697    pub(crate) key_up_listeners: Vec<KeyUpListener>,
1698    pub(crate) modifiers_changed_listeners: Vec<ModifiersChangedListener>,
1699    pub(crate) action_listeners: Vec<(TypeId, ActionListener)>,
1700    pub(crate) drop_listeners: Vec<(TypeId, DropListener)>,
1701    pub(crate) can_drop_predicate: Option<CanDropPredicate>,
1702    pub(crate) click_listeners: Vec<ClickListener>,
1703    pub(crate) aux_click_listeners: Vec<ClickListener>,
1704    pub(crate) drag_listener: Option<(Arc<dyn Any>, DragListener)>,
1705    pub(crate) hover_listener: Option<Box<dyn Fn(&bool, &mut Window, &mut App)>>,
1706    pub(crate) tooltip_builder: Option<TooltipBuilder>,
1707    pub(crate) window_control: Option<WindowControlArea>,
1708    pub(crate) hitbox_behavior: HitboxBehavior,
1709    pub(crate) tab_index: Option<isize>,
1710    pub(crate) tab_group: bool,
1711    pub(crate) tab_stop: bool,
1712
1713    #[cfg(any(feature = "inspector", debug_assertions))]
1714    pub(crate) source_location: Option<&'static core::panic::Location<'static>>,
1715
1716    #[cfg(any(test, feature = "test-support"))]
1717    pub(crate) debug_selector: Option<String>,
1718}
1719
1720impl Interactivity {
1721    /// Layout this element according to this interactivity state's configured styles
1722    pub fn request_layout(
1723        &mut self,
1724        global_id: Option<&GlobalElementId>,
1725        _inspector_id: Option<&InspectorElementId>,
1726        window: &mut Window,
1727        cx: &mut App,
1728        f: impl FnOnce(Style, &mut Window, &mut App) -> LayoutId,
1729    ) -> LayoutId {
1730        #[cfg(any(feature = "inspector", debug_assertions))]
1731        window.with_inspector_state(
1732            _inspector_id,
1733            cx,
1734            |inspector_state: &mut Option<DivInspectorState>, _window| {
1735                if let Some(inspector_state) = inspector_state {
1736                    self.base_style = inspector_state.base_style.clone();
1737                } else {
1738                    *inspector_state = Some(DivInspectorState {
1739                        base_style: self.base_style.clone(),
1740                        bounds: Default::default(),
1741                        content_size: Default::default(),
1742                    })
1743                }
1744            },
1745        );
1746
1747        window.with_optional_element_state::<InteractiveElementState, _>(
1748            global_id,
1749            |element_state, window| {
1750                let mut element_state =
1751                    element_state.map(|element_state| element_state.unwrap_or_default());
1752
1753                if let Some(element_state) = element_state.as_ref()
1754                    && cx.has_active_drag()
1755                {
1756                    if let Some(pending_mouse_down) = element_state.pending_mouse_down.as_ref() {
1757                        *pending_mouse_down.borrow_mut() = None;
1758                    }
1759                    if let Some(clicked_state) = element_state.clicked_state.as_ref() {
1760                        *clicked_state.borrow_mut() = ElementClickedState::default();
1761                    }
1762                }
1763
1764                // Ensure we store a focus handle in our element state if we're focusable.
1765                // If there's an explicit focus handle we're tracking, use that. Otherwise
1766                // create a new handle and store it in the element state, which lives for as
1767                // as frames contain an element with this id.
1768                if self.focusable
1769                    && self.tracked_focus_handle.is_none()
1770                    && let Some(element_state) = element_state.as_mut()
1771                {
1772                    let mut handle = element_state
1773                        .focus_handle
1774                        .get_or_insert_with(|| cx.focus_handle())
1775                        .clone()
1776                        .tab_stop(self.tab_stop);
1777
1778                    if let Some(index) = self.tab_index {
1779                        handle = handle.tab_index(index);
1780                    }
1781
1782                    self.tracked_focus_handle = Some(handle);
1783                }
1784
1785                if let Some(scroll_handle) = self.tracked_scroll_handle.as_ref() {
1786                    self.scroll_offset = Some(scroll_handle.0.borrow().offset.clone());
1787                } else if (self.base_style.overflow.x == Some(Overflow::Scroll)
1788                    || self.base_style.overflow.y == Some(Overflow::Scroll))
1789                    && let Some(element_state) = element_state.as_mut()
1790                {
1791                    self.scroll_offset = Some(
1792                        element_state
1793                            .scroll_offset
1794                            .get_or_insert_with(Rc::default)
1795                            .clone(),
1796                    );
1797                }
1798
1799                let style = self.compute_style_internal(None, element_state.as_mut(), window, cx);
1800                let layout_id = f(style, window, cx);
1801                (layout_id, element_state)
1802            },
1803        )
1804    }
1805
1806    /// Commit the bounds of this element according to this interactivity state's configured styles.
1807    pub fn prepaint<R>(
1808        &mut self,
1809        global_id: Option<&GlobalElementId>,
1810        _inspector_id: Option<&InspectorElementId>,
1811        bounds: Bounds<Pixels>,
1812        content_size: Size<Pixels>,
1813        window: &mut Window,
1814        cx: &mut App,
1815        f: impl FnOnce(&Style, Point<Pixels>, Option<Hitbox>, &mut Window, &mut App) -> R,
1816    ) -> R {
1817        self.content_size = content_size;
1818
1819        #[cfg(any(feature = "inspector", debug_assertions))]
1820        window.with_inspector_state(
1821            _inspector_id,
1822            cx,
1823            |inspector_state: &mut Option<DivInspectorState>, _window| {
1824                if let Some(inspector_state) = inspector_state {
1825                    inspector_state.bounds = bounds;
1826                    inspector_state.content_size = content_size;
1827                }
1828            },
1829        );
1830
1831        if let Some(focus_handle) = self.tracked_focus_handle.as_ref() {
1832            window.set_focus_handle(focus_handle, cx);
1833        }
1834        window.with_optional_element_state::<InteractiveElementState, _>(
1835            global_id,
1836            |element_state, window| {
1837                let mut element_state =
1838                    element_state.map(|element_state| element_state.unwrap_or_default());
1839                let style = self.compute_style_internal(None, element_state.as_mut(), window, cx);
1840
1841                if let Some(element_state) = element_state.as_mut() {
1842                    if let Some(clicked_state) = element_state.clicked_state.as_ref() {
1843                        let clicked_state = clicked_state.borrow();
1844                        self.active = Some(clicked_state.element);
1845                    }
1846                    if self.hover_style.is_some() || self.group_hover_style.is_some() {
1847                        element_state
1848                            .hover_state
1849                            .get_or_insert_with(Default::default);
1850                    }
1851                    if let Some(active_tooltip) = element_state.active_tooltip.as_ref() {
1852                        if self.tooltip_builder.is_some() {
1853                            self.tooltip_id = set_tooltip_on_window(active_tooltip, window);
1854                        } else {
1855                            // If there is no longer a tooltip builder, remove the active tooltip.
1856                            element_state.active_tooltip.take();
1857                        }
1858                    }
1859                }
1860
1861                window.with_text_style(style.text_style().cloned(), |window| {
1862                    window.with_content_mask(
1863                        style.overflow_mask(bounds, window.rem_size()),
1864                        |window| {
1865                            let hitbox = if self.should_insert_hitbox(&style, window, cx) {
1866                                Some(window.insert_hitbox(bounds, self.hitbox_behavior))
1867                            } else {
1868                                None
1869                            };
1870
1871                            let scroll_offset =
1872                                self.clamp_scroll_position(bounds, &style, window, cx);
1873                            let result = f(&style, scroll_offset, hitbox, window, cx);
1874                            (result, element_state)
1875                        },
1876                    )
1877                })
1878            },
1879        )
1880    }
1881
1882    fn should_insert_hitbox(&self, style: &Style, window: &Window, cx: &App) -> bool {
1883        self.hitbox_behavior != HitboxBehavior::Normal
1884            || self.window_control.is_some()
1885            || style.mouse_cursor.is_some()
1886            || self.group.is_some()
1887            || self.scroll_offset.is_some()
1888            || self.tracked_focus_handle.is_some()
1889            || self.hover_style.is_some()
1890            || self.group_hover_style.is_some()
1891            || self.hover_listener.is_some()
1892            || !self.mouse_up_listeners.is_empty()
1893            || !self.mouse_pressure_listeners.is_empty()
1894            || !self.mouse_down_listeners.is_empty()
1895            || !self.mouse_move_listeners.is_empty()
1896            || !self.click_listeners.is_empty()
1897            || !self.aux_click_listeners.is_empty()
1898            || !self.scroll_wheel_listeners.is_empty()
1899            || self.has_pinch_listeners()
1900            || self.drag_listener.is_some()
1901            || !self.drop_listeners.is_empty()
1902            || self.tooltip_builder.is_some()
1903            || window.is_inspector_picking(cx)
1904    }
1905
1906    fn clamp_scroll_position(
1907        &self,
1908        bounds: Bounds<Pixels>,
1909        style: &Style,
1910        window: &mut Window,
1911        _cx: &mut App,
1912    ) -> Point<Pixels> {
1913        fn round_to_two_decimals(pixels: Pixels) -> Pixels {
1914            const ROUNDING_FACTOR: f32 = 100.0;
1915            (pixels * ROUNDING_FACTOR).round() / ROUNDING_FACTOR
1916        }
1917
1918        if let Some(scroll_offset) = self.scroll_offset.as_ref() {
1919            let mut scroll_to_bottom = false;
1920            let mut tracked_scroll_handle = self
1921                .tracked_scroll_handle
1922                .as_ref()
1923                .map(|handle| handle.0.borrow_mut());
1924            if let Some(mut scroll_handle_state) = tracked_scroll_handle.as_deref_mut() {
1925                scroll_handle_state.overflow = style.overflow;
1926                scroll_to_bottom = mem::take(&mut scroll_handle_state.scroll_to_bottom);
1927            }
1928
1929            let rem_size = window.rem_size();
1930            let padding = style.padding.to_pixels(bounds.size.into(), rem_size);
1931            let padding_size = size(padding.left + padding.right, padding.top + padding.bottom);
1932            // The floating point values produced by Taffy and ours often vary
1933            // slightly after ~5 decimal places. This can lead to cases where after
1934            // subtracting these, the container becomes scrollable for less than
1935            // 0.00000x pixels. As we generally don't benefit from a precision that
1936            // high for the maximum scroll, we round the scroll max to 2 decimal
1937            // places here.
1938            let padded_content_size = self.content_size + padding_size;
1939            let scroll_max = Point::from(padded_content_size - bounds.size)
1940                .map(round_to_two_decimals)
1941                .max(&Default::default());
1942            // Clamp scroll offset in case scroll max is smaller now (e.g., if children
1943            // were removed or the bounds became larger).
1944            let mut scroll_offset = scroll_offset.borrow_mut();
1945
1946            scroll_offset.x = scroll_offset.x.clamp(-scroll_max.x, px(0.));
1947            if scroll_to_bottom {
1948                scroll_offset.y = -scroll_max.y;
1949            } else {
1950                scroll_offset.y = scroll_offset.y.clamp(-scroll_max.y, px(0.));
1951            }
1952
1953            if let Some(mut scroll_handle_state) = tracked_scroll_handle {
1954                scroll_handle_state.max_offset = scroll_max;
1955                scroll_handle_state.bounds = bounds;
1956            }
1957
1958            *scroll_offset
1959        } else {
1960            Point::default()
1961        }
1962    }
1963
1964    /// Paint this element according to this interactivity state's configured styles
1965    /// and bind the element's mouse and keyboard events.
1966    ///
1967    /// content_size is the size of the content of the element, which may be larger than the
1968    /// element's bounds if the element is scrollable.
1969    ///
1970    /// the final computed style will be passed to the provided function, along
1971    /// with the current scroll offset
1972    pub fn paint(
1973        &mut self,
1974        global_id: Option<&GlobalElementId>,
1975        _inspector_id: Option<&InspectorElementId>,
1976        bounds: Bounds<Pixels>,
1977        hitbox: Option<&Hitbox>,
1978        window: &mut Window,
1979        cx: &mut App,
1980        f: impl FnOnce(&Style, &mut Window, &mut App),
1981    ) {
1982        self.hovered = hitbox.map(|hitbox| hitbox.is_hovered(window));
1983        window.with_optional_element_state::<InteractiveElementState, _>(
1984            global_id,
1985            |element_state, window| {
1986                let mut element_state =
1987                    element_state.map(|element_state| element_state.unwrap_or_default());
1988
1989                let style = self.compute_style_internal(hitbox, element_state.as_mut(), window, cx);
1990
1991                #[cfg(any(feature = "test-support", test))]
1992                if let Some(debug_selector) = &self.debug_selector {
1993                    window
1994                        .next_frame
1995                        .debug_bounds
1996                        .insert(debug_selector.clone(), bounds);
1997                }
1998
1999                self.paint_hover_group_handler(window, cx);
2000
2001                if style.visibility == Visibility::Hidden {
2002                    return ((), element_state);
2003                }
2004
2005                let mut tab_group = None;
2006                if self.tab_group {
2007                    tab_group = self.tab_index;
2008                }
2009                if let Some(focus_handle) = &self.tracked_focus_handle {
2010                    window.next_frame.tab_stops.insert(focus_handle);
2011                }
2012
2013                window.with_element_opacity(style.opacity, |window| {
2014                    style.paint(bounds, window, cx, |window: &mut Window, cx: &mut App| {
2015                        window.with_text_style(style.text_style().cloned(), |window| {
2016                            window.with_content_mask(
2017                                style.overflow_mask(bounds, window.rem_size()),
2018                                |window| {
2019                                    window.with_tab_group(tab_group, |window| {
2020                                        if let Some(hitbox) = hitbox {
2021                                            #[cfg(debug_assertions)]
2022                                            self.paint_debug_info(
2023                                                global_id, hitbox, &style, window, cx,
2024                                            );
2025
2026                                            if let Some(drag) = cx.active_drag.as_ref() {
2027                                                if let Some(mouse_cursor) = drag.cursor_style {
2028                                                    window.set_window_cursor_style(mouse_cursor);
2029                                                }
2030                                            } else {
2031                                                if let Some(mouse_cursor) = style.mouse_cursor {
2032                                                    window.set_cursor_style(mouse_cursor, hitbox);
2033                                                }
2034                                            }
2035
2036                                            if let Some(group) = self.group.clone() {
2037                                                GroupHitboxes::push(group, hitbox.id, cx);
2038                                            }
2039
2040                                            if let Some(area) = self.window_control {
2041                                                window.insert_window_control_hitbox(
2042                                                    area,
2043                                                    hitbox.clone(),
2044                                                );
2045                                            }
2046
2047                                            self.paint_mouse_listeners(
2048                                                hitbox,
2049                                                element_state.as_mut(),
2050                                                window,
2051                                                cx,
2052                                            );
2053                                            self.paint_scroll_listener(hitbox, &style, window, cx);
2054                                        }
2055
2056                                        self.paint_keyboard_listeners(window, cx);
2057                                        f(&style, window, cx);
2058
2059                                        if let Some(_hitbox) = hitbox {
2060                                            #[cfg(any(feature = "inspector", debug_assertions))]
2061                                            window.insert_inspector_hitbox(
2062                                                _hitbox.id,
2063                                                _inspector_id,
2064                                                cx,
2065                                            );
2066
2067                                            if let Some(group) = self.group.as_ref() {
2068                                                GroupHitboxes::pop(group, cx);
2069                                            }
2070                                        }
2071                                    })
2072                                },
2073                            );
2074                        });
2075                    });
2076                });
2077
2078                ((), element_state)
2079            },
2080        );
2081    }
2082
2083    #[cfg(debug_assertions)]
2084    fn paint_debug_info(
2085        &self,
2086        global_id: Option<&GlobalElementId>,
2087        hitbox: &Hitbox,
2088        style: &Style,
2089        window: &mut Window,
2090        cx: &mut App,
2091    ) {
2092        use crate::{BorderStyle, TextAlign};
2093
2094        if let Some(global_id) = global_id
2095            && (style.debug || style.debug_below || cx.has_global::<crate::DebugBelow>())
2096            && hitbox.is_hovered(window)
2097        {
2098            const FONT_SIZE: crate::Pixels = crate::Pixels(10.);
2099            let element_id = format!("{global_id:?}");
2100            let str_len = element_id.len();
2101
2102            let render_debug_text = |window: &mut Window| {
2103                if let Some(text) = window
2104                    .text_system()
2105                    .shape_text(
2106                        element_id.into(),
2107                        FONT_SIZE,
2108                        &[window.text_style().to_run(str_len)],
2109                        None,
2110                        None,
2111                    )
2112                    .ok()
2113                    .and_then(|mut text| text.pop())
2114                {
2115                    text.paint(hitbox.origin, FONT_SIZE, TextAlign::Left, None, window, cx)
2116                        .ok();
2117
2118                    let text_bounds = crate::Bounds {
2119                        origin: hitbox.origin,
2120                        size: text.size(FONT_SIZE),
2121                    };
2122                    if let Some(source_location) = self.source_location
2123                        && text_bounds.contains(&window.mouse_position())
2124                        && window.modifiers().secondary()
2125                    {
2126                        let secondary_held = window.modifiers().secondary();
2127                        window.on_key_event({
2128                            move |e: &crate::ModifiersChangedEvent, _phase, window, _cx| {
2129                                if e.modifiers.secondary() != secondary_held
2130                                    && text_bounds.contains(&window.mouse_position())
2131                                {
2132                                    window.refresh();
2133                                }
2134                            }
2135                        });
2136
2137                        let was_hovered = hitbox.is_hovered(window);
2138                        let current_view = window.current_view();
2139                        window.on_mouse_event({
2140                            let hitbox = hitbox.clone();
2141                            move |_: &MouseMoveEvent, phase, window, cx| {
2142                                if phase == DispatchPhase::Capture {
2143                                    let hovered = hitbox.is_hovered(window);
2144                                    if hovered != was_hovered {
2145                                        cx.notify(current_view)
2146                                    }
2147                                }
2148                            }
2149                        });
2150
2151                        window.on_mouse_event({
2152                            let hitbox = hitbox.clone();
2153                            move |e: &crate::MouseDownEvent, phase, window, cx| {
2154                                if text_bounds.contains(&e.position)
2155                                    && phase.capture()
2156                                    && hitbox.is_hovered(window)
2157                                {
2158                                    cx.stop_propagation();
2159                                    let Ok(dir) = std::env::current_dir() else {
2160                                        return;
2161                                    };
2162
2163                                    eprintln!(
2164                                        "This element was created at:\n{}:{}:{}",
2165                                        dir.join(source_location.file()).to_string_lossy(),
2166                                        source_location.line(),
2167                                        source_location.column()
2168                                    );
2169                                }
2170                            }
2171                        });
2172                        window.paint_quad(crate::outline(
2173                            crate::Bounds {
2174                                origin: hitbox.origin
2175                                    + crate::point(crate::px(0.), FONT_SIZE - px(2.)),
2176                                size: crate::Size {
2177                                    width: text_bounds.size.width,
2178                                    height: crate::px(1.),
2179                                },
2180                            },
2181                            crate::red(),
2182                            BorderStyle::default(),
2183                        ))
2184                    }
2185                }
2186            };
2187
2188            window.with_text_style(
2189                Some(crate::TextStyleRefinement {
2190                    color: Some(crate::red()),
2191                    line_height: Some(FONT_SIZE.into()),
2192                    background_color: Some(crate::white()),
2193                    ..Default::default()
2194                }),
2195                render_debug_text,
2196            )
2197        }
2198    }
2199
2200    fn paint_mouse_listeners(
2201        &mut self,
2202        hitbox: &Hitbox,
2203        element_state: Option<&mut InteractiveElementState>,
2204        window: &mut Window,
2205        cx: &mut App,
2206    ) {
2207        let is_focused = self
2208            .tracked_focus_handle
2209            .as_ref()
2210            .map(|handle| handle.is_focused(window))
2211            .unwrap_or(false);
2212
2213        // If this element can be focused, register a mouse down listener
2214        // that will automatically transfer focus when hitting the element.
2215        // This behavior can be suppressed by using `cx.prevent_default()`.
2216        if let Some(focus_handle) = self.tracked_focus_handle.clone() {
2217            let hitbox = hitbox.clone();
2218            window.on_mouse_event(move |_: &MouseDownEvent, phase, window, cx| {
2219                if phase == DispatchPhase::Bubble
2220                    && hitbox.is_hovered(window)
2221                    && !window.default_prevented()
2222                {
2223                    window.focus(&focus_handle, cx);
2224                    // If there is a parent that is also focusable, prevent it
2225                    // from transferring focus because we already did so.
2226                    window.prevent_default();
2227                }
2228            });
2229        }
2230
2231        for listener in self.mouse_down_listeners.drain(..) {
2232            let hitbox = hitbox.clone();
2233            window.on_mouse_event(move |event: &MouseDownEvent, phase, window, cx| {
2234                listener(event, phase, &hitbox, window, cx);
2235            })
2236        }
2237
2238        for listener in self.mouse_up_listeners.drain(..) {
2239            let hitbox = hitbox.clone();
2240            window.on_mouse_event(move |event: &MouseUpEvent, phase, window, cx| {
2241                listener(event, phase, &hitbox, window, cx);
2242            })
2243        }
2244
2245        for listener in self.mouse_pressure_listeners.drain(..) {
2246            let hitbox = hitbox.clone();
2247            window.on_mouse_event(move |event: &MousePressureEvent, phase, window, cx| {
2248                listener(event, phase, &hitbox, window, cx);
2249            })
2250        }
2251
2252        for listener in self.mouse_move_listeners.drain(..) {
2253            let hitbox = hitbox.clone();
2254            window.on_mouse_event(move |event: &MouseMoveEvent, phase, window, cx| {
2255                listener(event, phase, &hitbox, window, cx);
2256            })
2257        }
2258
2259        for listener in self.scroll_wheel_listeners.drain(..) {
2260            let hitbox = hitbox.clone();
2261            window.on_mouse_event(move |event: &ScrollWheelEvent, phase, window, cx| {
2262                listener(event, phase, &hitbox, window, cx);
2263            })
2264        }
2265
2266        for listener in self.pinch_listeners.drain(..) {
2267            let hitbox = hitbox.clone();
2268            window.on_mouse_event(move |event: &PinchEvent, phase, window, cx| {
2269                listener(event, phase, &hitbox, window, cx);
2270            })
2271        }
2272
2273        if self.hover_style.is_some()
2274            || self.base_style.mouse_cursor.is_some()
2275            || cx.active_drag.is_some() && !self.drag_over_styles.is_empty()
2276        {
2277            let hitbox = hitbox.clone();
2278            let hover_state = self.hover_style.as_ref().and_then(|_| {
2279                element_state
2280                    .as_ref()
2281                    .and_then(|state| state.hover_state.as_ref())
2282                    .cloned()
2283            });
2284            let current_view = window.current_view();
2285
2286            window.on_mouse_event(move |_: &MouseMoveEvent, phase, window, cx| {
2287                let hovered = hitbox.is_hovered(window);
2288                let was_hovered = hover_state
2289                    .as_ref()
2290                    .is_some_and(|state| state.borrow().element);
2291                if phase == DispatchPhase::Capture && hovered != was_hovered {
2292                    if let Some(hover_state) = &hover_state {
2293                        hover_state.borrow_mut().element = hovered;
2294                        cx.notify(current_view);
2295                    }
2296                }
2297            });
2298        }
2299
2300        if let Some(group_hover) = self.group_hover_style.as_ref() {
2301            if let Some(group_hitbox_id) = GroupHitboxes::get(&group_hover.group, cx) {
2302                let hover_state = element_state
2303                    .as_ref()
2304                    .and_then(|element| element.hover_state.as_ref())
2305                    .cloned();
2306                let current_view = window.current_view();
2307
2308                window.on_mouse_event(move |_: &MouseMoveEvent, phase, window, cx| {
2309                    let group_hovered = group_hitbox_id.is_hovered(window);
2310                    let was_group_hovered = hover_state
2311                        .as_ref()
2312                        .is_some_and(|state| state.borrow().group);
2313                    if phase == DispatchPhase::Capture && group_hovered != was_group_hovered {
2314                        if let Some(hover_state) = &hover_state {
2315                            hover_state.borrow_mut().group = group_hovered;
2316                        }
2317                        cx.notify(current_view);
2318                    }
2319                });
2320            }
2321        }
2322
2323        let drag_cursor_style = self.base_style.as_ref().mouse_cursor;
2324
2325        let mut drag_listener = mem::take(&mut self.drag_listener);
2326        let drop_listeners = mem::take(&mut self.drop_listeners);
2327        let click_listeners = mem::take(&mut self.click_listeners);
2328        let aux_click_listeners = mem::take(&mut self.aux_click_listeners);
2329        let can_drop_predicate = mem::take(&mut self.can_drop_predicate);
2330
2331        if !drop_listeners.is_empty() {
2332            let hitbox = hitbox.clone();
2333            window.on_mouse_event({
2334                move |_: &MouseUpEvent, phase, window, cx| {
2335                    if let Some(drag) = &cx.active_drag
2336                        && phase == DispatchPhase::Bubble
2337                        && hitbox.is_hovered(window)
2338                    {
2339                        let drag_state_type = drag.value.as_ref().type_id();
2340                        for (drop_state_type, listener) in &drop_listeners {
2341                            if *drop_state_type == drag_state_type {
2342                                let drag = cx
2343                                    .active_drag
2344                                    .take()
2345                                    .expect("checked for type drag state type above");
2346
2347                                let mut can_drop = true;
2348                                if let Some(predicate) = &can_drop_predicate {
2349                                    can_drop = predicate(drag.value.as_ref(), window, cx);
2350                                }
2351
2352                                if can_drop {
2353                                    listener(drag.value.as_ref(), window, cx);
2354                                    window.refresh();
2355                                    cx.stop_propagation();
2356                                }
2357                            }
2358                        }
2359                    }
2360                }
2361            });
2362        }
2363
2364        if let Some(element_state) = element_state {
2365            if !click_listeners.is_empty()
2366                || !aux_click_listeners.is_empty()
2367                || drag_listener.is_some()
2368            {
2369                let pending_mouse_down = element_state
2370                    .pending_mouse_down
2371                    .get_or_insert_with(Default::default)
2372                    .clone();
2373
2374                let clicked_state = element_state
2375                    .clicked_state
2376                    .get_or_insert_with(Default::default)
2377                    .clone();
2378
2379                window.on_mouse_event({
2380                    let pending_mouse_down = pending_mouse_down.clone();
2381                    let hitbox = hitbox.clone();
2382                    let has_aux_click_listeners = !aux_click_listeners.is_empty();
2383                    move |event: &MouseDownEvent, phase, window, _cx| {
2384                        if phase == DispatchPhase::Bubble
2385                            && (event.button == MouseButton::Left || has_aux_click_listeners)
2386                            && hitbox.is_hovered(window)
2387                        {
2388                            *pending_mouse_down.borrow_mut() = Some(event.clone());
2389                            window.refresh();
2390                        }
2391                    }
2392                });
2393
2394                window.on_mouse_event({
2395                    let pending_mouse_down = pending_mouse_down.clone();
2396                    let hitbox = hitbox.clone();
2397                    move |event: &MouseMoveEvent, phase, window, cx| {
2398                        if phase == DispatchPhase::Capture {
2399                            return;
2400                        }
2401
2402                        let mut pending_mouse_down = pending_mouse_down.borrow_mut();
2403                        if let Some(mouse_down) = pending_mouse_down.clone()
2404                            && !cx.has_active_drag()
2405                            && (event.position - mouse_down.position).magnitude() > DRAG_THRESHOLD
2406                            && let Some((drag_value, drag_listener)) = drag_listener.take()
2407                            && mouse_down.button == MouseButton::Left
2408                        {
2409                            *clicked_state.borrow_mut() = ElementClickedState::default();
2410                            let cursor_offset = event.position - hitbox.origin;
2411                            let drag =
2412                                (drag_listener)(drag_value.as_ref(), cursor_offset, window, cx);
2413                            cx.active_drag = Some(AnyDrag {
2414                                view: drag,
2415                                value: drag_value,
2416                                cursor_offset,
2417                                cursor_style: drag_cursor_style,
2418                            });
2419                            pending_mouse_down.take();
2420                            window.refresh();
2421                            cx.stop_propagation();
2422                        }
2423                    }
2424                });
2425
2426                if is_focused {
2427                    // Press enter, space to trigger click, when the element is focused.
2428                    window.on_key_event({
2429                        let click_listeners = click_listeners.clone();
2430                        let hitbox = hitbox.clone();
2431                        move |event: &KeyUpEvent, phase, window, cx| {
2432                            if phase.bubble() && !window.default_prevented() {
2433                                let stroke = &event.keystroke;
2434                                let keyboard_button = if stroke.key.eq("enter") {
2435                                    Some(KeyboardButton::Enter)
2436                                } else if stroke.key.eq("space") {
2437                                    Some(KeyboardButton::Space)
2438                                } else {
2439                                    None
2440                                };
2441
2442                                if let Some(button) = keyboard_button
2443                                    && !stroke.modifiers.modified()
2444                                {
2445                                    let click_event = ClickEvent::Keyboard(KeyboardClickEvent {
2446                                        button,
2447                                        bounds: hitbox.bounds,
2448                                    });
2449
2450                                    for listener in &click_listeners {
2451                                        listener(&click_event, window, cx);
2452                                    }
2453                                }
2454                            }
2455                        }
2456                    });
2457                }
2458
2459                window.on_mouse_event({
2460                    let mut captured_mouse_down = None;
2461                    let hitbox = hitbox.clone();
2462                    move |event: &MouseUpEvent, phase, window, cx| match phase {
2463                        // Clear the pending mouse down during the capture phase,
2464                        // so that it happens even if another event handler stops
2465                        // propagation.
2466                        DispatchPhase::Capture => {
2467                            let mut pending_mouse_down = pending_mouse_down.borrow_mut();
2468                            if pending_mouse_down.is_some() && hitbox.is_hovered(window) {
2469                                captured_mouse_down = pending_mouse_down.take();
2470                                window.refresh();
2471                            } else if pending_mouse_down.is_some() {
2472                                // Clear the pending mouse down event (without firing click handlers)
2473                                // if the hitbox is not being hovered.
2474                                // This avoids dragging elements that changed their position
2475                                // immediately after being clicked.
2476                                pending_mouse_down.take();
2477                                window.refresh();
2478                            }
2479                        }
2480                        // Fire click handlers during the bubble phase.
2481                        DispatchPhase::Bubble => {
2482                            if let Some(mouse_down) = captured_mouse_down.take() {
2483                                let btn = mouse_down.button;
2484
2485                                let mouse_click = ClickEvent::Mouse(MouseClickEvent {
2486                                    down: mouse_down,
2487                                    up: event.clone(),
2488                                });
2489
2490                                match btn {
2491                                    MouseButton::Left => {
2492                                        for listener in &click_listeners {
2493                                            listener(&mouse_click, window, cx);
2494                                        }
2495                                    }
2496                                    _ => {
2497                                        for listener in &aux_click_listeners {
2498                                            listener(&mouse_click, window, cx);
2499                                        }
2500                                    }
2501                                }
2502                            }
2503                        }
2504                    }
2505                });
2506            }
2507
2508            if let Some(hover_listener) = self.hover_listener.take() {
2509                let hitbox = hitbox.clone();
2510                let was_hovered = element_state
2511                    .hover_listener_state
2512                    .get_or_insert_with(Default::default)
2513                    .clone();
2514                let has_mouse_down = element_state
2515                    .pending_mouse_down
2516                    .get_or_insert_with(Default::default)
2517                    .clone();
2518
2519                window.on_mouse_event(move |_: &MouseMoveEvent, phase, window, cx| {
2520                    if phase != DispatchPhase::Bubble {
2521                        return;
2522                    }
2523                    let is_hovered = has_mouse_down.borrow().is_none()
2524                        && !cx.has_active_drag()
2525                        && hitbox.is_hovered(window);
2526                    let mut was_hovered = was_hovered.borrow_mut();
2527
2528                    if is_hovered != *was_hovered {
2529                        *was_hovered = is_hovered;
2530                        drop(was_hovered);
2531
2532                        hover_listener(&is_hovered, window, cx);
2533                    }
2534                });
2535            }
2536
2537            if let Some(tooltip_builder) = self.tooltip_builder.take() {
2538                let active_tooltip = element_state
2539                    .active_tooltip
2540                    .get_or_insert_with(Default::default)
2541                    .clone();
2542                let pending_mouse_down = element_state
2543                    .pending_mouse_down
2544                    .get_or_insert_with(Default::default)
2545                    .clone();
2546
2547                let tooltip_is_hoverable = tooltip_builder.hoverable;
2548                let build_tooltip = Rc::new(move |window: &mut Window, cx: &mut App| {
2549                    Some(((tooltip_builder.build)(window, cx), tooltip_is_hoverable))
2550                });
2551                // Use bounds instead of testing hitbox since this is called during prepaint.
2552                let check_is_hovered_during_prepaint = Rc::new({
2553                    let pending_mouse_down = pending_mouse_down.clone();
2554                    let source_bounds = hitbox.bounds;
2555                    move |window: &Window| {
2556                        !window.last_input_was_keyboard()
2557                            && pending_mouse_down.borrow().is_none()
2558                            && source_bounds.contains(&window.mouse_position())
2559                    }
2560                });
2561                let check_is_hovered = Rc::new({
2562                    let hitbox = hitbox.clone();
2563                    move |window: &Window| {
2564                        pending_mouse_down.borrow().is_none() && hitbox.is_hovered(window)
2565                    }
2566                });
2567                register_tooltip_mouse_handlers(
2568                    &active_tooltip,
2569                    self.tooltip_id,
2570                    build_tooltip,
2571                    check_is_hovered,
2572                    check_is_hovered_during_prepaint,
2573                    window,
2574                );
2575            }
2576
2577            // We unconditionally bind both the mouse up and mouse down active state handlers
2578            // Because we might not get a chance to render a frame before the mouse up event arrives.
2579            let active_state = element_state
2580                .clicked_state
2581                .get_or_insert_with(Default::default)
2582                .clone();
2583
2584            {
2585                let active_state = active_state.clone();
2586                window.on_mouse_event(move |_: &MouseUpEvent, phase, window, _cx| {
2587                    if phase == DispatchPhase::Capture && active_state.borrow().is_clicked() {
2588                        *active_state.borrow_mut() = ElementClickedState::default();
2589                        window.refresh();
2590                    }
2591                });
2592            }
2593
2594            {
2595                let active_group_hitbox = self
2596                    .group_active_style
2597                    .as_ref()
2598                    .and_then(|group_active| GroupHitboxes::get(&group_active.group, cx));
2599                let hitbox = hitbox.clone();
2600                window.on_mouse_event(move |_: &MouseDownEvent, phase, window, _cx| {
2601                    if phase == DispatchPhase::Bubble && !window.default_prevented() {
2602                        let group_hovered = active_group_hitbox
2603                            .is_some_and(|group_hitbox_id| group_hitbox_id.is_hovered(window));
2604                        let element_hovered = hitbox.is_hovered(window);
2605                        if group_hovered || element_hovered {
2606                            *active_state.borrow_mut() = ElementClickedState {
2607                                group: group_hovered,
2608                                element: element_hovered,
2609                            };
2610                            window.refresh();
2611                        }
2612                    }
2613                });
2614            }
2615        }
2616    }
2617
2618    fn paint_keyboard_listeners(&mut self, window: &mut Window, _cx: &mut App) {
2619        let key_down_listeners = mem::take(&mut self.key_down_listeners);
2620        let key_up_listeners = mem::take(&mut self.key_up_listeners);
2621        let modifiers_changed_listeners = mem::take(&mut self.modifiers_changed_listeners);
2622        let action_listeners = mem::take(&mut self.action_listeners);
2623        if let Some(context) = self.key_context.clone() {
2624            window.set_key_context(context);
2625        }
2626
2627        for listener in key_down_listeners {
2628            window.on_key_event(move |event: &KeyDownEvent, phase, window, cx| {
2629                listener(event, phase, window, cx);
2630            })
2631        }
2632
2633        for listener in key_up_listeners {
2634            window.on_key_event(move |event: &KeyUpEvent, phase, window, cx| {
2635                listener(event, phase, window, cx);
2636            })
2637        }
2638
2639        for listener in modifiers_changed_listeners {
2640            window.on_modifiers_changed(move |event: &ModifiersChangedEvent, window, cx| {
2641                listener(event, window, cx);
2642            })
2643        }
2644
2645        for (action_type, listener) in action_listeners {
2646            window.on_action(action_type, listener)
2647        }
2648    }
2649
2650    fn paint_hover_group_handler(&self, window: &mut Window, cx: &mut App) {
2651        let group_hitbox = self
2652            .group_hover_style
2653            .as_ref()
2654            .and_then(|group_hover| GroupHitboxes::get(&group_hover.group, cx));
2655
2656        if let Some(group_hitbox) = group_hitbox {
2657            let was_hovered = group_hitbox.is_hovered(window);
2658            let current_view = window.current_view();
2659            window.on_mouse_event(move |_: &MouseMoveEvent, phase, window, cx| {
2660                let hovered = group_hitbox.is_hovered(window);
2661                if phase == DispatchPhase::Capture && hovered != was_hovered {
2662                    cx.notify(current_view);
2663                }
2664            });
2665        }
2666    }
2667
2668    fn paint_scroll_listener(
2669        &self,
2670        hitbox: &Hitbox,
2671        style: &Style,
2672        window: &mut Window,
2673        _cx: &mut App,
2674    ) {
2675        if let Some(scroll_offset) = self.scroll_offset.clone() {
2676            let overflow = style.overflow;
2677            let allow_concurrent_scroll = style.allow_concurrent_scroll;
2678            let restrict_scroll_to_axis = style.restrict_scroll_to_axis;
2679            let line_height = window.line_height();
2680            let hitbox = hitbox.clone();
2681            let current_view = window.current_view();
2682            window.on_mouse_event(move |event: &ScrollWheelEvent, phase, window, cx| {
2683                if phase == DispatchPhase::Bubble && hitbox.should_handle_scroll(window) {
2684                    let mut scroll_offset = scroll_offset.borrow_mut();
2685                    let old_scroll_offset = *scroll_offset;
2686                    let delta = event.delta.pixel_delta(line_height);
2687
2688                    let mut delta_x = Pixels::ZERO;
2689                    if overflow.x == Overflow::Scroll {
2690                        if !delta.x.is_zero() {
2691                            delta_x = delta.x;
2692                        } else if !restrict_scroll_to_axis && overflow.y != Overflow::Scroll {
2693                            delta_x = delta.y;
2694                        }
2695                    }
2696                    let mut delta_y = Pixels::ZERO;
2697                    if overflow.y == Overflow::Scroll {
2698                        if !delta.y.is_zero() {
2699                            delta_y = delta.y;
2700                        } else if !restrict_scroll_to_axis && overflow.x != Overflow::Scroll {
2701                            delta_y = delta.x;
2702                        }
2703                    }
2704                    if !allow_concurrent_scroll && !delta_x.is_zero() && !delta_y.is_zero() {
2705                        if delta_x.abs() > delta_y.abs() {
2706                            delta_y = Pixels::ZERO;
2707                        } else {
2708                            delta_x = Pixels::ZERO;
2709                        }
2710                    }
2711                    scroll_offset.y += delta_y;
2712                    scroll_offset.x += delta_x;
2713                    if *scroll_offset != old_scroll_offset {
2714                        cx.notify(current_view);
2715                    }
2716                }
2717            });
2718        }
2719    }
2720
2721    /// Compute the visual style for this element, based on the current bounds and the element's state.
2722    pub fn compute_style(
2723        &self,
2724        global_id: Option<&GlobalElementId>,
2725        hitbox: Option<&Hitbox>,
2726        window: &mut Window,
2727        cx: &mut App,
2728    ) -> Style {
2729        window.with_optional_element_state(global_id, |element_state, window| {
2730            let mut element_state =
2731                element_state.map(|element_state| element_state.unwrap_or_default());
2732            let style = self.compute_style_internal(hitbox, element_state.as_mut(), window, cx);
2733            (style, element_state)
2734        })
2735    }
2736
2737    /// Called from internal methods that have already called with_element_state.
2738    fn compute_style_internal(
2739        &self,
2740        hitbox: Option<&Hitbox>,
2741        element_state: Option<&mut InteractiveElementState>,
2742        window: &mut Window,
2743        cx: &mut App,
2744    ) -> Style {
2745        let mut style = Style::default();
2746        style.refine(&self.base_style);
2747
2748        if let Some(focus_handle) = self.tracked_focus_handle.as_ref() {
2749            if let Some(in_focus_style) = self.in_focus_style.as_ref()
2750                && focus_handle.within_focused(window, cx)
2751            {
2752                style.refine(in_focus_style);
2753            }
2754
2755            if let Some(focus_style) = self.focus_style.as_ref()
2756                && focus_handle.is_focused(window)
2757            {
2758                style.refine(focus_style);
2759            }
2760
2761            if let Some(focus_visible_style) = self.focus_visible_style.as_ref()
2762                && focus_handle.is_focused(window)
2763                && window.last_input_was_keyboard()
2764            {
2765                style.refine(focus_visible_style);
2766            }
2767        }
2768
2769        if !cx.has_active_drag() {
2770            if let Some(group_hover) = self.group_hover_style.as_ref() {
2771                let is_group_hovered =
2772                    if let Some(group_hitbox_id) = GroupHitboxes::get(&group_hover.group, cx) {
2773                        group_hitbox_id.is_hovered(window)
2774                    } else if let Some(element_state) = element_state.as_ref() {
2775                        element_state
2776                            .hover_state
2777                            .as_ref()
2778                            .map(|state| state.borrow().group)
2779                            .unwrap_or(false)
2780                    } else {
2781                        false
2782                    };
2783
2784                if is_group_hovered {
2785                    style.refine(&group_hover.style);
2786                }
2787            }
2788
2789            if let Some(hover_style) = self.hover_style.as_ref() {
2790                let is_hovered = if let Some(hitbox) = hitbox {
2791                    hitbox.is_hovered(window)
2792                } else if let Some(element_state) = element_state.as_ref() {
2793                    element_state
2794                        .hover_state
2795                        .as_ref()
2796                        .map(|state| state.borrow().element)
2797                        .unwrap_or(false)
2798                } else {
2799                    false
2800                };
2801
2802                if is_hovered {
2803                    style.refine(hover_style);
2804                }
2805            }
2806        }
2807
2808        if let Some(hitbox) = hitbox {
2809            if let Some(drag) = cx.active_drag.take() {
2810                let mut can_drop = true;
2811                if let Some(can_drop_predicate) = &self.can_drop_predicate {
2812                    can_drop = can_drop_predicate(drag.value.as_ref(), window, cx);
2813                }
2814
2815                if can_drop {
2816                    for (state_type, group_drag_style) in &self.group_drag_over_styles {
2817                        if let Some(group_hitbox_id) =
2818                            GroupHitboxes::get(&group_drag_style.group, cx)
2819                            && *state_type == drag.value.as_ref().type_id()
2820                            && group_hitbox_id.is_hovered(window)
2821                        {
2822                            style.refine(&group_drag_style.style);
2823                        }
2824                    }
2825
2826                    for (state_type, build_drag_over_style) in &self.drag_over_styles {
2827                        if *state_type == drag.value.as_ref().type_id() && hitbox.is_hovered(window)
2828                        {
2829                            style.refine(&build_drag_over_style(drag.value.as_ref(), window, cx));
2830                        }
2831                    }
2832                }
2833
2834                style.mouse_cursor = drag.cursor_style;
2835                cx.active_drag = Some(drag);
2836            }
2837        }
2838
2839        if let Some(element_state) = element_state {
2840            let clicked_state = element_state
2841                .clicked_state
2842                .get_or_insert_with(Default::default)
2843                .borrow();
2844            if clicked_state.group
2845                && let Some(group) = self.group_active_style.as_ref()
2846            {
2847                style.refine(&group.style)
2848            }
2849
2850            if let Some(active_style) = self.active_style.as_ref()
2851                && clicked_state.element
2852            {
2853                style.refine(active_style)
2854            }
2855        }
2856
2857        style
2858    }
2859}
2860
2861/// The per-frame state of an interactive element. Used for tracking stateful interactions like clicks
2862/// and scroll offsets.
2863#[derive(Default)]
2864pub struct InteractiveElementState {
2865    pub(crate) focus_handle: Option<FocusHandle>,
2866    pub(crate) clicked_state: Option<Rc<RefCell<ElementClickedState>>>,
2867    pub(crate) hover_state: Option<Rc<RefCell<ElementHoverState>>>,
2868    pub(crate) hover_listener_state: Option<Rc<RefCell<bool>>>,
2869    pub(crate) pending_mouse_down: Option<Rc<RefCell<Option<MouseDownEvent>>>>,
2870    pub(crate) scroll_offset: Option<Rc<RefCell<Point<Pixels>>>>,
2871    pub(crate) active_tooltip: Option<Rc<RefCell<Option<ActiveTooltip>>>>,
2872}
2873
2874/// Whether or not the element or a group that contains it is clicked by the mouse.
2875#[derive(Copy, Clone, Default, Eq, PartialEq)]
2876pub struct ElementClickedState {
2877    /// True if this element's group has been clicked, false otherwise
2878    pub group: bool,
2879
2880    /// True if this element has been clicked, false otherwise
2881    pub element: bool,
2882}
2883
2884impl ElementClickedState {
2885    fn is_clicked(&self) -> bool {
2886        self.group || self.element
2887    }
2888}
2889
2890/// Whether or not the element or a group that contains it is hovered.
2891#[derive(Copy, Clone, Default, Eq, PartialEq)]
2892pub struct ElementHoverState {
2893    /// True if this element's group is hovered, false otherwise
2894    pub group: bool,
2895
2896    /// True if this element is hovered, false otherwise
2897    pub element: bool,
2898}
2899
2900pub(crate) enum ActiveTooltip {
2901    /// Currently delaying before showing the tooltip.
2902    WaitingForShow { _task: Task<()> },
2903    /// Tooltip is visible, element was hovered or for hoverable tooltips, the tooltip was hovered.
2904    Visible {
2905        tooltip: AnyTooltip,
2906        is_hoverable: bool,
2907    },
2908    /// Tooltip is visible and hoverable, but the mouse is no longer hovering. Currently delaying
2909    /// before hiding it.
2910    WaitingForHide {
2911        tooltip: AnyTooltip,
2912        _task: Task<()>,
2913    },
2914}
2915
2916pub(crate) fn clear_active_tooltip(
2917    active_tooltip: &Rc<RefCell<Option<ActiveTooltip>>>,
2918    window: &mut Window,
2919) {
2920    match active_tooltip.borrow_mut().take() {
2921        None => {}
2922        Some(ActiveTooltip::WaitingForShow { .. }) => {}
2923        Some(ActiveTooltip::Visible { .. }) => window.refresh(),
2924        Some(ActiveTooltip::WaitingForHide { .. }) => window.refresh(),
2925    }
2926}
2927
2928pub(crate) fn clear_active_tooltip_if_not_hoverable(
2929    active_tooltip: &Rc<RefCell<Option<ActiveTooltip>>>,
2930    window: &mut Window,
2931) {
2932    let should_clear = match active_tooltip.borrow().as_ref() {
2933        None => false,
2934        Some(ActiveTooltip::WaitingForShow { .. }) => false,
2935        Some(ActiveTooltip::Visible { is_hoverable, .. }) => !is_hoverable,
2936        Some(ActiveTooltip::WaitingForHide { .. }) => false,
2937    };
2938    if should_clear {
2939        active_tooltip.borrow_mut().take();
2940        window.refresh();
2941    }
2942}
2943
2944pub(crate) fn set_tooltip_on_window(
2945    active_tooltip: &Rc<RefCell<Option<ActiveTooltip>>>,
2946    window: &mut Window,
2947) -> Option<TooltipId> {
2948    let tooltip = match active_tooltip.borrow().as_ref() {
2949        None => return None,
2950        Some(ActiveTooltip::WaitingForShow { .. }) => return None,
2951        Some(ActiveTooltip::Visible { tooltip, .. }) => tooltip.clone(),
2952        Some(ActiveTooltip::WaitingForHide { tooltip, .. }) => tooltip.clone(),
2953    };
2954    Some(window.set_tooltip(tooltip))
2955}
2956
2957pub(crate) fn register_tooltip_mouse_handlers(
2958    active_tooltip: &Rc<RefCell<Option<ActiveTooltip>>>,
2959    tooltip_id: Option<TooltipId>,
2960    build_tooltip: Rc<dyn Fn(&mut Window, &mut App) -> Option<(AnyView, bool)>>,
2961    check_is_hovered: Rc<dyn Fn(&Window) -> bool>,
2962    check_is_hovered_during_prepaint: Rc<dyn Fn(&Window) -> bool>,
2963    window: &mut Window,
2964) {
2965    window.on_mouse_event({
2966        let active_tooltip = active_tooltip.clone();
2967        let build_tooltip = build_tooltip.clone();
2968        let check_is_hovered = check_is_hovered.clone();
2969        move |_: &MouseMoveEvent, phase, window, cx| {
2970            handle_tooltip_mouse_move(
2971                &active_tooltip,
2972                &build_tooltip,
2973                &check_is_hovered,
2974                &check_is_hovered_during_prepaint,
2975                phase,
2976                window,
2977                cx,
2978            )
2979        }
2980    });
2981
2982    window.on_mouse_event({
2983        let active_tooltip = active_tooltip.clone();
2984        move |_: &MouseDownEvent, _phase, window: &mut Window, _cx| {
2985            if !tooltip_id.is_some_and(|tooltip_id| tooltip_id.is_hovered(window)) {
2986                clear_active_tooltip_if_not_hoverable(&active_tooltip, window);
2987            }
2988        }
2989    });
2990
2991    window.on_mouse_event({
2992        let active_tooltip = active_tooltip.clone();
2993        move |_: &ScrollWheelEvent, _phase, window: &mut Window, _cx| {
2994            if !tooltip_id.is_some_and(|tooltip_id| tooltip_id.is_hovered(window)) {
2995                clear_active_tooltip_if_not_hoverable(&active_tooltip, window);
2996            }
2997        }
2998    });
2999}
3000
3001/// Handles displaying tooltips when an element is hovered.
3002///
3003/// The mouse hovering logic also relies on being called from window prepaint in order to handle the
3004/// case where the element the tooltip is on is not rendered - in that case its mouse listeners are
3005/// also not registered. During window prepaint, the hitbox information is not available, so
3006/// `check_is_hovered_during_prepaint` is used which bases the check off of the absolute bounds of
3007/// the element.
3008///
3009/// TODO: There's a minor bug due to the use of absolute bounds while checking during prepaint - it
3010/// does not know if the hitbox is occluded. In the case where a tooltip gets displayed and then
3011/// gets occluded after display, it will stick around until the mouse exits the hover bounds.
3012fn handle_tooltip_mouse_move(
3013    active_tooltip: &Rc<RefCell<Option<ActiveTooltip>>>,
3014    build_tooltip: &Rc<dyn Fn(&mut Window, &mut App) -> Option<(AnyView, bool)>>,
3015    check_is_hovered: &Rc<dyn Fn(&Window) -> bool>,
3016    check_is_hovered_during_prepaint: &Rc<dyn Fn(&Window) -> bool>,
3017    phase: DispatchPhase,
3018    window: &mut Window,
3019    cx: &mut App,
3020) {
3021    // Separates logic for what mutation should occur from applying it, to avoid overlapping
3022    // RefCell borrows.
3023    enum Action {
3024        None,
3025        CancelShow,
3026        ScheduleShow,
3027    }
3028
3029    let action = match active_tooltip.borrow().as_ref() {
3030        None => {
3031            let is_hovered = check_is_hovered(window);
3032            if is_hovered && phase.bubble() {
3033                Action::ScheduleShow
3034            } else {
3035                Action::None
3036            }
3037        }
3038        Some(ActiveTooltip::WaitingForShow { .. }) => {
3039            let is_hovered = check_is_hovered(window);
3040            if is_hovered {
3041                Action::None
3042            } else {
3043                Action::CancelShow
3044            }
3045        }
3046        // These are handled in check_visible_and_update.
3047        Some(ActiveTooltip::Visible { .. }) | Some(ActiveTooltip::WaitingForHide { .. }) => {
3048            Action::None
3049        }
3050    };
3051
3052    match action {
3053        Action::None => {}
3054        Action::CancelShow => {
3055            // Cancel waiting to show tooltip when it is no longer hovered.
3056            active_tooltip.borrow_mut().take();
3057        }
3058        Action::ScheduleShow => {
3059            let delayed_show_task = window.spawn(cx, {
3060                let weak_active_tooltip = Rc::downgrade(active_tooltip);
3061                let build_tooltip = build_tooltip.clone();
3062                let check_is_hovered_during_prepaint = check_is_hovered_during_prepaint.clone();
3063                async move |cx| {
3064                    cx.background_executor().timer(TOOLTIP_SHOW_DELAY).await;
3065                    let Some(active_tooltip) = weak_active_tooltip.upgrade() else {
3066                        return;
3067                    };
3068                    cx.update(|window, cx| {
3069                        let new_tooltip =
3070                            build_tooltip(window, cx).map(|(view, tooltip_is_hoverable)| {
3071                                let weak_active_tooltip = Rc::downgrade(&active_tooltip);
3072                                ActiveTooltip::Visible {
3073                                    tooltip: AnyTooltip {
3074                                        view,
3075                                        mouse_position: window.mouse_position(),
3076                                        check_visible_and_update: Rc::new(
3077                                            move |tooltip_bounds, window, cx| {
3078                                                let Some(active_tooltip) =
3079                                                    weak_active_tooltip.upgrade()
3080                                                else {
3081                                                    return false;
3082                                                };
3083                                                handle_tooltip_check_visible_and_update(
3084                                                    &active_tooltip,
3085                                                    tooltip_is_hoverable,
3086                                                    &check_is_hovered_during_prepaint,
3087                                                    tooltip_bounds,
3088                                                    window,
3089                                                    cx,
3090                                                )
3091                                            },
3092                                        ),
3093                                    },
3094                                    is_hoverable: tooltip_is_hoverable,
3095                                }
3096                            });
3097                        *active_tooltip.borrow_mut() = new_tooltip;
3098                        window.refresh();
3099                    })
3100                    .ok();
3101                }
3102            });
3103            active_tooltip
3104                .borrow_mut()
3105                .replace(ActiveTooltip::WaitingForShow {
3106                    _task: delayed_show_task,
3107                });
3108        }
3109    }
3110}
3111
3112/// Returns a callback which will be called by window prepaint to update tooltip visibility. The
3113/// purpose of doing this logic here instead of the mouse move handler is that the mouse move
3114/// handler won't get called when the element is not painted (e.g. via use of `visible_on_hover`).
3115fn handle_tooltip_check_visible_and_update(
3116    active_tooltip: &Rc<RefCell<Option<ActiveTooltip>>>,
3117    tooltip_is_hoverable: bool,
3118    check_is_hovered: &Rc<dyn Fn(&Window) -> bool>,
3119    tooltip_bounds: Bounds<Pixels>,
3120    window: &mut Window,
3121    cx: &mut App,
3122) -> bool {
3123    // Separates logic for what mutation should occur from applying it, to avoid overlapping RefCell
3124    // borrows.
3125    enum Action {
3126        None,
3127        Hide,
3128        ScheduleHide(AnyTooltip),
3129        CancelHide(AnyTooltip),
3130    }
3131
3132    let is_hovered = check_is_hovered(window)
3133        || (tooltip_is_hoverable && tooltip_bounds.contains(&window.mouse_position()));
3134    let action = match active_tooltip.borrow().as_ref() {
3135        Some(ActiveTooltip::Visible { tooltip, .. }) => {
3136            if is_hovered {
3137                Action::None
3138            } else {
3139                if tooltip_is_hoverable {
3140                    Action::ScheduleHide(tooltip.clone())
3141                } else {
3142                    Action::Hide
3143                }
3144            }
3145        }
3146        Some(ActiveTooltip::WaitingForHide { tooltip, .. }) => {
3147            if is_hovered {
3148                Action::CancelHide(tooltip.clone())
3149            } else {
3150                Action::None
3151            }
3152        }
3153        None | Some(ActiveTooltip::WaitingForShow { .. }) => Action::None,
3154    };
3155
3156    match action {
3157        Action::None => {}
3158        Action::Hide => clear_active_tooltip(active_tooltip, window),
3159        Action::ScheduleHide(tooltip) => {
3160            let delayed_hide_task = window.spawn(cx, {
3161                let weak_active_tooltip = Rc::downgrade(active_tooltip);
3162                async move |cx| {
3163                    cx.background_executor()
3164                        .timer(HOVERABLE_TOOLTIP_HIDE_DELAY)
3165                        .await;
3166                    let Some(active_tooltip) = weak_active_tooltip.upgrade() else {
3167                        return;
3168                    };
3169                    if active_tooltip.borrow_mut().take().is_some() {
3170                        cx.update(|window, _cx| window.refresh()).ok();
3171                    }
3172                }
3173            });
3174            active_tooltip
3175                .borrow_mut()
3176                .replace(ActiveTooltip::WaitingForHide {
3177                    tooltip,
3178                    _task: delayed_hide_task,
3179                });
3180        }
3181        Action::CancelHide(tooltip) => {
3182            // Cancel waiting to hide tooltip when it becomes hovered.
3183            active_tooltip.borrow_mut().replace(ActiveTooltip::Visible {
3184                tooltip,
3185                is_hoverable: true,
3186            });
3187        }
3188    }
3189
3190    active_tooltip.borrow().is_some()
3191}
3192
3193#[derive(Default)]
3194pub(crate) struct GroupHitboxes(HashMap<SharedString, SmallVec<[HitboxId; 1]>>);
3195
3196impl Global for GroupHitboxes {}
3197
3198impl GroupHitboxes {
3199    pub fn get(name: &SharedString, cx: &mut App) -> Option<HitboxId> {
3200        cx.default_global::<Self>()
3201            .0
3202            .get(name)
3203            .and_then(|bounds_stack| bounds_stack.last())
3204            .cloned()
3205    }
3206
3207    pub fn push(name: SharedString, hitbox_id: HitboxId, cx: &mut App) {
3208        cx.default_global::<Self>()
3209            .0
3210            .entry(name)
3211            .or_default()
3212            .push(hitbox_id);
3213    }
3214
3215    pub fn pop(name: &SharedString, cx: &mut App) {
3216        cx.default_global::<Self>().0.get_mut(name).unwrap().pop();
3217    }
3218}
3219
3220/// A wrapper around an element that can store state, produced after assigning an ElementId.
3221pub struct Stateful<E> {
3222    pub(crate) element: E,
3223}
3224
3225impl<E> Styled for Stateful<E>
3226where
3227    E: Styled,
3228{
3229    fn style(&mut self) -> &mut StyleRefinement {
3230        self.element.style()
3231    }
3232}
3233
3234impl<E> StatefulInteractiveElement for Stateful<E>
3235where
3236    E: Element,
3237    Self: InteractiveElement,
3238{
3239}
3240
3241impl<E> InteractiveElement for Stateful<E>
3242where
3243    E: InteractiveElement,
3244{
3245    fn interactivity(&mut self) -> &mut Interactivity {
3246        self.element.interactivity()
3247    }
3248}
3249
3250impl<E> Element for Stateful<E>
3251where
3252    E: Element,
3253{
3254    type RequestLayoutState = E::RequestLayoutState;
3255    type PrepaintState = E::PrepaintState;
3256
3257    fn id(&self) -> Option<ElementId> {
3258        self.element.id()
3259    }
3260
3261    fn source_location(&self) -> Option<&'static core::panic::Location<'static>> {
3262        self.element.source_location()
3263    }
3264
3265    fn request_layout(
3266        &mut self,
3267        id: Option<&GlobalElementId>,
3268        inspector_id: Option<&InspectorElementId>,
3269        window: &mut Window,
3270        cx: &mut App,
3271    ) -> (LayoutId, Self::RequestLayoutState) {
3272        self.element.request_layout(id, inspector_id, window, cx)
3273    }
3274
3275    fn prepaint(
3276        &mut self,
3277        id: Option<&GlobalElementId>,
3278        inspector_id: Option<&InspectorElementId>,
3279        bounds: Bounds<Pixels>,
3280        state: &mut Self::RequestLayoutState,
3281        window: &mut Window,
3282        cx: &mut App,
3283    ) -> E::PrepaintState {
3284        self.element
3285            .prepaint(id, inspector_id, bounds, state, window, cx)
3286    }
3287
3288    fn paint(
3289        &mut self,
3290        id: Option<&GlobalElementId>,
3291        inspector_id: Option<&InspectorElementId>,
3292        bounds: Bounds<Pixels>,
3293        request_layout: &mut Self::RequestLayoutState,
3294        prepaint: &mut Self::PrepaintState,
3295        window: &mut Window,
3296        cx: &mut App,
3297    ) {
3298        self.element.paint(
3299            id,
3300            inspector_id,
3301            bounds,
3302            request_layout,
3303            prepaint,
3304            window,
3305            cx,
3306        );
3307    }
3308}
3309
3310impl<E> IntoElement for Stateful<E>
3311where
3312    E: Element,
3313{
3314    type Element = Self;
3315
3316    fn into_element(self) -> Self::Element {
3317        self
3318    }
3319}
3320
3321impl<E> ParentElement for Stateful<E>
3322where
3323    E: ParentElement,
3324{
3325    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
3326        self.element.extend(elements)
3327    }
3328}
3329
3330/// Represents an element that can be scrolled *to* in its parent element.
3331/// Contrary to [ScrollHandle::scroll_to_active_item], an anchored element does not have to be an immediate child of the parent.
3332#[derive(Clone)]
3333pub struct ScrollAnchor {
3334    handle: ScrollHandle,
3335    last_origin: Rc<RefCell<Point<Pixels>>>,
3336}
3337
3338impl ScrollAnchor {
3339    /// Creates a [ScrollAnchor] associated with a given [ScrollHandle].
3340    pub fn for_handle(handle: ScrollHandle) -> Self {
3341        Self {
3342            handle,
3343            last_origin: Default::default(),
3344        }
3345    }
3346    /// Request scroll to this item on the next frame.
3347    pub fn scroll_to(&self, window: &mut Window, _cx: &mut App) {
3348        let this = self.clone();
3349
3350        window.on_next_frame(move |_, _| {
3351            let viewport_bounds = this.handle.bounds();
3352            let self_bounds = *this.last_origin.borrow();
3353            this.handle.set_offset(viewport_bounds.origin - self_bounds);
3354        });
3355    }
3356}
3357
3358#[derive(Default, Debug)]
3359struct ScrollHandleState {
3360    offset: Rc<RefCell<Point<Pixels>>>,
3361    bounds: Bounds<Pixels>,
3362    max_offset: Point<Pixels>,
3363    child_bounds: Vec<Bounds<Pixels>>,
3364    scroll_to_bottom: bool,
3365    overflow: Point<Overflow>,
3366    active_item: Option<ScrollActiveItem>,
3367}
3368
3369#[derive(Default, Debug, Clone, Copy)]
3370struct ScrollActiveItem {
3371    index: usize,
3372    strategy: ScrollStrategy,
3373}
3374
3375#[derive(Default, Debug, Clone, Copy)]
3376enum ScrollStrategy {
3377    #[default]
3378    FirstVisible,
3379    Top,
3380}
3381
3382/// A handle to the scrollable aspects of an element.
3383/// Used for accessing scroll state, like the current scroll offset,
3384/// and for mutating the scroll state, like scrolling to a specific child.
3385#[derive(Clone, Debug)]
3386pub struct ScrollHandle(Rc<RefCell<ScrollHandleState>>);
3387
3388impl Default for ScrollHandle {
3389    fn default() -> Self {
3390        Self::new()
3391    }
3392}
3393
3394impl ScrollHandle {
3395    /// Construct a new scroll handle.
3396    pub fn new() -> Self {
3397        Self(Rc::default())
3398    }
3399
3400    /// Get the current scroll offset.
3401    pub fn offset(&self) -> Point<Pixels> {
3402        *self.0.borrow().offset.borrow()
3403    }
3404
3405    /// Get the maximum scroll offset.
3406    pub fn max_offset(&self) -> Point<Pixels> {
3407        self.0.borrow().max_offset
3408    }
3409
3410    /// Get the top child that's scrolled into view.
3411    pub fn top_item(&self) -> usize {
3412        let state = self.0.borrow();
3413        let top = state.bounds.top() - state.offset.borrow().y;
3414
3415        match state.child_bounds.binary_search_by(|bounds| {
3416            if top < bounds.top() {
3417                Ordering::Greater
3418            } else if top > bounds.bottom() {
3419                Ordering::Less
3420            } else {
3421                Ordering::Equal
3422            }
3423        }) {
3424            Ok(ix) => ix,
3425            Err(ix) => ix.min(state.child_bounds.len().saturating_sub(1)),
3426        }
3427    }
3428
3429    /// Get the bottom child that's scrolled into view.
3430    pub fn bottom_item(&self) -> usize {
3431        let state = self.0.borrow();
3432        let bottom = state.bounds.bottom() - state.offset.borrow().y;
3433
3434        match state.child_bounds.binary_search_by(|bounds| {
3435            if bottom < bounds.top() {
3436                Ordering::Greater
3437            } else if bottom > bounds.bottom() {
3438                Ordering::Less
3439            } else {
3440                Ordering::Equal
3441            }
3442        }) {
3443            Ok(ix) => ix,
3444            Err(ix) => ix.min(state.child_bounds.len().saturating_sub(1)),
3445        }
3446    }
3447
3448    /// Return the bounds into which this child is painted
3449    pub fn bounds(&self) -> Bounds<Pixels> {
3450        self.0.borrow().bounds
3451    }
3452
3453    /// Get the bounds for a specific child.
3454    pub fn bounds_for_item(&self, ix: usize) -> Option<Bounds<Pixels>> {
3455        self.0.borrow().child_bounds.get(ix).cloned()
3456    }
3457
3458    /// Update [ScrollHandleState]'s active item for scrolling to in prepaint
3459    pub fn scroll_to_item(&self, ix: usize) {
3460        let mut state = self.0.borrow_mut();
3461        state.active_item = Some(ScrollActiveItem {
3462            index: ix,
3463            strategy: ScrollStrategy::default(),
3464        });
3465    }
3466
3467    /// Update [ScrollHandleState]'s active item for scrolling to in prepaint
3468    /// This scrolls the minimal amount to ensure that the child is the first visible element
3469    pub fn scroll_to_top_of_item(&self, ix: usize) {
3470        let mut state = self.0.borrow_mut();
3471        state.active_item = Some(ScrollActiveItem {
3472            index: ix,
3473            strategy: ScrollStrategy::Top,
3474        });
3475    }
3476
3477    /// Scrolls the minimal amount to either ensure that the child is
3478    /// fully visible or the top element of the view depends on the
3479    /// scroll strategy
3480    fn scroll_to_active_item(&self) {
3481        let mut state = self.0.borrow_mut();
3482
3483        let Some(active_item) = state.active_item else {
3484            return;
3485        };
3486
3487        let active_item = match state.child_bounds.get(active_item.index) {
3488            Some(bounds) => {
3489                let mut scroll_offset = state.offset.borrow_mut();
3490
3491                match active_item.strategy {
3492                    ScrollStrategy::FirstVisible => {
3493                        if state.overflow.y == Overflow::Scroll {
3494                            let child_height = bounds.size.height;
3495                            let viewport_height = state.bounds.size.height;
3496                            if child_height > viewport_height {
3497                                scroll_offset.y = state.bounds.top() - bounds.top();
3498                            } else if bounds.top() + scroll_offset.y < state.bounds.top() {
3499                                scroll_offset.y = state.bounds.top() - bounds.top();
3500                            } else if bounds.bottom() + scroll_offset.y > state.bounds.bottom() {
3501                                scroll_offset.y = state.bounds.bottom() - bounds.bottom();
3502                            }
3503                        }
3504                    }
3505                    ScrollStrategy::Top => {
3506                        scroll_offset.y = state.bounds.top() - bounds.top();
3507                    }
3508                }
3509
3510                if state.overflow.x == Overflow::Scroll {
3511                    let child_width = bounds.size.width;
3512                    let viewport_width = state.bounds.size.width;
3513                    if child_width > viewport_width {
3514                        scroll_offset.x = state.bounds.left() - bounds.left();
3515                    } else if bounds.left() + scroll_offset.x < state.bounds.left() {
3516                        scroll_offset.x = state.bounds.left() - bounds.left();
3517                    } else if bounds.right() + scroll_offset.x > state.bounds.right() {
3518                        scroll_offset.x = state.bounds.right() - bounds.right();
3519                    }
3520                }
3521                None
3522            }
3523            None => Some(active_item),
3524        };
3525        state.active_item = active_item;
3526    }
3527
3528    /// Scrolls to the bottom.
3529    pub fn scroll_to_bottom(&self) {
3530        let mut state = self.0.borrow_mut();
3531        state.scroll_to_bottom = true;
3532    }
3533
3534    /// Set the offset explicitly. The offset is the distance from the top left of the
3535    /// parent container to the top left of the first child.
3536    /// As you scroll further down the offset becomes more negative.
3537    pub fn set_offset(&self, mut position: Point<Pixels>) {
3538        let state = self.0.borrow();
3539        *state.offset.borrow_mut() = position;
3540    }
3541
3542    /// Get the logical scroll top, based on a child index and a pixel offset.
3543    pub fn logical_scroll_top(&self) -> (usize, Pixels) {
3544        let ix = self.top_item();
3545        let state = self.0.borrow();
3546
3547        if let Some(child_bounds) = state.child_bounds.get(ix) {
3548            (
3549                ix,
3550                child_bounds.top() + state.offset.borrow().y - state.bounds.top(),
3551            )
3552        } else {
3553            (ix, px(0.))
3554        }
3555    }
3556
3557    /// Get the logical scroll bottom, based on a child index and a pixel offset.
3558    pub fn logical_scroll_bottom(&self) -> (usize, Pixels) {
3559        let ix = self.bottom_item();
3560        let state = self.0.borrow();
3561
3562        if let Some(child_bounds) = state.child_bounds.get(ix) {
3563            (
3564                ix,
3565                child_bounds.bottom() + state.offset.borrow().y - state.bounds.bottom(),
3566            )
3567        } else {
3568            (ix, px(0.))
3569        }
3570    }
3571
3572    /// Get the count of children for scrollable item.
3573    pub fn children_count(&self) -> usize {
3574        self.0.borrow().child_bounds.len()
3575    }
3576}
3577
3578#[cfg(test)]
3579mod tests {
3580    use super::*;
3581    use crate::{AppContext as _, Context, InputEvent, MouseMoveEvent, TestAppContext};
3582    use std::rc::Weak;
3583
3584    struct TestTooltipView;
3585
3586    impl Render for TestTooltipView {
3587        fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
3588            div().w(px(20.)).h(px(20.)).child("tooltip")
3589        }
3590    }
3591
3592    type CapturedActiveTooltip = Rc<RefCell<Option<Weak<RefCell<Option<ActiveTooltip>>>>>>;
3593
3594    struct TooltipCaptureElement {
3595        child: AnyElement,
3596        captured_active_tooltip: CapturedActiveTooltip,
3597    }
3598
3599    impl IntoElement for TooltipCaptureElement {
3600        type Element = Self;
3601
3602        fn into_element(self) -> Self::Element {
3603            self
3604        }
3605    }
3606
3607    impl Element for TooltipCaptureElement {
3608        type RequestLayoutState = ();
3609        type PrepaintState = ();
3610
3611        fn id(&self) -> Option<ElementId> {
3612            None
3613        }
3614
3615        fn source_location(&self) -> Option<&'static core::panic::Location<'static>> {
3616            None
3617        }
3618
3619        fn request_layout(
3620            &mut self,
3621            _id: Option<&GlobalElementId>,
3622            _inspector_id: Option<&InspectorElementId>,
3623            window: &mut Window,
3624            cx: &mut App,
3625        ) -> (LayoutId, Self::RequestLayoutState) {
3626            (self.child.request_layout(window, cx), ())
3627        }
3628
3629        fn prepaint(
3630            &mut self,
3631            _id: Option<&GlobalElementId>,
3632            _inspector_id: Option<&InspectorElementId>,
3633            _bounds: Bounds<Pixels>,
3634            _request_layout: &mut Self::RequestLayoutState,
3635            window: &mut Window,
3636            cx: &mut App,
3637        ) -> Self::PrepaintState {
3638            self.child.prepaint(window, cx);
3639        }
3640
3641        fn paint(
3642            &mut self,
3643            _id: Option<&GlobalElementId>,
3644            _inspector_id: Option<&InspectorElementId>,
3645            _bounds: Bounds<Pixels>,
3646            _request_layout: &mut Self::RequestLayoutState,
3647            _prepaint: &mut Self::PrepaintState,
3648            window: &mut Window,
3649            cx: &mut App,
3650        ) {
3651            self.child.paint(window, cx);
3652            window.with_global_id("target".into(), |global_id, window| {
3653                window.with_element_state::<InteractiveElementState, _>(
3654                    global_id,
3655                    |state, _window| {
3656                        let state = state.unwrap();
3657                        *self.captured_active_tooltip.borrow_mut() =
3658                            state.active_tooltip.as_ref().map(Rc::downgrade);
3659                        ((), state)
3660                    },
3661                )
3662            });
3663        }
3664    }
3665
3666    struct TooltipOwner {
3667        captured_active_tooltip: CapturedActiveTooltip,
3668    }
3669
3670    impl Render for TooltipOwner {
3671        fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
3672            TooltipCaptureElement {
3673                child: div()
3674                    .size_full()
3675                    .child(
3676                        div()
3677                            .id("target")
3678                            .w(px(50.))
3679                            .h(px(50.))
3680                            .tooltip(|_, cx| cx.new(|_| TestTooltipView).into()),
3681                    )
3682                    .into_any_element(),
3683                captured_active_tooltip: self.captured_active_tooltip.clone(),
3684            }
3685        }
3686    }
3687
3688    #[test]
3689    fn scroll_handle_aligns_wide_children_to_left_edge() {
3690        let handle = ScrollHandle::new();
3691        {
3692            let mut state = handle.0.borrow_mut();
3693            state.bounds = Bounds::new(point(px(0.), px(0.)), size(px(80.), px(20.)));
3694            state.child_bounds = vec![Bounds::new(point(px(25.), px(0.)), size(px(200.), px(20.)))];
3695            state.overflow.x = Overflow::Scroll;
3696            state.active_item = Some(ScrollActiveItem {
3697                index: 0,
3698                strategy: ScrollStrategy::default(),
3699            });
3700        }
3701
3702        handle.scroll_to_active_item();
3703
3704        assert_eq!(handle.offset().x, px(-25.));
3705    }
3706
3707    #[test]
3708    fn scroll_handle_aligns_tall_children_to_top_edge() {
3709        let handle = ScrollHandle::new();
3710        {
3711            let mut state = handle.0.borrow_mut();
3712            state.bounds = Bounds::new(point(px(0.), px(0.)), size(px(20.), px(80.)));
3713            state.child_bounds = vec![Bounds::new(point(px(0.), px(25.)), size(px(20.), px(200.)))];
3714            state.overflow.y = Overflow::Scroll;
3715            state.active_item = Some(ScrollActiveItem {
3716                index: 0,
3717                strategy: ScrollStrategy::default(),
3718            });
3719        }
3720
3721        handle.scroll_to_active_item();
3722
3723        assert_eq!(handle.offset().y, px(-25.));
3724    }
3725
3726    fn setup_tooltip_owner_test() -> (
3727        TestAppContext,
3728        crate::AnyWindowHandle,
3729        CapturedActiveTooltip,
3730    ) {
3731        let mut test_app = TestAppContext::single();
3732        let captured_active_tooltip: CapturedActiveTooltip = Rc::new(RefCell::new(None));
3733        let window = test_app.add_window({
3734            let captured_active_tooltip = captured_active_tooltip.clone();
3735            move |_, _| TooltipOwner {
3736                captured_active_tooltip,
3737            }
3738        });
3739        let any_window = window.into();
3740
3741        test_app
3742            .update_window(any_window, |_, window, cx| {
3743                window.draw(cx).clear();
3744            })
3745            .unwrap();
3746
3747        test_app
3748            .update_window(any_window, |_, window, cx| {
3749                window.dispatch_event(
3750                    MouseMoveEvent {
3751                        position: point(px(10.), px(10.)),
3752                        modifiers: Default::default(),
3753                        pressed_button: None,
3754                    }
3755                    .to_platform_input(),
3756                    cx,
3757                );
3758            })
3759            .unwrap();
3760
3761        test_app
3762            .update_window(any_window, |_, window, cx| {
3763                window.draw(cx).clear();
3764            })
3765            .unwrap();
3766
3767        (test_app, any_window, captured_active_tooltip)
3768    }
3769
3770    #[test]
3771    fn tooltip_waiting_for_show_is_released_when_its_owner_disappears() {
3772        let (mut test_app, any_window, captured_active_tooltip) = setup_tooltip_owner_test();
3773
3774        let weak_active_tooltip = captured_active_tooltip.borrow().clone().unwrap();
3775        let active_tooltip = weak_active_tooltip.upgrade().unwrap();
3776        assert!(matches!(
3777            active_tooltip.borrow().as_ref(),
3778            Some(ActiveTooltip::WaitingForShow { .. })
3779        ));
3780
3781        test_app
3782            .update_window(any_window, |_, window, _| {
3783                window.remove_window();
3784            })
3785            .unwrap();
3786        test_app.run_until_parked();
3787        drop(active_tooltip);
3788
3789        assert!(weak_active_tooltip.upgrade().is_none());
3790    }
3791
3792    #[test]
3793    fn tooltip_is_released_when_its_owner_disappears() {
3794        let (mut test_app, any_window, captured_active_tooltip) = setup_tooltip_owner_test();
3795
3796        let weak_active_tooltip = captured_active_tooltip.borrow().clone().unwrap();
3797        let active_tooltip = weak_active_tooltip.upgrade().unwrap();
3798
3799        test_app.dispatcher.advance_clock(TOOLTIP_SHOW_DELAY);
3800        test_app.run_until_parked();
3801
3802        assert!(matches!(
3803            active_tooltip.borrow().as_ref(),
3804            Some(ActiveTooltip::Visible { .. })
3805        ));
3806
3807        test_app
3808            .update_window(any_window, |_, window, _| {
3809                window.remove_window();
3810            })
3811            .unwrap();
3812        test_app.run_until_parked();
3813        drop(active_tooltip);
3814
3815        assert!(weak_active_tooltip.upgrade().is_none());
3816    }
3817}