Struct HtmlDocument 

pub struct HtmlDocument { /* private fields */ }

Implementations

impl HtmlDocument

pub fn from_html(html: &str, config: DocumentConfig) -> Self

Parse HTML (or XHTML) into an HtmlDocument

pub fn into_inner(self) -> BaseDocument

Convert the HtmlDocument into it’s inner BaseDocument

Methods from Deref<Target = BaseDocument>

pub fn set_net_provider(&mut self, net_provider: Arc<dyn NetProvider>)

Set the Document’s networking provider

pub fn set_navigation_provider( &mut self, navigation_provider: Arc<dyn NavigationProvider>, )

Set the Document’s navigation provider

pub fn set_shell_provider(&mut self, shell_provider: Arc<dyn ShellProvider>)

Set the Document’s shell provider

pub fn set_html_parser_provider( &mut self, html_parser_provider: Arc<dyn HtmlParserProvider>, )

Set the Document’s html parser provider

pub fn set_base_url(&mut self, url: &str)

Set base url for resolving linked resources (stylesheets, images, fonts, etc)

pub fn guard(&self) -> &SharedRwLock

pub fn tree(&self) -> &NodeTree

pub fn id(&self) -> usize

pub fn favicon_url(&self) -> Option<String>

pub fn get_node(&self, node_id: NodeId) -> Option<&Node>

pub fn get_node_mut(&mut self, node_id: NodeId) -> Option<&mut Node>

pub fn get_focussed_node_id(&self) -> Option<NodeId>

pub fn mutate<'doc>(&'doc mut self) -> DocumentMutator<'doc>

pub fn handle_dom_event<F>(&mut self, event: &mut DomEvent, dispatch_event: F)

where F: FnMut(DomEvent),

pub fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

pub fn label_bound_input_element(&self, label_node_id: NodeId) -> Option<&Node>

Find the label’s bound input elements: the element id referenced by the “for” attribute of a given label element or the first input element which is nested in the label Note that although there should only be one bound element, we return all possibilities instead of just the first in order to allow the caller to decide which one is correct

pub fn toggle_radio(&mut self, radio_set_name: String, target_radio_id: NodeId)

pub fn toggle_details_open(&mut self, details_id: NodeId)

Toggle the open attribute of a <details> element, expanding or collapsing it. This is the default action triggered when the element’s first <summary> child is activated.

pub fn set_style_property(&mut self, node_id: NodeId, name: &str, value: &str)

pub fn remove_style_property(&mut self, node_id: NodeId, name: &str)

pub fn sub_document_node_ids(&self) -> Vec<NodeId>

pub fn set_sub_document( &mut self, node_id: NodeId, sub_document: Box<dyn Document>, )

pub fn remove_sub_document(&mut self, node_id: NodeId)

pub fn poll_subdocuments(&mut self, waker: Option<&Waker>) -> bool

Poll all sub-documents (see Document::poll), allowing them to make progress on any pending async operations (e.g. JavaScript timers). Hosts which poll a wrapper around a BaseDocument should call this from their poll implementation.

Returns true if any sub-document reported changes.

pub fn root_node(&self) -> &Node

pub fn root_node_mut(&mut self) -> &mut Node

pub fn set_paint_damage_tracking(&mut self, enabled: bool)

Ask this document to work out which regions differ between frames.

Off by default. A consumer that turns it on is charged one pass over the node list per resolve - a pass resolve already makes to clear damage - plus a hash lookup and a rectangle comparison per node. Nothing else in the document reads the result, so leaving it off costs a single branch.

The consumer this exists for is a backdrop-filter cache. Blurring what is behind an element costs a render pass and a filter every frame, and the only way that stops being permanent is to skip the elements whose input has not changed. Turning this on is what makes that question answerable.

The first frame after enabling reports everything as changed, because there is no previous frame to compare against.

pub fn paint_damage_tracking(&self) -> bool

Whether set_paint_damage_tracking is on.

pub fn paint_damage(&self) -> &PaintDamage

What changed since the previously resolved frame.

Empty when tracking is off, which is indistinguishable from “nothing changed” and deliberately so: a consumer that has not asked for the question to be answered must not read the empty answer as a licence to reuse a cache. Check paint_damage_tracking first.

