#include <Ultralight/dom/Document.h>

Overview

The root of a page's DOM tree in a View or frame.

dom::Document provides native C++ access to a page's DOM tree. It's the starting point for querying elements and updating the user interface rendered by a View.

You typically obtain the document during page loads and keep handles to the elements you want to modify later.

The following listener stores a score element once the main frame's document is parsed and ready:

class Hud : public LoadListener {
 public:
  void OnDOMReady(View* caller, uint64_t frame_id, bool is_main_frame,
                  const String& url) override {
    if (!is_main_frame)
      return;
    dom::Document document(caller);
    score_ = document.getElementById("score");
  }
 
  void SetScore(int score) { score_.textContent = std::to_string(score); }
 
 private:
  dom::Element score_;
};

Getting a Document

You obtain a document from its owning View or frame:

Main frame documents come from the View. Passing a View pointer to the Document constructor returns the active document of the top-level frame.
Subframe documents come from their elements. Calling dom::HTMLIFrameElement::contentDocument() on a frame element returns the document loaded inside that frame.

You should construct the main frame's document inside LoadListener::OnDOMReady(), where the new document is in place. Before the first page loads and while a new page is loading, the constructor returns the previous document, which goes away when the new page replaces it.

LoadListener::OnDOMReady() runs for every frame on the page. Check the is_main_frame parameter to ensure top-level setup logic runs only for the main frame.

Navigating to a new page creates a new document– handles from the previous page belong to a page that is gone (dom::Element covers handle states).

Relationship to Nodes

dom::Document is a distinct type that doesn't inherit from dom::Node. Because the document isn't a node, the root element has no parent in the DOM tree.

On the root element, parentNode() is empty and ownerDocument() gets back to the document:

dom::Element root = document.documentElement();
 
root.parentNode();     // empty
root.ownerDocument();  // the document

Document Events

You can listen for events on the document with addEventListener() or handle matching descendants using On(). Events dispatched on elements throughout the page bubble up to the document unless stopped along the way.

Page load and viewport resize events target the window rather than the document, so document listeners never receive them. Call defaultView() to obtain the page's dom::Window when you need to handle window-level events.

Note: Don't add a DOMContentLoaded listener in LoadListener::OnDOMReady(). The event has already fired by the time the callback runs, so a listener added there never fires.

See also: dom::Element, dom::Node, dom::Window, dom::Triggers, LoadListener::OnDOMReady()

Static Public Member Functions
static Document	Adopt (ULDOMDocument handle)
	Wrap a C handle you own, taking ownership of it.
static Document	FromBorrowed (ULDOMDocument handle)
	Wrap a C handle the library owns (eg, a callback argument), adding a reference.

Public Member Functions
	Document ()=default
	Create an empty Document.
	Document (View *view)
	Get the document of a View's main frame.
	Document (const Document &other)
	Copy constructor (both handles refer to the same document).
	Document (Document &&other) noexcept
	Move constructor (other becomes empty).
