Skip to main content

LayoutDom

layout_dom_api

Trait LayoutDom 

Source 
pub trait LayoutDom {
    type NodeId: Copy + Eq + Hash + Debug + 'static;


Show 19 methods    // Required methods
    fn document(&self) -> Self::NodeId;
    fn parent(&self, id: Self::NodeId) -> Option<Self::NodeId>;
    fn prev_sibling(&self, id: Self::NodeId) -> Option<Self::NodeId>;
    fn next_sibling(&self, id: Self::NodeId) -> Option<Self::NodeId>;
    fn dom_children(
        &self,
        id: Self::NodeId,
    ) -> impl Iterator<Item = Self::NodeId> + '_;
    fn kind(&self, id: Self::NodeId) -> NodeKind;
    fn element_name(&self, id: Self::NodeId) -> Option<&QualName>;
    fn attribute(
        &self,
        id: Self::NodeId,
        ns: &Namespace,
        local: &LocalName,
    ) -> Option<&str>;
    fn attributes(
        &self,
        id: Self::NodeId,
    ) -> impl Iterator<Item = AttributeView<'_>> + '_;
    fn text(&self, id: Self::NodeId) -> Option<&str>;

    // Provided methods
    fn is_live(&self, _id: Self::NodeId) -> bool { ... }
    fn quirks_mode(&self) -> QuirksMode { ... }
    fn flat_children(
        &self,
        id: Self::NodeId,
    ) -> impl Iterator<Item = Self::NodeId> + '_ { ... }
    fn opaque_id(&self, id: Self::NodeId) -> u64 { ... }
    fn walk<V>(&self, visitor: &mut V) -> ControlFlow<V::Stop>
       where V: NodeVisitor<Self> + ?Sized { ... }
    fn has_class(&self, id: Self::NodeId, class: &str) -> bool { ... }
    fn first_with_class(
        &self,
        id: Self::NodeId,
        class: &str,
    ) -> Option<Self::NodeId> { ... }
    fn all_with_class(&self, id: Self::NodeId, class: &str) -> Vec<Self::NodeId> { ... }
    fn first_tag(&self, id: Self::NodeId, local: &str) -> Option<Self::NodeId> { ... }

}
Expand description

Profile-neutral DOM. Implementors expose opaque NodeIds and a small set of lookup primitives; traversal happens through the default walk impl over a NodeVisitor, or through caller-driven cursors built on the lookup primitives.

Required Associated Types§

Source

type NodeId: Copy + Eq + Hash + Debug + 'static

Opaque per-backend node identity. Must be Copy for cheap pass-through.

Required Methods§

Source

fn document(&self) -> Self::NodeId

The document root.

Two shapes are supported. A Document wrapper node whose element children are the roots: parsed HTML has exactly one (<html>), but a host-built synthetic DOM (an app chrome layer, a widget pool) may hang SEVERAL elements here with no wrapper — layout styles and paints every one of them (serval-layout wraps them in a synthetic block root; see its multi_root_document_paints_every_root_element test). Or an element node (a re-rooted subtree view): that element is itself the root. Hosts do not need to invent an <html>/container element just to satisfy layout. Note the CSS root-background propagation (<html>/<body> background painting the whole canvas) applies only to a sole-root document.

Source

fn parent(&self, id: Self::NodeId) -> Option<Self::NodeId>

Parent node, if any.

Source

fn prev_sibling(&self, id: Self::NodeId) -> Option<Self::NodeId>

Previous sibling in DOM order. Hot on selector-matching paths (prev_sibling_element in selectors::Element); deriving it from dom_children(parent) would be O(siblings) per call.

Source

fn next_sibling(&self, id: Self::NodeId) -> Option<Self::NodeId>

Next sibling in DOM order. See Self::prev_sibling.

Source

fn dom_children( &self, id: Self::NodeId, ) -> impl Iterator<Item = Self::NodeId> + '_