pub fn try_root_element(&self) -> Option<&Node>

pub fn root_element(&self) -> &Node

pub fn create_node(&mut self, node_data: NodeData) -> NodeId

pub fn has_changes(&self) -> bool

Whether the document has been mutated

pub fn create_text_node(&mut self, text: &str) -> NodeId

pub fn deep_clone_node(&mut self, node_id: NodeId) -> NodeId

pub fn print_tree(&self)

pub fn print_subtree(&self, node_id: NodeId)

pub fn reload_resource_by_href(&mut self, href_to_reload: &str)

pub fn process_style_element(&mut self, target_id: NodeId)

pub fn remove_user_agent_stylesheet(&mut self, contents: &str)

pub fn url(&self) -> &Url

The document’s base URL

pub fn author_stylesheets(&self) -> impl Iterator<Item = &DocumentStyleSheet>

Iterate over the author stylesheets (from <style> and <link> nodes) currently associated with this document

pub fn useragent_stylesheets(&self) -> impl Iterator<Item = &DocumentStyleSheet>

Iterate over the user-agent stylesheets currently associated with this document

pub fn add_user_agent_stylesheet(&mut self, css: &str)

pub fn make_stylesheet( &self, css: impl AsRef<str>, origin: Origin, ) -> DocumentStyleSheet

pub fn upsert_stylesheet_for_node(&mut self, node_id: NodeId)

pub fn add_stylesheet_for_node( &mut self, stylesheet: DocumentStyleSheet, node_id: NodeId, )

pub fn handle_messages(&mut self)

pub fn handle_message(&mut self, msg: DocumentEvent)

pub fn has_pending_critical_resources(&self) -> bool

Whether the Document has pending requests for “critical” resources (that should block rendering)

pub fn pending_image_count(&self) -> usize

How many distinct image URLs are still being fetched.

Images are deliberately not “critical” resources, so they never block rendering. An embedder that needs a settled page (a screenshot, a test, a print) has no other way to tell an image that is still in flight from one that will never arrive.

pub fn load_resource(&mut self, res: ResourceLoadResponse)

pub fn snapshot_node(&mut self, node_id: NodeId)

pub fn snapshot_node_and(&mut self, node_id: NodeId, cb: impl FnOnce(&mut Node))

Snapshot a node and act on it, if it is still there.

Tolerant of a node that has gone, because the ids reaching this are remembered across events — focus, hover, the last press — and the node they name can be removed between one event and the next. Indexing directly turned that ordinary case into a panic inside an event handler.

pub fn hit(&self, x: f32, y: f32) -> Option<HitResult>

pub fn nearest_non_anonymous_ancestor(&self, node_id: NodeId) -> Option<NodeId>

Walk up the tree to the nearest DOM node whose id is stable across box-tree reconstruction, so canonicalized interaction state never goes stale.

Layout-generated nodes (anonymous blocks and ::before/::after pseudo-elements, both stored as anonymous blocks) get new ids on every reconstruction, so we skip any anonymous node and a non-anonymous node whose parent is anonymous (the pseudo’s text content). The first non-anonymous node with a non-anonymous parent is a real DOM node; the root element’s Document parent guarantees termination.

Returns None if node_id (or an ancestor) no longer exists.

pub fn focus_next_node(&mut self) -> Option<NodeId>

pub fn focus_prev_node(&mut self) -> Option<NodeId>

Move focus to the previous focussable node in the document

pub fn clear_focus(&mut self)

Clear the focussed node

pub fn set_mousedown_node_id(&mut self, node_id: Option<NodeId>)

pub fn set_focus_to(&mut self, focus_node_id: NodeId) -> bool

pub fn active_node(&mut self) -> bool

pub fn unactive_node(&mut self) -> bool

pub fn hovered_scrollbar(&self) -> Option<ScrollbarRef>

The scrollbar thumb currently under the pointer, if any.

pub fn scrollbar_drag_target(&self) -> Option<ScrollbarRef>

The scrollbar thumb currently being dragged, if any.

pub fn scrollbar_opacity(&self, node_id: NodeId) -> f32

The current opacity of node_id’s overlay scrollbars. They show at full opacity on scroll and fade out after a delay (Chromium’s overlay timings); the pointer resting on a thumb, or dragging it, holds them visible.

