//! Elements are the workhorses of GPUI. They are responsible for laying out and painting all of//! the contents of a window. Elements form a tree and are laid out according to the web layout//! standards as implemented by [taffy](https://github.com/DioxusLabs/taffy). Most of the time,//! you won't need to interact with this module or these APIs directly. Elements provide their//! own APIs and GPUI, or other element implementation, uses the APIs in this module to convert//! that element tree into the pixels you see on the screen.//!//! # Element Basics//!//! Elements are constructed by calling [`Render::render()`] on the root view of the window,//! which recursively constructs the element tree from the current state of the application,.//! These elements are then laid out by Taffy, and painted to the screen according to their own//! implementation of [`Element::paint()`]. Before the start of the next frame, the entire element//! tree and any callbacks they have registered with GPUI are dropped and the process repeats.//!//! But some state is too simple and voluminous to store in every view that needs it, e.g.//! whether a hover has been started or not. For this, GPUI provides the [`Element::PrepaintState`], associated type.//!//! # Implementing your own elements//!//! Elements are intended to be the low level, imperative API to GPUI. They are responsible for upholding,//! or breaking, GPUI's features as they deem necessary. As an example, most GPUI elements are expected//! to stay in the bounds that their parent element gives them. But with [`Window::with_content_mask`],//! you can ignore this restriction and paint anywhere inside of the window's bounds. This is useful for overlays//! and popups and anything else that shows up 'on top' of other elements.//! With great power, comes great responsibility.//!//! However, most of the time, you won't need to implement your own elements. GPUI provides a number of//! elements that should cover most common use cases out of the box and it's recommended that you use those//! to construct `components`, using the [`RenderOnce`] trait and the `#[derive(IntoElement)]` macro. Only implement//! elements when you need to take manual control of the layout and painting process, such as when using//! your own custom layout algorithm or rendering a code editor. use crate::{    A11ySubtreeBuilder, App, ArenaBox, AvailableSpace, Bounds, Context, DispatchNodeId, ElementId,    FocusHandle, InspectorElementId, LayoutId, Pixels, Point, Size, Style, Window,    util::FluentBuilder, window::with_element_arena,};use derive_more::{Deref, DerefMut};use std::{    any::Any,    fmt::{self, Debug, Display},    mem, panic,    sync::Arc,}; /// Implemented by types that participate in laying out and painting the contents of a window./// Elements form a tree and are laid out according to web-based layout rules, as implemented by Taffy./// You can create custom elements by implementing this trait, see the module-level documentation/// for more details.pub trait Element: 'static + IntoElement {    /// The type of state returned from [`Element::request_layout`]. A mutable reference to this state is subsequently    /// provided to [`Element::prepaint`] and [`Element::paint`].    type RequestLayoutState: 'static;     /// The type of state returned from [`Element::prepaint`]. A mutable reference to this state is subsequently    /// provided to [`Element::paint`].    type PrepaintState: 'static;     /// If this element has a unique identifier, return it here. This is used to track elements across frames, and    /// will cause a GlobalElementId to be passed to the request_layout, prepaint, and paint methods.    ///    /// The global id can in turn be used to access state that's connected to an element with the same id across    /// frames. This id must be unique among children of the first containing element with an id.    fn id(&self) -> Option<ElementId>;     /// Source location where this element was constructed, used to disambiguate elements in the    /// inspector and navigate to their source code.    fn source_location(&self) -> Option<&'static panic::Location<'static>>;     /// Before an element can be painted, we need to know where it's going to be and how big it is.    /// Use this method to request a layout from Taffy and initialize the element's state.    fn request_layout(        &mut self,        id: Option<&GlobalElementId>,        inspector_id: Option<&InspectorElementId>,        window: &mut Window,        cx: &mut App,    ) -> (LayoutId, Self::RequestLayoutState);     /// After laying out an element, we need to commit its bounds to the current frame for hitbox    /// purposes. The state argument is the same state that was returned from [`Element::request_layout()`].    fn prepaint(        &mut self,        id: Option<&GlobalElementId>,        inspector_id: Option<&InspectorElementId>,        bounds: Bounds<Pixels>,        request_layout: &mut Self::RequestLayoutState,        window: &mut Window,        cx: &mut App,    ) -> Self::PrepaintState;     /// Once layout has been completed, this method will be called to paint the element to the screen.    /// The state argument is the same state that was returned from [`Element::request_layout()`].    fn paint(        &mut self,        id: Option<&GlobalElementId>,        inspector_id: Option<&InspectorElementId>,        bounds: Bounds<Pixels>,        request_layout: &mut Self::RequestLayoutState,        prepaint: &mut Self::PrepaintState,        window: &mut Window,        cx: &mut App,    );     /// Returns the accessible role for this element, if any.    /// Elements that return `None` are not included in the accessibility tree.    ///    /// Note: inclusion in accessibility tree requires non-`None` [`id`][Element::id].    ///    /// See the [accessibility guide](crate::_accessibility) for an overview.    fn a11y_role(&self) -> Option<accesskit::Role> {        None    }     /// Write accessibility properties to the given node.    /// Called only when `a11y_role()` returns `Some`.    ///    /// See the [accessibility guide](crate::_accessibility) for an overview.    fn write_a11y_info(&self, _node: &mut accesskit::Node) {}     /// Add synthetic child nodes to an [`Element`] that has an    /// [`.id()`][Element::id] and a [`.role()`][Element::a11y_role].    ///    /// Some elements may want to inject accessibility nodes that do not    /// correspond to any GPUI element. For example, a custom text field element    /// may want to inject synthetic child nodes for the text content.    ///    /// See [Synthetic children](crate::_accessibility#synthetic-children) in    /// the accessibility guide for more detail.    fn a11y_synthetic_children(        &mut self,        _prepaint: &mut Self::PrepaintState,        _builder: &mut A11ySubtreeBuilder,    ) {    }     /// Convert this element into a dynamically-typed [`AnyElement`].    fn into_any(self) -> AnyElement {        AnyElement::new(self)    }} /// Implemented by any type that can be converted into an element.pub trait IntoElement: Sized {    /// The specific type of element into which the implementing type is converted.    /// Useful for converting other types into elements automatically, like Strings    type Element: Element;     /// Convert self into a type that implements [`Element`].    fn into_element(self) -> Self::Element;     /// Convert self into a dynamically-typed [`AnyElement`].    fn into_any_element(self) -> AnyElement {        self.into_element().into_any()    }} impl<T: IntoElement> FluentBuilder for T {} /// An object that can be drawn to the screen. This is the trait that distinguishes "views" from/// other entities. Views are `Entity`'s which `impl Render` and drawn to the screen.pub trait Render: 'static + Sized {    /// Render this view into an element tree.    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement;} impl Render for Empty {    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {        Empty    }} /// You can derive [`IntoElement`] on any type that implements this trait./// It is used to construct reusable `components` out of plain data. Think of/// components as a recipe for a certain pattern of elements. RenderOnce allows/// you to invoke this pattern, without breaking the fluent builder pattern of/// the element APIs.pub trait RenderOnce: 'static {    /// Render this component into an element tree. Note that this method    /// takes ownership of self, as compared to [`Render::render()`] method    /// which takes a mutable reference.    fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement;} /// This is a helper trait to provide a uniform interface for constructing elements that/// can accept any number of any kind of child elementspub trait ParentElement {    /// Extend this element's children with the given child elements.    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>);     /// Add a single child element to this element.    fn child(mut self, child: impl IntoElement) -> Self    where        Self: Sized,    {        self.extend(std::iter::once(child.into_element().into_any()));        self    }     /// Add multiple child elements to this element.    fn children(mut self, children: impl IntoIterator<Item = impl IntoElement>) -> Self    where        Self: Sized,    {        self.extend(children.into_iter().map(|child| child.into_any_element()));        self    }} /// A globally unique identifier for an element, used to track state across frames.#[derive(Deref, DerefMut, Clone, Default, Debug, Eq, PartialEq, Hash)]pub struct GlobalElementId(pub(crate) Arc<[ElementId]>); impl Display for GlobalElementId {    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {        for (i, element_id) in self.0.iter().enumerate() {            if i > 0 {                write!(f, ".")?;            }            write!(f, "{}", element_id)?;        }        Ok(())    }} impl GlobalElementId {    pub(crate) fn accesskit_node_id(&self) -> accesskit::NodeId {        use std::hash::{Hash, Hasher};        let mut hasher = std::hash::DefaultHasher::default();        self.hash(&mut hasher);        accesskit::NodeId(hasher.finish())    }} trait ElementObject {    fn inner_element(&mut self) -> &mut dyn Any;     fn request_layout(&mut self, window: &mut Window, cx: &mut App) -> LayoutId;     fn prepaint(&mut self, window: &mut Window, cx: &mut App);     fn paint(&mut self, window: &mut Window, cx: &mut App);     fn layout_as_root(        &mut self,        available_space: Size<AvailableSpace>,        window: &mut Window,        cx: &mut App,    ) -> Size<Pixels>;} /// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.pub struct Drawable<E: Element> {    /// The drawn element.    pub element: E,    phase: ElementDrawPhase<E::RequestLayoutState, E::PrepaintState>,} #[derive(Default)]enum ElementDrawPhase<RequestLayoutState, PrepaintState> {    #[default]    Start,    RequestLayout {        layout_id: LayoutId,        global_id: Option<GlobalElementId>,        inspector_id: Option<InspectorElementId>,        request_layout: RequestLayoutState,    },    LayoutComputed {        layout_id: LayoutId,        global_id: Option<GlobalElementId>,        inspector_id: Option<InspectorElementId>,        available_space: Size<AvailableSpace>,        request_layout: RequestLayoutState,    },    Prepaint {        node_id: DispatchNodeId,        global_id: Option<GlobalElementId>,        inspector_id: Option<InspectorElementId>,        bounds: Bounds<Pixels>,        request_layout: RequestLayoutState,        prepaint: PrepaintState,    },    Painted,} /// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window.impl<E: Element> Drawable<E> {    pub(crate) fn new(element: E) -> Self {        Drawable {            element,            phase: ElementDrawPhase::Start,        }    }     fn request_layout(&mut self, window: &mut Window, cx: &mut App) -> LayoutId {        match mem::take(&mut self.phase) {            ElementDrawPhase::Start => {                let global_id = self.element.id().map(|element_id| {                    window.element_id_stack.push(element_id);                    GlobalElementId(Arc::from(&*window.element_id_stack))                });                 let inspector_id;                #[cfg(any(feature = "inspector", debug_assertions))]                {                    inspector_id = self.element.source_location().map(|source| {                        let path = crate::InspectorElementPath {                            global_id: GlobalElementId(Arc::from(&*window.element_id_stack)),                            source_location: source,                        };                        window.build_inspector_element_id(path)                    });                }                #[cfg(not(any(feature = "inspector", debug_assertions)))]                {                    inspector_id = None;                }                 let (layout_id, request_layout) = self.element.request_layout(                    global_id.as_ref(),                    inspector_id.as_ref(),                    window,                    cx,                );                 if global_id.is_some() {                    window.element_id_stack.pop();                }                 self.phase = ElementDrawPhase::RequestLayout {                    layout_id,                    global_id,                    inspector_id,                    request_layout,                };                layout_id            }            _ => panic!("must call request_layout only once"),        }    }     pub(crate) fn prepaint(&mut self, window: &mut Window, cx: &mut App) {        match mem::take(&mut self.phase) {            ElementDrawPhase::RequestLayout {                layout_id,                global_id,                inspector_id,                mut request_layout,            }            | ElementDrawPhase::LayoutComputed {                layout_id,                global_id,                inspector_id,                mut request_layout,                ..            } => {                if let Some(element_id) = self.element.id() {                    window.element_id_stack.push(element_id);                    debug_assert_eq!(&*global_id.as_ref().unwrap().0, &*window.element_id_stack);                }                 let bounds = window.layout_bounds(layout_id);                let mut pushed_a11y_node = false;                if window.a11y.is_active() {                    if let Some(global_id) = global_id.as_ref() {                        if let Some(role) = self.element.a11y_role() {                            let node_id = global_id.accesskit_node_id();                            let mut node = accesskit::Node::new(role);                            let scale = window.scale_factor();                            node.set_bounds(accesskit::Rect {                                x0: (bounds.origin.x.0 * scale) as f64,                                y0: (bounds.origin.y.0 * scale) as f64,                                x1: ((bounds.origin.x.0 + bounds.size.width.0) * scale) as f64,                                y1: ((bounds.origin.y.0 + bounds.size.height.0) * scale) as f64,                            });                            self.element.write_a11y_info(&mut node);                            window.a11y.node_bounds.insert(node_id, bounds);                            pushed_a11y_node = window.a11y.nodes.push(node_id, node);                            #[cfg(debug_assertions)]                            if pushed_a11y_node {                                let view = window                                    .a11y                                    .view_type_names                                    .get(&window.current_view())                                    .copied();                                let source_location = self.element.source_location();                                window.a11y.nodes.record_node_info(                                    node_id,                                    crate::window::a11y::debug::NodeDebugInfo {                                        synthetic: false,                                        view,                                        element_id: global_id.0.last().map(|id| format!("{id:?}")),                                        source_location,                                    },                                );                            }                        }                    }                }                 let node_id = window.next_frame.dispatch_tree.push_node();                let mut prepaint = self.element.prepaint(                    global_id.as_ref(),                    inspector_id.as_ref(),                    bounds,                    &mut request_layout,                    window,                    cx,                );                window.next_frame.dispatch_tree.pop_node();                 if pushed_a11y_node {                    if let Some(global_id) = global_id.as_ref() {                        #[cfg(debug_assertions)]                        let creator = crate::window::a11y::debug::NodeCreator {                            view: window                                .a11y                                .view_type_names                                .get(&window.current_view())                                .copied(),                            element_id: global_id.0.last().map(|id| format!("{id:?}")),                            source_location: self.element.source_location(),                        };                        let mut builder = A11ySubtreeBuilder::new(                            global_id.accesskit_node_id(),                            &mut window.a11y.nodes,                        );                        #[cfg(debug_assertions)]                        {                            builder = builder.with_creator(creator);                        }                        self.element                            .a11y_synthetic_children(&mut prepaint, &mut builder);                    }                    window.a11y.nodes.pop();                }                 if global_id.is_some() {                    window.element_id_stack.pop();                }                 self.phase = ElementDrawPhase::Prepaint {                    node_id,                    global_id,                    inspector_id,                    bounds,                    request_layout,                    prepaint,                };            }            _ => panic!("must call request_layout before prepaint"),        }    }     pub(crate) fn paint(        &mut self,        window: &mut Window,        cx: &mut App,    ) -> (E::RequestLayoutState, E::PrepaintState) {        match mem::take(&mut self.phase) {            ElementDrawPhase::Prepaint {                node_id,                global_id,                inspector_id,                bounds,                mut request_layout,                mut prepaint,                ..            } => {                if let Some(element_id) = self.element.id() {                    window.element_id_stack.push(element_id);                    debug_assert_eq!(&*global_id.as_ref().unwrap().0, &*window.element_id_stack);                }                 window.next_frame.dispatch_tree.set_active_node(node_id);                self.element.paint(                    global_id.as_ref(),                    inspector_id.as_ref(),                    bounds,                    &mut request_layout,                    &mut prepaint,                    window,                    cx,                );                 if global_id.is_some() {                    window.element_id_stack.pop();                }                 self.phase = ElementDrawPhase::Painted;                (request_layout, prepaint)            }            _ => panic!("must call prepaint before paint"),        }    }     pub(crate) fn layout_as_root(        &mut self,

Lines 1–500 of 792. Load more