25.230. Range: represents a contiguous range of a document DOM Level 2 Range: Object  Range 25.230.1. Constants These constants specify how the boundary points of two Range objects are 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 Compares the start of the specified range to the start of this range.
unsigned short START_TO_END = 1 Compares the start of the specified range to the end of this range.
unsigned short END_TO_END = 2 Compares the end of the specified range to the end of this range.
unsigned short END_TO_START = 3 Compares the end of the specified range to the start of this range. 25.230.2. 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 documentthat 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 position of the range's ending point 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. 25.230.3. 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 constants listed in the Constants section.
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. 25.230.4. 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 (at the time of this writing, Firefox and Opera support it, Safari has partial support, and Internet Explorer does not support it), 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 a nonstandard 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 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 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. 25.230.5. See Also Document.createRange( ), DocumentFragment |
