1//! Elements are the workhorses of GPUI. They are responsible for laying out and painting all of
2//! the contents of a window. Elements form a tree and are laid out according to the web layout
3//! standards as implemented by [taffy](https://github.com/DioxusLabs/taffy). Most of the time,
4//! you won't need to interact with this module or these APIs directly. Elements provide their
5//! own APIs and GPUI, or other element implementation, uses the APIs in this module to convert
6//! that element tree into the pixels you see on the screen.
7//!
8//! # Element Basics
9//!
10//! Elements are constructed by calling [`Render::render()`] on the root view of the window,
11//! which recursively constructs the element tree from the current state of the application,.
12//! These elements are then laid out by Taffy, and painted to the screen according to their own
13//! implementation of [`Element::paint()`]. Before the start of the next frame, the entire element
14//! tree and any callbacks they have registered with GPUI are dropped and the process repeats.
15//!
16//! But some state is too simple and voluminous to store in every view that needs it, e.g.
17//! whether a hover has been started or not. For this, GPUI provides the [`Element::State`], associated type.
18//!
19//! # Implementing your own elements
20//!
21//! Elements are intended to be the low level, imperative API to GPUI. They are responsible for upholding,
22//! or breaking, GPUI's features as they deem necessary. As an example, most GPUI elements are expected
23//! to stay in the bounds that their parent element gives them. But with [`WindowContext::break_content_mask`],
24//! you can ignore this restriction and paint anywhere inside of the window's bounds. This is useful for overlays
25//! and popups and anything else that shows up 'on top' of other elements.
26//! With great power, comes great responsibility.
27//!
28//! However, most of the time, you won't need to implement your own elements. GPUI provides a number of
29//! elements that should cover most common use cases out of the box and it's recommended that you use those
30//! to construct `components`, using the [`RenderOnce`] trait and the `#[derive(IntoElement)]` macro. Only implement
31//! elements when you need to take manual control of the layout and painting process, such as when using
32//! your own custom layout algorithm or rendering a code editor.
33
34use crate::{
35 App, ArenaBox, AvailableSpace, Bounds, Context, DispatchNodeId, ELEMENT_ARENA, ElementId,
36 FocusHandle, LayoutId, Pixels, Point, Size, Style, Window, util::FluentBuilder,
37};
38use derive_more::{Deref, DerefMut};
39pub(crate) use smallvec::SmallVec;
40use std::{any::Any, fmt::Debug, mem};
41
42/// Implemented by types that participate in laying out and painting the contents of a window.
43/// Elements form a tree and are laid out according to web-based layout rules, as implemented by Taffy.
44/// You can create custom elements by implementing this trait, see the module-level documentation
45/// for more details.
46pub trait Element: 'static + IntoElement {
47 /// The type of state returned from [`Element::request_layout`]. A mutable reference to this state is subsequently
48 /// provided to [`Element::prepaint`] and [`Element::paint`].
49 type RequestLayoutState: 'static;
50
51 /// The type of state returned from [`Element::prepaint`]. A mutable reference to this state is subsequently
52 /// provided to [`Element::paint`].
53 type PrepaintState: 'static;
54
55 /// If this element has a unique identifier, return it here. This is used to track elements across frames, and
56 /// will cause a GlobalElementId to be passed to the request_layout, prepaint, and paint methods.
57 ///
58 /// The global id can in turn be used to access state that's connected to an element with the same id across
59 /// frames. This id must be unique among children of the first containing element with an id.
60 fn id(&self) -> Option<ElementId>;
61
62 /// Before an element can be painted, we need to know where it's going to be and how big it is.
63 /// Use this method to request a layout from Taffy and initialize the element's state.
64 fn request_layout(
65 &mut self,
66 id: Option<&GlobalElementId>,
67 window: &mut Window,
68 cx: &mut App,
69 ) -> (LayoutId, Self::RequestLayoutState);
70
71 /// After laying out an element, we need to commit its bounds to the current frame for hitbox
72 /// purposes. The state argument is the same state that was returned from [`Element::request_layout()`].
73 fn prepaint(
74 &mut self,
75 id: Option<&GlobalElementId>,
76 bounds: Bounds<Pixels>,
77 request_layout: &mut Self::RequestLayoutState,
78 window: &mut Window,
79 cx: &mut App,
80 ) -> Self::PrepaintState;
81
82 /// Once layout has been completed, this method will be called to paint the element to the screen.
83 /// The state argument is the same state that was returned from [`Element::request_layout()`].
84 fn paint(
85 &mut self,
86 id: Option<&GlobalElementId>,
87 bounds: Bounds<Pixels>,
88 request_layout: &mut Self::RequestLayoutState,
89 prepaint: &mut Self::PrepaintState,
90 window: &mut Window,
91 cx: &mut App,
92 );
93
94 /// Convert this element into a dynamically-typed [`AnyElement`].
95 fn into_any(self) -> AnyElement {
96 AnyElement::new(self)
97 }
98}
99
100/// Implemented by any type that can be converted into an element.
101pub trait IntoElement: Sized {
102 /// The specific type of element into which the implementing type is converted.
103 /// Useful for converting other types into elements automatically, like Strings
104 type Element: Element;
105
106 /// Convert self into a type that implements [`Element`].
107 fn into_element(self) -> Self::Element;
108
109 /// Convert self into a dynamically-typed [`AnyElement`].
110 fn into_any_element(self) -> AnyElement {
111 self.into_element().into_any()
112 }
113}
114
115impl<T: IntoElement> FluentBuilder for T {}
116
117/// An object that can be drawn to the screen. This is the trait that distinguishes "views" from
118/// other entities. Views are `Entity`'s which `impl Render` and drawn to the screen.
119pub trait Render: 'static + Sized {
120 /// Render this view into an element tree.
121 fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement;
122}
123
124impl Render for Empty {
125 fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
126 Empty
127 }
128}
129
130/// You can derive [`IntoElement`] on any type that implements this trait.
131/// It is used to construct reusable `components` out of plain data. Think of
132/// components as a recipe for a certain pattern of elements. RenderOnce allows
133/// you to invoke this pattern, without breaking the fluent builder pattern of
134/// the element APIs.
135pub trait RenderOnce: 'static {
136 /// Render this component into an element tree. Note that this method
137 /// takes ownership of self, as compared to [`Render::render()`] method
138 /// which takes a mutable reference.
139 fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement;
140}
141
142/// This is a helper trait to provide a uniform interface for constructing elements that
143/// can accept any number of any kind of child elements
144pub trait ParentElement {
145 /// Extend this element's children with the given child elements.
146 fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>);
147
148 /// Add a single child element to this element.
149 fn child(mut self, child: impl IntoElement) -> Self
150 where
151 Self: Sized,
152 {
153 self.extend(std::iter::once(child.into_element().into_any()));
154 self
155 }
156
157 /// Add multiple child elements to this element.
158 fn children(mut self, children: impl IntoIterator<Item = impl IntoElement>) -> Self
159 where
160 Self: Sized,
161 {
162 self.extend(children.into_iter().map(|child| child.into_any_element()));
163 self
164 }
165}
166
167/// An element for rendering components. An implementation detail of the [`IntoElement`] derive macro
168/// for [`RenderOnce`]
169#[doc(hidden)]
170pub struct Component<C: RenderOnce>(Option<C>);
171
172impl<C: RenderOnce> Component<C> {
173 /// Create a new component from the given RenderOnce type.
174 pub fn new(component: C) -> Self {
175 Component(Some(component))
176 }
177}
178
179impl<C: RenderOnce> Element for Component<C> {
180 type RequestLayoutState = AnyElement;
181 type PrepaintState = ();
182
183 fn id(&self) -> Option<ElementId> {
184 None
185 }
186
187 fn request_layout(
188 &mut self,
189 _id: Option<&GlobalElementId>,
190 window: &mut Window,
191 cx: &mut App,
192 ) -> (LayoutId, Self::RequestLayoutState) {
193 let mut element = self.0.take().unwrap().render(window, cx).into_any_element();
194 let layout_id = element.request_layout(window, cx);
195 (layout_id, element)
196 }
197
198 fn prepaint(
199 &mut self,
200 _id: Option<&GlobalElementId>,
201 _: Bounds<Pixels>,
202 element: &mut AnyElement,
203 window: &mut Window,
204 cx: &mut App,
205 ) {
206 element.prepaint(window, cx);
207 }
208
209 fn paint(
210 &mut self,
211 _id: Option<&GlobalElementId>,
212 _: Bounds<Pixels>,
213 element: &mut Self::RequestLayoutState,
214 _: &mut Self::PrepaintState,
215 window: &mut Window,
216 cx: &mut App,
217 ) {
218 element.paint(window, cx);
219 }
220}
221
222impl<C: RenderOnce> IntoElement for Component<C> {
223 type Element = Self;
224
225 fn into_element(self) -> Self::Element {
226 self
227 }
228}
229
230/// A globally unique identifier for an element, used to track state across frames.
231#[derive(Deref, DerefMut, Default, Debug, Eq, PartialEq, Hash)]
232pub struct GlobalElementId(pub(crate) SmallVec<[ElementId; 32]>);
233
234trait ElementObject {
235 fn inner_element(&mut self) -> &mut dyn Any;
236
237 fn request_layout(&mut self, window: &mut Window, cx: &mut App) -> LayoutId;
238
239 fn prepaint(&mut self, window: &mut Window, cx: &mut App);
240
241 fn paint(&mut self, window: &mut Window, cx: &mut App);
242
243 fn layout_as_root(
244 &mut self,
245 available_space: Size<AvailableSpace>,
246 window: &mut Window,
247 cx: &mut App,
248 ) -> Size<Pixels>;
249}
250
251/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.
252pub struct Drawable<E: Element> {
253 /// The drawn element.
254 pub element: E,
255 phase: ElementDrawPhase<E::RequestLayoutState, E::PrepaintState>,
256}
257
258#[derive(Default)]
259enum ElementDrawPhase<RequestLayoutState, PrepaintState> {
260 #[default]
261 Start,
262 RequestLayout {
263 layout_id: LayoutId,
264 global_id: Option<GlobalElementId>,
265 request_layout: RequestLayoutState,
266 },
267 LayoutComputed {
268 layout_id: LayoutId,
269 global_id: Option<GlobalElementId>,
270 available_space: Size<AvailableSpace>,
271 request_layout: RequestLayoutState,
272 },
273 Prepaint {
274 node_id: DispatchNodeId,
275 global_id: Option<GlobalElementId>,
276 bounds: Bounds<Pixels>,
277 request_layout: RequestLayoutState,
278 prepaint: PrepaintState,
279 },
280 Painted,
281}
282
283/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.
284impl<E: Element> Drawable<E> {
285 pub(crate) fn new(element: E) -> Self {
286 Drawable {
287 element,
288 phase: ElementDrawPhase::Start,
289 }
290 }
291
292 fn request_layout(&mut self, window: &mut Window, cx: &mut App) -> LayoutId {
293 match mem::take(&mut self.phase) {
294 ElementDrawPhase::Start => {
295 let global_id = self.element.id().map(|element_id| {
296 window.element_id_stack.push(element_id);
297 GlobalElementId(window.element_id_stack.clone())
298 });
299
300 let (layout_id, request_layout) =
301 self.element.request_layout(global_id.as_ref(), window, cx);
302
303 if global_id.is_some() {
304 window.element_id_stack.pop();
305 }
306
307 self.phase = ElementDrawPhase::RequestLayout {
308 layout_id,
309 global_id,
310 request_layout,
311 };
312 layout_id
313 }
314 _ => panic!("must call request_layout only once"),
315 }
316 }
317
318 pub(crate) fn prepaint(&mut self, window: &mut Window, cx: &mut App) {
319 match mem::take(&mut self.phase) {
320 ElementDrawPhase::RequestLayout {
321 layout_id,
322 global_id,
323 mut request_layout,
324 }
325 | ElementDrawPhase::LayoutComputed {
326 layout_id,
327 global_id,
328 mut request_layout,
329 ..
330 } => {
331 if let Some(element_id) = self.element.id() {
332 window.element_id_stack.push(element_id);
333 debug_assert_eq!(global_id.as_ref().unwrap().0, window.element_id_stack);
334 }
335
336 let bounds = window.layout_bounds(layout_id);
337 let node_id = window.next_frame.dispatch_tree.push_node();
338 let prepaint = self.element.prepaint(
339 global_id.as_ref(),
340 bounds,
341 &mut request_layout,
342 window,
343 cx,
344 );
345 window.next_frame.dispatch_tree.pop_node();
346
347 if global_id.is_some() {
348 window.element_id_stack.pop();
349 }
350
351 self.phase = ElementDrawPhase::Prepaint {
352 node_id,
353 global_id,
354 bounds,
355 request_layout,
356 prepaint,
357 };
358 }
359 _ => panic!("must call request_layout before prepaint"),
360 }
361 }
362
363 pub(crate) fn paint(
364 &mut self,
365 window: &mut Window,
366 cx: &mut App,
367 ) -> (E::RequestLayoutState, E::PrepaintState) {
368 match mem::take(&mut self.phase) {
369 ElementDrawPhase::Prepaint {
370 node_id,
371 global_id,
372 bounds,
373 mut request_layout,
374 mut prepaint,
375 ..
376 } => {
377 if let Some(element_id) = self.element.id() {
378 window.element_id_stack.push(element_id);
379 debug_assert_eq!(global_id.as_ref().unwrap().0, window.element_id_stack);
380 }
381
382 window.next_frame.dispatch_tree.set_active_node(node_id);
383 self.element.paint(
384 global_id.as_ref(),
385 bounds,
386 &mut request_layout,
387 &mut prepaint,
388 window,
389 cx,
390 );
391
392 if global_id.is_some() {
393 window.element_id_stack.pop();
394 }
395
396 self.phase = ElementDrawPhase::Painted;
397 (request_layout, prepaint)
398 }
399 _ => panic!("must call prepaint before paint"),
400 }
401 }
402
403 pub(crate) fn layout_as_root(
404 &mut self,
405 available_space: Size<AvailableSpace>,
406 window: &mut Window,
407 cx: &mut App,
408 ) -> Size<Pixels> {
409 if matches!(&self.phase, ElementDrawPhase::Start) {
410 self.request_layout(window, cx);
411 }
412
413 let layout_id = match mem::take(&mut self.phase) {
414 ElementDrawPhase::RequestLayout {
415 layout_id,
416 global_id,
417 request_layout,
418 } => {
419 window.compute_layout(layout_id, available_space, cx);
420 self.phase = ElementDrawPhase::LayoutComputed {
421 layout_id,
422 global_id,
423 available_space,
424 request_layout,
425 };
426 layout_id
427 }
428 ElementDrawPhase::LayoutComputed {
429 layout_id,
430 global_id,
431 available_space: prev_available_space,
432 request_layout,
433 } => {
434 if available_space != prev_available_space {
435 window.compute_layout(layout_id, available_space, cx);
436 }
437 self.phase = ElementDrawPhase::LayoutComputed {
438 layout_id,
439 global_id,
440 available_space,
441 request_layout,
442 };
443 layout_id
444 }
445 _ => panic!("cannot measure after painting"),
446 };
447
448 window.layout_bounds(layout_id).size
449 }
450}
451
452impl<E> ElementObject for Drawable<E>
453where
454 E: Element,
455 E::RequestLayoutState: 'static,
456{
457 fn inner_element(&mut self) -> &mut dyn Any {
458 &mut self.element
459 }
460
461 fn request_layout(&mut self, window: &mut Window, cx: &mut App) -> LayoutId {
462 Drawable::request_layout(self, window, cx)
463 }
464
465 fn prepaint(&mut self, window: &mut Window, cx: &mut App) {
466 Drawable::prepaint(self, window, cx);
467 }
468
469 fn paint(&mut self, window: &mut Window, cx: &mut App) {
470 Drawable::paint(self, window, cx);
471 }
472
473 fn layout_as_root(
474 &mut self,
475 available_space: Size<AvailableSpace>,
476 window: &mut Window,
477 cx: &mut App,
478 ) -> Size<Pixels> {
479 Drawable::layout_as_root(self, available_space, window, cx)
480 }
481}
482
483/// A dynamically typed element that can be used to store any element type.
484pub struct AnyElement(ArenaBox<dyn ElementObject>);
485
486impl AnyElement {
487 pub(crate) fn new<E>(element: E) -> Self
488 where
489 E: 'static + Element,
490 E::RequestLayoutState: Any,
491 {
492 let element = ELEMENT_ARENA
493 .with_borrow_mut(|arena| arena.alloc(|| Drawable::new(element)))
494 .map(|element| element as &mut dyn ElementObject);
495 AnyElement(element)
496 }
497
498 /// Attempt to downcast a reference to the boxed element to a specific type.
499 pub fn downcast_mut<T: 'static>(&mut self) -> Option<&mut T> {
500 self.0.inner_element().downcast_mut::<T>()
501 }
502
503 /// Request the layout ID of the element stored in this `AnyElement`.
504 /// Used for laying out child elements in a parent element.
505 pub fn request_layout(&mut self, window: &mut Window, cx: &mut App) -> LayoutId {
506 self.0.request_layout(window, cx)
507 }
508
509 /// Prepares the element to be painted by storing its bounds, giving it a chance to draw hitboxes and
510 /// request autoscroll before the final paint pass is confirmed.
511 pub fn prepaint(&mut self, window: &mut Window, cx: &mut App) -> Option<FocusHandle> {
512 let focus_assigned = window.next_frame.focus.is_some();
513
514 self.0.prepaint(window, cx);
515
516 if !focus_assigned {
517 if let Some(focus_id) = window.next_frame.focus {
518 return FocusHandle::for_id(focus_id, &cx.focus_handles);
519 }
520 }
521
522 None
523 }
524
525 /// Paints the element stored in this `AnyElement`.
526 pub fn paint(&mut self, window: &mut Window, cx: &mut App) {
527 self.0.paint(window, cx);
528 }
529
530 /// Performs layout for this element within the given available space and returns its size.
531 pub fn layout_as_root(
532 &mut self,
533 available_space: Size<AvailableSpace>,
534 window: &mut Window,
535 cx: &mut App,
536 ) -> Size<Pixels> {
537 self.0.layout_as_root(available_space, window, cx)
538 }
539
540 /// Prepaints this element at the given absolute origin.
541 /// If any element in the subtree beneath this element is focused, its FocusHandle is returned.
542 pub fn prepaint_at(
543 &mut self,
544 origin: Point<Pixels>,
545 window: &mut Window,
546 cx: &mut App,
547 ) -> Option<FocusHandle> {
548 window.with_absolute_element_offset(origin, |window| self.prepaint(window, cx))
549 }
550
551 /// Performs layout on this element in the available space, then prepaints it at the given absolute origin.
552 /// If any element in the subtree beneath this element is focused, its FocusHandle is returned.
553 pub fn prepaint_as_root(
554 &mut self,
555 origin: Point<Pixels>,
556 available_space: Size<AvailableSpace>,
557 window: &mut Window,
558 cx: &mut App,
559 ) -> Option<FocusHandle> {
560 self.layout_as_root(available_space, window, cx);
561 window.with_absolute_element_offset(origin, |window| self.prepaint(window, cx))
562 }
563}
564
565impl Element for AnyElement {
566 type RequestLayoutState = ();
567 type PrepaintState = ();
568
569 fn id(&self) -> Option<ElementId> {
570 None
571 }
572
573 fn request_layout(
574 &mut self,
575 _: Option<&GlobalElementId>,
576 window: &mut Window,
577 cx: &mut App,
578 ) -> (LayoutId, Self::RequestLayoutState) {
579 let layout_id = self.request_layout(window, cx);
580 (layout_id, ())
581 }
582
583 fn prepaint(
584 &mut self,
585 _: Option<&GlobalElementId>,
586 _: Bounds<Pixels>,
587 _: &mut Self::RequestLayoutState,
588 window: &mut Window,
589 cx: &mut App,
590 ) {
591 self.prepaint(window, cx);
592 }
593
594 fn paint(
595 &mut self,
596 _: Option<&GlobalElementId>,
597 _: Bounds<Pixels>,
598 _: &mut Self::RequestLayoutState,
599 _: &mut Self::PrepaintState,
600 window: &mut Window,
601 cx: &mut App,
602 ) {
603 self.paint(window, cx);
604 }
605}
606
607impl IntoElement for AnyElement {
608 type Element = Self;
609
610 fn into_element(self) -> Self::Element {
611 self
612 }
613
614 fn into_any_element(self) -> AnyElement {
615 self
616 }
617}
618
619/// The empty element, which renders nothing.
620pub struct Empty;
621
622impl IntoElement for Empty {
623 type Element = Self;
624
625 fn into_element(self) -> Self::Element {
626 self
627 }
628}
629
630impl Element for Empty {
631 type RequestLayoutState = ();
632 type PrepaintState = ();
633
634 fn id(&self) -> Option<ElementId> {
635 None
636 }
637
638 fn request_layout(
639 &mut self,
640 _id: Option<&GlobalElementId>,
641 window: &mut Window,
642 cx: &mut App,
643 ) -> (LayoutId, Self::RequestLayoutState) {
644 (window.request_layout(Style::default(), None, cx), ())
645 }
646
647 fn prepaint(
648 &mut self,
649 _id: Option<&GlobalElementId>,
650 _bounds: Bounds<Pixels>,
651 _state: &mut Self::RequestLayoutState,
652 _window: &mut Window,
653 _cx: &mut App,
654 ) {
655 }
656
657 fn paint(
658 &mut self,
659 _id: Option<&GlobalElementId>,
660 _bounds: Bounds<Pixels>,
661 _request_layout: &mut Self::RequestLayoutState,
662 _prepaint: &mut Self::PrepaintState,
663 _window: &mut Window,
664 _cx: &mut App,
665 ) {
666 }
667}