Document &	operator= (Document other) noexcept
	Assignment (copies or moves).
	~Document ()
	Destroy this handle (the document itself isn't affected).
	operator bool () const
	Whether or not this Document is valid (see IsAlive()).
bool	IsEmpty () const
	Whether or not this Document is empty (it holds no handle).
bool	IsAlive () const
	Whether or not this Document is valid (it isn't empty and its page is still alive).
Element	getElementById (std::string_view id) const
	Find the element with a certain id (getElementById).
Element	querySelector (std::string_view selectors) const
	Find the first element matching a CSS selector (querySelector).
Result< Element >	querySelector (std::string_view selectors, Checked_t) const
	Same as querySelector(), but returns a Result with the reason for a failure (eg, a SyntaxError for a malformed selector).
ElementList	querySelectorAll (std::string_view selectors) const
	Find every element matching a CSS selector (querySelectorAll).
Result< ElementList >	querySelectorAll (std::string_view selectors, Checked_t) const
	Same as querySelectorAll(), but returns a Result with the reason for a failure (eg, a SyntaxError for a malformed selector).
Element	elementFromPoint (double x, double y) const
	Find the topmost element at a point in the viewport (elementFromPoint).
ElementList	elementsFromPoint (double x, double y) const
	Find every element at a point in the viewport, topmost first (elementsFromPoint).
Element	documentElement () const
	Get the document's root element (documentElement).
Element	body () const
	Get the document's body element (body).
Element	head () const
	Get the document's head element (head).
Element	activeElement () const
	Get the element that has keyboard focus (activeElement).
bool	hasFocus () const
	Whether or not the document has keyboard focus (hasFocus).
Node	firstChild () const
	Get the document's first child of any kind (firstChild).
Node	lastChild () const
	Get the document's last child of any kind (lastChild).
Element	firstElementChild () const
	Get the document's first child element (firstElementChild).
Element	lastElementChild () const
	Get the document's last child element (lastElementChild).
size_t	childElementCount () const
	Get the number of the document's child elements (childElementCount).
ElementList	children () const
	Get the document's child elements in order (children).
NodeList	childNodes () const
	Get the document's children of every kind in order (childNodes).
bool	hasChildNodes () const
	Whether or not the document has any children (hasChildNodes).
Window	defaultView () const
	Get the document's window (defaultView).
Selection	getSelection () const
	Get the document's selection (getSelection).
Element	createElement (std::string_view tag_name) const
	Create an element (createElement).
Node	createTextNode (std::string_view data) const
	Create a text node (createTextNode).
Node	createComment (std::string_view data) const
	Create a comment node (createComment).
DocumentFragment	createDocumentFragment () const
	Create an empty document fragment (createDocumentFragment).
Range	createRange () const
	Create a range (createRange).
bool	dispatchEvent (std::string_view type, const EventInit &init={}) const
	Dispatch a synthetic event to the document (dispatchEvent).
bool	dispatchCustomEvent (std::string_view type, std::string_view event_detail, const EventInit &init={}) const
	Dispatch a synthetic CustomEvent with a string payload to the document.
template<typename F>
EventListener	addEventListener (std::string_view type, F &&callback, const AddEventListenerOptions &options={}) const
	Listen for an event on the document (addEventListener).
template<typename F>
EventListener	addEventListener (std::string_view type, F &&callback, EventListenerFlags flags) const
	Listen for an event on the document, with options as flags (eg, dom::Once \| dom::Capture).
template<typename C, typename M> requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)
EventListener	addEventListener (std::string_view type, C &receiver, M method, const AddEventListenerOptions &options={}) const
	Listen for an event on the document by calling a member function of an object.
template<typename C, typename M> requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)
EventListener	addEventListener (std::string_view type, C &receiver, M method, EventListenerFlags flags) const
	Listen for an event on the document by calling a member function of an object, with options as flags.
template<typename H, typename M> requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)
EventListener	addEventListener (std::string_view type, H holder, M method, const AddEventListenerOptions &options={}) const
	Listen for an event on the document by calling a member function through a smart pointer.
template<typename H, typename M> requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)
EventListener	addEventListener (std::string_view type, H holder, M method, EventListenerFlags flags) const
	Listen for an event on the document by calling a member function through a smart pointer, with options as flags.
template<typename F>
EventListener	On (std::string_view selector, std::string_view type, F &&callback, const AddEventListenerOptions &options={}) const
	Listen for an event on every element that matches a CSS selector, including elements added later (event delegation from the document).
template<typename F>
EventListener	On (std::string_view selector, std::string_view type, F &&callback, EventListenerFlags flags) const
	Listen for an event on every element that matches a CSS selector, with options as flags.
template<typename F>
Result< EventListener >	On (std::string_view selector, std::string_view type, F &&callback, const AddEventListenerOptions &options, Checked_t) const
	Same as On(), but returns a Result with the reason for a failure (eg, a SyntaxError for a malformed selector).
template<typename F>
Result< EventListener >	On (std::string_view selector, std::string_view type, F &&callback, Checked_t) const
	Same as On() with default options, but returns a Result with the reason for a failure.
template<typename C, typename M> requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)
EventListener	On (std::string_view selector, std::string_view type, C &receiver, M method, const AddEventListenerOptions &options={}) const
	Listen for an event on every element that matches a CSS selector by calling a member function of an object.
template<typename C, typename M> requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)
EventListener	On (std::string_view selector, std::string_view type, C &receiver, M method, EventListenerFlags flags) const
	Listen for an event on every element that matches a CSS selector by calling a member function of an object, with options as flags.