pub fn set_hover_to(&mut self, x: f32, y: f32) -> bool

pub fn clear_hover(&mut self) -> bool

pub fn refresh_hover(&mut self) -> bool

Re-resolve hover state against the current layout using the last known pointer position.

TODO: synthesizing pointerenter/pointerleave DOM events for hover changes caused by layout shifts.

pub fn get_hover_node_id(&self) -> Option<NodeId>

pub fn get_mousedown_node_id(&self) -> Option<NodeId>

pub fn set_viewport(&mut self, viewport: Viewport)

pub fn media_type(&self) -> &MediaType

Returns the current CSS media type used to evaluate @media rules.

pub fn set_media_type(&mut self, media_type: MediaType)

Sets the CSS media type used to evaluate @media rules (e.g. screen or print) and rebuilds the stylist device so updated rules apply on the next restyle.

pub fn viewport(&self) -> &Viewport

pub fn viewport_mut(&mut self) -> ViewportMut<'_>

pub fn zoom_by(&mut self, increment: f32)

pub fn zoom_to(&mut self, zoom: f32)

pub fn get_viewport(&self) -> Viewport

pub fn incremental_layout(&self) -> bool

Returns whether incremental layout is currently enabled for this document.

pub fn set_incremental_layout(&mut self, enabled: bool)

Enables or disables incremental layout for this document.

pub fn devtools(&self) -> &DevtoolSettings

pub fn devtools_mut(&mut self) -> &mut DevtoolSettings