DOM-tree children (parse-order, ignores shadow trees).

Source

fn kind(&self, id: Self::NodeId) -> NodeKind

What kind of node id is. Plain enum; details via the typed accessors below.

Source

fn element_name(&self, id: Self::NodeId) -> Option<&QualName>

Element name when id is an element, else None. Hot on selector/style match paths.

Source

fn attribute( &self, id: Self::NodeId, ns: &Namespace, local: &LocalName, ) -> Option<&str>

Attribute value lookup by namespace + local name. Hot on selector/style match paths. Backends with column-stored attrs can implement this as a keyed lookup without materializing a full slice.

Source

fn attributes( &self, id: Self::NodeId, ) -> impl Iterator<Item = AttributeView<'_>> + '_

Iterate this element’s attributes (cold path: serialization, introspection). Yields AttributeViews borrowed from the backing store.

Source

fn text(&self, id: Self::NodeId) -> Option<&str>

Text content for text or comment nodes, else None.

Provided Methods§

Source

fn is_live(&self, _id: Self::NodeId) -> bool

Whether id still resolves to a live node — the dangle contract.

Contract: an id for an attached node is always live. An id for a node that was dropped (by LayoutDomMut::remove, or — once a backend collects detached nodes — orphaned, unpinned, and collected) is dead. is_live is the only read that is safe to call on a possibly-dead id; it never panics. The other accessors assume a live id and may panic on a dead one (the same “not found” outcome a removed slot gives). A caller that holds an id across frames (a handler registry, a layout side-table, a query result, an undrained mutation log) must treat it as possibly dead and guard reads with is_live.

Default: true. Immutable backends (a parsed LayoutDom with no removal) never produce dead ids; a mutable backend overrides this.

Source

fn quirks_mode(&self) -> QuirksMode

The document’s quirks mode, as selected by the parser (presence/absence of a <!DOCTYPE>). Drives quirk-gated cascade behaviour (Stylo’s QuirksMode-conditional UA rules, e.g. the table font-size quirk). Defaults to standards mode; a backend that parses a real document overrides it.

Source

fn flat_children( &self, id: Self::NodeId, ) -> impl Iterator<Item = Self::NodeId> + '_

Flat-tree children (slot-assigned for shadow hosts, otherwise DOM order). Backends without shadow DOM should leave this defaulted.

Source

fn opaque_id(&self, id: Self::NodeId) -> u64

Stable per-node identity as a u64. Used by foreign trait adapters (Stylo’s OpaqueNode, selectors::OpaqueElement) that need a pointer-shaped value for identity comparisons in the cascade.

Must satisfy: distinct nodes within the same backing store return distinct opaque_id values, and the same node returns the same value across calls. Implementations may use the inner storage index (dense DOMs) or a hash (sparse DOMs).

The default implementation hashes id with DefaultHasher — works for any NodeId: Hash but isn’t guaranteed to be collision-free across all node sets. Backends should override when they can return the natural underlying index cheaply.

Source

fn walk<V>(&self, visitor: &mut V) -> ControlFlow<V::Stop>
where V: NodeVisitor<Self> + ?Sized,

Walk the whole document from document(), descending via dom_children. Backends override when they want backend-driven traversal (parallel layout pass, prefetching, flat-tree descent).

Source

fn has_class(&self, id: Self::NodeId, class: &str) -> bool

Whether element id carries CSS class class (whitespace-split class attr).

Source

fn first_with_class( &self, id: Self::NodeId, class: &str, ) -> Option<Self::NodeId>

The first element carrying CSS class class in pre-order under id (inclusive).

Source

fn all_with_class(&self, id: Self::NodeId, class: &str) -> Vec<Self::NodeId>

Every element carrying CSS class class in pre-order under id (inclusive).

Source

fn first_tag(&self, id: Self::NodeId, local: &str) -> Option<Self::NodeId>

The first element with local tag name local in pre-order under id (inclusive).

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§