template<typename H, typename M> requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)
EventListener	On (std::string_view selector, std::string_view type, H holder, M method, const AddEventListenerOptions &options={}) const
	Listen for an event on every element that matches a CSS selector by calling a member function through a smart pointer.
template<typename H, typename M> requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)
EventListener	On (std::string_view selector, std::string_view type, H holder, M method, EventListenerFlags flags) const
	Listen for an event on every element that matches a CSS selector by calling a member function through a smart pointer, with options as flags.
ULDOMDocument	raw () const
	Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMDocument.h> functions.
ULDOMDocument	LeakRef ()
	Give up ownership of the C handle and return it.

Public Attributes
detail::DocumentStringProp< detail::DocumentTitleTag >	title
	The document's title (title), the text of its <title> element with whitespace collapsed.

Protected Member Functions
	Document (ULDOMDocument handle)

Constructor & Destructor Documentation

◆ Document() [1/5]

Document ( )

default

Create an empty Document.

◆ Document() [2/5]

Document ( View * view )

inlineexplicit

Get the document of a View's main frame.

Parameters

view	The View (a nullptr gives an empty Document).

Note: This is the document the frame has now. Before the first page loads, and while a new page is loading, that's the previous document, which goes away when the new page replaces it. Getting it in LoadListener::OnDOMReady() makes sure it's your page.

◆ Document() [3/5]

Document ( const Document & other )

inline

Copy constructor (both handles refer to the same document).

Parameters

◆ Document() [4/5]

Document ( Document && other )

inlinenoexcept

Move constructor (other becomes empty).

Parameters

◆ ~Document()

~Document ( )

inline

