| Range |
represents a contiguous range of a
document |
Availability
DOM Level 2
Range
Constants
These constants specify how the boundary points of two Range objects
are to be compared. They are the legal values for the
how argument to the
compareBoundaryPoints( ) method. See the
Range.compareBoundaryPoints( ) reference page.
- unsigned short START_TO_START = 0
-
Compare the start of the specified range to the start of this range.
- unsigned short START_TO_END = 1
-
Compare the start of the specified range to the end of this range.
- unsigned short END_TO_END = 2
-
Compare the end of the specified range to the end of this range.
- unsigned short END_TO_START = 3
-
Compare the end of the specified range to the start of this range.
Properties
The Range interface defines the following properties. Note that all
of these properties are read-only. You cannot change the start or end
points of a range by setting properties; you must call
setEnd( ) or setStart( )
instead. Note also that after you call the detach(
) method of a Range object, any subsequent attempt to read
any of these properties throws a DOMException with a
code of INVALID_STATE_ERR.
- readonly boolean collapsed
-
true if the start
and the end of the range are at the same point in the
document -- that is, if the range is empty or
"collapsed."
- readonly Node commonAncestorContainer
-
The most deeply nested Document node
that contains (i.e., is an ancestor of ) both the start and end
points of the range.
- readonly Node endContainer
-
The
Document node that contains the end point of the range.
- readonly long endOffset
-
The end
point position within endContainer.
- readonly Node startContainer
-
The
Document node that contains the starting point of the range.
- readonly long startOffset
-
The
position of the range's starting point within
startContainer.
Methods
The Range interface defines the following methods. Note that if you
call detach( ) on a range, any subsequent calls of
any methods on that range throw a DOMException with a
code of INVALID_STATE_ERR.
Because this exception is ubiquitous within this interface, it is not
listed in the reference pages for the individual Range methods.
- cloneContents( )
-
Returns a new DocumentFragment object that contains a copy of the
region of the document represented by this range.
- cloneRange( )
-
Creates a new Range object that represents the same region of the
document as this one.
- collapse( )
-
Collapses this range so that one boundary point is the same as the
other.
- compareBoundaryPoints( )
-
Compares a boundary point of the specified range to a boundary point
of this range, and returns -1, 0, or 1, depending on their order.
Which points to compare is specified by the first argument, which
must be one of the previously defined constants.
- deleteContents( )
-
Deletes the region of the document represented by this range.
- detach( )
-
Tells the implementation that this range will no longer be used and
that it can stop keeping track of it. If you call this method for a
range, subsequent method calls or property lookups on that range
throw a DOMException with a code of
INVALID_STATE_ERR.
- extractContents( )
-
Deletes the region of the document represented by this range, but
returns the contents of that region as a DocumentFragment object.
This method is like a combination of cloneContents(
) and deleteContents( ).
- insertNode( )
-
Inserts the specified node into the document at the start point of
the range.
- selectNode( )
-
Sets the boundary points of this range so that it contains the
specified node and all of its descendants.
- selectNodeContents( )
-
Sets the boundary points of this range so that it contains all the
descendants of the specified node but not the node itself.
- setEnd( )
-
Sets the end point of this range to the specified node and offset.
- setEndAfter( )
-
Sets the end point of this range to immediately after the specified
node.
- setEndBefore( )
-
Sets the end point of this range to immediately before the specified
node.
- setStart( )
-
Sets the start position of this range to the specified offset within
the specified node.
- setStartAfter( )
-
Sets the start position of this range to immediately after the
specified node.
- setStartBefore( )
-
Sets the start position of this range to immediately before the
specified node.
- surroundContents( )
-
Inserts the specified node into the document at the start position of
the range and then reparents all the nodes within the range so that
they become descendants of the newly inserted node.
- toString( )
-
Returns the plain-text content of the document region described by
this range.
Description
A Range object represents a contiguous range or region of a document,
such as the region that the user might select with a mouse drag in a
web browser window. If an implementation supports the Range module,
the Document object defines a createRange( )
method that you can call to create a new Range object. (Be careful,
however: Internet Explorer defines an incompatible
Document.createRange( ) method that returns an
object similar to, but not compatible with, the Range interface.) The
Range interface defines a number of methods for specifying a
"selected" region of a document and several more methods
for implementing cut and paste-type operations on the selected
region.
A range has two boundary points: a start point and an end point. Each
boundary point is specified by a combination of a node and an offset
within that node. The node is typically an Element, Document, or Text
node. For Element and Document nodes, the offset refers to the
children of that node. An offset of 0 specifies a boundary point
before the first child of the node. An offset of 1 specifies a
boundary point after the first child and before the second child. If
the boundary node is a Text node, however, the offset specifies a
position between two characters of that text.
The properties of the Range interface provide a way to obtain
boundary nodes and offsets of a range. The methods of the interface
provide a number of ways to set the boundaries of a range. Note that
the boundaries of a range may be set to nodes within a Document or a
DocumentFragment.
Once the boundary points of a range are defined, you can use
deleteContents( ), extractContents(
), cloneContents( ), and
insertNode( ) to implement cut-, copy-, and
paste-style operations.
When a document is altered by insertion or deletion, all Range
objects that represent portions of that document are altered, if
necessary, so that their boundary points remain valid and they
represent (as closely as possible) the same document content.
For further details, read the reference pages for each of the Range
methods and see the discussion of the Range API in Chapter 17.
See Also
Document.createRange( ), DocumentFragment; Chapter 17
Passed to
Range.compareBoundaryPoints( )
Returned by
Document.createRange( ), Range.cloneRange( )
|
