Object: Range

Help Center

Search This Document

Download PDF

Availability

BlackBerry® Device Software version 4.7.1 or later

The Range object represents a range of content between two boundary points, a start point and an end point, in a Document, DocumentFragment, or Attr node.

You can create a Range object by using Document.createRange. You can retrieve a Range object by using Selection.getRangeAt.

Range properties

Property name	Type	Description	Status	Availability
`collapsed`	boolean	Returns `true` if the start point and end point of the range are the same.	read-only	4.7.1 or later
`commonAncestorContainer`	`Node`	Returns the deepest node that contains the `startContainer` and `endContainer` nodes.	read-only	4.7.1 or later
`endContainer`	`Node`	Returns the node that contains the end point of the range.	read-only	4.7.1 or later
`endOffset`	int	Returns a number that represents the end point of the range within the `endContainer` node.	read-only	4.7.1 or later
`startContainer`	`Node`	Returns the node that contains the start point of the range.	read-only	4.7.1 or later
`startOffset`	int	Returns a number that represents the start point of the range within the `startContainer` node.	read-only	4.7.1 or later

Range methods

Method name	Description	Availability
`cloneContents()`	Duplicates the contents of a specified range.	4.7.1 or later
`cloneRange()`	Creates a new `Range` object with the same start point and end point as the specified range.	4.7.1 or later
`collapse()`	Collapses a range onto its start point or end point.	4.7.1 or later
`compareBoundaryPoints()`	Compares the start points and end points of two ranges.	4.7.1 or later
`deleteContents()`	Deletes the contents of the range from the `Document` or `DocumentFragment` node.	4.7.1 or later
`detach()`	Immediately releases the `Range` object from the object model.	4.7.1 or later
`extractContents()`	Extracts the entire contents of the range from a `Document` or `DocumentFragment` node and moves it to a new `DocumentFragment` object.	4.7.1 or later
`insertNode()`	Inserts a new node at the start of the range.	4.7.1 or later
`selectNode()`	Populates the range with a specified node and its contents.	4.7.1 or later
`selectNodeContents()`	Populates the range with the contents of a specified node.	4.7.1 or later
`setEnd()`	Sets the end point of the range.	4.7.1 or later
`setEndAfter()`	Sets the end point of a range at a position that is after the specified node.	4.7.1 or later
`setEndBefore()`	Sets the end point of a range at a position that is before the specified node.	4.7.1 or later
`setStart()`	Sets the start point of the range.	4.7.1 or later
`setStartAfter()`	Sets the start point of a range at a position that is after the specified node.	4.7.1 or later
`setStartBefore()`	Sets the start point of a range at a position that is before the specified node.	4.7.1 or later
`surroundContents()`	Moves the contents of the range to a new node object, and inserts the new node at the start point of the range.	4.7.1 or later
`toString()`	Returns the contents of the range as a string.	4.7.1 or later

Method: Range.cloneContents()

Availability

BlackBerry® Device Software version 4.7.1 or later

The cloneContents() method duplicates the contents of a specified range.

Syntax

Range.cloneContents()

Parameters

None.

Return values

This method returns a DocumentFragment object that contains the same contents as the range.

Exceptions

Exception	Description
HIERARCHY_REQUEST_ERR	Thrown if the result of this action is that a `DocumentType` node is inserted into the `DocumentFragment` object.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.cloneRange()

Availability

BlackBerry® Device Software version 4.7.1 or later

The cloneRange() method creates a new Range object with the same start point and end point as the specified range.

Syntax

Range.cloneRange()

Parameters

None.

Return values

This method returns the new Range object.

Exceptions

Exception	Description
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.collapse()

Availability

BlackBerry® Device Software version 4.7.1 or later

The collapse() method collapses a range onto its start point or end point.

Syntax

Range.collapse( toStart )

Parameters

Parameter	Type	Description
`toStart`	boolean	When `true`, indicates that the range is collapsed onto its start point. When `false`, indicates that the range is collapsed onto its end point.

Return values

None.

Exceptions

Exception	Description
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.compareBoundaryPoints()

Availability

BlackBerry® Device Software version 4.7.1 or later

The compareBoundaryPoints() method compares the start points and end points of two ranges.

Syntax

Range.compareBoundaryPoints( how, sourceRange )

Parameters

