A handle to the active user selection or caret in a document.
A dom::Selection represents either a caret or highlighted text on a page. You obtain one by calling Document::getSelection() or Window::getSelection().
The handle is live– reading its properties reflects the user's current selection.
This example checks whether the user highlighted text and shows a quote button:
A handle to the active user selection or caret in a document.
Definition Selection.h:101
bool isCollapsed() const
Whether or not the selection is a caret (isCollapsed).
Definition Selection.h:191
std::string toString() const
Get the selected text (toString).
Definition Selection.h:210
Anchor and Focus
A selection spans between two endpoints in the document tree:
- The anchor marks where the selection starts. Calling anchorNode() returns the containing dom::Node, and anchorOffset() returns the offset within that node.
- The focus marks where the selection ends. Calling focusNode() and focusOffset() returns its position, which can sit before the anchor when the user selects backward.
Each document has its own Selection (including each subframe).
Reacting to Selection Changes
Every change to the active selection dispatches a selectionchange event on the document. The library delivers these events during a later Renderer::Update(), dispatching one event for each change.
This example updates UI state whenever the selection changes:
document.addEventListener("selectionchange", [selection] {
UpdateQuoteButton(selection.
toString());
});
Selecting a Range
To select a dom::Range, call removeAllRanges() before calling addRange(). On its own, addRange() only expands an existing selection if the new range overlaps it, and it ignores any range that doesn't overlap.
This example selects the contents of an element:
A handle to a live range (a span of a page between two boundary points).
Definition Range.h:58
void selectNodeContents(const Node &node) const
Make the range cover everything inside a node (selectNodeContents).
Definition Range.h:281
void addRange(const Range &range) const
Select a range (addRange).
Definition Selection.h:426
void removeAllRanges() const
Clear the selection (removeAllRanges or empty).
Definition Selection.h:412
Selections in Text Fields
The selection doesn't enter editable form controls. When an <input> or <textarea> has focus, anchorNode() and focusNode() sit just outside the element, and isCollapsed() returns true. To read or change selected text inside an editable field, use the element's selectionStart and selectionEnd properties instead (see dom::HTMLInputElement).
Differences from Web Browsers
Several methods handle node validation and range ownership differently from JavaScript:
- Cross-document nodes are ignored. Passing a node from another document (such as a subframe) leaves the selection unchanged instead of throwing an exception.
- Offsets past the end of a node fail only in extend(). Other placement methods like collapse(), setBaseAndExtent(), and selectAllChildren() don't check whether an offset exceeds the node's length.
- getRangeAt() returns an independent copy. Changes made to the returned dom::Range don't alter the active selection.
After its page goes away, a Selection stops working like a dom::Element does (see that class).
- See also
- dom::Document::getSelection(), dom::Window::getSelection(), dom::Range, dom::HTMLInputElement
|
| | Selection () |
| | Create an empty Selection.
|
| | Selection (const Selection &other) |
| | Copy constructor (both handles refer to the same selection).
|
| | Selection (Selection &&other) noexcept |
| | Move constructor (other becomes empty).
|
| Selection & | operator= (Selection other) noexcept |
| | Assignment (copies or moves).
|
| | ~Selection () |
| | Destroy this handle (the selection itself isn't affected).
|
| | operator bool () const |
| | Whether or not this Selection is valid (see IsAlive()).
|
| bool | IsEmpty () const |
| | Whether or not this Selection is empty (it holds no handle).
|
| bool | IsAlive () const |
| | Whether or not this Selection is valid (it isn't empty and its page is still alive).
|
| Node | anchorNode () const |
| | Get the node the selection starts in (anchorNode).
|
| size_t | anchorOffset () const |
| | Get the offset of the anchor in anchorNode() (anchorOffset).
|
| Node | focusNode () const |
| | Get the node the selection ends in (focusNode).
|
| size_t | focusOffset () const |
| | Get the offset of the focus in focusNode() (focusOffset).
|
| bool | isCollapsed () const |
| | Whether or not the selection is a caret (isCollapsed).
|
| size_t | rangeCount () const |
| | Get the number of ranges in the selection (rangeCount).
|
| std::string | type () const |
| | Get the kind of selection (type).
|
| std::string | toString () const |
| | Get the selected text (toString).
|
| void | collapse (const Node &node, size_t offset=0) const |
| | Place a caret (collapse or setPosition).
|
| Result< void > | collapse (const Node &node, Checked_t) const |
| | Same as collapse(), but returns a Result with the reason for a failure.
|
| Result< void > | collapse (const Node &node, size_t offset, Checked_t) const |
| | Same as collapse() with an offset, but returns a Result with the reason for a failure.
|
| void | collapseToStart () const |
| | Collapse the selection to its start (collapseToStart).
|
| Result< void > | collapseToStart (Checked_t) const |
| | Same as collapseToStart(), but returns a Result with the reason for a failure (eg, an InvalidStateError if nothing is selected).
|
| void | collapseToEnd () const |
| | Collapse the selection to its end (collapseToEnd).
|
| Result< void > | collapseToEnd (Checked_t) const |
| | Same as collapseToEnd(), but returns a Result with the reason for a failure (eg, an InvalidStateError if nothing is selected).
|
| void | extend (const Node &node, size_t offset=0) const |
| | Move the focus and keep the anchor where it is (extend).
|
| Result< void > | extend (const Node &node, Checked_t) const |
| | Same as extend(), but returns a Result with the reason for a failure (eg, an InvalidStateError if nothing is selected).
|
| Result< void > | extend (const Node &node, size_t offset, Checked_t) const |
| | Same as extend() with an offset, but returns a Result with the reason for a failure (eg, an IndexSizeError if offset is past the end of node).
|
| void | setBaseAndExtent (const Node &anchor_node, size_t anchor_offset, const Node &focus_node, size_t focus_offset) const |
| | Set the anchor and the focus in one call (setBaseAndExtent).
|
| Result< void > | setBaseAndExtent (const Node &anchor_node, size_t anchor_offset, const Node &focus_node, size_t focus_offset, Checked_t) const |
| | Same as setBaseAndExtent(), but returns a Result with the reason for a failure.
|
| void | selectAllChildren (const Node &node) const |
| | Select everything inside a node (selectAllChildren).
|
| Result< void > | selectAllChildren (const Node &node, Checked_t) const |
| | Same as selectAllChildren(), but returns a Result with the reason for a failure.
|
| void | removeAllRanges () const |
| | Clear the selection (removeAllRanges or empty).
|
| void | addRange (const Range &range) const |
| | Select a range (addRange).
|
| Range | getRangeAt (size_t index) const |
| | Get a range with the selection's start and end (getRangeAt).
|
| Result< Range > | getRangeAt (size_t index, Checked_t) const |
| | Same as getRangeAt(), but returns a Result with the reason for a failure (eg, an IndexSizeError if index isn't less than rangeCount()).
|
| void | deleteFromDocument () const |
| | Remove the selected content from the page (deleteFromDocument).
|
| bool | containsNode (const Node &node, bool partial=false) const |
| | Whether or not a node is in the selection (containsNode).
|
| void | modify (std::string_view alter, std::string_view direction, std::string_view granularity) const |
| | Move or extend the selection by a unit of text (modify), like the arrow keys do.
|
| ULDOMSelection | raw () const |
| | Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMSelection.h> functions.
|
| ULDOMSelection | LeakRef () |
| | Give up ownership of the C handle and return it.
|