#include <Ultralight/dom/Node.h>

Overview

A reference to an item in the DOM tree.

While query methods like Document::querySelector() find only elements, Node represents any item in the document hierarchy.

Use Node to walk tree relationships when your application needs to reach content that element queries skip.

Consider an element containing both text and markup:

<p id="greeting">Howdy <b>world</b>!</p>

You can step from the element to its first child and narrow the next sibling to an element:

dom::Element greeting = document.getElementById("greeting");
 
dom::Node first = greeting.firstChild();
Log(first.nodeName());  // "#text" (the "Howdy " text)
 
dom::Element bold = first.nextSibling().AsElement();
Log(bold.tagName());    // "B"

Kinds of Nodes

Both dom::Element and dom::DocumentFragment are Nodes. Unlike on the web, dom::Document is a separate type and doesn't inherit from Node (call ownerDocument() on any node to reach its document).

nodeType() returns the kind of node, and nodeName() returns its name. Call AsElement() to narrow a node to a dom::Element (it returns an empty handle for text and comments).

Traversal methods differ in which node kinds they visit:

Node methods visit every child. Calls like firstChild() and nextSibling() return text and comments alongside elements.
Element methods visit elements only. Calls on dom::Element like Element::firstElementChild() and Element::nextElementSibling() skip text and comments.

Like other DOM handles, a Node is always Valid, Empty, or Gone (see dom::Element).

Text and Comment Nodes

You can create standalone text and comment nodes on the document using Document::createTextNode() and Document::createComment(). Passing strings to insertion methods like Element::append(), Element::prepend(), or before() creates text nodes automatically (strings are never parsed as markup).

Assigning to nodeValue updates a text node in place, leaving sibling nodes untouched (unlike assigning to textContent on the parent):

dom::Element scoreboard = document.getElementById("score");
dom::Node points = document.createTextNode("0");
scoreboard.append("Score: ", points);  // the string becomes a text node too
 
points.nodeValue = "42";               // changes only that text node

Note: Whitespace between HTML tags becomes a text node (firstElementChild() skips it).

See also: dom::Element, dom::DocumentFragment, dom::NodeList, dom::Document::createTextNode(), dom::Document::createComment()

Inheritance diagram for Node:

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

Public Member Functions
	Node ()
	Create an empty Node.
	Node (const Node &other)
	Copy constructor (both handles refer to the same node).
	Node (Node &&other) noexcept
	Move constructor (other becomes empty).
