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, which
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 util::FluentBuilder, ArenaBox, AvailableSpace, Bounds, DispatchNodeId, ElementContext,
36 ElementId, LayoutId, Pixels, Point, Size, ViewContext, WindowContext, ELEMENT_ARENA,
37};
38use derive_more::{Deref, DerefMut};
39pub(crate) use smallvec::SmallVec;
40use std::{any::Any, fmt::Debug, mem, ops::DerefMut};
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 /// Before an element can be painted, we need to know where it's going to be and how big it is.
56 /// Use this method to request a layout from Taffy and initialize the element's state.
57 fn request_layout(&mut self, cx: &mut ElementContext) -> (LayoutId, Self::RequestLayoutState);
58
59 /// After laying out an element, we need to commit its bounds to the current frame for hitbox
60 /// purposes. The state argument is the same state that was returned from [`Element::request_layout()`].
61 fn prepaint(
62 &mut self,
63 bounds: Bounds<Pixels>,
64 request_layout: &mut Self::RequestLayoutState,
65 cx: &mut ElementContext,
66 ) -> Self::PrepaintState;
67
68 /// Once layout has been completed, this method will be called to paint the element to the screen.
69 /// The state argument is the same state that was returned from [`Element::request_layout()`].
70 fn paint(
71 &mut self,
72 bounds: Bounds<Pixels>,
73 request_layout: &mut Self::RequestLayoutState,
74 prepaint: &mut Self::PrepaintState,
75 cx: &mut ElementContext,
76 );
77
78 /// Convert this element into a dynamically-typed [`AnyElement`].
79 fn into_any(self) -> AnyElement {
80 AnyElement::new(self)
81 }
82}
83
84/// Implemented by any type that can be converted into an element.
85pub trait IntoElement: Sized {
86 /// The specific type of element into which the implementing type is converted.
87 /// Useful for converting other types into elements automatically, like Strings
88 type Element: Element;
89
90 /// Convert self into a type that implements [`Element`].
91 fn into_element(self) -> Self::Element;
92
93 /// Convert self into a dynamically-typed [`AnyElement`].
94 fn into_any_element(self) -> AnyElement {
95 self.into_element().into_any()
96 }
97}
98
99impl<T: IntoElement> FluentBuilder for T {}
100
101/// An object that can be drawn to the screen. This is the trait that distinguishes `Views` from
102/// models. Views are drawn to the screen and care about the current window's state, models are not and do not.
103pub trait Render: 'static + Sized {
104 /// Render this view into an element tree.
105 fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement;
106}
107
108impl Render for Empty {
109 fn render(&mut self, _cx: &mut ViewContext<Self>) -> impl IntoElement {
110 Empty
111 }
112}
113
114/// You can derive [`IntoElement`] on any type that implements this trait.
115/// It is used to construct reusable `components` out of plain data. Think of
116/// components as a recipe for a certain pattern of elements. RenderOnce allows
117/// you to invoke this pattern, without breaking the fluent builder pattern of
118/// the element APIs.
119pub trait RenderOnce: 'static {
120 /// Render this component into an element tree. Note that this method
121 /// takes ownership of self, as compared to [`Render::render()`] method
122 /// which takes a mutable reference.
123 fn render(self, cx: &mut WindowContext) -> impl IntoElement;
124}
125
126/// This is a helper trait to provide a uniform interface for constructing elements that
127/// can accept any number of any kind of child elements
128pub trait ParentElement {
129 /// Extend this element's children with the given child elements.
130 fn extend(&mut self, elements: impl Iterator<Item = AnyElement>);
131
132 /// Add a single child element to this element.
133 fn child(mut self, child: impl IntoElement) -> Self
134 where
135 Self: Sized,
136 {
137 self.extend(std::iter::once(child.into_element().into_any()));
138 self
139 }
140
141 /// Add multiple child elements to this element.
142 fn children(mut self, children: impl IntoIterator<Item = impl IntoElement>) -> Self
143 where
144 Self: Sized,
145 {
146 self.extend(children.into_iter().map(|child| child.into_any_element()));
147 self
148 }
149}
150
151/// An element for rendering components. An implementation detail of the [`IntoElement`] derive macro
152/// for [`RenderOnce`]
153#[doc(hidden)]
154pub struct Component<C: RenderOnce>(Option<C>);
155
156impl<C: RenderOnce> Component<C> {
157 /// Create a new component from the given RenderOnce type.
158 pub fn new(component: C) -> Self {
159 Component(Some(component))
160 }
161}
162
163impl<C: RenderOnce> Element for Component<C> {
164 type RequestLayoutState = AnyElement;
165 type PrepaintState = ();
166
167 fn request_layout(&mut self, cx: &mut ElementContext) -> (LayoutId, Self::RequestLayoutState) {
168 let mut element = self
169 .0
170 .take()
171 .unwrap()
172 .render(cx.deref_mut())
173 .into_any_element();
174 let layout_id = element.request_layout(cx);
175 (layout_id, element)
176 }
177
178 fn prepaint(&mut self, _: Bounds<Pixels>, element: &mut AnyElement, cx: &mut ElementContext) {
179 element.prepaint(cx);
180 }
181
182 fn paint(
183 &mut self,
184 _: Bounds<Pixels>,
185 element: &mut Self::RequestLayoutState,
186 _: &mut Self::PrepaintState,
187 cx: &mut ElementContext,
188 ) {
189 element.paint(cx)
190 }
191}
192
193impl<C: RenderOnce> IntoElement for Component<C> {
194 type Element = Self;
195
196 fn into_element(self) -> Self::Element {
197 self
198 }
199}
200
201/// A globally unique identifier for an element, used to track state across frames.
202#[derive(Deref, DerefMut, Default, Clone, Debug, Eq, PartialEq, Hash)]
203pub(crate) struct GlobalElementId(SmallVec<[ElementId; 32]>);
204
205trait ElementObject {
206 fn inner_element(&mut self) -> &mut dyn Any;
207
208 fn request_layout(&mut self, cx: &mut ElementContext) -> LayoutId;
209
210 fn prepaint(&mut self, cx: &mut ElementContext);
211
212 fn paint(&mut self, cx: &mut ElementContext);
213
214 fn layout_as_root(
215 &mut self,
216 available_space: Size<AvailableSpace>,
217 cx: &mut ElementContext,
218 ) -> Size<Pixels>;
219}
220
221/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.
222pub struct Drawable<E: Element> {
223 /// The drawn element.
224 pub element: E,
225 phase: ElementDrawPhase<E::RequestLayoutState, E::PrepaintState>,
226}
227
228#[derive(Default)]
229enum ElementDrawPhase<RequestLayoutState, PrepaintState> {
230 #[default]
231 Start,
232 RequestLayoutState {
233 layout_id: LayoutId,
234 request_layout: RequestLayoutState,
235 },
236 LayoutComputed {
237 layout_id: LayoutId,
238 available_space: Size<AvailableSpace>,
239 request_layout: RequestLayoutState,
240 },
241 PrepaintState {
242 node_id: DispatchNodeId,
243 bounds: Bounds<Pixels>,
244 request_layout: RequestLayoutState,
245 prepaint: PrepaintState,
246 },
247 Painted,
248}
249
250/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.
251impl<E: Element> Drawable<E> {
252 fn new(element: E) -> Self {
253 Drawable {
254 element,
255 phase: ElementDrawPhase::Start,
256 }
257 }
258
259 fn request_layout(&mut self, cx: &mut ElementContext) -> LayoutId {
260 match mem::take(&mut self.phase) {
261 ElementDrawPhase::Start => {
262 let (layout_id, request_layout) = self.element.request_layout(cx);
263 self.phase = ElementDrawPhase::RequestLayoutState {
264 layout_id,
265 request_layout,
266 };
267 layout_id
268 }
269 _ => panic!("must call request_layout only once"),
270 }
271 }
272
273 fn prepaint(&mut self, cx: &mut ElementContext) {
274 match mem::take(&mut self.phase) {
275 ElementDrawPhase::RequestLayoutState {
276 layout_id,
277 mut request_layout,
278 }
279 | ElementDrawPhase::LayoutComputed {
280 layout_id,
281 mut request_layout,
282 ..
283 } => {
284 let bounds = cx.layout_bounds(layout_id);
285 let node_id = cx.window.next_frame.dispatch_tree.push_node();
286 let prepaint = self.element.prepaint(bounds, &mut request_layout, cx);
287 self.phase = ElementDrawPhase::PrepaintState {
288 node_id,
289 bounds,
290 request_layout,
291 prepaint,
292 };
293 cx.window.next_frame.dispatch_tree.pop_node();
294 }
295 _ => panic!("must call request_layout before prepaint"),
296 }
297 }
298
299 fn paint(&mut self, cx: &mut ElementContext) -> E::RequestLayoutState {
300 match mem::take(&mut self.phase) {
301 ElementDrawPhase::PrepaintState {
302 node_id,
303 bounds,
304 mut request_layout,
305 mut prepaint,
306 ..
307 } => {
308 cx.window.next_frame.dispatch_tree.set_active_node(node_id);
309 self.element
310 .paint(bounds, &mut request_layout, &mut prepaint, cx);
311 self.phase = ElementDrawPhase::Painted;
312 request_layout
313 }
314 _ => panic!("must call prepaint before paint"),
315 }
316 }
317
318 fn layout_as_root(
319 &mut self,
320 available_space: Size<AvailableSpace>,
321 cx: &mut ElementContext,
322 ) -> Size<Pixels> {
323 if matches!(&self.phase, ElementDrawPhase::Start) {
324 self.request_layout(cx);
325 }
326
327 let layout_id = match mem::take(&mut self.phase) {
328 ElementDrawPhase::RequestLayoutState {
329 layout_id,
330 request_layout,
331 } => {
332 cx.compute_layout(layout_id, available_space);
333 self.phase = ElementDrawPhase::LayoutComputed {
334 layout_id,
335 available_space,
336 request_layout,
337 };
338 layout_id
339 }
340 ElementDrawPhase::LayoutComputed {
341 layout_id,
342 available_space: prev_available_space,
343 request_layout,
344 } => {
345 if available_space != prev_available_space {
346 cx.compute_layout(layout_id, available_space);
347 }
348 self.phase = ElementDrawPhase::LayoutComputed {
349 layout_id,
350 available_space,
351 request_layout,
352 };
353 layout_id
354 }
355 _ => panic!("cannot measure after painting"),
356 };
357
358 cx.layout_bounds(layout_id).size
359 }
360}
361
362impl<E> ElementObject for Drawable<E>
363where
364 E: Element,
365 E::RequestLayoutState: 'static,
366{
367 fn inner_element(&mut self) -> &mut dyn Any {
368 &mut self.element
369 }
370
371 fn request_layout(&mut self, cx: &mut ElementContext) -> LayoutId {
372 Drawable::request_layout(self, cx)
373 }
374
375 fn prepaint(&mut self, cx: &mut ElementContext) {
376 Drawable::prepaint(self, cx);
377 }
378
379 fn paint(&mut self, cx: &mut ElementContext) {
380 Drawable::paint(self, cx);
381 }
382
383 fn layout_as_root(
384 &mut self,
385 available_space: Size<AvailableSpace>,
386 cx: &mut ElementContext,
387 ) -> Size<Pixels> {
388 Drawable::layout_as_root(self, available_space, cx)
389 }
390}
391
392/// A dynamically typed element that can be used to store any element type.
393pub struct AnyElement(ArenaBox<dyn ElementObject>);
394
395impl AnyElement {
396 pub(crate) fn new<E>(element: E) -> Self
397 where
398 E: 'static + Element,
399 E::RequestLayoutState: Any,
400 {
401 let element = ELEMENT_ARENA
402 .with_borrow_mut(|arena| arena.alloc(|| Drawable::new(element)))
403 .map(|element| element as &mut dyn ElementObject);
404 AnyElement(element)
405 }
406
407 /// Attempt to downcast a reference to the boxed element to a specific type.
408 pub fn downcast_mut<T: 'static>(&mut self) -> Option<&mut T> {
409 self.0.inner_element().downcast_mut::<T>()
410 }
411
412 /// Request the layout ID of the element stored in this `AnyElement`.
413 /// Used for laying out child elements in a parent element.
414 pub fn request_layout(&mut self, cx: &mut ElementContext) -> LayoutId {
415 self.0.request_layout(cx)
416 }
417
418 /// Prepares the element to be painted by storing its bounds, giving it a chance to draw hitboxes and
419 /// request autoscroll before the final paint pass is confirmed.
420 pub fn prepaint(&mut self, cx: &mut ElementContext) {
421 self.0.prepaint(cx)
422 }
423
424 /// Paints the element stored in this `AnyElement`.
425 pub fn paint(&mut self, cx: &mut ElementContext) {
426 self.0.paint(cx)
427 }
428
429 /// Performs layout for this element within the given available space and returns its size.
430 pub fn layout_as_root(
431 &mut self,
432 available_space: Size<AvailableSpace>,
433 cx: &mut ElementContext,
434 ) -> Size<Pixels> {
435 self.0.layout_as_root(available_space, cx)
436 }
437
438 /// Prepaints this element at the given absolute origin.
439 pub fn prepaint_at(&mut self, origin: Point<Pixels>, cx: &mut ElementContext) {
440 cx.with_absolute_element_offset(origin, |cx| self.0.prepaint(cx));
441 }
442
443 /// Performs layout on this element in the available space, then prepaints it at the given absolute origin.
444 pub fn prepaint_as_root(
445 &mut self,
446 origin: Point<Pixels>,
447 available_space: Size<AvailableSpace>,
448 cx: &mut ElementContext,
449 ) {
450 self.layout_as_root(available_space, cx);
451 cx.with_absolute_element_offset(origin, |cx| self.0.prepaint(cx));
452 }
453}
454
455impl Element for AnyElement {
456 type RequestLayoutState = ();
457 type PrepaintState = ();
458
459 fn request_layout(&mut self, cx: &mut ElementContext) -> (LayoutId, Self::RequestLayoutState) {
460 let layout_id = self.request_layout(cx);
461 (layout_id, ())
462 }
463
464 fn prepaint(
465 &mut self,
466 _: Bounds<Pixels>,
467 _: &mut Self::RequestLayoutState,
468 cx: &mut ElementContext,
469 ) {
470 self.prepaint(cx)
471 }
472
473 fn paint(
474 &mut self,
475 _: Bounds<Pixels>,
476 _: &mut Self::RequestLayoutState,
477 _: &mut Self::PrepaintState,
478 cx: &mut ElementContext,
479 ) {
480 self.paint(cx)
481 }
482}
483
484impl IntoElement for AnyElement {
485 type Element = Self;
486
487 fn into_element(self) -> Self::Element {
488 self
489 }
490
491 fn into_any_element(self) -> AnyElement {
492 self
493 }
494}
495
496/// The empty element, which renders nothing.
497pub struct Empty;
498
499impl IntoElement for Empty {
500 type Element = Self;
501
502 fn into_element(self) -> Self::Element {
503 self
504 }
505}
506
507impl Element for Empty {
508 type RequestLayoutState = ();
509 type PrepaintState = ();
510
511 fn request_layout(&mut self, cx: &mut ElementContext) -> (LayoutId, Self::RequestLayoutState) {
512 (cx.request_layout(&crate::Style::default(), None), ())
513 }
514
515 fn prepaint(
516 &mut self,
517 _bounds: Bounds<Pixels>,
518 _state: &mut Self::RequestLayoutState,
519 _cx: &mut ElementContext,
520 ) {
521 }
522
523 fn paint(
524 &mut self,
525 _bounds: Bounds<Pixels>,
526 _request_layout: &mut Self::RequestLayoutState,
527 _prepaint: &mut Self::PrepaintState,
528 _cx: &mut ElementContext,
529 ) {
530 }
531}