Destroy this handle (the document itself isn't affected).

◆ Document() [5/5]

Document ( ULDOMDocument handle )

inlineexplicitprotected

Member Function Documentation

◆ activeElement()

Element activeElement ( ) const

inline

Get the element that has keyboard focus (activeElement).

Returns: Returns the focused element. When nothing has focus this is the body (empty if there's no body).

◆ addEventListener() [1/6]

template<typename C, typename M>
requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)

EventListener addEventListener	(	std::string_view	type,
		C &	receiver,
		M	method,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen for an event on the document by calling a member function of an object.

Parameters

type	The event type.
receiver	The object to call.
method	The member function to call. It can take the event or nothing.
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

Warning: The listener calls receiver for as long as it lives, so receiver must outlive the page, or the listener must be added with the signal of an AbortController that receiver owns. The smart-pointer overload with a std::weak_ptr skips calls once the object is gone instead.

◆ addEventListener() [2/6]

template<typename C, typename M>
requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)

EventListener addEventListener	(	std::string_view	type,
		C &	receiver,
		M	method,
		EventListenerFlags	flags ) const

inline

Listen for an event on the document by calling a member function of an object, with options as flags.

Parameters

type	The event type.
receiver	The object to call.
method	The member function to call. It can take the event or nothing.
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

Warning: The listener calls receiver for as long as it lives, so receiver must outlive the page. To tie the listener to receiver instead, use the options overload with the signal of an AbortController that receiver owns.

◆ addEventListener() [3/6]

template<typename F>

EventListener addEventListener	(	std::string_view	type,
		F &&	callback,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen for an event on the document (addEventListener).

This works like Element::addEventListener().

Parameters

type	The event type (eg, keydown).
callback	The function to call for each event. It can take the event or nothing: [](dom::Event event) { ... } or [] { ... }.
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

◆ addEventListener() [4/6]

template<typename F>

EventListener addEventListener	(	std::string_view	type,
		F &&	callback,
		EventListenerFlags	flags ) const

inline

Listen for an event on the document, with options as flags (eg, dom::Once | dom::Capture).

Parameters

type	The event type.
callback	The function to call for each event. It can take the event or nothing.
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

◆ addEventListener() [5/6]

template<typename H, typename M>
requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)

EventListener addEventListener	(	std::string_view	type,
		H	holder,
		M	method,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen for an event on the document by calling a member function through a smart pointer.

A std::shared_ptr keeps the object alive for as long as the listener exists. A std::weak_ptr doesn't, and events are skipped once the object is gone.

Parameters

type	The event type.
holder	The smart pointer (a std::shared_ptr, a std::weak_ptr, or any type with a HolderTraits specialization).
method	The member function to call. It can take the event or nothing.
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

◆ addEventListener() [6/6]

template<typename H, typename M>
requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)

EventListener addEventListener	(	std::string_view	type,
		H	holder,
		M	method,
		EventListenerFlags	flags ) const

inline

Listen for an event on the document by calling a member function through a smart pointer, with options as flags.

Parameters

type	The event type.
holder	The smart pointer (a std::shared_ptr, a std::weak_ptr, or any type with a HolderTraits specialization).
method	The member function to call. It can take the event or nothing.
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

◆ Adopt()

Document Adopt ( ULDOMDocument handle )

inlinestatic

Wrap a C handle you own, taking ownership of it.

Parameters

handle A handle from the C API that you would otherwise destroy with ulDestroyDOMDocument() (NULL gives an empty Document).

Returns: Returns a Document that destroys handle when it's done.

◆ body()

Element body ( ) const

inline

Get the document's body element (body).

Returns: Returns the <body> element (empty if there's none).

◆ childElementCount()

size_t childElementCount ( ) const

inline

Get the number of the document's child elements (childElementCount).

Returns: Returns the number of child elements (1 for a document with a root element).

◆ childNodes()

NodeList childNodes ( ) const

inline

Get the document's children of every kind in order (childNodes).

Returns: Returns the children, including the doctype and any comments outside the root element (an empty list if there are none).

Note: The list is a snapshot, where the web's childNodes is live. Call this again to see later changes.

◆ children()

ElementList children ( ) const

inline

Get the document's child elements in order (children).

Returns: Returns the child elements (an empty list if there are none).

Note: Unlike the web's live collection, the list doesn't change when the document does. Call this again to see later changes.

◆ createComment()

Node createComment ( std::string_view data ) const

inline

Create a comment node (createComment).

The new node belongs to this document but isn't in the page yet. Add it with Element::appendChild() or another insertion method.

Parameters

data	The comment's text.

Returns: Returns the new comment node.

◆ createDocumentFragment()

DocumentFragment createDocumentFragment ( ) const

inline

Create an empty document fragment (createDocumentFragment).

Use a fragment to build a group of nodes off the page and insert them in one step (see DocumentFragment).

Returns: Returns the new fragment.

◆ createElement()

Element createElement ( std::string_view tag_name ) const

inline

Create an element (createElement).

The new element belongs to this document but isn't in the page yet. Add it with Element::appendChild() or another insertion method.

Parameters

tag_name The tag name (eg, div). In an HTML document it's lowercased.

Returns: Returns the new element (empty if tag_name isn't a valid element name).

◆ createRange()

Range createRange ( ) const

inline

Create a range (createRange).

The range starts collapsed at the start of the document. Move it with Range::setStart() or Range::selectNodeContents().

Returns: Returns the new range.

◆ createTextNode()

Node createTextNode ( std::string_view data ) const

inline

Create a text node (createTextNode).

The new node belongs to this document but isn't in the page yet. Add it with Element::appendChild() or another insertion method. The text is never parsed as markup.

Parameters

data The text.

Returns: Returns the new text node.

◆ defaultView()

Window defaultView ( ) const

inline

Get the document's window (defaultView).

The window holds the viewport's size and scroll position. It receives the page's load and the viewport's resize events.

Returns: Returns the window.

Note: Include <Ultralight/dom/Window.h> (or <Ultralight/DOM.h>) to call this.

◆ dispatchCustomEvent()

bool dispatchCustomEvent	(	std::string_view	type,
		std::string_view	event_detail,
		const EventInit &	init = {} ) const

inline

Dispatch a synthetic CustomEvent with a string payload to the document.

Listeners run before this returns. Native listeners read the payload with CustomEvent::detail(), and page scripts read it as event.detail.

Parameters

type	The event type.
event_detail	The payload as UTF-8 text (see Element::dispatchCustomEvent()).
init	Whether the event bubbles, can be canceled, and is composed (see EventInit).

Returns: Returns false if a listener canceled the event with Event::preventDefault(). Returns true otherwise.

◆ dispatchEvent()

bool dispatchEvent	(	std::string_view	type,
		const EventInit &	init = {} ) const

inline

Dispatch a synthetic event to the document (dispatchEvent).

Listeners run before this returns. A bubbling event also reaches window listeners.

Parameters

type	The event type (eg, my-app-ready).
init	Whether the event bubbles, can be canceled, and is composed (see EventInit).

Returns: Returns false if a listener canceled the event with Event::preventDefault() (only possible when init.cancelable is true). Returns true otherwise.

◆ documentElement()

Element documentElement ( ) const

inline

Get the document's root element (documentElement).

Returns: Returns the root element (empty if there's none). In an HTML document it's the <html> element.

◆ elementFromPoint()

Element elementFromPoint	(	double	x,
		double	y ) const

inline

Find the topmost element at a point in the viewport (elementFromPoint).

Parameters

x	The horizontal position, in CSS pixels from the viewport's left edge.
y	The vertical position, in CSS pixels from the viewport's top edge.

Returns: Returns the topmost element at that point (empty if the point is outside the viewport).

Note: These are the same coordinates as event client positions and Element::getBoundingClientRect(). To convert from View pixels, divide by View::device_scale() (an 800x600 View with a device scale of 2.0 is 400x300 CSS pixels).

◆ elementsFromPoint()

ElementList elementsFromPoint	(	double	x,
		double	y ) const

inline

Find every element at a point in the viewport, topmost first (elementsFromPoint).

The list starts with the element elementFromPoint() returns and continues with the elements painted below it. It ends with the root <html> element.

Parameters

x	The horizontal position, in CSS pixels from the viewport's left edge.
y	The vertical position, in CSS pixels from the viewport's top edge.

Returns: Returns the elements, topmost first (an empty list if the point is outside the viewport).

Note: These are the same coordinates elementFromPoint() takes. Like that method, this updates the layout first if the page has pending changes.

◆ firstChild()

Node firstChild ( ) const

inline

Get the document's first child of any kind (firstChild).

Returns: Returns the first child (eg, the doctype, a comment, or the root element; empty if there's none).

◆ firstElementChild()

Element firstElementChild ( ) const

inline

Get the document's first child element (firstElementChild).

Returns: Returns the first child element, which is the root element (empty if there's none).

◆ FromBorrowed()

Document FromBorrowed ( ULDOMDocument handle )

inlinestatic

Wrap a C handle the library owns (eg, a callback argument), adding a reference.

Parameters

handle The borrowed handle (NULL gives an empty Document).

Returns: Returns a Document with its own reference, so you can keep it after the callback.

◆ getElementById()

Element getElementById ( std::string_view id ) const

inline

Find the element with a certain id (getElementById).

Parameters

id	The id to look for.

Returns: Returns the element (empty if no element has that id).

◆ getSelection()

Selection getSelection ( ) const

inline

Get the document's selection (getSelection).

The selection is the highlighted text or the caret on the page. It's the same selection Window::getSelection() returns.

Returns: Returns the selection.

Note: Include <Ultralight/dom/Selection.h> (or <Ultralight/DOM.h>) to call this.

◆ hasChildNodes()

bool hasChildNodes ( ) const

inline

Whether or not the document has any children (hasChildNodes).

Returns: Returns true if the document has at least one child node.

◆ hasFocus()

bool hasFocus ( ) const

inline

Whether or not the document has keyboard focus (hasFocus).

This is true when the View has focus (see View::Focus()) and the focused frame is this document's frame or one of its subframes.

◆ head()

Element head ( ) const

inline

Get the document's head element (head).

Returns: Returns the <head> element (empty if there's none).

◆ IsAlive()

bool IsAlive ( ) const

inline

Whether or not this Document is valid (it isn't empty and its page is still alive).

Note: Safe to call from any thread.

◆ IsEmpty()

bool IsEmpty ( ) const

inline

Whether or not this Document is empty (it holds no handle).

◆ lastChild()

Node lastChild ( ) const

inline

Get the document's last child of any kind (lastChild).

Returns: Returns the last child (empty if there's none).

◆ lastElementChild()

Element lastElementChild ( ) const

inline

Get the document's last child element (lastElementChild).

Returns: Returns the last child element, which is the root element (empty if there's none).

◆ LeakRef()

ULDOMDocument LeakRef ( )

inline

Give up ownership of the C handle and return it.

This Document becomes empty.

Returns: Returns the handle. You must call ulDestroyDOMDocument() when finished.

◆ On() [1/8]

template<typename C, typename M>
requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)

EventListener On	(	std::string_view	selector,
		std::string_view	type,
		C &	receiver,
		M	method,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen for an event on every element that matches a CSS selector by calling a member function of an object.

Parameters

selector	A CSS selector the event's target or one of its ancestors must match.
type	The event type.
receiver	The object to call.
method	The member function to call. It can take the event and the matching element, only the matching element, or nothing.
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

Warning: The listener calls receiver for as long as it lives, so receiver must outlive the page, or the listener must be added with the signal of an AbortController that receiver owns. The smart-pointer overload with a std::weak_ptr skips calls once the object is gone instead.

◆ On() [2/8]

template<typename C, typename M>
requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)

EventListener On	(	std::string_view	selector,
		std::string_view	type,
		C &	receiver,
		M	method,
		EventListenerFlags	flags ) const

inline

Listen for an event on every element that matches a CSS selector by calling a member function of an object, with options as flags.

Parameters

selector	A CSS selector the event's target or one of its ancestors must match.
type	The event type.
receiver	The object to call.
method	The member function to call. It can take the event and the matching element, only the matching element, or nothing.
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

Warning: The listener calls receiver for as long as it lives, so receiver must outlive the page. To tie the listener to receiver instead, use the options overload with the signal of an AbortController that receiver owns.

◆ On() [3/8]

template<typename F>

Result< EventListener > On	(	std::string_view	selector,
		std::string_view	type,
		F &&	callback,
		Checked_t	) const

inlinenodiscard

Same as On() with default options, but returns a Result with the reason for a failure.

Parameters

selector	A CSS selector the event's target or one of its ancestors must match.
type	The event type.
callback	The function to call for each matching event. It can take the event and the matching element, only the matching element, or nothing.

Returns: Returns a handle for removing the listener. Fails with a SyntaxError if selector is malformed.

◆ On() [4/8]

template<typename F>

Result< EventListener > On	(	std::string_view	selector,
		std::string_view	type,
		F &&	callback,
		const AddEventListenerOptions &	options,
		Checked_t	) const

inlinenodiscard

Same as On(), but returns a Result with the reason for a failure (eg, a SyntaxError for a malformed selector).

Parameters

selector	A CSS selector the event's target or one of its ancestors must match.
type	The event type.
callback	The function to call for each matching event. It can take the event and the matching element, only the matching element, or nothing.
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener (empty when options.signal is already aborted). Fails with a SyntaxError if selector is malformed.

◆ On() [5/8]

template<typename F>

EventListener On	(	std::string_view	selector,
		std::string_view	type,
		F &&	callback,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen for an event on every element that matches a CSS selector, including elements added later (event delegation from the document).

Works like Element::On().

Parameters

selector	A CSS selector (eg, .row button). The callback runs when the event's target or one of its ancestors matches it. A malformed selector adds nothing and logs a warning.
type	The event type.
callback	The function to call for each matching event. It can take the event and the matching element, only the matching element, or nothing.
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

◆ On() [6/8]

template<typename F>

EventListener On	(	std::string_view	selector,
		std::string_view	type,
		F &&	callback,
		EventListenerFlags	flags ) const

inline

Listen for an event on every element that matches a CSS selector, with options as flags.

Parameters

selector	A CSS selector the event's target or one of its ancestors must match.
type	The event type.
callback	The function to call for each matching event. It can take the event and the matching element, only the matching element, or nothing.
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

◆ On() [7/8]

template<typename H, typename M>
requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)

EventListener On	(	std::string_view	selector,
		std::string_view	type,
		H	holder,
		M	method,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen for an event on every element that matches a CSS selector by calling a member function through a smart pointer.

A std::shared_ptr keeps the object alive for as long as the listener exists. A std::weak_ptr doesn't, and events are skipped once the object is gone.

Parameters

selector	A CSS selector the event's target or one of its ancestors must match.
type	The event type.
holder	The smart pointer (a std::shared_ptr, a std::weak_ptr, or any type with a HolderTraits specialization).
method	The member function to call. It can take the event and the matching element, only the matching element, or nothing.
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

◆ On() [8/8]

template<typename H, typename M>
requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)

EventListener On	(	std::string_view	selector,
		std::string_view	type,
		H	holder,
		M	method,
		EventListenerFlags	flags ) const

inline

Listen for an event on every element that matches a CSS selector by calling a member function through a smart pointer, with options as flags.

Parameters

selector	A CSS selector the event's target or one of its ancestors must match.
type	The event type.
holder	The smart pointer (a std::shared_ptr, a std::weak_ptr, or any type with a HolderTraits specialization).
method	The member function to call. It can take the event and the matching element, only the matching element, or nothing.
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

◆ operator bool()

operator bool ( ) const

inlineexplicit

Whether or not this Document is valid (see IsAlive()).

◆ operator=()

Document & operator= ( Document other )

inlinenoexcept

Assignment (copies or moves).

Parameters

◆ querySelector() [1/2]

Element querySelector ( std::string_view selectors ) const

inline

Find the first element matching a CSS selector (querySelector).

Parameters

selectors A CSS selector list (eg, .item > a[href]).

Returns: Returns the first match in document order (empty if nothing matches, the selector is malformed, or the page is gone).

◆ querySelector() [2/2]

Result< Element > querySelector	(	std::string_view	selectors,
		Checked_t	) const

inlinenodiscard

Same as querySelector(), but returns a Result with the reason for a failure (eg, a SyntaxError for a malformed selector).

Returns: Returns the first match in document order (an empty Element if nothing matches, which isn't an error). Fails with a SyntaxError if the selector is malformed.

◆ querySelectorAll() [1/2]

ElementList querySelectorAll ( std::string_view selectors ) const

inline

Find every element matching a CSS selector (querySelectorAll).

The list is a snapshot, so later changes to the page don't change it.

Parameters

selectors A CSS selector list (eg, .item > a[href]).

Returns: Returns the matches in document order (an empty list if nothing matches, the selector is malformed, or the page is gone).

◆ querySelectorAll() [2/2]

Result< ElementList > querySelectorAll	(	std::string_view	selectors,
		Checked_t	) const

inlinenodiscard

Same as querySelectorAll(), but returns a Result with the reason for a failure (eg, a SyntaxError for a malformed selector).

Returns: Returns the matches in document order (an empty list if nothing matches). Fails with a SyntaxError if the selector is malformed.

◆ raw()

ULDOMDocument raw ( ) const

inline

Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMDocument.h> functions.

Returns: Returns the handle (NULL for an empty Document). This Document still owns it, so don't destroy it.

Member Data Documentation

◆ title

detail::DocumentStringProp<detail::DocumentTitleTag> title

The document's title (title), the text of its <title> element with whitespace collapsed.

Assign to replace the text of the <title> element. If there's no <title>, one is added to the <head> (nothing happens if there's no <head> either).

The documentation for this class was generated from the following files:

Ultralight/dom/Document.h
Ultralight/dom/Selection.h
Ultralight/dom/Window.h

Overview

Getting a Document

Relationship to Nodes

Document Events

Static Public Member Functions

Public Member Functions

Public Attributes

Protected Member Functions

Constructor & Destructor Documentation

◆ Document() [1/5]

◆ Document() [2/5]

◆ Document() [3/5]

◆ Document() [4/5]

◆ ~Document()

◆ Document() [5/5]

Member Function Documentation

◆ activeElement()

◆ addEventListener() [1/6]

◆ addEventListener() [2/6]

◆ addEventListener() [3/6]

◆ addEventListener() [4/6]

◆ addEventListener() [5/6]

◆ addEventListener() [6/6]

◆ Adopt()

◆ body()

◆ childElementCount()

◆ childNodes()

◆ children()

◆ createComment()

◆ createDocumentFragment()

◆ createElement()

◆ createRange()

◆ createTextNode()

◆ defaultView()

◆ dispatchCustomEvent()

◆ dispatchEvent()

◆ documentElement()

◆ elementFromPoint()

◆ elementsFromPoint()

◆ firstChild()

◆ firstElementChild()

◆ FromBorrowed()

◆ getElementById()

◆ getSelection()

◆ hasChildNodes()

◆ hasFocus()

◆ head()

◆ IsAlive()

◆ IsEmpty()

◆ lastChild()

◆ lastElementChild()

◆ LeakRef()

◆ On() [1/8]

◆ On() [2/8]

◆ On() [3/8]

◆ On() [4/8]

◆ On() [5/8]

◆ On() [6/8]

◆ On() [7/8]

◆ On() [8/8]

◆ operator bool()

◆ operator=()

◆ querySelector() [1/2]

◆ querySelector() [2/2]

◆ querySelectorAll() [1/2]

◆ querySelectorAll() [2/2]

◆ raw()

Member Data Documentation

◆ title