XML DOM - Range object

Range object represents a continuous range in the document.

Range object

Range object represents a continuous range area in the document, such as the area selected by the user dragging with the mouse in the browser window.

If an implementation supports the Range module, then Document objectdefines createRange() method, calling it can create a new Range object.

Note:IE defines an incompatible Document.createRange() method, which returns an object similar to the Range interface but incompatible.

The Range interface defines a large number of methods for specifying the selected area of the document, in addition to several methods that can be used for cut and paste operations within the selected area.

The properties of the Range interface provide methods to get the boundary nodes and offsets of the range. Its methods provide methods to set the range boundaries. Note that the boundaries of the range can be set to Document or DocumentFragment objectnodes. Once the boundary points of the range are defined, the deleteContents(), extractContents(), cloneContents(), and insertNode() methods can be used to perform cut, copy, and paste operations.

When the document is changed through insertion or deletion operations, all Range objects representing a part of the document will change (if necessary) to keep their boundary points valid and to represent the same document content as closely as possible.

Terms: range, boundary point, and offset

A range has two boundary points, namely a start point and an end point. Each boundary point is specified by a node and the offset of that node. The node is usually Element node,Document nodeor Text nodeFor Element nodes and Document nodes, the offset refers to the child node of the node. An offset of 0 indicates that the boundary point is before the first child node of the node. An offset of 1 indicates that the boundary point is after the first child node and before the second child node. However, if the boundary node is a Text node, the offset refers to the position between two characters in the text.

Constants of the Range object

These constants specify how to compare the boundary points of Range objects.

They are the parameters of the compareBoundaryPoints() method how Valid values for parameters:

Constants Description
START_TO_START Compare the starting point of the specified range with the starting point of the current range.
START_TO_END Compare the starting point of the specified range with the ending point of the current range.
END_TO_END Compare the ending point of the specified range with the ending point of the current range.
END_TO_START Compare the ending point of the specified range with the starting point of the current range.

Properties of the Range object

Note:All properties are read-only and cannot be changed by setting these properties to change the starting and ending points of the range. You must call the setEnd() method and the setStart() method to achieve this.

Note:Any read operation on these properties after calling the detach() method will throw an error with the code INVALID_STATE_ERR DOMException exception.

Properties Description
collapsed If the starting and ending points of the range are at the same location in the document, it is true, i.e., the range is empty or collapsed.
commonAncestorContainer The common ancestor container of the starting and ending points of the range (i.e., their ancestor nodes), the deepest nested Document node.
endContainer The Document node containing the ending point of the range.
endOffset The ending point position in the endContainer.
startContainer The Document node containing the starting point of the range.
startOffset The starting point position in the startContainer.

Methods of the Range object

Note:If the detach() method of the range has been called, any subsequent call to a method of the Range object will throw an error with the code INVALID_STATE_ERR DOMException exception.

Method Description
cloneContents() Returns a new DocumentFragment object containing a copy of the document region represented by the range.
cloneRange() Create a new Range object representing the same document region as the current Range object.
collapse() Collapse the range so that its boundary points coincide.
compareBoundaryPoints() Compare the boundary points of the specified range and the current range, and return -1, 0, and 1 according to their order. The comparison of which boundary point is specified by its first parameter, and its value must be one of the constants defined earlier.
deleteContents() Delete the document region represented by the current Range object.
detach() Notify the implementation that the current range is no longer used and can stop tracking. If this method of the range is called, any subsequent method call on the range will throw an exception with the code INVALID_STATE_ERR. DOMException exception.
extractContents() Delete the document region represented by the current range and return the content of that region in the form of a DocumentFragment object. This method and the combination of cloneContents() and deleteContents() methods are very similar.
insertNode() Insert the specified node at the beginning point of the document range.
selectNode() Set the boundary points of this range to include the specified node and all its descendants.
selectNodeContents() Set the boundary points of this range to include the descendants of the specified node but not the node itself.
setEnd() Set the end point of this range to the specified node and offset.
setEndAfter() Set the end point of this range to immediately after the specified node.
setEndBefore() Set the end point of this range to immediately before the specified node.
setStart() Set the beginning point of this range to the specified offset within the specified node.
setStartAfter() Set the beginning point of this range to immediately after the specified node.
setStartBefore() Set the beginning point of this range to immediately before the specified node.
surroundContents() Insert the specified node at the beginning point of the document range, and then redefine the parent nodes of all nodes within the range to make them descendants of the newly inserted node.
toString() Return the plain text content of the document region represented by this range.