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, ElementId, LayoutId,
36 Pixels, Point, Size, Style, ViewContext, WindowContext, ELEMENT_ARENA,
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 /// 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 WindowContext) -> (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 WindowContext,
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 WindowContext,
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 WindowContext) -> (LayoutId, Self::RequestLayoutState) {
168 let mut element = self.0.take().unwrap().render(cx).into_any_element();
169 let layout_id = element.request_layout(cx);
170 (layout_id, element)
171 }
172
173 fn prepaint(&mut self, _: Bounds<Pixels>, element: &mut AnyElement, cx: &mut WindowContext) {
174 element.prepaint(cx);
175 }
176
177 fn paint(
178 &mut self,
179 _: Bounds<Pixels>,
180 element: &mut Self::RequestLayoutState,
181 _: &mut Self::PrepaintState,
182 cx: &mut WindowContext,
183 ) {
184 element.paint(cx)
185 }
186}
187
188impl<C: RenderOnce> IntoElement for Component<C> {
189 type Element = Self;
190
191 fn into_element(self) -> Self::Element {
192 self
193 }
194}
195
196/// A globally unique identifier for an element, used to track state across frames.
197#[derive(Deref, DerefMut, Default, Clone, Debug, Eq, PartialEq, Hash)]
198pub(crate) struct GlobalElementId(SmallVec<[ElementId; 32]>);
199
200trait ElementObject {
201 fn inner_element(&mut self) -> &mut dyn Any;
202
203 fn request_layout(&mut self, cx: &mut WindowContext) -> LayoutId;
204
205 fn prepaint(&mut self, cx: &mut WindowContext);
206
207 fn paint(&mut self, cx: &mut WindowContext);
208
209 fn layout_as_root(
210 &mut self,
211 available_space: Size<AvailableSpace>,
212 cx: &mut WindowContext,
213 ) -> Size<Pixels>;
214}
215
216/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.
217pub struct Drawable<E: Element> {
218 /// The drawn element.
219 pub element: E,
220 phase: ElementDrawPhase<E::RequestLayoutState, E::PrepaintState>,
221}
222
223#[derive(Default)]
224enum ElementDrawPhase<RequestLayoutState, PrepaintState> {
225 #[default]
226 Start,
227 RequestLayoutState {
228 layout_id: LayoutId,
229 request_layout: RequestLayoutState,
230 },
231 LayoutComputed {
232 layout_id: LayoutId,
233 available_space: Size<AvailableSpace>,
234 request_layout: RequestLayoutState,
235 },
236 PrepaintState {
237 node_id: DispatchNodeId,
238 bounds: Bounds<Pixels>,
239 request_layout: RequestLayoutState,
240 prepaint: PrepaintState,
241 },
242 Painted,
243}
244
245/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.
246impl<E: Element> Drawable<E> {
247 pub(crate) fn new(element: E) -> Self {
248 Drawable {
249 element,
250 phase: ElementDrawPhase::Start,
251 }
252 }
253
254 fn request_layout(&mut self, cx: &mut WindowContext) -> LayoutId {
255 match mem::take(&mut self.phase) {
256 ElementDrawPhase::Start => {
257 let (layout_id, request_layout) = self.element.request_layout(cx);
258 self.phase = ElementDrawPhase::RequestLayoutState {
259 layout_id,
260 request_layout,
261 };
262 layout_id
263 }
264 _ => panic!("must call request_layout only once"),
265 }
266 }
267
268 pub(crate) fn prepaint(&mut self, cx: &mut WindowContext) {
269 match mem::take(&mut self.phase) {
270 ElementDrawPhase::RequestLayoutState {
271 layout_id,
272 mut request_layout,
273 }
274 | ElementDrawPhase::LayoutComputed {
275 layout_id,
276 mut request_layout,
277 ..
278 } => {
279 let bounds = cx.layout_bounds(layout_id);
280 let node_id = cx.window.next_frame.dispatch_tree.push_node();
281 let prepaint = self.element.prepaint(bounds, &mut request_layout, cx);
282 self.phase = ElementDrawPhase::PrepaintState {
283 node_id,
284 bounds,
285 request_layout,
286 prepaint,
287 };
288 cx.window.next_frame.dispatch_tree.pop_node();
289 }
290 _ => panic!("must call request_layout before prepaint"),
291 }
292 }
293
294 pub(crate) fn paint(
295 &mut self,
296 cx: &mut WindowContext,
297 ) -> (E::RequestLayoutState, E::PrepaintState) {
298 match mem::take(&mut self.phase) {
299 ElementDrawPhase::PrepaintState {
300 node_id,
301 bounds,
302 mut request_layout,
303 mut prepaint,
304 ..
305 } => {
306 cx.window.next_frame.dispatch_tree.set_active_node(node_id);
307 self.element
308 .paint(bounds, &mut request_layout, &mut prepaint, cx);
309 self.phase = ElementDrawPhase::Painted;
310 (request_layout, prepaint)
311 }
312 _ => panic!("must call prepaint before paint"),
313 }
314 }
315
316 pub(crate) fn layout_as_root(
317 &mut self,
318 available_space: Size<AvailableSpace>,
319 cx: &mut WindowContext,
320 ) -> Size<Pixels> {
321 if matches!(&self.phase, ElementDrawPhase::Start) {
322 self.request_layout(cx);
323 }
324
325 let layout_id = match mem::take(&mut self.phase) {
326 ElementDrawPhase::RequestLayoutState {
327 layout_id,
328 request_layout,
329 } => {
330 cx.compute_layout(layout_id, available_space);
331 self.phase = ElementDrawPhase::LayoutComputed {
332 layout_id,
333 available_space,
334 request_layout,
335 };
336 layout_id
337 }
338 ElementDrawPhase::LayoutComputed {
339 layout_id,
340 available_space: prev_available_space,
341 request_layout,
342 } => {
343 if available_space != prev_available_space {
344 cx.compute_layout(layout_id, available_space);
345 }
346 self.phase = ElementDrawPhase::LayoutComputed {
347 layout_id,
348 available_space,
349 request_layout,
350 };
351 layout_id
352 }
353 _ => panic!("cannot measure after painting"),
354 };
355
356 cx.layout_bounds(layout_id).size
357 }
358}
359
360impl<E> ElementObject for Drawable<E>
361where
362 E: Element,
363 E::RequestLayoutState: 'static,
364{
365 fn inner_element(&mut self) -> &mut dyn Any {
366 &mut self.element
367 }
368
369 fn request_layout(&mut self, cx: &mut WindowContext) -> LayoutId {
370 Drawable::request_layout(self, cx)
371 }
372
373 fn prepaint(&mut self, cx: &mut WindowContext) {
374 Drawable::prepaint(self, cx);
375 }
376
377 fn paint(&mut self, cx: &mut WindowContext) {
378 Drawable::paint(self, cx);
379 }
380
381 fn layout_as_root(
382 &mut self,
383 available_space: Size<AvailableSpace>,
384 cx: &mut WindowContext,
385 ) -> Size<Pixels> {
386 Drawable::layout_as_root(self, available_space, cx)
387 }
388}
389
390/// A dynamically typed element that can be used to store any element type.
391pub struct AnyElement(ArenaBox<dyn ElementObject>);
392
393impl AnyElement {
394 pub(crate) fn new<E>(element: E) -> Self
395 where
396 E: 'static + Element,
397 E::RequestLayoutState: Any,
398 {
399 let element = ELEMENT_ARENA
400 .with_borrow_mut(|arena| arena.alloc(|| Drawable::new(element)))
401 .map(|element| element as &mut dyn ElementObject);
402 AnyElement(element)
403 }
404
405 /// Attempt to downcast a reference to the boxed element to a specific type.
406 pub fn downcast_mut<T: 'static>(&mut self) -> Option<&mut T> {
407 self.0.inner_element().downcast_mut::<T>()
408 }
409
410 /// Request the layout ID of the element stored in this `AnyElement`.
411 /// Used for laying out child elements in a parent element.
412 pub fn request_layout(&mut self, cx: &mut WindowContext) -> LayoutId {
413 self.0.request_layout(cx)
414 }
415
416 /// Prepares the element to be painted by storing its bounds, giving it a chance to draw hitboxes and
417 /// request autoscroll before the final paint pass is confirmed.
418 pub fn prepaint(&mut self, cx: &mut WindowContext) {
419 self.0.prepaint(cx)
420 }
421
422 /// Paints the element stored in this `AnyElement`.
423 pub fn paint(&mut self, cx: &mut WindowContext) {
424 self.0.paint(cx)
425 }
426
427 /// Performs layout for this element within the given available space and returns its size.
428 pub fn layout_as_root(
429 &mut self,
430 available_space: Size<AvailableSpace>,
431 cx: &mut WindowContext,
432 ) -> Size<Pixels> {
433 self.0.layout_as_root(available_space, cx)
434 }
435
436 /// Prepaints this element at the given absolute origin.
437 pub fn prepaint_at(&mut self, origin: Point<Pixels>, cx: &mut WindowContext) {
438 cx.with_absolute_element_offset(origin, |cx| self.0.prepaint(cx));
439 }
440
441 /// Performs layout on this element in the available space, then prepaints it at the given absolute origin.
442 pub fn prepaint_as_root(
443 &mut self,
444 origin: Point<Pixels>,
445 available_space: Size<AvailableSpace>,
446 cx: &mut WindowContext,
447 ) {
448 self.layout_as_root(available_space, cx);
449 cx.with_absolute_element_offset(origin, |cx| self.0.prepaint(cx));
450 }
451}
452
453impl Element for AnyElement {
454 type RequestLayoutState = ();
455 type PrepaintState = ();
456
457 fn request_layout(&mut self, cx: &mut WindowContext) -> (LayoutId, Self::RequestLayoutState) {
458 let layout_id = self.request_layout(cx);
459 (layout_id, ())
460 }
461
462 fn prepaint(
463 &mut self,
464 _: Bounds<Pixels>,
465 _: &mut Self::RequestLayoutState,
466 cx: &mut WindowContext,
467 ) {
468 self.prepaint(cx)
469 }
470
471 fn paint(
472 &mut self,
473 _: Bounds<Pixels>,
474 _: &mut Self::RequestLayoutState,
475 _: &mut Self::PrepaintState,
476 cx: &mut WindowContext,
477 ) {
478 self.paint(cx)
479 }
480}
481
482impl IntoElement for AnyElement {
483 type Element = Self;
484
485 fn into_element(self) -> Self::Element {
486 self
487 }
488
489 fn into_any_element(self) -> AnyElement {
490 self
491 }
492}
493
494/// The empty element, which renders nothing.
495pub struct Empty;
496
497impl IntoElement for Empty {
498 type Element = Self;
499
500 fn into_element(self) -> Self::Element {
501 self
502 }
503}
504
505impl Element for Empty {
506 type RequestLayoutState = ();
507 type PrepaintState = ();
508
509 fn request_layout(&mut self, cx: &mut WindowContext) -> (LayoutId, Self::RequestLayoutState) {
510 (cx.request_layout(&Style::default(), None), ())
511 }
512
513 fn prepaint(
514 &mut self,
515 _bounds: Bounds<Pixels>,
516 _state: &mut Self::RequestLayoutState,
517 _cx: &mut WindowContext,
518 ) {
519 }
520
521 fn paint(
522 &mut self,
523 _bounds: Bounds<Pixels>,
524 _request_layout: &mut Self::RequestLayoutState,
525 _prepaint: &mut Self::PrepaintState,
526 _cx: &mut WindowContext,
527 ) {
528 }
529}