82b88df622
http://www.w3.org/DOM/DOMTM git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@225913 13f79535-47bb-0310-9956-ffa450edef68
2795 lines
80 KiB
HTML
2795 lines
80 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<!--
|
|
Generated: Thu Nov 09 17:46:00 EST 2000 jfouffa.w3.org
|
|
-->
|
|
<html lang='en' xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Document Object Model Range</title>
|
|
<link rel='stylesheet' type='text/css' href='./spec.css' />
|
|
<link rel='stylesheet' type='text/css' href='W3C-REC.css' />
|
|
<link rel='next' href='idl-definitions.html' />
|
|
<link rel='contents' href='Overview.html#contents' />
|
|
<link rel='index' href='def-index.html' />
|
|
<link rel='previous' href='traversal.html' />
|
|
</head>
|
|
<body>
|
|
<div class='navbar' align='center'><a accesskey='p'
|
|
href='traversal.html'>previous</a> <a accesskey='n'
|
|
href='idl-definitions.html'>next</a> <a accesskey='c'
|
|
href='Overview.html#contents'>contents</a> <a accesskey='i'
|
|
href='def-index.html'>index</a>
|
|
|
|
<hr title='Navigation area separator' />
|
|
</div>
|
|
|
|
<div class='noprint' style='text-align: right'>
|
|
<p style='font-family: monospace;font-size:small'>13 November,
|
|
2000</p>
|
|
</div>
|
|
|
|
<div class='div1'><a id="Range" name='Range'></a>
|
|
|
|
<h1 id='Range-h1' class='div1'>2. Document Object Model Range</h1>
|
|
|
|
<dl>
|
|
<dt><i>Editors</i></dt>
|
|
|
|
<dd>Peter Sharpe, SoftQuad Software Inc.</dd>
|
|
|
|
<dd>Vidur Apparao, Netscape Communications Corp.</dd>
|
|
|
|
<dd>Lauren Wood, SoftQuad Software Inc.</dd>
|
|
</dl>
|
|
|
|
<div class='noprint'>
|
|
<h2 id='table-of-contents'>Table of contents</h2>
|
|
|
|
<ul class='toc'>
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-introduction'>2.1. Introduction</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Definitions'>2.2. Definitions and Notation</a>
|
|
|
|
|
|
<ul class='toc'>
|
|
<li class='tocline4'><a class='tocxref'
|
|
href='#Level-2-Range-Position'>2.2.1. Position</a></li>
|
|
|
|
<li class='tocline4'><a class='tocxref'
|
|
href='#Level-2-Range-Containment'>2.2.2. Selection and Partial
|
|
Selection</a></li>
|
|
|
|
<li class='tocline4'><a class='tocxref'
|
|
href='#Level-2-Range-Notation'>2.2.3. Notation</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Creating'>2.3. Creating a Range</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Changing'>2.4. Changing a Range's
|
|
Position</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Comparing'>2.5. Comparing Range
|
|
Boundary-Points</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Deleting-Content'>2.6. Deleting Content with a
|
|
Range</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Extracting'>2.7. Extracting Content</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Cloning'>2.8. Cloning Content</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Inserting'>2.9. Inserting Content</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Surrounding'>2.10. Surrounding
|
|
Content</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Misc'>2.11. Miscellaneous Members</a></li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Mutation'>2.12. Range modification under
|
|
document mutation</a>
|
|
|
|
<ul class='toc'>
|
|
<li class='tocline4'><a class='tocxref'
|
|
href='#Level-2-Range-Insertions'>2.12.1. Insertions</a></li>
|
|
|
|
<li class='tocline4'><a class='tocxref'
|
|
href='#Level-2-Range-Deletions'>2.12.2. Deletions</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li class='tocline3'><a class='tocxref'
|
|
href='#Level-2-Range-Interface'>2.13. Formal Description of the
|
|
Range Interface</a>
|
|
|
|
<ul class='toc'>
|
|
<li class='tocline4'><a href='#Level-2-Range-idl'>Range</a>, <a
|
|
href='#Level-2-DocumentRange-idl'>DocumentRange</a>, <a
|
|
href='#RangeException'>RangeException</a>, <a
|
|
href='#RangeExceptionCode'>RangeExceptionCode</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class='div2'><a id="Level-2-Range-introduction"
|
|
name='Level-2-Range-introduction'></a>
|
|
|
|
<h2 id='Level-2-Range-introduction-h2' class='div2'>2.1.
|
|
Introduction</h2>
|
|
|
|
<p>A Range identifies a range of content in a Document,
|
|
DocumentFragment or Attr. It is contiguous in the sense that it can
|
|
be characterized as selecting all of the content between a pair of
|
|
boundary-points.</p>
|
|
|
|
<p><b>Note:</b> In a text editor or a word processor, a user can
|
|
make a selection by pressing down the mouse at one point in a
|
|
document, moving the mouse to another point, and releasing the
|
|
mouse. The resulting selection is contiguous and consists of the
|
|
content between the two points.</p>
|
|
|
|
<p>The term 'selecting' does not mean that every Range corresponds
|
|
to a selection made by a GUI user; however, such a selection can be
|
|
returned to a DOM user as a Range.</p>
|
|
|
|
<p><b>Note:</b> In bidirectional writing (Arabic, Hebrew), a range
|
|
may correspond to a logical selection that is not necessarily
|
|
contiguous when displayed. A visually contiguous selection, also
|
|
used in some cases, may not correspond to a single logical
|
|
selection, and may therefore have to be represented by more than
|
|
one range.</p>
|
|
|
|
<p>The Range interface provides methods for accessing and
|
|
manipulating the document tree at a higher level than similar
|
|
methods in the Node interface. The expectation is that each of the
|
|
methods provided by the Range interface for the insertion, deletion
|
|
and copying of content can be directly mapped to a series of Node
|
|
editing operations enabled by DOM Core. In this sense, the Range
|
|
operations can be viewed as convenience methods that also enable
|
|
the implementation to optimize common editing patterns.</p>
|
|
|
|
<p>This chapter describes the Range interface, including methods
|
|
for creating and moving a Range and methods for manipulating
|
|
content with Ranges.</p>
|
|
|
|
<p>The interfaces found within this section are not mandatory. A
|
|
DOM application may use the <code>hasFeature(feature,
|
|
version)</code> method of the <code>DOMImplementation</code>
|
|
interface with parameter values "Range" and "2.0" (respectively) to
|
|
determine whether or not this module is supported by the
|
|
implementation. In order to fully support this module, an
|
|
implementation must also support the "Core" feature defined defined
|
|
in the DOM Level 2 Core specification [<a class='noxref'
|
|
href='references.html#DOMCore'>DOM Level 2 Core</a>]. Please refer
|
|
to additional information about <a
|
|
href='http://www.w3.org/TR/DOM-Level-2-Core/introduction.html#ID-Conformance'>
|
|
<em>conformance</em></a> in the DOM Level 2 Core specification [<a
|
|
class='noxref' href='references.html#DOMCore'>DOM Level 2
|
|
Core</a>].</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-introduction -->
|
|
<div class='div2'><a id="Level-2-Range-Definitions"
|
|
name='Level-2-Range-Definitions'></a>
|
|
|
|
<h2 id='Level-2-Range-Definitions-h2' class='div2'>2.2. Definitions
|
|
and Notation</h2>
|
|
|
|
<div class='div3'><a id="Level-2-Range-Position"
|
|
name='Level-2-Range-Position'></a>
|
|
|
|
<h3 id='Level-2-Range-Position-h3' class='div3'>2.2.1.
|
|
Position</h3>
|
|
|
|
<p>This chapter refers to two different representations of a
|
|
document: the text or source form that includes the document markup
|
|
and the tree representation similar to the one described in the
|
|
introduction section of the DOM Level 2 Core [<a class='noxref'
|
|
href='references.html#DOMCore'>DOM Level 2 Core</a>].</p>
|
|
|
|
<p>A Range consists of two <i>boundary-points</i> corresponding to
|
|
the start and the end of the Range. <a id="td-boundarypoint"
|
|
name='td-boundarypoint'></a>A boundary-point's position in a
|
|
Document or DocumentFragment tree can be characterized by a node
|
|
and an offset. <a id="td-container" name='td-container'></a>The
|
|
node is called the <i>container</i> of the boundary-point and of
|
|
its position. <a id="td-ancestor-container"
|
|
name='td-ancestor-container'></a>The container and its ancestors
|
|
are the <i>ancestor container</i>s of the boundary-point and of its
|
|
position. <a id="td-offset" name='td-offset'></a>The offset within
|
|
the node is called the <i>offset</i> of the boundary-point and its
|
|
position. If the container is an Attr, Document, DocumentFragment,
|
|
Element or EntityReference node, the offset is between its <a
|
|
href='glossary.html#dt-child'><em>child</em></a> nodes. If the
|
|
container is a CharacterData, Comment or ProcessingInstruction
|
|
node, the offset is between the <a
|
|
href='glossary.html#dt-16-bit-unit'><em>16-bit units</em></a> of
|
|
the UTF-16 encoded string contained by it.</p>
|
|
|
|
<p>The <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-points</em></a> of
|
|
a Range must have a common <a
|
|
href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> which is either a Document, DocumentFragment or
|
|
Attr node. That is, the content of a Range must be entirely within
|
|
the subtree rooted by a single Document, DocumentFragment or Attr
|
|
Node. <a id="td-root-container" name='td-root-container'></a>This
|
|
common <a href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> is known as the <i>root container</i> of the
|
|
Range. <a id="td-context-tree" name='td-context-tree'></a>The tree
|
|
rooted by the <a href='ranges.html#td-root-container'><em>root
|
|
container</em></a> is known as the Range's <i>context tree</i>.</p>
|
|
|
|
<p>The <a href='ranges.html#td-container'><em>container</em></a> of
|
|
a <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> of
|
|
a Range must be an Element, Comment, ProcessingInstruction,
|
|
EntityReference, CDATASection, Document, DocumentFragment, Attr, or
|
|
Text node. None of the <a
|
|
href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a>s of the <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> of
|
|
a Range can be a DocumentType, Entity or Notation node.</p>
|
|
|
|
<p>In terms of the text representation of a document, the <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-points</em></a> of
|
|
a Range can only be on token boundaries. That is, the <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> of
|
|
the text range cannot be in the middle of a start- or end-tag of an
|
|
element or within the name of an entity or character reference. A
|
|
Range locates a contiguous portion of the content of the structure
|
|
model.</p>
|
|
|
|
<p>The relationship between locations in a text representation of
|
|
the document and in the Node tree interface of the DOM is
|
|
illustrated in the following diagram:<br />
|
|
</p>
|
|
|
|
<div align='center'>
|
|
<hr width='90%' size='2' />
|
|
<img src='images/RangeExample.gif' alt='Range Example' />
|
|
|
|
<hr width='90%' size='2' />
|
|
<b>Range Example</b>
|
|
|
|
<hr width='90%' size='2' />
|
|
</div>
|
|
|
|
<p>In this diagram, four different Ranges are illustrated. The <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-points</em></a> of
|
|
each Range are labelled with <i>s#</i> (the start of the Range) and
|
|
<i>e#</i> (the end of the Range), where # is the number of the
|
|
Range. For Range 2, the start is in the BODY element and is
|
|
immediately after the H1 element and immediately before the P
|
|
element, so its position is between the H1 and P children of BODY.
|
|
The <a href='ranges.html#td-offset'><em>offset</em></a> of a <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>
|
|
whose <a href='ranges.html#td-container'><em>container</em></a> is
|
|
not a CharacterData node is 0 if it is before the first child, 1 if
|
|
between the first and second child, and so on. So, for the start of
|
|
the Range 2, the <a
|
|
href='ranges.html#td-container'><em>container</em></a> is BODY and
|
|
the <a href='ranges.html#td-offset'><em>offset</em></a> is 1. The
|
|
<a href='ranges.html#td-offset'><em>offset</em></a> of a <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>
|
|
whose <a href='ranges.html#td-container'><em>container</em></a> is
|
|
a CharacterData node is obtained similarly but using <a
|
|
href='glossary.html#dt-16-bit-unit'><em>16-bit unit</em></a>
|
|
positions instead. For example, the <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>
|
|
labelled s1 of the Range 1 has a Text node (the one containing
|
|
"Title") as its <a
|
|
href='ranges.html#td-container'><em>container</em></a> and an <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> of 2 since it is
|
|
between the second and third <a
|
|
href='glossary.html#dt-16-bit-unit'><em>16-bit unit</em></a>.</p>
|
|
|
|
<p>Notice that the <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>s of
|
|
Ranges 3 and 4 correspond to the same location in the text
|
|
representation. An important feature of the Range is that a <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> of
|
|
a Range can unambiguously represent every position within the
|
|
document tree.</p>
|
|
|
|
<p>The <a href='ranges.html#td-container'><em>container</em></a>s
|
|
and <a href='ranges.html#td-offset'><em>offset</em></a>s of the <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>s
|
|
can be obtained through the following read-only Range
|
|
attributes:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
readonly attribute Node startContainer;
|
|
readonly attribute long startOffset;
|
|
readonly attribute Node endContainer;
|
|
readonly attribute long endOffset;
|
|
</pre>
|
|
</div>
|
|
|
|
<p><a id="td-collapsed" name='td-collapsed'></a>If the <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>s of
|
|
a Range have the same <a
|
|
href='ranges.html#td-container'><em>container</em></a>s and <a
|
|
href='ranges.html#td-offset'><em>offset</em></a>s, the Range is
|
|
said to be a <i>collapsed</i> Range. (This is often referred to as
|
|
an insertion point in a user agent.)</p>
|
|
</div>
|
|
|
|
<!-- div3 Level-2-Range-Position -->
|
|
<div class='div3'><a id="Level-2-Range-Containment"
|
|
name='Level-2-Range-Containment'></a>
|
|
|
|
<h3 id='Level-2-Range-Containment-h3' class='div3'>2.2.2. Selection
|
|
and Partial Selection</h3>
|
|
|
|
<p><a id="td-selected" name='td-selected'></a>A node or <a
|
|
href='glossary.html#dt-16-bit-unit'><em>16-bit unit</em></a> unit
|
|
is said to be <i>selected</i> by a Range if it is between the two
|
|
<a href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>s
|
|
of the Range, that is, if the position immediately before the node
|
|
or 16-bit unit is before the end of the Range and the position
|
|
immediately after the node or 16-bit unit is after the start of the
|
|
range. For example, in terms of a text representation of the
|
|
document, an element would be <a
|
|
href='ranges.html#td-selected'><em>selected</em></a> by a Range if
|
|
its corresponding start-tag was located after the start of the
|
|
Range and its end-tag was located before the end of the Range. In
|
|
the examples in the above diagram, the Range 2 <a
|
|
href='ranges.html#td-selected'><em>selects</em></a> the P node and
|
|
the Range 3 <a href='ranges.html#td-selected'><em>selects</em></a>
|
|
the text node containing the text "Blah xyz."</p>
|
|
|
|
<p><a id="td-partially-selected" name='td-partially-selected'></a>A
|
|
node is said to be <i>partially selected</i> by a Range if it is an
|
|
<a href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of exactly one <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> of
|
|
the Range. For example, consider Range 1 in the above diagram. The
|
|
element H1 is <a
|
|
href='ranges.html#td-partially-selected'><em>partially
|
|
selected</em></a> by that Range since the start of the Range is
|
|
within one of its children.</p>
|
|
</div>
|
|
|
|
<!-- div3 Level-2-Range-Containment -->
|
|
<div class='div3'><a id="Level-2-Range-Notation"
|
|
name='Level-2-Range-Notation'></a>
|
|
|
|
<h3 id='Level-2-Range-Notation-h3' class='div3'>2.2.3.
|
|
Notation</h3>
|
|
|
|
<p>Many of the examples in this chapter are illustrated using a
|
|
text representation of a document. The <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>s of
|
|
a Range are indicated by displaying the characters (be they markup
|
|
or data characters) between the two <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>s in
|
|
bold, as in</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<FOO>A<b>BC<BAR>DE</b>F</BAR></FOO>
|
|
|
|
</pre>
|
|
</div>
|
|
|
|
<p>When both <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>s
|
|
are at the same position, they are indicated with a bold caret
|
|
('<b>^</b>'), as in</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<FOO>A<b>^</b>BC<BAR>DEF</BAR></FOO>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- div3 Level-2-Range-Notation --></div>
|
|
|
|
<!-- div2 Level-2-Range-Definitions -->
|
|
<div class='div2'><a id="Level-2-Range-Creating"
|
|
name='Level-2-Range-Creating'></a>
|
|
|
|
<h2 id='Level-2-Range-Creating-h2' class='div2'>2.3. Creating a
|
|
Range</h2>
|
|
|
|
<p>A Range is created by calling the <code>createRange()</code>
|
|
method on the <a
|
|
href='ranges.html#Level-2-DocumentRange-idl'><code>DocumentRange</code></a>
|
|
interface. This interface can be obtained from the object
|
|
implementing the <code>Document</code> interface using
|
|
binding-specific casting methods.</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
interface DocumentRange {
|
|
Range createRange();
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>The initial state of the Range returned from this method is such
|
|
that both of its <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a>s
|
|
are positioned at the beginning of the corresponding Document,
|
|
before any content. In other words, the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of each <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> is
|
|
the Document node and the offset within that node is 0.</p>
|
|
|
|
<p>Like some objects created using methods in the Document
|
|
interface (such as Nodes and DocumentFragments), Ranges created via
|
|
a particular document instance can select only content associated
|
|
with that Document, or with DocumentFragments and Attrs for which
|
|
that Document is the <code>ownerDocument</code>. Such Ranges, then,
|
|
can not be used with other Document instances.</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Creating -->
|
|
<div class='div2'><a id="Level-2-Range-Changing"
|
|
name='Level-2-Range-Changing'></a>
|
|
|
|
<h2 id='Level-2-Range-Changing-h2' class='div2'>2.4. Changing a
|
|
Range's Position</h2>
|
|
|
|
<p>A Range's position can be specified by setting the <a
|
|
href='ranges.html#td-container'><em>container</em></a> and <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> of each
|
|
boundary-point with the <code>setStart</code> and
|
|
<code>setEnd</code> methods.</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
void setStart(in Node parent, in long offset)
|
|
raises(RangeException);
|
|
void setEnd(in Node parent, in long offset)
|
|
raises(RangeException);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>If one boundary-point of a Range is set to have a <a
|
|
href='ranges.html#td-root-container'><em>root container</em></a>
|
|
other than the current one for the Range, the Range is <a
|
|
href='ranges.html#td-collapsed'><em>collapsed</em></a> to the new
|
|
position. This enforces the restriction that both boundary-points
|
|
of a Range must have the same <a
|
|
href='ranges.html#td-root-container'><em>root
|
|
container</em></a>.</p>
|
|
|
|
<p>The start position of a Range is guaranteed to never be after
|
|
the end position. To enforce this restriction, if the start is set
|
|
to be at a position after the end, the Range is <a
|
|
href='ranges.html#td-collapsed'><em>collapsed</em></a> to that
|
|
position. Similarly, if the end is set to be at a position before
|
|
the start, the Range is <a
|
|
href='ranges.html#td-collapsed'><em>collapsed</em></a> to that
|
|
position.</p>
|
|
|
|
<p>It is also possible to set a Range's position relative to nodes
|
|
in the tree:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
void setStartBefore(in Node node);
|
|
raises(RangeException);
|
|
void setStartAfter(in Node node);
|
|
raises(RangeException);
|
|
void setEndBefore(in Node node);
|
|
raises(RangeException);
|
|
void setEndAfter(in Node node);
|
|
raises(RangeException);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>The <a href='glossary.html#dt-parent'><em>parent</em></a> of the
|
|
node becomes the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of the <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> and
|
|
the Range is subject to the same restrictions as given above in the
|
|
description of <code>setStart()</code>and
|
|
<code>setEnd()</code>.</p>
|
|
|
|
<p>A Range can be <a
|
|
href='ranges.html#td-collapsed'><em>collapsed</em></a> to either
|
|
boundary-point:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
void collapse(in boolean toStart);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>Passing <code>TRUE</code> as the parameter <code>toStart</code>
|
|
will <a href='ranges.html#td-collapsed'><em>collapse</em></a> the
|
|
Range to its start, <code>FALSE</code> to its end.</p>
|
|
|
|
<p>Testing whether a Range is <a
|
|
href='ranges.html#td-collapsed'><em>collapsed</em></a> can be done
|
|
by examining the <code>collapsed</code> attribute:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
readonly attribute boolean collapsed;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>The following methods can be used to make a Range select the
|
|
contents of a node or the node itself.</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
void selectNode(in Node n);
|
|
void selectNodeContents(in Node n);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>The following examples demonstrate the operation of the methods
|
|
<code>selectNode</code> and <code>selectNodeContents</code>:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
Before:
|
|
<b>^</b><BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>
|
|
After Range.selectNodeContents(FOO):
|
|
<BAR><FOO><b>A<MOO>B</MOO>C</b></FOO></BAR>
|
|
(In this case, FOO is the parent of both boundary-points)
|
|
After Range.selectNode(FOO):
|
|
|
|
<BAR><b><FOO>A<MOO>B</MOO>C</FOO></b></BAR>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Changing -->
|
|
<div class='div2'><a id="Level-2-Range-Comparing"
|
|
name='Level-2-Range-Comparing'></a>
|
|
|
|
<h2 id='Level-2-Range-Comparing-h2' class='div2'>2.5. Comparing
|
|
Range Boundary-Points</h2>
|
|
|
|
<p>It is possible to compare two Ranges by comparing their
|
|
boundary-points:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
short compareBoundaryPoints(in CompareHow how, in Range sourceRange) raises(RangeException);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>where <code>CompareHow</code> is one of four values:
|
|
<code>START_TO_START</code>, <code>START_TO_END</code>,
|
|
<code>END_TO_END</code> and <code>END_TO_START</code>. The return
|
|
value is -1, 0 or 1 depending on whether the corresponding
|
|
boundary-point of the Range is before, equal to, or after the
|
|
corresponding boundary-point of <code>sourceRange</code>. An
|
|
exception is thrown if the two Ranges have different <a
|
|
href='ranges.html#td-root-container'><em>root
|
|
container</em></a>s.</p>
|
|
|
|
<p>The result of comparing two boundary-points (or positions) is
|
|
specified below. An informal but not always correct specification
|
|
is that an boundary-point is before, equal to, or after another if
|
|
it corresponds to a location in a text representation before, equal
|
|
to, or after the other's corresponding location.</p>
|
|
|
|
<p><a id="td-comparison" name='td-comparison'></a>Let A and B be
|
|
two boundary-points or positions. Then one of the following holds:
|
|
A is <i>before</i> B, A is <i>equal to</i> B, or A is <i>after</i>
|
|
B. Which one holds is specified in the following by examining four
|
|
cases:</p>
|
|
|
|
<p>In the first case the boundary-points have the same <a
|
|
href='ranges.html#td-container'><em>container</em></a>. A is
|
|
<i>before</i> B if its <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> is less than the
|
|
<a href='ranges.html#td-offset'><em>offset</em></a> of B, A is
|
|
<i>equal to</i> B if its <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> is equal to the <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> of B, and A is
|
|
<i>after</i> B if its <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> is greater than
|
|
the <a href='ranges.html#td-offset'><em>offset</em></a> of B.</p>
|
|
|
|
<p>In the second case a child node C of the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of A is an
|
|
<a href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of B. In this case, A is <i>before</i> B if the
|
|
<a href='ranges.html#td-offset'><em>offset</em></a> of A is less
|
|
than or equal to the index of the child node C and A is
|
|
<i>after</i> B otherwise.</p>
|
|
|
|
<p>In the third case a child node C of the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of B is an
|
|
<a href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of A. In this case, A is <i>before</i> B if the
|
|
index of the child node C is less than the <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> of B and A is
|
|
<i>after</i> B otherwise.</p>
|
|
|
|
<p>In the fourth case, none of three other cases hold: the
|
|
containers of A and B are <a
|
|
href='glossary.html#dt-sibling'><em>siblings</em></a> or <a
|
|
href='glossary.html#dt-descendant'><em>descendants</em></a> of
|
|
sibling nodes. In this case, A is <i>before</i> B if the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of A is
|
|
before the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of B in a
|
|
pre-order traversal of the Ranges' <a
|
|
href='ranges.html#td-context-tree'><em>context tree</em></a> and A
|
|
is <i>after</i> B otherwise.</p>
|
|
|
|
<p>Note that because the same location in a text representation of
|
|
the document can correspond to two different positions in the DOM
|
|
tree, it is possible for two boundary-points to not compare equal
|
|
even though they would be equal in the text representation. For
|
|
this reason, the informal definition above can sometimes be
|
|
incorrect.</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Comparing -->
|
|
<div class='div2'><a id="Level-2-Range-Deleting-Content"
|
|
name='Level-2-Range-Deleting-Content'></a>
|
|
|
|
<h2 id='Level-2-Range-Deleting-Content-h2' class='div2'>2.6.
|
|
Deleting Content with a Range</h2>
|
|
|
|
<p>One can delete the contents selected by a Range with:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
void deleteContents();
|
|
</pre>
|
|
</div>
|
|
|
|
<p><code>deleteContents()</code> deletes all nodes and characters
|
|
selected by the Range. All other nodes and characters remain in the
|
|
<a href='ranges.html#td-context-tree'><em>context tree</em></a> of
|
|
the Range. Some examples of this deletion operation are:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
(1) <FOO>A<b>B<MOO>CD</MOO></b>CD</FOO> -->
|
|
<FOO>A<b>^</b>CD</FOO>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
(2) <FOO>A<MOO>B<b>C</MOO>D</b>E</FOO> -->
|
|
<FOO>A<MOO>B</MOO><b>^</b>E</FOO>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
(3) <FOO>X<b>Y<BAR>Z</b>W</BAR>Q</FOO> -->
|
|
<FOO>X<b>^</b><BAR>W</BAR>Q</FOO>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
(4) <FOO><BAR1>A<b>B</BAR1><BAR2/><BAR3>C</b>D</BAR3></FOO>
|
|
--> <FOO><BAR1>A</BAR1><b>^</b><BAR3>D</BAR3>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>After <code>deleteContents()</code> is invoked on a Range, the
|
|
Range is <a href='ranges.html#td-collapsed'><em>collapsed</em></a>.
|
|
If no node was <a
|
|
href='ranges.html#td-partially-selected'><em>partially
|
|
selected</em></a> by the Range, then it is <a
|
|
href='ranges.html#td-collapsed'><em>collapsed</em></a> to its
|
|
original start point, as in example (1). If a node was <a
|
|
href='ranges.html#td-partially-selected'><em>partially
|
|
selected</em></a> by the Range and was an <a
|
|
href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of the start of the Range and no <a
|
|
href='glossary.html#dt-ancestor'><em>ancestor</em></a> of the node
|
|
satisfies these two conditions, then the Range is collapsed to the
|
|
position immediately after the node, as in examples (2) and (4). If
|
|
a node was <a
|
|
href='ranges.html#td-partially-selected'><em>partially
|
|
selected</em></a> by the Range and was an <a
|
|
href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of the end of the Range and no ancestor of the
|
|
node satisfies these two conditions, then the Range is collapsed to
|
|
the position immediately before the node, as in examples (3) and
|
|
(4).</p>
|
|
|
|
<p>Note that if deletion of a Range leaves adjacent Text nodes,
|
|
they are not automatically merged, and empty Text nodes are not
|
|
automatically removed. Two Text nodes should be joined only if each
|
|
is the container of one of the boundary-points of a Range whose
|
|
contents are deleted. To merge adjacent Text nodes, or remove empty
|
|
text nodes, the <code>normalize()</code> method on the
|
|
<code>Node</code> interface should be used.</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Deleting-Content -->
|
|
<div class='div2'><a id="Level-2-Range-Extracting"
|
|
name='Level-2-Range-Extracting'></a>
|
|
|
|
<h2 id='Level-2-Range-Extracting-h2' class='div2'>2.7. Extracting
|
|
Content</h2>
|
|
|
|
<p>If the contents of a Range need to be extracted rather than
|
|
deleted, the following method may be used:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
DocumentFragment extractContents();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>The <code>extractContents()</code> method removes nodes from the
|
|
Range's <a href='ranges.html#td-context-tree'><em>context
|
|
tree</em></a> similarly to the <code>deleteContents()</code>
|
|
method. In addition, it places the deleted contents in a new
|
|
<code>DocumentFragment</code>. The following examples illustrate
|
|
the contents of the returned DocumentFragment:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
(1) <FOO>A<b>B<MOO>CD</MOO></b>CD</FOO> -->
|
|
B<MOO>CD</MOO>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
(2) <FOO>A<MOO>B<b>C</MOO>D</b>E</FOO> -->
|
|
<MOO>C<MOO>D
|
|
</pre>
|
|
</div>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
(3) <FOO>X<b>Y<BAR>Z</b>W</BAR>Q</FOO> -->
|
|
Y<BAR>Z</BAR>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
(4)
|
|
<FOO><BAR1>A<b>B</BAR1><BAR2/><BAR3>C</b>D</BAR3></FOO> -->
|
|
<BAR1>B</BAR1><BAR2/><BAR3>C</BAR3>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>It is important to note that nodes that are <a
|
|
href='ranges.html#td-partially-selected'><em>partially
|
|
selected</em></a> by the Range are cloned. Since part of such a
|
|
node's contents must remain in the Range's <a
|
|
href='ranges.html#td-context-tree'><em>context tree</em></a> and
|
|
part of the contents must be moved to the new DocumentFragment, a
|
|
clone of the <a
|
|
href='ranges.html#td-partially-selected'><em>partially
|
|
selected</em></a> node is included in the new DocumentFragment.
|
|
Note that cloning does not take place for <a
|
|
href='ranges.html#td-selected'><em>selected</em></a> elements;
|
|
these nodes are moved to the new DocumentFragment.</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Extracting -->
|
|
<div class='div2'><a id="Level-2-Range-Cloning"
|
|
name='Level-2-Range-Cloning'></a>
|
|
|
|
<h2 id='Level-2-Range-Cloning-h2' class='div2'>2.8. Cloning
|
|
Content</h2>
|
|
|
|
<p>The contents of a Range may be duplicated using the following
|
|
method:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
DocumentFragment cloneContents();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>This method returns a <code>DocumentFragment</code> that is
|
|
similar to the one returned by the method
|
|
<code>extractContents()</code>. However, in this case, the original
|
|
nodes and character data in the Range are not removed from the
|
|
Range's <a href='ranges.html#td-context-tree'><em>context
|
|
tree</em></a>. Instead, all of the nodes and text content within
|
|
the returned <code>DocumentFragment</code> are cloned.</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Cloning -->
|
|
<div class='div2'><a id="Level-2-Range-Inserting"
|
|
name='Level-2-Range-Inserting'></a>
|
|
|
|
<h2 id='Level-2-Range-Inserting-h2' class='div2'>2.9. Inserting
|
|
Content</h2>
|
|
|
|
<p>A node may be inserted into a Range using the following
|
|
method:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
void insertNode(in Node n) raises(RangeException);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>The <code>insertNode()</code> method inserts the specified node
|
|
into the Range's <a href='ranges.html#td-context-tree'><em>context
|
|
tree</em></a>. The node is inserted at the start <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> of
|
|
the Range, without modifying it.</p>
|
|
|
|
<p>If the start boundary point of the Range is in a
|
|
<code>Text</code> node, the <code>insertNode</code> operation
|
|
splits the <code>Text</code> node at the boundary point. If the
|
|
node to be inserted is also a <code>Text</code> node, the resulting
|
|
adjacent <code>Text</code> nodes are not normalized automatically;
|
|
this operation is left to the application.</p>
|
|
|
|
<p>The Node passed into this method can be a
|
|
<code>DocumentFragment</code>. In that case, the contents of the
|
|
<code>DocumentFragment</code> are inserted at the start <a
|
|
href='ranges.html#td-boundarypoint'><em>boundary-point</em></a> of
|
|
the Range, but the <code>DocumentFragment</code> itself is not.
|
|
Note that if the Node represents the root of a sub-tree, the entire
|
|
sub-tree is inserted.</p>
|
|
|
|
<p>The same rules that apply to the <code>insertBefore()</code>
|
|
method on the Node interface apply here. Specifically, the Node
|
|
passed in, if it already has a parent, will be removed from its
|
|
existing position.</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Inserting -->
|
|
<div class='div2'><a id="Level-2-Range-Surrounding"
|
|
name='Level-2-Range-Surrounding'></a>
|
|
|
|
<h2 id='Level-2-Range-Surrounding-h2' class='div2'>2.10.
|
|
Surrounding Content</h2>
|
|
|
|
<p>The insertion of a single node to subsume the content selected
|
|
by a Range can be performed with:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
void surroundContents(in Node newParent);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>The <code>surroundContents()</code> method causes all of the
|
|
content selected by the Range to be rooted by the specified node.
|
|
The nodes may not be Attr, Entity, DocumentType, Notation,
|
|
Document, or DocumentFragment nodes. Calling
|
|
<code>surroundContents()</code> with the Element node FOO in the
|
|
following examples yields:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
Before:
|
|
<BAR>A<b>B<MOO>C</MOO>D</b>E</BAR>
|
|
|
|
After surroundContents(FOO):
|
|
|
|
<BAR>A<b><FOO>B<MOO>C</MOO>D</FOO></b>E</BAR>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>Another way of describing the effect of this method on the
|
|
Range's <a href='ranges.html#td-context-tree'><em>context
|
|
tree</em></a> is to decompose it in terms of other operations:</p>
|
|
|
|
<ol>
|
|
<li>Remove the contents selected by the Range with a call to
|
|
<code>extractContents()</code>.</li>
|
|
|
|
<li>Insert the node <code>newParent</code> where the Range is
|
|
collapsed (after the extraction) with
|
|
<code>insertNode().</code></li>
|
|
|
|
<li>Insert the entire contents of the extracted DocumentFragment
|
|
into <code>newParent</code>. Specifically, invoke the
|
|
<code>appendChild()</code> on <code>newParent</code> passing in the
|
|
DocumentFragment returned as a result of the call to
|
|
<code>extractContents()</code></li>
|
|
|
|
<li>Select <code>newParent</code> and all of its contents with
|
|
<code>selectNode()</code>.</li>
|
|
</ol>
|
|
|
|
<p>The <code>surroundContents()</code> method raises an exception
|
|
if the Range <a
|
|
href='ranges.html#td-partially-selected'><em>partially
|
|
selects</em></a> a non-Text node. An example of a Range for which
|
|
<code>surroundContents()</code>raises an exception is:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<FOO>A<b>B<BAR>C</b>D</BAR>E</FOO>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>If the node <code>newParent</code> has any children, those
|
|
children are removed before its insertion. Also, if the node
|
|
<code>newParent</code> already has a parent, it is removed from the
|
|
original parent's <code>childNodes</code> list.</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Surrounding -->
|
|
<div class='div2'><a id="Level-2-Range-Misc"
|
|
name='Level-2-Range-Misc'></a>
|
|
|
|
<h2 id='Level-2-Range-Misc-h2' class='div2'>2.11. Miscellaneous
|
|
Members</h2>
|
|
|
|
<p>One can clone a Range:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
Range cloneRange();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>This creates a new Range which selects exactly the same content
|
|
as that selected by the Range on which the method
|
|
<code>cloneRange</code> was invoked. No content is affected by this
|
|
operation.</p>
|
|
|
|
<p>Because the boundary-points of a Range do not necessarily have
|
|
the same <a
|
|
href='ranges.html#td-container'><em>container</em></a>s, use:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
readonly attribute Node commonAncestorContainer;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>to get the <a
|
|
href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of both boundary-points that is furthest down
|
|
from the Range's <a href='ranges.html#td-root-container'><em>root
|
|
container</em></a></p>
|
|
|
|
<p>One can get a copy of all the character data selected or
|
|
partially selected by a Range with:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
DOMString toString();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>This does nothing more than simply concatenate all the character
|
|
data selected by the Range. This includes character data in both
|
|
<code>Text</code> and <code>CDATASection</code> nodes.</p>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Misc -->
|
|
<div class='div2'><a id="Level-2-Range-Mutation"
|
|
name='Level-2-Range-Mutation'></a>
|
|
|
|
<h2 id='Level-2-Range-Mutation-h2' class='div2'>2.12. Range
|
|
modification under document mutation</h2>
|
|
|
|
<p>As a document is modified, the Ranges within the document need
|
|
to be updated. For example, if one boundary-point of a Range is
|
|
within a node and that node is removed from the document, then the
|
|
Range would be invalid unless it is fixed up in some way. This
|
|
section describes how Ranges are modified under document mutations
|
|
so that they remain valid.</p>
|
|
|
|
<p>There are two general principles which apply to Ranges under
|
|
document mutation: The first is that all Ranges in a document will
|
|
remain valid after any mutation operation and the second is that,
|
|
as much as possible, all Ranges will select the same portion of the
|
|
document after any mutation operation.</p>
|
|
|
|
<p>Any mutation of the document tree which affect Ranges can be
|
|
considered to be a combination of basic deletion and insertion
|
|
operations. In fact, it can be convenient to think of those
|
|
operations as being accomplished using the
|
|
<code>deleteContents()</code> and <code>insertNode()</code> Range
|
|
methods and, in the case of Text mutations, the
|
|
<code>splitText()</code> and <code>normalize()</code> methods.</p>
|
|
|
|
<div class='div3'><a id="Level-2-Range-Insertions"
|
|
name='Level-2-Range-Insertions'></a>
|
|
|
|
<h3 id='Level-2-Range-Insertions-h3' class='div3'>2.12.1.
|
|
Insertions</h3>
|
|
|
|
<p>An insertion occurs at a single point, the insertion point, in
|
|
the document. For any Range in the document tree, consider each
|
|
boundary-point. The only case in which the boundary-point will be
|
|
changed after the insertion is when the boundary-point and the
|
|
insertion point have the same <a
|
|
href='ranges.html#td-container'><em>container</em></a> and the <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> of the insertion
|
|
point is strictly less than the <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> of the Range's
|
|
boundary-point. In that case the <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> of the Range's
|
|
boundary-point will be increased so that it is between the same
|
|
nodes or characters as it was before the insertion.</p>
|
|
|
|
<p>Note that when content is inserted at a boundary-point, it is
|
|
ambiguous as to where the boundary-point should be repositioned if
|
|
its relative position is to be maintained. There are two
|
|
possibilities: at the start or at the end of the newly inserted
|
|
content. We have chosen that in this case neither the <a
|
|
href='ranges.html#td-container'><em>container</em></a> nor <a
|
|
href='ranges.html#td-offset'><em>offset</em></a> of the
|
|
boundary-point is changed. As a result, the boundary-point will be
|
|
positioned at the start of the newly inserted content.</p>
|
|
|
|
<p><em>Examples:</em></p>
|
|
|
|
<p>Suppose the Range selects the following:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>Abcd efgh X<b>Y blah i</b>jkl</P>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>Consider the insertion of the text "<i>inserted text</i>" at the
|
|
following positions:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
1. Before the 'X':
|
|
|
|
<P>Abcd efgh <i>inserted text</i>X<b>Y blah i</b>jkl</P>
|
|
|
|
2. After the 'X':
|
|
|
|
<P>Abcd efgh X<b><i>inserted text</i>Y blah i</b>jkl</P>
|
|
|
|
3. After the 'Y':
|
|
|
|
<P>Abcd efgh X<b>Y<i>inserted text</i> blah i</b>jkl</P>
|
|
|
|
4. After the 'h' in "Y blah":
|
|
|
|
<P>Abcd efgh X<b>Y blah<i>inserted text</i> i</b>jkl</P>
|
|
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- div3 Level-2-Range-Insertions -->
|
|
<div class='div3'><a id="Level-2-Range-Deletions"
|
|
name='Level-2-Range-Deletions'></a>
|
|
|
|
<h3 id='Level-2-Range-Deletions-h3' class='div3'>2.12.2.
|
|
Deletions</h3>
|
|
|
|
<p>Any deletion from the document tree can be considered as a
|
|
sequence of <code>deleteContents()</code> operations applied to a
|
|
minimal set of disjoint Ranges. To specify how a Range is modified
|
|
under deletions we need only consider what happens to a Range under
|
|
a single <code>deleteContents()</code>operation of another Range.
|
|
And, in fact, we need only consider what happens to a single
|
|
boundary-point of the Range since both boundary-points are modified
|
|
using the same algorithm.</p>
|
|
|
|
<p>If a boundary-point of the original Range is within the content
|
|
being deleted, then after the deletion it will be at the same
|
|
position as the resulting boundary-point of the (now <a
|
|
href='ranges.html#td-collapsed'><em>collapsed</em></a>) Range used
|
|
to delete the contents.</p>
|
|
|
|
<p>If a boundary-point is after the content being deleted then it
|
|
is not affected by the deletion unless its <a
|
|
href='ranges.html#td-container'><em>container</em></a> is also the
|
|
<a href='ranges.html#td-container'><em>container</em></a> of one of
|
|
the boundary-points of the Range being deleted. If there is such a
|
|
common <a href='ranges.html#td-container'><em>container</em></a>,
|
|
then the index of the boundary-point is modified so that the
|
|
boundary-point maintains its position relative to the content of
|
|
the <a href='ranges.html#td-container'><em>container</em></a>.</p>
|
|
|
|
<p>If a boundary-point is before the content being deleted then it
|
|
is not affected by the deletion at all.</p>
|
|
|
|
<p><em>Examples:</em></p>
|
|
|
|
<p>In these examples, the Range on which
|
|
<code>deleteContents()</code>is invoked is indicated by the
|
|
underline.</p>
|
|
|
|
<p><em>Example 1.</em></p>
|
|
|
|
<p>Before:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>Abcd <u>efgh T</u><b><u>he</u> Range i</b>jkl</P>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>After:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>Abcd <b>Range i</b>jkl</P>
|
|
</pre>
|
|
</div>
|
|
|
|
<p><em>Example 2.</em></p>
|
|
|
|
<p>Before:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<p>Abcd <u>efgh T<b>he Range i</b>j</u>kl</p>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>After:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<p>Abcd <b>^</b>kl</p>
|
|
</pre>
|
|
</div>
|
|
|
|
<p><em>Example 3.</em></p>
|
|
|
|
<p>Before:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>ABCD <u>efgh T</u><b><u>he <EM>R</u>ange</b></EM> ijkl</P>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>After:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>ABCD <EM><b>ange</b></EM> ijkl</P>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>In this example, the container of the start boundary-point after
|
|
the deletion is the Text node holding the string "ange".</p>
|
|
|
|
<p><em>Example 4.</em></p>
|
|
|
|
<p>Before:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>Abcd <u>efgh T</u><b>he Range i</b>jkl</P>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>After:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>Abcd <b>he Range i</b>jkl</P>
|
|
</pre>
|
|
</div>
|
|
|
|
<p><em>Example 5.</em></p>
|
|
|
|
<p>Before:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>Abcd <u><EM>efgh T<b>he Range i</b>j</EM></u>kl</P>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>After:</p>
|
|
|
|
<div class='eg'>
|
|
<pre>
|
|
<P>Abcd <b>^</b>kl</P>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- div3 Level-2-Range-Deletions --></div>
|
|
|
|
<!-- div2 Level-2-Range-Mutation -->
|
|
<div class='div2'><a id="Level-2-Range-Interface"
|
|
name='Level-2-Range-Interface'></a>
|
|
|
|
<h2 id='Level-2-Range-Interface-h2' class='div2'>2.13. Formal
|
|
Description of the Range Interface</h2>
|
|
|
|
<p>To summarize, the complete, formal description of the <a
|
|
href='ranges.html#Level-2-Range-idl'><code>Range</code></a>
|
|
interface is given below:</p>
|
|
|
|
<dl>
|
|
<dt><b>Interface <i><a id="Level-2-Range-idl"
|
|
name='Level-2-Range-idl'>Range</a></i></b> (introduced in <b
|
|
class='since'>DOM Level 2</b>)</dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><br />
|
|
<b>IDL Definition</b></dt>
|
|
|
|
<dd>
|
|
<div class='idl-code'>
|
|
<pre>
|
|
// Introduced in DOM Level 2:
|
|
interface Range {
|
|
readonly attribute Node startContainer;
|
|
// raises(DOMException) on retrieval
|
|
|
|
readonly attribute long startOffset;
|
|
// raises(DOMException) on retrieval
|
|
|
|
readonly attribute Node endContainer;
|
|
// raises(DOMException) on retrieval
|
|
|
|
readonly attribute long endOffset;
|
|
// raises(DOMException) on retrieval
|
|
|
|
readonly attribute boolean collapsed;
|
|
// raises(DOMException) on retrieval
|
|
|
|
readonly attribute Node commonAncestorContainer;
|
|
// raises(DOMException) on retrieval
|
|
|
|
void setStart(in Node refNode,
|
|
in long offset)
|
|
raises(RangeException,
|
|
DOMException);
|
|
void setEnd(in Node refNode,
|
|
in long offset)
|
|
raises(RangeException,
|
|
DOMException);
|
|
void setStartBefore(in Node refNode)
|
|
raises(RangeException,
|
|
DOMException);
|
|
void setStartAfter(in Node refNode)
|
|
raises(RangeException,
|
|
DOMException);
|
|
void setEndBefore(in Node refNode)
|
|
raises(RangeException,
|
|
DOMException);
|
|
void setEndAfter(in Node refNode)
|
|
raises(RangeException,
|
|
DOMException);
|
|
void collapse(in boolean toStart)
|
|
raises(DOMException);
|
|
void selectNode(in Node refNode)
|
|
raises(RangeException,
|
|
DOMException);
|
|
void selectNodeContents(in Node refNode)
|
|
raises(RangeException,
|
|
DOMException);
|
|
|
|
// CompareHow
|
|
const unsigned short START_TO_START = 0;
|
|
const unsigned short START_TO_END = 1;
|
|
const unsigned short END_TO_END = 2;
|
|
const unsigned short END_TO_START = 3;
|
|
|
|
short compareBoundaryPoints(in unsigned short how,
|
|
in Range sourceRange)
|
|
raises(DOMException);
|
|
void deleteContents()
|
|
raises(DOMException);
|
|
DocumentFragment extractContents()
|
|
raises(DOMException);
|
|
DocumentFragment cloneContents()
|
|
raises(DOMException);
|
|
void insertNode(in Node newNode)
|
|
raises(DOMException,
|
|
RangeException);
|
|
void surroundContents(in Node newParent)
|
|
raises(DOMException,
|
|
RangeException);
|
|
Range cloneRange()
|
|
raises(DOMException);
|
|
DOMString toString()
|
|
raises(DOMException);
|
|
void detach()
|
|
raises(DOMException);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<br />
|
|
</dd>
|
|
|
|
<dt><b>Definition group <i><a id="Level2-Range-compareHow"
|
|
name='Level2-Range-compareHow'>CompareHow</a></i></b></dt>
|
|
|
|
<dd>
|
|
<p>Passed as a parameter to the <code>compareBoundaryPoints</code>
|
|
method.</p>
|
|
|
|
<dl>
|
|
<dt><b>Defined Constants</b></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class='constant-name'>END_TO_END</code></dt>
|
|
|
|
<dd>Compare end boundary-point of <code>sourceRange</code> to end
|
|
boundary-point of Range on which <code>compareBoundaryPoints</code>
|
|
is invoked.</dd>
|
|
|
|
<dt><code class='constant-name'>END_TO_START</code></dt>
|
|
|
|
<dd>Compare end boundary-point of <code>sourceRange</code> to start
|
|
boundary-point of Range on which <code>compareBoundaryPoints</code>
|
|
is invoked.</dd>
|
|
|
|
<dt><code class='constant-name'>START_TO_END</code></dt>
|
|
|
|
<dd>Compare start boundary-point of <code>sourceRange</code> to end
|
|
boundary-point of Range on which <code>compareBoundaryPoints</code>
|
|
is invoked.</dd>
|
|
|
|
<dt><code class='constant-name'>START_TO_START</code></dt>
|
|
|
|
<dd>Compare start boundary-point of <code>sourceRange</code> to
|
|
start boundary-point of Range on which
|
|
<code>compareBoundaryPoints</code> is invoked.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><b>Attributes</b></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class='attribute-name'><a
|
|
id="Level-2-Range-attr-collapsed"
|
|
name='Level-2-Range-attr-collapsed'>collapsed</a></code> of type
|
|
<code>boolean</code>, readonly</dt>
|
|
|
|
<dd>TRUE if the Range is collapsed<br />
|
|
|
|
|
|
<div class='exceptions'><b>Exceptions on retrieval</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
</dd>
|
|
|
|
<dt><code class='attribute-name'><a
|
|
id="Level-2-Range-attr-commonParent"
|
|
name='Level-2-Range-attr-commonParent'>commonAncestorContainer</a></code>
|
|
of type <code>Node</code>, readonly</dt>
|
|
|
|
<dd>The <a href='glossary.html#dt-deepest'><em>deepest</em></a>
|
|
common <a href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of the Range's two boundary-points.<br />
|
|
|
|
|
|
<div class='exceptions'><b>Exceptions on retrieval</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
</dd>
|
|
|
|
<dt><code class='attribute-name'><a
|
|
id="Level-2-Range-attr-endParent"
|
|
name='Level-2-Range-attr-endParent'>endContainer</a></code> of type
|
|
<code>Node</code>, readonly</dt>
|
|
|
|
<dd>Node within which the Range ends<br />
|
|
|
|
|
|
<div class='exceptions'><b>Exceptions on retrieval</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
</dd>
|
|
|
|
<dt><code class='attribute-name'><a
|
|
id="Level-2-Range-attr-endOffset"
|
|
name='Level-2-Range-attr-endOffset'>endOffset</a></code> of type
|
|
<code>long</code>, readonly</dt>
|
|
|
|
<dd>Offset within the ending node of the Range.<br />
|
|
|
|
|
|
<div class='exceptions'><b>Exceptions on retrieval</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
</dd>
|
|
|
|
<dt><code class='attribute-name'><a
|
|
id="Level-2-Range-attr-startParent"
|
|
name='Level-2-Range-attr-startParent'>startContainer</a></code> of
|
|
type <code>Node</code>, readonly</dt>
|
|
|
|
<dd>Node within which the Range begins<br />
|
|
|
|
|
|
<div class='exceptions'><b>Exceptions on retrieval</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
</dd>
|
|
|
|
<dt><code class='attribute-name'><a
|
|
id="Level-2-Range-attr-startOffset"
|
|
name='Level-2-Range-attr-startOffset'>startOffset</a></code> of
|
|
type <code>long</code>, readonly</dt>
|
|
|
|
<dd>Offset within the starting node of the Range.<br />
|
|
|
|
|
|
<div class='exceptions'><b>Exceptions on retrieval</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><b>Methods</b></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-cloneContents"
|
|
name='Level2-Range-method-cloneContents'>cloneContents</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Duplicates the contents of a Range
|
|
|
|
<div class='return'><b>Return Value</b>
|
|
|
|
<div class='returntable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the return value, the second contains a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DocumentFragment</code></p>
|
|
</td>
|
|
<td>
|
|
<p>A DocumentFragment that contains content equivalent to this
|
|
Range.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- return -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
|
|
extracted into the new DocumentFragment.</p>
|
|
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Parameters</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a id="Level2-Range-method-clone"
|
|
name='Level2-Range-method-clone'>cloneRange</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Produces a new Range whose boundary-points are
|
|
equal to the boundary-points of the Range.
|
|
|
|
<div class='return'><b>Return Value</b>
|
|
|
|
<div class='returntable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the return value, the second contains a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#Level-2-Range-idl'><code>Range</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>The duplicated Range.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- return -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Parameters</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a id="Level2-Range-method-collapse"
|
|
name='Level2-Range-method-collapse'>collapse</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Collapse a Range onto one of its
|
|
boundary-points
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>toStart</code> of type
|
|
<code>boolean</code></dt>
|
|
|
|
<dd>If TRUE, collapses the Range onto its start; if FALSE,
|
|
collapses it onto its end.<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-compareBoundaryPoints"
|
|
name='Level2-Range-method-compareBoundaryPoints'>compareBoundaryPoints</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Compare the boundary-points of two Ranges in a
|
|
document.
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>how</code> of type <code>unsigned
|
|
short</code></dt>
|
|
|
|
<dd>A code representing the type of comparison, as defined
|
|
above.<br />
|
|
</dd>
|
|
|
|
<dt><code class='parameter-name'>sourceRange</code> of type <a
|
|
href='ranges.html#Level-2-Range-idl'><code>Range</code></a></dt>
|
|
|
|
<dd>The <code>Range</code> on which this current <code>Range</code>
|
|
is compared to.<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='return'><b>Return Value</b>
|
|
|
|
<div class='returntable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the return value, the second contains a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>short</code></p>
|
|
</td>
|
|
<td>
|
|
<p>-1, 0 or 1 depending on whether the corresponding boundary-point
|
|
of the Range is respectively before, equal to, or after the
|
|
corresponding boundary-point of <code>sourceRange</code>.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- return -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same
|
|
Document or DocumentFragment.</p>
|
|
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-deleteContents"
|
|
name='Level2-Range-method-deleteContents'>deleteContents</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Removes the contents of a Range from the
|
|
containing document or document fragment without returning a
|
|
reference to the removed content.
|
|
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the
|
|
content of the Range is read-only or any of the nodes that contain
|
|
any of the content of the Range are read-only.</p>
|
|
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Parameters</b></div>
|
|
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a id="Level2-Range-method-detach"
|
|
name='Level2-Range-method-detach'>detach</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Called to indicate that the Range is no longer
|
|
in use and that the implementation may relinquish any resources
|
|
associated with this Range. Subsequent calls to any methods or
|
|
attribute getters on this Range will result in a
|
|
<code>DOMException</code> being thrown with an error code of
|
|
<code>INVALID_STATE_ERR</code>.
|
|
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Parameters</b></div>
|
|
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-extractContents"
|
|
name='Level2-Range-method-extractContents'>extractContents</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Moves the contents of a Range from the
|
|
containing document or document fragment to a new DocumentFragment.
|
|
|
|
|
|
<div class='return'><b>Return Value</b>
|
|
|
|
<div class='returntable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the return value, the second contains a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DocumentFragment</code></p>
|
|
</td>
|
|
<td>
|
|
<p>A DocumentFragment containing the extracted contents.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- return -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the
|
|
content of the Range is read-only or any of the nodes which contain
|
|
any of the content of the Range are read-only.</p>
|
|
|
|
<p>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
|
|
extracted into the new DocumentFragment.</p>
|
|
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Parameters</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-insertNode"
|
|
name='Level2-Range-method-insertNode'>insertNode</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Inserts a node into the Document or
|
|
DocumentFragment at the start of the Range. If the container is a
|
|
Text node, this will be split at the start of the Range (as if the
|
|
Text node's splitText method was performed at the insertion point)
|
|
and the insertion will occur between the two resulting Text nodes.
|
|
Adjacent Text nodes will not be automatically merged. If the node
|
|
to be inserted is a DocumentFragment node, the children will be
|
|
inserted rather than the DocumentFragment node itself.
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>newNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>The node to insert at the start of the Range<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if an <a
|
|
href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of the start of the Range is read-only.</p>
|
|
|
|
<p>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of the start
|
|
of the Range were not created from the same document.</p>
|
|
|
|
<p>HIERARCHY_REQUEST_ERR: Raised if the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of the start
|
|
of the Range is of a type that does not allow children of the type
|
|
of <code>newNode</code> or if <code>newNode</code> is an ancestor
|
|
of the <a
|
|
href='ranges.html#td-container'><em>container</em></a>.</p>
|
|
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an
|
|
Attr, Entity, Notation, or Document node.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-selectNode"
|
|
name='Level2-Range-method-selectNode'>selectNode</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Select a node and its contents
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>refNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>The node to select.<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if an ancestor of
|
|
<code>refNode</code> is an Entity, Notation or DocumentType node or
|
|
if <code>refNode</code> is a Document, DocumentFragment, Attr,
|
|
Entity, or Notation node.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-selectNodeContents"
|
|
name='Level2-Range-method-selectNodeContents'>selectNodeContents</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Select the contents within a node
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>refNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>Node to select from<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an
|
|
ancestor of <code>refNode</code> is an Entity, Notation or
|
|
DocumentType node.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a id="Level2-Range-method-setEnd"
|
|
name='Level2-Range-method-setEnd'>setEnd</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Sets the attributes describing the end of a
|
|
Range.
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>refNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>The <code>refNode</code> value. This parameter must be
|
|
different from <code>null</code>.<br />
|
|
</dd>
|
|
|
|
<dt><code class='parameter-name'>offset</code> of type
|
|
<code>long</code></dt>
|
|
|
|
<dd>The <code>endOffset</code> value.<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an
|
|
ancestor of <code>refNode</code> is an Entity, Notation, or
|
|
DocumentType node.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or
|
|
greater than the number of child units in <code>refNode</code>.
|
|
Child units are <a href='glossary.html#dt-16-bit-unit'><em>16-bit
|
|
units</em></a> if <code>refNode</code> is a type of CharacterData
|
|
node (e.g., a Text or Comment node) or a ProcessingInstruction
|
|
node. Child units are Nodes in all other cases.</p>
|
|
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-setEndAfter"
|
|
name='Level2-Range-method-setEndAfter'>setEndAfter</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Sets the end of a Range to be after a node
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>refNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>Range ends after <code>refNode</code>.<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if the root container of
|
|
<code>refNode</code> is not an Attr, Document or DocumentFragment
|
|
node or if <code>refNode</code> is a Document, DocumentFragment,
|
|
Attr, Entity, or Notation node.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-setEndBefore"
|
|
name='Level2-Range-method-setEndBefore'>setEndBefore</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Sets the end position to be before a node.
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>refNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>Range ends before <code>refNode</code><br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if the root container of
|
|
<code>refNode</code> is not an Attr, Document, or DocumentFragment
|
|
node or if <code>refNode</code> is a Document, DocumentFragment,
|
|
Attr, Entity, or Notation node.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a id="Level2-Range-method-setStart"
|
|
name='Level2-Range-method-setStart'>setStart</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Sets the attributes describing the start of the
|
|
Range.
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>refNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>The <code>refNode</code> value. This parameter must be
|
|
different from <code>null</code>.<br />
|
|
</dd>
|
|
|
|
<dt><code class='parameter-name'>offset</code> of type
|
|
<code>long</code></dt>
|
|
|
|
<dd>The <code>startOffset</code> value.<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an
|
|
ancestor of <code>refNode</code> is an Entity, Notation, or
|
|
DocumentType node.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or
|
|
greater than the number of child units in <code>refNode</code>.
|
|
Child units are <a href='glossary.html#dt-16-bit-unit'><em>16-bit
|
|
units</em></a> if <code>refNode</code> is a type of CharacterData
|
|
node (e.g., a Text or Comment node) or a ProcessingInstruction
|
|
node. Child units are Nodes in all other cases.</p>
|
|
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-setStartAfter"
|
|
name='Level2-Range-method-setStartAfter'>setStartAfter</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Sets the start position to be after a node
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>refNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>Range starts after <code>refNode</code><br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if the root container of
|
|
<code>refNode</code> is not an Attr, Document, or DocumentFragment
|
|
node or if <code>refNode</code> is a Document, DocumentFragment,
|
|
Attr, Entity, or Notation node.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a id="Level2-Range-setStartBefore"
|
|
name='Level2-Range-setStartBefore'>setStartBefore</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Sets the start position to be before a node
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>refNode</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>Range starts before <code>refNode</code><br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if the root container of
|
|
<code>refNode</code> is not an Attr, Document, or DocumentFragment
|
|
node or if <code>refNode</code> is a Document, DocumentFragment,
|
|
Attr, Entity, or Notation node.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a
|
|
id="Level2-Range-method-surroundContents"
|
|
name='Level2-Range-method-surroundContents'>surroundContents</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Reparents the contents of the Range to the
|
|
given node and inserts the node at the position of the start of the
|
|
Range.
|
|
|
|
<div class='parameters'><b>Parameters</b>
|
|
|
|
<div class='paramtable'>
|
|
<dl>
|
|
<dt><code class='parameter-name'>newParent</code> of type
|
|
<code>Node</code></dt>
|
|
|
|
<dd>The node to surround the contents with.<br />
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- parameters -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if an <a
|
|
href='ranges.html#td-ancestor-container'><em>ancestor
|
|
container</em></a> of either boundary-point of the Range is
|
|
read-only.</p>
|
|
|
|
<p>WRONG_DOCUMENT_ERR: Raised if <code>newParent</code> and the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of the start
|
|
of the Range were not created from the same document.</p>
|
|
|
|
<p>HIERARCHY_REQUEST_ERR: Raised if the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of the start
|
|
of the Range is of a type that does not allow children of the type
|
|
of <code>newParent</code> or if <code>newParent</code> is an
|
|
ancestor of the <a
|
|
href='ranges.html#td-container'><em>container</em></a> or if
|
|
<code>node</code> would end up with a child node of a type not
|
|
allowed by the type of <code>node</code>.</p>
|
|
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>BAD_BOUNDARYPOINTS_ERR: Raised if the Range <a
|
|
href='ranges.html#td-partially-selected'><em>partially
|
|
selects</em></a> a non-text node.</p>
|
|
|
|
<p>INVALID_NODE_TYPE_ERR: Raised if <code>node</code> is an Attr,
|
|
Entity, DocumentType, Notation, Document, or DocumentFragment
|
|
node.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Return Value</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
|
|
<dt><code class='method-name'><a id="Level2-Range-method-toString"
|
|
name='Level2-Range-method-toString'>toString</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>Returns the contents of a Range as a string.
|
|
This string contains only the data characters, not any markup.
|
|
|
|
<div class='return'><b>Return Value</b>
|
|
|
|
<div class='returntable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the return value, the second contains a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMString</code></p>
|
|
</td>
|
|
<td>
|
|
<p>The contents of the Range.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- return -->
|
|
<div class='exceptions'><b>Exceptions</b>
|
|
|
|
<div class='exceptiontable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><code>DOMException</code></p>
|
|
</td>
|
|
<td>
|
|
<p>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
|
|
been invoked on this object.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- exceptions -->
|
|
<div><b>No Parameters</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><b>Interface <i><a id="Level-2-DocumentRange-idl"
|
|
name='Level-2-DocumentRange-idl'>DocumentRange</a></i></b>
|
|
(introduced in <b class='since'>DOM Level 2</b>)</dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><br />
|
|
<b>IDL Definition</b></dt>
|
|
|
|
<dd>
|
|
<div class='idl-code'>
|
|
<pre>
|
|
// Introduced in DOM Level 2:
|
|
interface DocumentRange {
|
|
Range createRange();
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<br />
|
|
</dd>
|
|
|
|
<dt><b>Methods</b></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class='method-name'><a
|
|
id="Level2-DocumentRange-method-createRange"
|
|
name='Level2-DocumentRange-method-createRange'>createRange</a></code></dt>
|
|
|
|
<dd>
|
|
<div class='method'>This interface can be obtained from the object
|
|
implementing the <code>Document</code> interface using
|
|
binding-specific casting methods.
|
|
|
|
<div class='return'><b>Return Value</b>
|
|
|
|
<div class='returntable'>
|
|
<table
|
|
summary='Layout table: the first cell contains the type of the return value, the second contains a short description'
|
|
border='0'>
|
|
<tr>
|
|
<td valign='top'>
|
|
<p><a
|
|
href='ranges.html#Level-2-Range-idl'><code>Range</code></a></p>
|
|
</td>
|
|
<td>
|
|
<p>The initial state of the Range returned from this method is such
|
|
that both of its boundary-points are positioned at the beginning of
|
|
the corresponding Document, before any content. The Range returned
|
|
can only be used to select content associated with this Document,
|
|
or with DocumentFragments and Attrs for which this Document is the
|
|
<code>ownerDocument</code>.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- return -->
|
|
<div><b>No Parameters</b></div>
|
|
|
|
<div><b>No Exceptions</b></div>
|
|
</div>
|
|
|
|
<!-- method -->
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><b>Exception <i><a id="RangeException"
|
|
name='RangeException'>RangeException</a></i></b> introduced in <b
|
|
class='version'>DOM Level 2</b></dt>
|
|
|
|
<dd>
|
|
<p>Range operations may throw a <a
|
|
href='ranges.html#RangeException'><code>RangeException</code></a>
|
|
as specified in their method descriptions.</p>
|
|
|
|
<dl>
|
|
<dt><br />
|
|
<b>IDL Definition</b></dt>
|
|
|
|
<dd>
|
|
<div class='idl-code'>
|
|
<pre>
|
|
// Introduced in DOM Level 2:
|
|
exception RangeException {
|
|
unsigned short code;
|
|
};
|
|
// RangeExceptionCode
|
|
const unsigned short BAD_BOUNDARYPOINTS_ERR = 1;
|
|
const unsigned short INVALID_NODE_TYPE_ERR = 2;
|
|
</pre>
|
|
</div>
|
|
|
|
<br />
|
|
</dd>
|
|
|
|
<dt><b>Definition group <i><a id="RangeExceptionCode"
|
|
name='RangeExceptionCode'>RangeExceptionCode</a></i></b></dt>
|
|
|
|
<dd>
|
|
<p>An integer indicating the type of error generated.</p>
|
|
|
|
<dl>
|
|
<dt><b>Defined Constants</b></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><code class='constant-name'>BAD_BOUNDARYPOINTS_ERR</code></dt>
|
|
|
|
<dd>If the boundary-points of a Range do not meet specific
|
|
requirements.</dd>
|
|
|
|
<dt><code class='constant-name'>INVALID_NODE_TYPE_ERR</code></dt>
|
|
|
|
<dd>If the <a
|
|
href='ranges.html#td-container'><em>container</em></a> of an
|
|
boundary-point of a Range is being set to either a node of an
|
|
invalid type or a node with an ancestor of an invalid type.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
|
|
<!-- div2 Level-2-Range-Interface --></div>
|
|
|
|
<!-- div1 Range -->
|
|
<div class='navbar' align='center'>
|
|
<hr title='Navigation area separator' />
|
|
<a accesskey='p' href='traversal.html'>previous</a> <a
|
|
accesskey='n' href='idl-definitions.html'>next</a> <a
|
|
accesskey='c' href='Overview.html#contents'>contents</a> <a
|
|
accesskey='i' href='def-index.html'>index</a></div>
|
|
</body>
|
|
</html>
|
|
|