Node &	operator= (Node other) noexcept
	Assignment (copies or moves).
	~Node ()
	Destroy this handle (the node itself isn't affected).
	operator bool () const
	Whether or not this Node is valid (see IsAlive()).
bool	IsEmpty () const
	Whether or not this Node is empty (it holds no handle).
bool	IsAlive () const
	Whether or not this Node is valid (it isn't empty and its page is still alive).
bool	IsSame (const Node &other) const
	Whether or not two handles refer to the same node (isSameNode).
NodeType	nodeType () const
	Get the kind of node (nodeType).
std::string	nodeName () const
	Get the node's name (nodeName).
Node	parentNode () const
	Get the node's parent (parentNode).
Element	parentElement () const
	Get the node's parent element (parentElement).
Node	firstChild () const
	Get the node's first child of any kind (firstChild).
Node	lastChild () const
	Get the node's last child of any kind (lastChild).
Node	previousSibling () const
	Get the node's previous sibling of any kind (previousSibling).
Node	nextSibling () const
	Get the node's next sibling of any kind (nextSibling).
NodeList	childNodes () const
	Get the node's children of every kind in order (childNodes).
bool	hasChildNodes () const
	Whether or not the node has any children (hasChildNodes).
bool	isConnected () const
	Whether or not the node is in its document (isConnected).
Document	ownerDocument () const
	Get the document this node belongs to (ownerDocument).
Element	AsElement () const
	Get this node as an Element.
DocumentFragment	AsFragment () const
	Get this node as a DocumentFragment.
template<typename... T> requires ((detail::NodeOrString<T> && ...))
void	before (T &&... nodes) const
	Insert nodes and strings just before this node, in its parent (before).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
Result< void >	before (Checked_t, T &&... nodes) const
	Same as before(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
void	after (T &&... nodes) const
	Insert nodes and strings just after this node, in its parent (after).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
Result< void >	after (Checked_t, T &&... nodes) const
	Same as after(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
void	replaceWith (T &&... nodes) const
	Replace this node with nodes and strings, in its parent (replaceWith).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
Result< void >	replaceWith (Checked_t, T &&... nodes) const
	Same as replaceWith(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).
void	remove () const
	Remove this node from its parent (remove).
Result< void >	remove (Checked_t) const
	Same as remove(), but returns a Result with the reason for a failure.
ULDOMNode	raw () const
	Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMNode.h> functions.
ULDOMNode	LeakRef ()
	Give up ownership of the C handle and return it.

Public Attributes
detail::NodeStringProp< detail::NodeValueTag >	nodeValue
	The text of a text or comment node (nodeValue).
detail::NodeStringProp< detail::NodeTextContentTag >	textContent
	The text of this node and all its descendants (textContent).
detail::NodeStorage	detail_
	Internal storage (not part of the API).

Protected Member Functions
	Node (ULDOMNode handle)

Constructor & Destructor Documentation

◆ Node() [1/4]

Node ( )

inline

Create an empty Node.

◆ Node() [2/4]

Node ( const Node & other )

inline

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

Parameters

other The Node to copy.

◆ Node() [3/4]

Node ( Node && other )

inlinenoexcept

Move constructor (other becomes empty).

Parameters

other The Node to move from.

◆ ~Node()

~Node ( )

inline

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

◆ Node() [4/4]

Node ( ULDOMNode handle )

inlineexplicitprotected

Member Function Documentation

◆ Adopt()

Node Adopt ( ULDOMNode 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 ulDestroyDOMNode() (NULL gives an empty Node).

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

◆ after() [1/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

Result< void > after	(	Checked_t	,
		T &&...	nodes ) const

inlinenodiscard

Same as after(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).

dom::Checked comes first here, before the nodes (node.after(dom::Checked, a, "b")).

Returns: Returns success (including when this node has no parent). Fails with a HierarchyRequestError if one of the nodes can't go there (eg, it's this node's parent or one of its ancestors).

◆ after() [2/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

void after ( T &&... nodes ) const

inline

Insert nodes and strings just after this node, in its parent (after).

Each string is inserted as a new text node (it's never parsed as markup). This does nothing if the node has no parent.

Parameters

nodes The nodes and strings to insert, in order. A node that's already in a document moves (even if it's one of this node's siblings).

Note: With more than one argument, the nodes leave their old positions before the insertion is checked (like the web), so a call that fails can leave them out of the page.

◆ AsElement()

Element AsElement ( ) const

inline

Get this node as an Element.

Returns: Returns an Element for the same node (empty if the node isn't an element).

◆ AsFragment()

DocumentFragment AsFragment ( ) const

inline

Get this node as a DocumentFragment.

This is defined in <Ultralight/dom/DocumentFragment.h>. Include that header (or <Ultralight/DOM.h>) to call it.

Returns: Returns a DocumentFragment for the same node (empty if the node isn't a document fragment).

◆ before() [1/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

Result< void > before	(	Checked_t	,
		T &&...	nodes ) const

inlinenodiscard

Same as before(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).

dom::Checked comes first here, before the nodes (node.before(dom::Checked, a, "b")).

Returns: Returns success (including when this node has no parent). Fails with a HierarchyRequestError if one of the nodes can't go there (eg, it's this node's parent or one of its ancestors).

◆ before() [2/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

void before ( T &&... nodes ) const

inline

Insert nodes and strings just before this node, in its parent (before).

Each string is inserted as a new text node (it's never parsed as markup). This does nothing if the node has no parent.

Parameters

nodes The nodes and strings to insert, in order. A node that's already in a document moves (even if it's one of this node's siblings).

Note: With more than one argument, the nodes leave their old positions before the insertion is checked (like the web), so a call that fails can leave them out of the page.

◆ childNodes()

NodeList childNodes ( ) const

inline

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

This is defined in <Ultralight/dom/NodeList.h>. Include that header (or <Ultralight/DOM.h>) to call it.

Returns: Returns the children, including text and comment nodes (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.

◆ firstChild()

Node firstChild ( ) const

inline

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

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

◆ FromBorrowed()

Node FromBorrowed ( ULDOMNode 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 Node).

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

◆ hasChildNodes()

bool hasChildNodes ( ) const

inline

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

Returns: Returns true if the node has at least one child of any kind.

◆ IsAlive()

bool IsAlive ( ) const

inline

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

Note: Safe to call from any thread.

◆ isConnected()

bool isConnected ( ) const

inline

Whether or not the node is in its document (isConnected).

A node you just created, or one you removed, isn't connected until you insert it into the page.

Returns: Returns true if the node is in the document (false for an empty Node or one whose page is gone).

◆ IsEmpty()

bool IsEmpty ( ) const

inline

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

◆ IsSame()

bool IsSame ( const Node & other ) const

inline

Whether or not two handles refer to the same node (isSameNode).

Parameters

other The handle to compare with.

Returns: Returns true if both handles are valid and refer to the same node.

◆ lastChild()

Node lastChild ( ) const

inline

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

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

◆ LeakRef()

ULDOMNode LeakRef ( )

inline

Give up ownership of the C handle and return it.

This Node becomes empty.

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

◆ nextSibling()

Node nextSibling ( ) const

inline

Get the node's next sibling of any kind (nextSibling).

Returns: Returns the next sibling (empty if there's none).

◆ nodeName()

std::string nodeName ( ) const

inline

Get the node's name (nodeName).

Returns: Returns the tag name for an element (uppercase for HTML, eg, DIV), #text for a text node, or #comment for a comment.

◆ nodeType()

NodeType nodeType ( ) const

inline

Get the kind of node (nodeType).

Returns: Returns the kind of node (NodeType::None for an empty Node or one whose page is gone).

◆ operator bool()

operator bool ( ) const

inlineexplicit

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

◆ operator=()

Node & operator= ( Node other )

inlinenoexcept

Assignment (copies or moves).

Parameters

other The Node to assign from.

Returns: Returns this Node.

◆ ownerDocument()

Document ownerDocument ( ) const

inline

Get the document this node belongs to (ownerDocument).

Returns: Returns the document of the page this handle came from.

◆ parentElement()

Element parentElement ( ) const

inline

Get the node's parent element (parentElement).

Returns: Returns the parent element (empty if the parent isn't an element).

◆ parentNode()

Node parentNode ( ) const

inline

Get the node's parent (parentNode).

Returns: Returns the parent node (empty if the node has no parent or its parent is the document).

◆ previousSibling()

Node previousSibling ( ) const

inline

Get the node's previous sibling of any kind (previousSibling).

Returns: Returns the previous sibling (empty if there's none).

◆ raw()

ULDOMNode raw ( ) const

inline

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

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

◆ remove() [1/2]

void remove ( ) const

inline

Remove this node from its parent (remove).

Does nothing if it has no parent.

This handle still refers to the removed node, so you can insert it again.

◆ remove() [2/2]

Result< void > remove ( Checked_t ) const

inlinenodiscard

Same as remove(), but returns a Result with the reason for a failure.

Returns: Returns success (including when this node has no parent). It fails only when this Node is empty or its page is gone.

◆ replaceWith() [1/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

Result< void > replaceWith	(	Checked_t	,
		T &&...	nodes ) const

inlinenodiscard

Same as replaceWith(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).

dom::Checked comes first here, before the nodes (node.replaceWith(dom::Checked, a, "b")).

Returns: Returns success (including when this node has no parent). Fails with a HierarchyRequestError if one of the nodes can't go there (eg, it's this node's parent or one of its ancestors).

◆ replaceWith() [2/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

void replaceWith ( T &&... nodes ) const

inline

Replace this node with nodes and strings, in its parent (replaceWith).

Each string is inserted as a new text node (it's never parsed as markup). With no arguments, this removes the node. This does nothing if the node has no parent. This handle still refers to the removed node afterward.

Parameters

nodes The nodes and strings to put in its place, in order. A node that's already in a document moves (even if it's one of this node's siblings).

Note: With more than one argument, the nodes leave their old positions before the insertion is checked (like the web), so a call that fails can leave them out of the page.

Member Data Documentation

◆ detail_

detail::NodeStorage detail_

Internal storage (not part of the API).

Use raw() to get the C handle.

◆ nodeValue

detail::NodeStringProp<detail::NodeValueTag> nodeValue

The text of a text or comment node (nodeValue).

Assign to replace it.

Other kinds of node (eg, elements) read as an empty string and ignore writes.

◆ textContent

detail::NodeStringProp<detail::NodeTextContentTag> textContent

The text of this node and all its descendants (textContent).

Assigning to an element replaces its children with the text (an empty string removes them).

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

Ultralight/dom/Node.h
Ultralight/dom/Document.h
Ultralight/dom/DocumentFragment.h
Ultralight/dom/Element.h
Ultralight/dom/NodeList.h

Overview

Kinds of Nodes

Text and Comment Nodes

Static Public Member Functions

Public Member Functions

Public Attributes

Protected Member Functions

Constructor & Destructor Documentation

◆ Node() [1/4]

◆ Node() [2/4]

◆ Node() [3/4]

◆ ~Node()

◆ Node() [4/4]

Member Function Documentation

◆ Adopt()

◆ after() [1/2]

◆ after() [2/2]

◆ AsElement()

◆ AsFragment()

◆ before() [1/2]

◆ before() [2/2]

◆ childNodes()

◆ firstChild()

◆ FromBorrowed()

◆ hasChildNodes()

◆ IsAlive()

◆ isConnected()

◆ IsEmpty()

◆ IsSame()

◆ lastChild()

◆ LeakRef()

◆ nextSibling()

◆ nodeName()

◆ nodeType()

◆ operator bool()

◆ operator=()

◆ ownerDocument()

◆ parentElement()

◆ parentNode()

◆ previousSibling()

◆ raw()

◆ remove() [1/2]

◆ remove() [2/2]

◆ replaceWith() [1/2]

◆ replaceWith() [2/2]

Member Data Documentation

◆ detail_

◆ nodeValue

◆ textContent