Class Selection
- Namespace
- CSharpToJavaScript.APIs.JS
- Assembly
- CSharpToJavaScript.dll
A Selection object represents the range of text selected by the user or the current position of the caret. Each Document is associated with a unique selection object, which can be retrieved by GetSelection() or GetSelection() and then be examined and modified.
[Value("Selection")]
public class Selection- Inheritance
-
Selection
- Inherited Members
Remarks
A user may make a selection from left to right (in document order) or right to left (reverse of document order). The anchor is where the user began the selection and the focus is where the user ends the selection. If you make a selection with a desktop mouse, the anchor is placed where you pressed the mouse button, and the focus is placed where you released the mouse button.
NOTE
Anchor and focus should not be confused with the start and end positions of a selection. The anchor can be placed before the focus or vice versa, depending on the direction you made your selection.
-GetSelection(), GetSelection(), Range
-Selection-related events: Documentselectionchange and Nodeselectstart
-HTML inputs provide simpler helper APIs for working with selection (see SetSelectionRange(ulong, ulong, string))
-Document.ActiveElement, HTMLElement.Focus, and HTMLElement.Blur
Constructors
Selection()
public Selection()Properties
AnchorNode
The Selection.anchorNode read-only property returns the Node in which the selection begins. It can return null if selection never existed in the document (e.g., an iframe that was never clicked on, or the node belongs to another document tree).
[Value("anchorNode")]
public Node? AnchorNode { get; }Property Value
Remarks
A user may make a selection from left to right (in document order) or right to left (reverse of document order). The anchor is where the user began the selection. This can be visualized by holding the <kbd>Shift</kbd> key and pressing the arrow keys on your keyboard. The selection's anchor does not move, but the selection's focus, the other end of the selection, does move.
AnchorOffset
The Selection.anchorOffset read-only property returns the
number of characters that the selection's anchor is offset within the
AnchorNode if said node is of type Text, CDATASection or Comment.
[Value("anchorOffset")]
public ulong AnchorOffset { get; }Property Value
- ulong
A number.
Remarks
In the case of AnchorNode being another type of node, Selection.anchorOffset returns the number of ChildNodes the selection's anchor is offset within the AnchorNode.
This number is zero-based. If the selection begins with the first character in the
AnchorNode, 0 is returned.
-Selection, the interface it belongs to.
Direction
The direction read-only property of the Selection interface is a string that provides the direction of the current selection.
[Value("direction")]
public string Direction { get; }Property Value
- string
A string describing the type of the current selection.
Possible values are:
Remarks
The value is determined by the order in which the user chooses the boundary points of the selection.
For example, a user might make a selection by clicking a starting boundary point, dragging the cursor, and releasing at an end boundary point.
If the end boundary point is later in the document than the start point, then the direction is "forwards", while the direction is "backwards" if the end point is before the start point within the document.
The value is "directionless" if no direction is implied by the user. For example, if the user made the selection by double-clicking on a word or element, or the selection was made programmatically.
The direction does not change if a selection's range is mutated, for example, using methods like SelectNode(Node).
FocusNode
The Selection.focusNode read-only property returns the Node in which the selection ends. It can return null if selection never existed in the document (e.g., an iframe that was never clicked on, or the node belongs to another document tree).
[Value("focusNode")]
public Node? FocusNode { get; }Property Value
Remarks
A user may make a selection from left to right (in document order) or right to left (reverse of document order). The focus is where the user ended the selection. This can be visualized by holding the <kbd>Shift</kbd> key and pressing the arrow keys on your keyboard. The selection's focus moves, but the selection's anchor, the other end of the selection, does not move.
FocusOffset
The Selection.focusOffset read-only property returns the
number of characters that the selection's focus is offset within the
FocusNode if said node is of type Text, CDATASection or Comment.
[Value("focusOffset")]
public ulong FocusOffset { get; }Property Value
- ulong
A number.
Remarks
In the case of FocusNode being another type of node, Selection.focusOffset returns the number of ChildNodes the selection's focus is offset within the FocusNode.
This number is zero-based. If the selection ends with the first character in the
FocusNode, 0 is returned.
-Selection, the interface it belongs to.
IsCollapsed
The Selection.isCollapsed read-only property returns a
boolean value which indicates whether or not there is currently any text
selected. No text is selected when the selection's start and end points are at the same
position in the content.
[Value("isCollapsed")]
public bool IsCollapsed { get; }Property Value
- bool
A boolean.
Remarks
Keep in mind that a collapsed selection may still have one (or more, in Gecko)
Ranges, so RangeCount may not be zero. In that
scenario, calling a Selection object's GetRangeAt(ulong)
method may return a Range object which is collapsed.
RangeCount
The Selection.rangeCount read-only property returns the
number of ranges in the selection.
[Value("rangeCount")]
public ulong RangeCount { get; }Property Value
- ulong
A number.
Remarks
Before the user has clicked a freshly loaded page, the rangeCount is0. After the user clicks on the page, rangeCount is1, even if no selection is visible.
A user can normally only select one range at a time, so the rangeCount
will usually be 1. Scripting can be used to make the selection contain more
than one range.
Gecko browsers allow multiple selections across table cells. Firefox allows to select
multiple ranges in the document by using Ctrl+click (unless the click occurs within an
element that has the display: table-cell CSS property assigned).
-Selection, the interface it belongs to.
Type
The type read-only property of the
Selection interface returns a string describing the
type of the current selection.
[Value("type")]
public string Type { get; }Property Value
- string
A string describing the type of the current selection. Possible
values are:
Remarks
Methods
AddRange(Range)
[Value("addRange")]
public GlobalObject.Undefined AddRange(Range range)Parameters
rangeRange
Returns
Remarks
-Selection, the interface this method belongs to
Collapse(Node?, ulong)
The Selection.collapse() method collapses the current selection to a single point. The document is not modified. If the content is focused and editable, the caret will blink there.
[Value("collapse")]
public GlobalObject.Undefined Collapse(Node? node, ulong offset = 0)Parameters
Returns
Remarks
NOTE
This method is an alias for the SetPosition(Node?, ulong) method.
CollapseToEnd()
The Selection.collapseToEnd() method collapses the
selection to the end of the last range in the selection. If the content of the selection
is focused and editable, the caret will blink there.
[Value("collapseToEnd")]
public GlobalObject.Undefined CollapseToEnd()Returns
Remarks
-Selection, the interface it belongs to.
CollapseToStart()
The Selection.collapseToStart() method collapses the
selection to the start of the first range in the selection. If the content of the
selection is focused and editable, the caret will blink there.
[Value("collapseToStart")]
public GlobalObject.Undefined CollapseToStart()Returns
Remarks
-Selection, the interface it belongs to.
ContainsNode(Node, bool)
The Selection.containsNode() method indicates whether a
specified node is part of the selection.
[Value("containsNode")]
public bool ContainsNode(Node node, bool allowPartialContainment = false)Parameters
Returns
- bool
Returns
trueif the given node is part of the selection, andfalseotherwise.
Remarks
-Selection, the interface it belongs to.
DeleteFromDocument()
The deleteFromDocument() method of the
Selection interface invokes the DeleteContents() method on the selected Range.
[Value("deleteFromDocument")]
public GlobalObject.Undefined DeleteFromDocument()Returns
Remarks
-Selection, the interface defining this method
Empty()
The Selection.empty() method removes all ranges from the selection, leaving the AnchorNode and FocusNode properties equal to null and nothing selected. When this method is called, a Documentselectionchange event is fired at the document.
[Value("empty")]
public GlobalObject.Undefined Empty()Returns
Remarks
NOTE
This method is an alias for the RemoveAllRanges() method.
-RemoveAllRanges()
-Documentselectionchange
Extend(Node, ulong)
The Selection.extend() method moves the focus of the
selection to a specified point. The anchor of the selection does not move. The selection
will be from the anchor to the new focus, regardless of direction.
[Value("extend")]
public GlobalObject.Undefined Extend(Node node, ulong offset = 0)Parameters
Returns
Remarks
-Selection, the interface it belongs to.
GetComposedRanges(GetComposedRangesOptions)
The Selection.getComposedRanges() method returns an array of StaticRange objects representing the current selection ranges, and can return ranges that potentially cross shadow boundaries.
[Value("getComposedRanges")]
public List<StaticRange> GetComposedRanges(GetComposedRangesOptions options = null)Parameters
optionsGetComposedRangesOptions
Returns
- List<StaticRange>
An array of StaticRange objects that represent the selected ranges within the composed (flattened) tree of the document.
At time of writing the specification expects this array to only contain one object.
Remarks
As the selection range endpoints may be within a shadow tree, or even different shadow trees, and because these may be closed, the method cannot by default return nodes from within a shadow tree.
If the method needs to return a selection that includes nodes inside shadow trees, then the ShadowRoot objects for these trees must be passed as arguments to the method.
If a corresponding roots are not provided and the start or endpoint of the selection are within a shadow tree, the returned range is re-scoped to include the host of the shadow root rather than some node with in the root.
The returned ranges represent the range at the time that getComposedRanges() was called.
If the DOM or a shadow DOM is mutated, the selected range is likely to be incorrect.
Application code might use a MutationObserver to monitor for DOM mutations and then call SetBaseAndExtent(Node, ulong, Node, ulong) to update the selection.
NOTE
This method should be used instead of GetRangeAt(ulong) when selecting ranges that can potentially cross shadow root boundaries.
GetRangeAt(ulong) is not aware of shadow roots.
The returned range is not specified, and varies between browsers.
-Selection, the interface it belongs to.
GetRangeAt(ulong)
The getRangeAt() method of the Selection interface returns a range object representing a currently selected range.
[Value("getRangeAt")]
public Range GetRangeAt(ulong index)Parameters
indexulong
Returns
Remarks
If the endpoints of the selected range are within a shadow tree then JavaScript does not have visibility of the shadow nodes, and the method should re-scope the range to include the host element that contains the end point.
In practice most browsers do not yet implement this behavior, and the returned range is unpredictable.
NOTE
When selecting within nodes that might contain a shadow root, you can use GetComposedRanges(GetComposedRangesOptions) (if supported) to get a selection range inside a shadow tree, or to reliably re-scope the selection to the host node.
-Selection, the interface it belongs to.
Modify(string, string, string)
The Selection.modify() method applies a change to the
current selection or cursor position, using simple textual commands.
[Value("modify")]
public GlobalObject.Undefined Modify(string alter = null, string direction = null, string granularity = null)Parameters
Returns
Remarks
-Selection, the interface it belongs to.
RemoveAllRanges()
The Selection.removeAllRanges() method removes all ranges from the selection, leaving the AnchorNode and FocusNode properties equal to null and nothing selected. When this method is called, a Documentselectionchange event is fired at the document.
[Value("removeAllRanges")]
public GlobalObject.Undefined RemoveAllRanges()Returns
Remarks
RemoveRange(Range)
The Selection.removeRange() method removes a range from a
selection.
[Value("removeRange")]
public GlobalObject.Undefined RemoveRange(Range range)Parameters
rangeRange
Returns
Remarks
-Selection, the interface it belongs to.
SelectAllChildren(Node)
The Selection.selectAllChildren() method adds all the
children of the specified node to the selection. Previous selection is lost.
[Value("selectAllChildren")]
public GlobalObject.Undefined SelectAllChildren(Node node)Parameters
nodeNode
Returns
Remarks
-Selection, the interface it belongs to.
SetBaseAndExtent(Node, ulong, Node, ulong)
The setBaseAndExtent() method of the Selection interface sets the selection to be a range including all or parts of two specified DOM nodes, and any content located between them.
[Value("setBaseAndExtent")]
public GlobalObject.Undefined SetBaseAndExtent(Node anchorNode, ulong anchorOffset, Node focusNode, ulong focusOffset)Parameters
Returns
Remarks
The anchor and focus nodes can be located in a shadow tree, if supported by the browser.
SetPosition(Node?, ulong)
The Selection.setPosition() method collapses the current selection to a single point. The document is not modified. If the content is focused and editable, the caret will blink there.
[Value("setPosition")]
public GlobalObject.Undefined SetPosition(Node? node, ulong offset = 0)Parameters
Returns
Remarks
NOTE
This method is an alias for the Collapse(Node?, ulong) method.