Parameter	Type	Description
`how`	short	Describes the type of comparison using one of the following constants: `END_TO_END`: Compares the end point of `sourceRange` to the end point of the current range. `END_TO_START`: Compares the end point of `sourceRange` to the start point of the current range. `START_TO_END`: Compares the start point of `sourceRange` to the end point of the current range. `START_TO_START`: Compares the start point of `sourceRange` to the start point of the current range.
`sourceRange`	`Range`	Specifies the `Range` object to which the current range is compared.

Return values

This method returns one of the following values:

-1: Indicates that the specified start point or end point of the current range is before the corresponding start point or end point of sourceRange.
0: Indicates that the specified start point or end point of the given range is identical to the corresponding start point or end point of sourceRange.
1: Indicates that the specified start point or end point of the given range is after the corresponding start point or end point of sourceRange.

Exceptions

Exception	Description
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.
WRONG_DOCUMENT_ERR	Thrown if the current range and `sourceRange` are not in the same `Document` or `DocumentFragment` node.

Method: Range.deleteContents()

Availability

BlackBerry® Device Software version 4.7.1 or later

The deleteContents() method deletes the contents of the range from the Document or DocumentFragment node.

Syntax

Range.deleteContents()

Parameters

None.

Return values

None.

Exceptions

Exception	Description
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.
NO_MODIFICATION_ALLOWED_ERR	Thrown if any portion of the contents of the range is read-only, or if any of the nodes that contain any of the contents of the range is read-only.

Method: Range.detach()

Availability

BlackBerry® Device Software version 4.7.1 or later

The detach() method immediately releases the Range object from the object model. Although it is permissible to just stop using a Range object when you are finished with it, the browser will continue to expend some resources maintaining it. Detaching a Range object informs the browser that it can release those resources, making them available to other objects. As a result, it is a good practice to invoke the Range.detach() method whenever a range is no longer needed.

Once a Range object is detached, any attempts to access it will result in an exception.

Syntax

Range.detach()

Parameters

None.

Return values

None.

Exceptions

Exception	Description
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.extractContents()

Availability

BlackBerry® Device Software version 4.7.1 or later

The extractContents() method extracts the entire contents of the range from a Document or DocumentFragment node and moves it to a new DocumentFragment object.

Syntax

Range.extractContents()

Parameters

None

Return values

This method returns a new DocumentFragment object that contains the extracted range contents.

Exceptions

Exception	Description
HIERARCHY_REQUEST_ERR	Thrown if this action would result in a `DocumentType` node being inserted into the `DocumentFragment` object.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.
NO_MODIFICATION_ALLOWED_ERR	Thrown if any portion of the contents of the range is read-only, or if any of the `Node` objects that contain any of the contents of the range is read-only.

Method: Range.insertNode()

Availability

BlackBerry® Device Software version 4.7.1 or later

The insertNode() method inserts a new node at the start of the range.

If the container is a Text node, the node is split (as if the Text.splitText method had been invoked), and the new node is inserted between the resulting pair of Text nodes.

Syntax

Range.insertNode( newNode )

Parameters

Parameter	Type	Description
`newNode`	`Node`	Specifies the new node to insert. If `newNode` is a `DocumentFragment` node, only the child nodes will be inserted, not the `DocumentFragment` node itself.

Parameter

Type

Description

newNode

Node

Specifies the new node to insert.

If newNode is a DocumentFragment node, only the child nodes will be inserted, not the DocumentFragment node itself.

Return values

None.

Exceptions

Exception	Description
HIERARCHY_REQUEST_ERR	Thrown if this action would result in a `DocumentType` node being inserted into the `DocumentFragment` object.
INVALID_NODE_TYPE_ERR	Thrown if `newNode` is an `Attr`, `Entity`, `Notation`, or `Document` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.
NO_MODIFICATION_ALLOWED_ERR	Thrown if any portion of the contents of the range is read-only, or if any of the `Node` objects that contain any of the contents of the range is read-only.
WRONG_DOCUMENT_ERR	Thrown if `newNode` and the container of the start of the range were not created from the same document.

Method: Range.selectNodeContents()

Availability

BlackBerry® Device Software version 4.7.1 or later

The selectNodeContents() method populates the range with the contents of a specified node.

Syntax

Range.selectNodeContents( refNode )

Parameters

Parameter	Type	Description
`refNode`	`Node`	Specifies the node from which to select the contents. This node will become the parent node for the start and end of the range.

Return values

None.

Exceptions

Exception	Description
INVALID_NODE_TYPE_ERR	Thrown if `refNode` or an ancestor of `refNode` is an `Attr`, `Entity`, `Notation`, or `Document` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.selectNode()

Availability