pub fn subdoc(&self, node_id: NodeId) -> Option<&(dyn Document + 'static)>

pub fn subdoc_mut( &mut self, node_id: NodeId, ) -> Option<&mut (dyn Document + 'static)>

pub fn is_animating(&self) -> bool

pub fn animation_pacing(&self) -> AnimationPacing

Return the cadence class for the next animation-only frame.

CSS animations are commonly decorative and can use a lower cadence. Canvas, scrolling and custom widgets remain at the interactive cadence.

pub fn set_stylist_device(&mut self, device: Device)

Update the device and reset the stylist to process the new size

pub fn stylist_device(&mut self) -> &Device

pub fn get_cursor(&self) -> Option<CursorIcon>

The cursor to show, where None means cursor: none — hide it.

None is an answer, not the absence of one. The shell hides the pointer when it sees None, so every path that means “nothing to say here” must return Default instead. Returning None from those made the pointer vanish as it crossed into page content, which is the shape this used to have: three ?s that each meant “no opinion” and all read as “hide”.

pub fn scroll_node_by<F>( &mut self, node_id: NodeId, x: f64, y: f64, dispatch_event: F, )

where F: FnMut(DomEvent),

pub fn scroll_node_by_has_changed<F>( &mut self, node_id: NodeId, x: f64, y: f64, dispatch_event: F, ) -> bool

where F: FnMut(DomEvent),

Scroll a node by given x and y Will bubble scrolling up to parent node once it can no longer scroll further If we’re already at the root node, bubbles scrolling up to the viewport

pub fn scroll_viewport_by(&mut self, x: f64, y: f64)

pub fn scroll_viewport_by_has_changed(&mut self, x: f64, y: f64) -> bool

Scroll the viewport by the given values

pub fn scroll_by( &mut self, anchor_node_id: Option<NodeId>, scroll_x: f64, scroll_y: f64, dispatch_event: &mut dyn FnMut(DomEvent), ) -> bool

pub fn viewport_scroll(&self) -> Point<f64>

pub fn set_viewport_scroll(&mut self, scroll: Point<f64>)

pub fn get_fragment_target(&self, fragment: &str) -> Option<NodeId>

Find the node targeted by a URL fragment (the #... part of a URL).

Per the HTML spec, this is the element whose id matches the fragment, falling back to the first <a> element whose name attribute matches.

pub fn nearest_scroll_container(&self, node_id: NodeId) -> Option<NodeId>

Scroll the viewport so that the given node is aligned with the top of the viewport. Scroll the nearest scroll container at or above node_id.

“Scroll this panel” is the operation callers actually want, and scroll_node_by only moves the node itself, so naming any inner element silently did nothing. Wheel events are no help either: they are delivered to whatever the document last saw hovered, which an injected pointer move does not set, so an automated caller had no way to scroll anything at all. The nearest scroll container at or above node_id, if there is one.

pub fn scroll_nearest_container_by( &mut self, node_id: NodeId, x: f64, y: f64, ) -> bool

pub fn scroll_to_node(&mut self, node_id: NodeId)

pub fn scroll_to_fragment(&mut self, fragment: &str) -> bool

Scroll to the element targeted by the given URL fragment (the #... part of a URL).

An empty fragment (or a top fragment that matches no element) scrolls to the top of the document, matching browser behaviour. Returns true if a scroll target was found.

pub fn get_client_bounding_rect(&self, node_id: NodeId) -> Option<BoundingRect>

Computes the size and position of the Node relative to the viewport

pub fn node_client_rects(&self, node_id: NodeId) -> Vec<BoundingRect>

Computes the sizes and positions of the Node’s box fragments relative to the viewport (CSSOM getClientRects() semantics). Nodes with their own layout box return a single rect. Non-atomic inline elements (which are laid out as style spans within an inline root’s text layout) return one rect per line box.

pub fn inline_fragment_rects( &self, node_id: NodeId, ) -> Option<Vec<BoundingRect>>

pub fn find_title_node(&self) -> Option<&Node>

pub fn with_text_input( &mut self, node_id: NodeId, cb: impl FnOnce(PlainEditorDriver<'_, TextBrush>), )

pub fn find_text_position(&self, x: f32, y: f32) -> Option<(NodeId, usize)>

Find the text position (inline_root_id, byte_offset) at a given point. Uses hit() for proper coordinate transformation, then finds the inline root and byte offset.

pub fn find_text_range( &self, x: f32, y: f32, granularity: TextGranularity, ) -> Option<(NodeId, usize, usize)>

Find the word or line at a point, as (inline_root_id, start, end).

The multi-click counterpart of find_text_position: that one answers where a caret goes, this one answers what a double or triple click selects.

pub fn set_text_selection( &mut self, anchor_node: NodeId, anchor_offset: usize, focus_node: NodeId, focus_offset: usize, )

Set the text selection range (creates a new selection from anchor to focus)

pub fn clear_text_selection(&mut self)

Clear the text selection

pub fn update_selection_focus( &mut self, focus_node: NodeId, focus_offset: usize, )

Update the selection focus point (used during mouse drag to extend selection).

pub fn extend_text_selection_to_point(&mut self, x: f32, y: f32) -> bool

Extend text selection to the given point. Returns true if selection was updated. This is a convenience method that combines find_text_position and update_selection_focus.

pub fn has_text_selection(&self) -> bool

Check if there is an active (non-empty) text selection

pub fn get_selected_text(&self) -> Option<String>

Get the selected text content, supporting selection across multiple inline roots.

pub fn get_text_selection_ranges(&self) -> Vec<(NodeId, usize, usize)>

Get all selection ranges as Vec<(node_id, start_offset, end_offset)>. Returns empty vec if no selection.

pub fn print_taffy_tree(&self)

pub fn debug_log_node(&self, node_id: NodeId)

pub fn reset_form_owner(&mut self, node_id: NodeId)

Resets the form owner for a given node by either using an explicit form attribute or finding the nearest ancestor form element

Arguments

• node_id - The ID of the node whose form owner needs to be reset

https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#reset-the-form-owner

pub fn submit_form(&self, node_id: NodeId, submitter_id: NodeId)

Submits a form with the given form node ID and submitter node ID

Arguments

• node_id - The ID of the form node to submit
• submitter_id - The ID of the node that triggered the submission

https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#form-submission-algorithm

pub fn flush_styles_to_layout(&mut self, node_id: NodeId)

pub fn get_element_by_id(&self, id: &str) -> Option<NodeId>

Find the node with the specified id attribute (if one exists). If multiple nodes have the same id, the first in tree order is returned.

pub fn query_selector<'input>( &self, selector: &'input str, ) -> Result<Option<NodeId>, ParseError<'input, StyleParseErrorKind<'input>>>

Find the first node that matches the selector specified as a string Returns:

• Err(_) if parsing the selector fails
• Ok(None) if nothing matches
• Ok(Some(node_id)) with the first node ID that matches if one is found

pub fn query_selector_in<'input>( &self, scope: NodeId, selector: &'input str, ) -> Result<Option<NodeId>, ParseError<'input, StyleParseErrorKind<'input>>>

Find the first descendant of scope that matches the selector specified as a string.

The scope node itself is never matched. Selector parts may match nodes outside the scope while evaluating relationships between descendants.

Returns:

• Err(_) if parsing the selector fails
• Ok(None) if nothing matches
• Ok(Some(node_id)) with the first matching descendant ID otherwise

pub fn query_selector_raw( &self, selector_list: &SelectorList<SelectorImpl>, ) -> Option<NodeId>

Find the first descendant of the document root that matches the selector(s) specified in selector_list.

The document root itself is never matched. Selector parts may match nodes outside the scope while evaluating relationships between descendants.

pub fn query_selector_in_raw( &self, scope: NodeId, selector_list: &SelectorList<SelectorImpl>, ) -> Option<NodeId>

Find the first descendant of scope that matches the selector(s) specified in selector_list.

The scope node itself is never matched. Selector parts may match nodes outside the scope while evaluating relationships between descendants.

pub fn query_selector_all<'input>( &self, selector: &'input str, ) -> Result<SmallVec<[NodeId; 32]>, ParseError<'input, StyleParseErrorKind<'input>>>

Find all nodes that match the selector specified as a string Returns:

• Err(_) if parsing the selector fails
• Ok(SmallVec<usize>) with all matching nodes otherwise

pub fn query_selector_all_in<'input>( &self, scope: NodeId, selector: &'input str, ) -> Result<SmallVec<[NodeId; 32]>, ParseError<'input, StyleParseErrorKind<'input>>>

Find all descendants of scope that match the selector specified as a string, in tree order.

The scope node itself is never matched. Selector parts may match nodes outside the scope while evaluating relationships between descendants.

Returns:

• Err(_) if parsing the selector fails
• Ok(_) with all matching descendant IDs otherwise

pub fn query_selector_all_raw( &self, selector_list: &SelectorList<SelectorImpl>, ) -> SmallVec<[NodeId; 32]>

Find all descendants of the document root that match the selector(s) specified in selector_list, in tree order.

The document root itself is never matched. Selector parts may match nodes outside the scope while evaluating relationships between descendants.

pub fn query_selector_all_in_raw( &self, scope: NodeId, selector_list: &SelectorList<SelectorImpl>, ) -> SmallVec<[NodeId; 32]>

Find all descendants of scope that match the selector(s) specified in selector_list, in tree order.

The scope node itself is never matched. Selector parts may match nodes outside the scope while evaluating relationships between descendants.

pub fn matches_selector<'input>( &self, node_id: NodeId, selector: &'input str, ) -> Result<bool, ParseError<'input, StyleParseErrorKind<'input>>>

Test whether the node identified by node_id matches the selector specified as a string.

Non-element nodes never match.

pub fn closest<'input>( &self, node_id: NodeId, selector: &'input str, ) -> Result<Option<NodeId>, ParseError<'input, StyleParseErrorKind<'input>>>

