#include <Ultralight/dom/Range.h>

Overview

A handle to a live range (a span of a page between two boundary points).

A Range works like the JavaScript Range. Get one from Document::createRange() and point it at some content:

dom::Range range = document.createRange();
range.selectNodeContents(para);
std::string text = range.toString();
dom::DOMRect box = range.getBoundingClientRect();

Copying a Range copies the handle, so both refer to the same range. Use cloneRange() to make an independent copy.

After its page goes away, a Range stops working like a dom::Element does (see that class).

Boundary Points

Each boundary point is a node plus an offset. In a text or comment node the offset counts UTF-16 code units. In any other node it counts children.

A new range starts at the document. A boundary point in the document itself reads as an empty Node (the document is never a Node), so point the range at real content first.
Boundary nodes must come from the range's own document. A node from another document (eg, a subframe's) leaves the range unchanged (with dom::Checked, the call fails with a WrongDocumentError).

Live Updates

The range stays valid while the page changes. When nodes are inserted or removed, the library moves the boundary points to match. If a boundary point's node is removed, the point moves to where that node was in its parent.

Each live range adds a little work to every DOM change in its document, so destroy a Range once you're done with it.

Public Types
enum class	CompareHow : uint8_t { StartToStart = kULDOMRangeCompareHow_StartToStart , StartToEnd = kULDOMRangeCompareHow_StartToEnd , EndToEnd = kULDOMRangeCompareHow_EndToEnd , EndToStart = kULDOMRangeCompareHow_EndToStart }
	Which boundary points compareBoundaryPoints() compares (the web's Range.START_TO_START constants). More...

Static Public Member Functions
static Range	Adopt (ULDOMRange handle)
	Wrap a C handle you own, taking ownership of it.
static Range	FromBorrowed (ULDOMRange handle)
	Wrap a C handle you don't own, adding a reference.

Public Member Functions
	Range ()
	Create an empty Range.
	Range (const Range &other)
	Copy constructor (both handles refer to the same range).
	Range (Range &&other) noexcept
	Move constructor (other becomes empty).
Range &	operator= (Range other) noexcept
	Assignment (copies or moves).
	~Range ()
	Destroy this handle (the page isn't affected).
	operator bool () const
	Whether or not this Range is valid (see IsAlive()).
bool	IsEmpty () const
	Whether or not this Range is empty (it holds no handle).
bool	IsAlive () const
	Whether or not this Range is valid (it isn't empty and its page is still alive).
Node	startContainer () const
	Get the node that holds the range's start (startContainer).
size_t	startOffset () const
	Get the offset of the range's start in startContainer() (startOffset).
Node	endContainer () const
	Get the node that holds the range's end (endContainer).
size_t	endOffset () const
	Get the offset of the range's end in endContainer() (endOffset).
bool	collapsed () const
	Whether or not the range's start and end are the same point (collapsed).
Node	commonAncestorContainer () const
	Get the deepest node that contains both boundary points (commonAncestorContainer).
void	setStart (const Node &node, size_t offset) const
	Set the range's start (setStart).
Result< void >	setStart (const Node &node, size_t offset, Checked_t) const
	Same as setStart(), but returns a Result with the reason for a failure (eg, an IndexSizeError if offset is past the end of node).
void	setEnd (const Node &node, size_t offset) const
	Set the range's end (setEnd).
Result< void >	setEnd (const Node &node, size_t offset, Checked_t) const
	Same as setEnd(), but returns a Result with the reason for a failure (eg, an IndexSizeError if offset is past the end of node).
void	collapse (bool to_start=false) const
	Collapse the range to its start or its end (collapse).
void	selectNode (const Node &node) const
	Make the range cover a whole node (selectNode).
Result< void >	selectNode (const Node &node, Checked_t) const
	Same as selectNode(), but returns a Result with the reason for a failure (eg, an InvalidNodeTypeError if node has no parent).
void	selectNodeContents (const Node &node) const
	Make the range cover everything inside a node (selectNodeContents).
Result< void >	selectNodeContents (const Node &node, Checked_t) const
	Same as selectNodeContents(), but returns a Result with the reason for a failure (eg, a WrongDocumentError if node is from another document).
int	compareBoundaryPoints (CompareHow how, const Range &other) const
	Compare a boundary point of this range with one of another range (compareBoundaryPoints).
Result< int >	compareBoundaryPoints (CompareHow how, const Range &other, Checked_t) const
	Same as compareBoundaryPoints(), but returns a Result with the reason for a failure (eg, a WrongDocumentError if the ranges are in different documents).
void	deleteContents () const
	Remove the range's contents from the page (deleteContents).
Result< void >	deleteContents (Checked_t) const
	Same as deleteContents(), but returns a Result with the reason for a failure.
DocumentFragment	extractContents () const
	Move the range's contents out of the page into a new fragment (extractContents).
Result< DocumentFragment >	extractContents (Checked_t) const
	Same as extractContents(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError if the range contains a doctype).
DocumentFragment	cloneContents () const
	Copy the range's contents into a new fragment (cloneContents).
Result< DocumentFragment >	cloneContents (Checked_t) const
	Same as cloneContents(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError if the range contains a doctype).
void	insertNode (const Node &node) const
	Insert a node at the range's start (insertNode).
Result< void >	insertNode (const Node &node, Checked_t) const
	Same as insertNode(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError if node can't go there).
Range	cloneRange () const
	Create an independent copy of the range (cloneRange).
std::string	toString () const
	Get the text the range covers (toString).
DOMRect	getBoundingClientRect () const
	Get the smallest rectangle that contains everything the range covers (getBoundingClientRect).
std::vector< DOMRect >	getClientRects () const
	Get a rectangle for each box the range covers (getClientRects).
ULDOMRange	raw () const
	Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMRange.h> functions.
ULDOMRange	LeakRef ()
	Give up ownership of the C handle and return it.

Protected Member Functions
	Range (ULDOMRange handle)

Protected Attributes
ULDOMRange	handle_ = nullptr

Member Enumeration Documentation

◆ CompareHow

enum class CompareHow : uint8_t

strong

Which boundary points compareBoundaryPoints() compares (the web's Range.START_TO_START constants).

Enumerator
StartToStart	Compare the two start points.
StartToEnd	This end vs the other's start.
EndToEnd	Compare the two end points.
EndToStart	This start vs the other's end.

Constructor & Destructor Documentation

◆ Range() [1/4]

Range ( )

inline

Create an empty Range.

◆ Range() [2/4]

Range ( const Range & other )

inline

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

Parameters

other The Range to copy.

◆ Range() [3/4]

Range ( Range && other )

inlinenoexcept

Move constructor (other becomes empty).

Parameters

other The Range to move from.

◆ ~Range()

~Range ( )

inline

Destroy this handle (the page isn't affected).

◆ Range() [4/4]

Range ( ULDOMRange handle )

inlineexplicitprotected

Member Function Documentation

◆ Adopt()

Range Adopt ( ULDOMRange 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 ulDestroyDOMRange() (NULL gives an empty Range).

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

◆ cloneContents() [1/2]

DocumentFragment cloneContents ( ) const

inline

Copy the range's contents into a new fragment (cloneContents).

The page doesn't change.

Returns: Returns the fragment (empty if the range contains a doctype or its page is gone).

◆ cloneContents() [2/2]

Result< DocumentFragment > cloneContents ( Checked_t ) const

inlinenodiscard

Same as cloneContents(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError if the range contains a doctype).

Returns: Returns the fragment. Fails with a HierarchyRequestError if the range contains a doctype.

◆ cloneRange()

Range cloneRange ( ) const

inline

Create an independent copy of the range (cloneRange).

Returns: Returns a new Range with the same boundary points. From then on, each range updates on its own.

◆ collapse()

void collapse ( bool to_start = false ) const

inline

Collapse the range to its start or its end (collapse).

Parameters

to_start Pass true to collapse to the start and false to collapse to the end.

◆ collapsed()

bool collapsed ( ) const

inline

Whether or not the range's start and end are the same point (collapsed).

Returns: Returns true if the range is collapsed (also for an empty Range or one whose page is gone).

◆ commonAncestorContainer()

Node commonAncestorContainer ( ) const

inline

Get the deepest node that contains both boundary points (commonAncestorContainer).

Returns: Returns the node (empty if it's the document itself).

◆ compareBoundaryPoints() [1/2]

int compareBoundaryPoints	(	CompareHow	how,
		const Range &	other ) const

inline

Compare a boundary point of this range with one of another range (compareBoundaryPoints).

Parameters

how	Which point of each range to compare (see CompareHow).
other	The range to compare with.

Returns: Returns -1, 0, or 1 if this range's point is before, at, or after the other range's point. Also returns 0 if the call fails (eg, the ranges are in different documents), so use the dom::Checked overload to tell a failure from equal points.

◆ compareBoundaryPoints() [2/2]

Result< int > compareBoundaryPoints	(	CompareHow	how,
		const Range &	other,
		Checked_t	) const

inlinenodiscard

Same as compareBoundaryPoints(), but returns a Result with the reason for a failure (eg, a WrongDocumentError if the ranges are in different documents).

Returns: Returns -1, 0, or 1 if this range's point is before, at, or after the other range's point. Fails with a WrongDocumentError if the two points aren't in the same tree (eg, the ranges are in different documents).

◆ deleteContents() [1/2]

void deleteContents ( ) const

inline

Remove the range's contents from the page (deleteContents).

Text at the edges of the range is trimmed, and the range collapses to where the contents were.

◆ deleteContents() [2/2]

Result< void > deleteContents ( Checked_t ) const

inlinenodiscard

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

Returns: Returns success (it fails only when this range is empty or its page is gone).

◆ endContainer()

Node endContainer ( ) const

inline

Get the node that holds the range's end (endContainer).

Returns: Returns the node (empty if the end is in the document itself).

◆ endOffset()

size_t endOffset ( ) const

inline

Get the offset of the range's end in endContainer() (endOffset).

◆ extractContents() [1/2]

DocumentFragment extractContents ( ) const

inline

Move the range's contents out of the page into a new fragment (extractContents).

A node that's only partly inside the range stays in the page without the covered part, and the fragment gets a copy that holds that part. The range collapses to where the contents were.

Returns: Returns the fragment (empty if the range contains a doctype or its page is gone, in which case nothing is removed).

◆ extractContents() [2/2]

Result< DocumentFragment > extractContents ( Checked_t ) const

inlinenodiscard

Same as extractContents(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError if the range contains a doctype).

Returns: Returns the fragment. Fails with a HierarchyRequestError if the range contains a doctype.

◆ FromBorrowed()

Range FromBorrowed ( ULDOMRange handle )

inlinestatic

Wrap a C handle you don't own, adding a reference.

Parameters

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

Returns: Returns a Range with its own reference, so you can keep it as long as you like.

◆ getBoundingClientRect()

DOMRect getBoundingClientRect ( ) const

inline

Get the smallest rectangle that contains everything the range covers (getBoundingClientRect).

Returns: Returns the rectangle in the same viewport coordinates as Element::getBoundingClientRect() (all zero if nothing in the range is displayed).

Note: This reads the layout, so it forces a synchronous style and layout pass if the document has pending changes.

◆ getClientRects()

std::vector< DOMRect > getClientRects ( ) const

inline

Get a rectangle for each box the range covers (getClientRects).

Text that wraps gives one rectangle per line. An element that's fully inside the range adds its own border box too.

Returns: Returns the rectangles in document order, in the same viewport coordinates as Element::getBoundingClientRect().

Note: This reads the layout, so it forces a synchronous style and layout pass if the document has pending changes.

◆ insertNode() [1/2]

void insertNode ( const Node & node ) const

inline

Insert a node at the range's start (insertNode).

If the start is inside a text node, the text node is split there. If the range is collapsed, it grows to cover the inserted node.

Parameters

node	The node to insert (from this range's document). If it already has a parent, it's moved.

Note: Nothing is inserted if node can't go there (eg, the start is inside a comment, or node contains the start) or node is from another document.

◆ insertNode() [2/2]

Result< void > insertNode	(	const Node &	node,
		Checked_t	) const

inlinenodiscard

Same as insertNode(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError if node can't go there).

Returns: Returns success. Fails with a HierarchyRequestError if node can't go there (eg, the start is inside a comment, or node contains the start), or a WrongDocumentError if node is from another document.

◆ IsAlive()

bool IsAlive ( ) const

inline

Whether or not this Range 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 Range is empty (it holds no handle).

◆ LeakRef()

ULDOMRange LeakRef ( )

inline

Give up ownership of the C handle and return it.

This Range becomes empty.

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

◆ operator bool()

operator bool ( ) const

inlineexplicit

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

◆ operator=()

Range & operator= ( Range other )

inlinenoexcept

Assignment (copies or moves).

Parameters

other The Range to assign from.

Returns: Returns this Range.

◆ raw()

ULDOMRange raw ( ) const

inline

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

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

◆ selectNode() [1/2]

void selectNode ( const Node & node ) const

inline

Make the range cover a whole node (selectNode).

The range starts just before node and ends just after it, in node's parent.

Parameters

node	The node to cover (from this range's document).

Note: Nothing changes if node has no parent or is from another document.

◆ selectNode() [2/2]

Result< void > selectNode	(	const Node &	node,
		Checked_t	) const

inlinenodiscard

Same as selectNode(), but returns a Result with the reason for a failure (eg, an InvalidNodeTypeError if node has no parent).

Returns: Returns success. Fails with an InvalidNodeTypeError if node has no parent, or a WrongDocumentError if node is from another document.

◆ selectNodeContents() [1/2]

void selectNodeContents ( const Node & node ) const

inline

Make the range cover everything inside a node (selectNodeContents).

For an element that's all of its children. For a text or comment node it's all of its text.

Parameters

node	The node whose contents to cover (from this range's document).

Note: Nothing changes if node is a doctype or is from another document.

◆ selectNodeContents() [2/2]

Result< void > selectNodeContents	(	const Node &	node,
		Checked_t	) const

inlinenodiscard

Same as selectNodeContents(), but returns a Result with the reason for a failure (eg, a WrongDocumentError if node is from another document).

Returns: Returns success. Fails with an InvalidNodeTypeError if node is a doctype, or a WrongDocumentError if node is from another document.

◆ setEnd() [1/2]

void setEnd	(	const Node &	node,
		size_t	offset ) const

inline

Set the range's end (setEnd).

If the new end is before the range's start, the range collapses to the new end.

Parameters

node	The node for the new end (from this range's document).
offset	The offset in node (see Boundary Points above).

Note: Nothing changes if offset is past the end of node, node is a doctype, or node is from another document.

◆ setEnd() [2/2]

Result< void > setEnd	(	const Node &	node,
		size_t	offset,
		Checked_t	) const

inlinenodiscard

Same as setEnd(), but returns a Result with the reason for a failure (eg, an IndexSizeError if offset is past the end of node).

Returns: Returns success. Fails with an IndexSizeError if offset is past the end of node, an InvalidNodeTypeError if node is a doctype, or a WrongDocumentError if node is from another document.

◆ setStart() [1/2]

void setStart	(	const Node &	node,
		size_t	offset ) const

inline

Set the range's start (setStart).

If the new start is after the range's end, the range collapses to the new start.

Parameters

node	The node for the new start (from this range's document).
offset	The offset in node (see Boundary Points above).

Note: Nothing changes if offset is past the end of node, node is a doctype, or node is from another document.

◆ setStart() [2/2]

Result< void > setStart	(	const Node &	node,
		size_t	offset,
		Checked_t	) const

inlinenodiscard

Same as setStart(), but returns a Result with the reason for a failure (eg, an IndexSizeError if offset is past the end of node).

Returns: Returns success. Fails with an IndexSizeError if offset is past the end of node, an InvalidNodeTypeError if node is a doctype, or a WrongDocumentError if node is from another document.

◆ startContainer()

Node startContainer ( ) const

inline

Get the node that holds the range's start (startContainer).

Returns: Returns the node (empty if the start is in the document itself).

◆ startOffset()

size_t startOffset ( ) const

inline

Get the offset of the range's start in startContainer() (startOffset).

◆ toString()

std::string toString ( ) const

inline

Get the text the range covers (toString).

Returns: Returns the text of the text nodes in the range (comments aren't included).

Member Data Documentation

◆ handle_

ULDOMRange handle_ = nullptr

protected

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

Ultralight/dom/Range.h

Overview

Boundary Points

Live Updates

Public Types

Static Public Member Functions

Public Member Functions

Protected Member Functions

Protected Attributes

Member Enumeration Documentation

◆ CompareHow

Constructor & Destructor Documentation

◆ Range() [1/4]

◆ Range() [2/4]

◆ Range() [3/4]

◆ ~Range()

◆ Range() [4/4]

Member Function Documentation

◆ Adopt()

◆ cloneContents() [1/2]

◆ cloneContents() [2/2]

◆ cloneRange()

◆ collapse()

◆ collapsed()

◆ commonAncestorContainer()

◆ compareBoundaryPoints() [1/2]

◆ compareBoundaryPoints() [2/2]

◆ deleteContents() [1/2]

◆ deleteContents() [2/2]

◆ endContainer()

◆ endOffset()

◆ extractContents() [1/2]

◆ extractContents() [2/2]

◆ FromBorrowed()

◆ getBoundingClientRect()

◆ getClientRects()

◆ insertNode() [1/2]

◆ insertNode() [2/2]

◆ IsAlive()

◆ IsEmpty()

◆ LeakRef()

◆ operator bool()

◆ operator=()

◆ raw()

◆ selectNode() [1/2]

◆ selectNode() [2/2]

◆ selectNodeContents() [1/2]

◆ selectNodeContents() [2/2]

◆ setEnd() [1/2]

◆ setEnd() [2/2]

◆ setStart() [1/2]

◆ setStart() [2/2]

◆ startContainer()

◆ startOffset()

◆ toString()

Member Data Documentation

◆ handle_