BlackBerry® Device Software version 4.7.1 or later

The selectNode() method populates the range with a node and its contents.

Syntax

Range.selectNode( refNode )

Parameters

Parameter	Type	Description
`refNode`	`Node`	Specifies the node from which to select the contents. This node will become the parent node for the start and end of the range.

Return values

None.

Exceptions

Exception	Description
INVALID_NODE_TYPE_ERR	Thrown if an ancestor of `refNode` is an `Entity`, `Notation` or `DocumentType` node, or if `refNode` is an `Attr`, `Document`, `DocumentFragment`, `Entity`, or `Notation` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.setEndAfter()

Availability

BlackBerry® Device Software version 4.7.1 or later

The setEndAfter() method sets the end point of a range at a position that is after the specified node.

Syntax

Range.setEndAfter( refNode )

Parameters

Parameter	Type	Description
`refNode`	`Node`	Specifies the node after which the range ends. The parent node for the end of the range will be the same as the parent node of `refNode`.

Return values

None.

Exceptions

Exception	Description
INVALID_NODE_TYPE_ERR	Thrown if the root container of `refNode` is not an `Attr`, `Document`, or `DocumentFragment` node, or if `refNode` is an `Attr`, `Document`, `DocumentFragment`, `Entity`, or `Notation` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.setEndBefore()

Availability

BlackBerry® Device Software version 4.7.1 or later

The setEndBefore() method sets the end point of a range at a position that is before the specified node.

Syntax

Range.setEndBefore( refNode )

Parameters

Parameter	Type	Description
`refNode`	`Node`	Specifies the node before which the range ends. The parent node for the end of the range will be the same as the parent node of `refNode`.

Return values

None.

Exceptions

Exception	Description
INVALID_NODE_TYPE_ERR	Thrown if the root container of `refNode` is not an `Attr`, `Document`, or `DocumentFragment` node, or if `refNode` is an `Attr`, `Document`, `DocumentFragment`, `Entity`, or `Notation` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.setEnd()

Availability

BlackBerry® Device Software version 4.7.1 or later

The setEnd() method sets the end point of the range.

Syntax

Range.setEnd( endNode, endOffset )

Parameters

Parameter	Type	Description
`endNode`	`Node`	Specifies the node at which the range ends. This parameter must not be null.
`endOffset`	int	Specifies the offset for the end of the range from the start of `endNode`.

Return values

None.

Exceptions

Exception	Description
INDEX_SIZE_ERR	Thrown if `endOffset` is greater than the number of child units in `endNode`. For `CharacterData` nodes (such as `Text` or `Comment` nodes) or `ProcessingInstruction` nodes, child units are 16-bit units. For all other nodes, child units are child nodes.
INVALID_NODE_TYPE_ERR	Thrown if `endNode` or an ancestor of `endNode` is an `Entity`, `Notation`, or `DocumentType` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Exception

Description

INDEX_SIZE_ERR

Thrown if endOffset is greater than the number of child units in endNode.

For CharacterData nodes (such as Text or Comment nodes) or ProcessingInstruction nodes, child units are 16-bit units. For all other nodes, child units are child nodes.

INVALID_NODE_TYPE_ERR

Thrown if endNode or an ancestor of endNode is an Entity, Notation, or DocumentType node.

INVALID_STATE_ERR

Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.setStartAfter()

Availability

BlackBerry® Device Software version 4.7.1 or later

The setStartAfter() method sets the start point of a range at a position that is after the specified node.

Syntax

Range.setStartAfter( refNode )

Parameters

Parameter	Type	Description
`refNode`	`Node`	Specifies the node after which the range begins. The parent node for the start of the range will be the same as the parent node of `refNode`.

Return values

None.

Exceptions

Exception	Description
INVALID_NODE_TYPE_ERR	Thrown if the root container of `refNode` is not an `Attr`, `Document`, or `DocumentFragment` node, or if `refNode` is an `Attr`, `Document`, `DocumentFragment`, `Entity`, or `Notation` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.setStartBefore()

Availability

BlackBerry® Device Software version 4.7.1 or later

The setStartBefore() method sets the start point of a range at a position that is before the specified node.

Syntax

Range.setStartBefore( refNode )

Parameters

Parameter	Type	Description
`refNode`	`Node`	Specifies the node before which the range begins. The parent node for the start of the range will be the same as the parent node of `refNode`.

Return values

None.

Exceptions