Find the closest matching element at or above the node identified by node_id.

Non-element nodes never match and return None.

pub fn try_parse_selector_list<'input>( &self, input: &'input str, ) -> Result<SelectorList<SelectorImpl>, ParseError<'input, StyleParseErrorKind<'input>>>

pub fn resolve(&mut self, current_time_for_animations: f64)

Restyle the tree and then relayout it

pub fn resolve_scroll_animation(&mut self)

pub fn resolve_layout_children(&mut self)

Ensure that the layout_children field is populated for all nodes

pub fn hoist_fixed_position_nodes(&mut self)

Reparent position: fixed nodes onto the root element for layout.

Taffy has no Fixed position, so stylo_taffy maps it to Absolute. An absolutely positioned node resolves its insets against its containing block, which for a fixed node must be the viewport. Laid out in place it would instead resolve against the nearest positioned ancestor, so both its offset and — when opposite insets are set — its size come out wrong.

Reparenting them onto the root element takes the positioned ancestor out of the picture. This runs after resolve_layout_children and before flush_styles_to_layout, which derives paint_children from layout_children, so painting and hit testing follow the hoist without further work.

Note this is not yet the full containing block a browser would use. The root element takes its height from its content, whereas the initial containing block is always viewport-sized, so inset: 0 still sizes against the document rather than the viewport. Closing that gap needs an ICB distinct from the root element.