Exception	Description
INVALID_NODE_TYPE_ERR	Thrown if the root container of `refNode` is not an `Attr`, `Document`, or `DocumentFragment` node, or if `refNode` is an `Attr`, `Document`, `DocumentFragment`, `Entity`, or `Notation` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Method: Range.setStart()

Availability

BlackBerry® Device Software version 4.7.1 or later

The setStart() method sets the start point of the range.

Syntax

Range.setStart( startNode, startOffset )

Parameters

Parameter	Type	Description
`startNode`	`Node`	Specifies the node at which the range begins. This parameter must not be null.
`startOffset`	int	Specifies the offset for the start of the range from the start of `startNode`.

Return values

None.

Exceptions

Exception	Description
INDEX_SIZE_ERR	Thrown if `startOffset` is greater than the number of child units in `startNode`. For `CharacterData` nodes (such as `Text` or `Comment` nodes) or `ProcessingInstruction` nodes, child units are 16-bit units. For all other nodes, child units are child nodes.
INVALID_NODE_TYPE_ERR	Thrown if `startNode` or an ancestor of `startNode` is an `Entity`, `Notation`, or `DocumentType` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Exception

Description

INDEX_SIZE_ERR

Thrown if startOffset is greater than the number of child units in startNode.

For CharacterData nodes (such as Text or Comment nodes) or ProcessingInstruction nodes, child units are 16-bit units. For all other nodes, child units are child nodes.

INVALID_NODE_TYPE_ERR

Thrown if startNode or an ancestor of startNode is an Entity, Notation, or DocumentType node.

INVALID_STATE_ERR

Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.surroundContents()

Availability

BlackBerry® Device Software version 4.7.1 or later

The surroundContents() method moves the contents of the range to a new node object, and inserts the new node at the start point of the range.

Syntax

Range.surroundContents( newNode )

Parameters

Parameter	Type	Description
`newNode`	`Node`	Specifies the node with which to surround the contents.

Return values

None.

Exceptions

Exception	Description
BAD_BOUNDARYPOINTS_ERR	Thrown if the range partially selects a non-text node.
HIERARCHY_REQUEST_ERR	Thrown if: the container of the start of the range is of a type that does not allow child nodes of the type of `newNode` `newNode` is an ancestor of the container inserting `newNode` results in `newNode` having a child node of a type that it does not allow
INVALID_NODE_TYPE_ERR	Thrown if `newNode` is an `Attr`, `Document`, `DocumentFragment`, `DocumentType`, `Entity`, or `Notation` node.
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.
NO_MODIFICATION_ALLOWED_ERR	Thrown if an ancestor container of either start point or the end point of the range is read-only.
WRONG_DOCUMENT_ERR	Thrown if `newNode` and the container of the start point of the range are not created from the same document.

Method: Range.toString()

Availability

BlackBerry® Device Software version 4.7.1 or later

The toString() method returns the contents of the range as a string.

Syntax

Range.toString()

Parameters

None.

Return values

This method returns the contents of the range as a string.

Exceptions

Exception	Description
INVALID_STATE_ERR	Thrown if the `Range.detach()` method is already invoked on the `Range` object.

Next topic: Object: Rect

Previous topic: ProcessingInstruction properties

Was this information helpful? Send us your comments.

Global Navigation

Help Center

Local Navigation

Object: Range

Range properties

Range methods

Method: Range.cloneContents()

Syntax

Parameters

Return values

Exceptions

Method: Range.cloneRange()

Syntax

Parameters

Return values

Exceptions

Method: Range.collapse()

Syntax

Parameters

Return values

Exceptions

Method: Range.compareBoundaryPoints()

Syntax

Parameters

Return values

Exceptions

Method: Range.deleteContents()

Syntax

Parameters

Return values

Exceptions

Method: Range.detach()

Syntax

Parameters

Return values

Exceptions

Method: Range.extractContents()

Syntax

Parameters

Return values

Exceptions

Method: Range.insertNode()

Syntax

Parameters

Return values

Exceptions

Method: Range.selectNodeContents()

Syntax

Parameters

Return values

Exceptions

Method: Range.selectNode()

Syntax

Parameters

Return values

Exceptions

Method: Range.setEndAfter()

Syntax

Parameters

Return values

Exceptions

Method: Range.setEndBefore()

Syntax

Parameters

Return values

Exceptions

Method: Range.setEnd()

Syntax

Parameters

Return values

Exceptions

Method: Range.setStartAfter()

Syntax

Parameters

Return values

Exceptions

Method: Range.setStartBefore()

Syntax

Parameters

Return values