A transformed ancestor becomes the containing block for its fixed descendants, so those are left where they are.

https://drafts.csswg.org/css-position/#fixed-pos https://drafts.csswg.org/css-transforms-1/#propdef-transform

pub fn resolve_deferred_tasks(&mut self)

pub fn resolve_layout(&mut self)

Walk the nodes now that they’re properly styled and transfer their styles to the taffy style system

TODO: update taffy to use an associated type instead of slab key TODO: update taffy to support traited styles so we don’t even need to rely on taffy for storage

pub fn resolve_stylist(&mut self, now: f64)

pub fn node_chain(&self, node_id: NodeId) -> Vec<NodeId>

Collect the nodes into a chain by traversing upwards

pub fn visit<F>(&self, visit: F)

where F: FnMut(NodeId, &Node),

pub fn non_anon_ancestor_if_anon(&self, node_id: NodeId) -> NodeId

If the node is non-anonymous then returns the node’s id Else find’s the first non-anonymous ancester of the node

pub fn iter_children_mut( &mut self, node_id: NodeId, cb: impl FnMut(NodeId, &mut BaseDocument), )

pub fn iter_subtree_mut( &mut self, node_id: NodeId, cb: impl FnMut(NodeId, &mut BaseDocument), )

pub fn iter_children_and_pseudos_mut( &mut self, node_id: NodeId, cb: impl FnMut(NodeId, &mut BaseDocument), )

pub fn iter_layout_children_mut( &mut self, node_id: NodeId, cb: impl FnMut(NodeId, &mut BaseDocument), )

Like iter_children_mut but iterates the flattened-tree children (used for box construction, so shadow hosts and slots compose correctly).

pub fn iter_layout_children_and_pseudos_mut( &mut self, node_id: NodeId, cb: impl FnMut(NodeId, &mut BaseDocument), )

Like iter_children_and_pseudos_mut but iterates the flattened-tree children.

pub fn next_node( &self, start: &Node, filter: impl FnMut(&Node) -> bool, ) -> Option<NodeId>

pub fn prev_node( &self, start: &Node, filter: impl FnMut(&Node) -> bool, ) -> Option<NodeId>

Mirror of Self::next_node: walks the tree in reverse document order, wrapping around to the end of the document.

pub fn node_layout_ancestors(&self, node_id: NodeId) -> Vec<NodeId>

pub fn maybe_node_layout_ancestors( &self, node_id: Option<NodeId>, ) -> Vec<NodeId>

pub fn compare_document_order(&self, node_a: NodeId, node_b: NodeId) -> Ordering

Compare the document order of two nodes. Returns Ordering::Less if node_a comes before node_b in document order. Returns Ordering::Greater if node_a comes after node_b. Returns Ordering::Equal if they are the same node.

pub fn collect_inline_roots_in_range( &self, start_node: NodeId, end_node: NodeId, ) -> Vec<NodeId>

Collect all inline root nodes between start_node and end_node in document order. Both start and end are assumed to be inline roots. Returns the nodes in document order (from first to last).

Trait Implementations

impl Deref for HtmlDocument

type Target = BaseDocument

The resulting type after dereferencing.

fn deref(&self) -> &BaseDocument

Dereferences the value.

impl DerefMut for HtmlDocument

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Document for HtmlDocument

fn inner(&self) -> DocGuard<'_>

fn inner_mut(&mut self) -> DocGuardMut<'_>

fn handle_ui_event(&mut self, event: UiEvent)

Update the Document in response to a UiEvent (click, keypress, etc)

fn poll(&mut self, task_context: Option<Context<'_>>) -> bool

Poll any pending async operations, and flush changes to the underlying BaseDocument

fn id(&self) -> usize

Get the Document’s id

impl From<HtmlDocument> for BaseDocument

fn from(doc: HtmlDocument) -> BaseDocument

Converts to this type from the input type.