Permalink
Browse files

An introduction to "DOM Ranges".

  • Loading branch information...
1 parent 8f73159 commit 5fec971369045d7e1c7945b899760afe35909d40 @annevk annevk committed Dec 17, 2012
Showing with 147 additions and 20 deletions.
  1. +72 −9 Overview.src.html
  2. +75 −11 dom-core.html
View
@@ -8,7 +8,7 @@
[data-anolis-spec]::after { content:"[" attr(data-anolis-spec) "]"; font-size:.6em; vertical-align:super; text-transform:uppercase }
}
</style>
- <link rel=stylesheet href=//www.whatwg.org/style/specification>
+ <link rel=stylesheet href=http://www.whatwg.org/style/specification>
<link rel=icon href=//resources.whatwg.org/logo-dom.svg>
</head>
<body>
@@ -1309,25 +1309,25 @@ <h2 class=no-num>Goals</h2>
<li>
<span title=concept-document>Document</span>
<ul>
- <li class="t10"><span title=concept-doctype>Doctype:</span> <code>html</code></li>
- <li class="t1"><span title=concept-element>Element:</span> <code>html</code> <span class="t2"><code class="attribute name">class</code>="<code class="attribute value">e</code>"</span>
+ <li class="t10"><span title=concept-doctype>Doctype</span>: <code>html</code></li>
+ <li class="t1"><span title=concept-element>Element</span>: <code>html</code> <span class="t2" title><code class="attribute name">class</code>="<code class="attribute value">e</code>"</span>
<ul>
<li class="t1">
- <span title=concept-element>Element:</span> <code>head</code>
+ <span title=concept-element>Element</span>: <code>head</code>
<ul>
<li class="t1">
- <span title=concept-element>Element:</span> <code>title</code>
+ <span title=concept-element>Element</span>: <code>title</code>
<ul>
- <li class="t3"><code>Text</code>: <span>Aliens?</span></li>
+ <li class="t3"><code>Text</code>: <span title>Aliens?</span></li>
</ul>
</li>
</ul>
</li>
- <li class="t3"><code>Text</code>: <span>⏎␣</span></li>
+ <li class="t3"><code>Text</code>: <span title>⏎␣</span></li>
<li class="t1">
- <span title=concept-element>Element:</span> <code>body</code>
+ <span title=concept-element>Element</span>: <code title>body</code>
<ul>
- <li class="t3"><code>Text</code>: <span>Why yes.⏎</span></li>
+ <li class="t3"><code>Text</code>: <span title>Why yes.⏎</span></li>
</ul>
</li>
</ul>
@@ -5792,6 +5792,69 @@ <h2 class=no-num>Goals</h2>
<h2>Ranges</h2>
<!-- XXX do not call other methods but use concepts -->
+<h3>Introduction to "DOM Ranges"</h3>
+
+<p>A <code>Range</code> object (<span title=concept-range>range</span>)
+represents a sequence of content within a
+<span title=concept-node-tree>node tree</span>. Each
+<span title=concept-range>range</span> has a
+<span title=concept-range-start>start</span> and an
+<span title=concept-range-end>end</span> which are
+<span title=concept-range-bp>boundary points</span>. A
+<span title=concept-range-bp>boundary point</span> is a tuple consisting of
+a <span title=concept-node>node</span> and a non-negative numeric
+<span title=concept-range-bp-offset>offset</span>. So in other words, a
+<span title=concept-range>range</span> represents a piece of content within
+a <span title=concept-node-tree>node tree</span> between two
+<span title=concept-range-bp>boundary points</span>.
+
+<p><span title=concept-range>Ranges</span> are frequently used in editing
+for selecting and copying content.
+
+<ul class="domTree">
+ <li class="t1"><span title=concept-element>Element</span>: <code>p</code>
+ <ul>
+ <li class="t1"><span title=concept-element>Element</span>: <code>img</code> <span class="t2" title><code class="attribute name">src</code>="<code class="attribute value">insanity-wolf</code>"</span> <span class="t2" title><code class="attribute name">alt</code>="<code class="attribute value">Little-endian BOM; decode as big-endian!</code>"</span>
+ <li class="t3"><code>Text</code>: <span title>&nbsp;CSS 2.1 syndata is&nbsp;</span>
+ <li class="t1"><span title=concept-element>Element</span>: <code>em</code>
+ <ul>
+ <li class="t3"><code>Text</code>: <span title>awesome</span>
+ </ul>
+ <li class="t3"><code>Text</code>: <span title>!</span>
+ </ul>
+</ul>
+<!-- http://w3cmemes.tumblr.com/post/35332222321/css-2-1-syndata-is-awesome -->
+
+<p>In the <span title=concept-node-tree>node tree</span> above a
+<span title=concept-range>range</span> can be used to represent the sequence
+“syndata is awes”. Assuming <var title>p</var> is assigned to the
+<code>p</code> <span title=concept-element>element</span>, and
+<var title>em</var> to the <code>em</code>
+<span title=concept-element>element</span>, this would be done as follows:
+
+<pre><code>var range = document.createRange(),
+ firstText = p.childNodes[1],
+ secondText = em.firstChild
+range.setStart(firstText, 9) // do not forget the leading space
+range.setEnd(secondText, 4)
+// range now stringifies to the aforementioned quote</code></pre>
+
+<p><span title=concept-range>Ranges</span> are affected by mutations to the
+<span title=concept-node-tree>node tree</span>. Such mutations will not
+invalidate a <span title=concept-range>range</span> and will try to ensure
+that the <span title=concept-range>range</span> still represents the same
+piece of content. Necessarily, a <span title=concept-range>range</span>
+might itself be modified as part of the mutation to the
+<span title=concept-node-tree>node tree</span> when e.g. part of the content
+it represents is mutated.
+
+<p class=note>See the <span title=concept-node-insert>insert</span> and
+<span title=concept-node-remove>remove</span> algorithms, the
+<code title=concept-node-normalize>normalize()</code> method, and the
+<span title=concept-CD-replace>replace data</span> and
+<span title=concept-Text-split>split</span> algorithms for the hairy
+details.
+
<h3>Interface <code>Range</code></h3>
<pre class=idl>interface <dfn>Range</dfn> {
View
@@ -1,7 +1,7 @@
<!DOCTYPE html><html lang="en-US"><head>
<meta charset="UTF-8">
<title>DOM Standard</title>
- <link href="//www.whatwg.org/style/specification" rel="stylesheet">
+ <link href="http://www.whatwg.org/style/specification" rel="stylesheet">
<link href="//resources.whatwg.org/logo-dom.svg" rel="icon">
</head>
<body>
@@ -118,7 +118,8 @@ <h2 class="no-num no-toc" id="table-of-contents">Table of Contents</h2>
<li><a href="#interface-comment"><span class="secno">5.12 </span>Interface <code>Comment</code></a></ol></li>
<li><a href="#ranges"><span class="secno">6 </span>Ranges</a>
<ol>
- <li><a href="#interface-range"><span class="secno">6.1 </span>Interface <code>Range</code></a></ol></li>
+ <li><a href="#introduction-to-dom-ranges"><span class="secno">6.1 </span>Introduction to "DOM Ranges"</a></li>
+ <li><a href="#interface-range"><span class="secno">6.2 </span>Interface <code>Range</code></a></ol></li>
<li><a href="#traversal"><span class="secno">7 </span>Traversal</a>
<ol>
<li><a href="#interface-nodeiterator"><span class="secno">7.1 </span>Interface <code>NodeIterator</code></a></li>
@@ -1381,25 +1382,25 @@ <h3 id="introduction-to-the-dom"><span class="secno">5.1 </span>Introduction to
<li>
<a href="#concept-document" title="concept-document">Document</a>
<ul>
- <li class="t10"><a href="#concept-doctype" title="concept-doctype">Doctype:</a> <code>html</code></li>
- <li class="t1"><a href="#concept-element" title="concept-element">Element:</a> <code>html</code> <span class="t2"><code class="attribute name">class</code>="<code class="attribute value">e</code>"</span>
+ <li class="t10"><a href="#concept-doctype" title="concept-doctype">Doctype</a>: <code>html</code></li>
+ <li class="t1"><a href="#concept-element" title="concept-element">Element</a>: <code>html</code> <span class="t2" title=""><code class="attribute name">class</code>="<code class="attribute value">e</code>"</span>
<ul>
<li class="t1">
- <a href="#concept-element" title="concept-element">Element:</a> <code>head</code>
+ <a href="#concept-element" title="concept-element">Element</a>: <code>head</code>
<ul>
<li class="t1">
- <a href="#concept-element" title="concept-element">Element:</a> <code>title</code>
+ <a href="#concept-element" title="concept-element">Element</a>: <code>title</code>
<ul>
- <li class="t3"><code><a href="#text">Text</a></code>: <span>Aliens?</span></li>
+ <li class="t3"><code><a href="#text">Text</a></code>: <span title="">Aliens?</span></li>
</ul>
</li>
</ul>
</li>
- <li class="t3"><code><a href="#text">Text</a></code>: <span>⏎␣</span></li>
+ <li class="t3"><code><a href="#text">Text</a></code>: <span title="">⏎␣</span></li>
<li class="t1">
- <a href="#concept-element" title="concept-element">Element:</a> <code>body</code>
+ <a href="#concept-element" title="concept-element">Element</a>: <code title="">body</code>
<ul>
- <li class="t3"><code><a href="#text">Text</a></code>: <span>Why yes.⏎</span></li>
+ <li class="t3"><code><a href="#text">Text</a></code>: <span title="">Why yes.⏎</span></li>
</ul>
</li>
</ul>
@@ -5849,8 +5850,71 @@ <h3 id="interface-comment"><span class="secno">5.12 </span>Interface <code><a hr
<h2 id="ranges"><span class="secno">6 </span>Ranges</h2>
<!-- XXX do not call other methods but use concepts -->
+<h3 id="introduction-to-dom-ranges"><span class="secno">6.1 </span>Introduction to "DOM Ranges"</h3>
+
+<p>A <code><a href="#range">Range</a></code> object (<a href="#concept-range" title="concept-range">range</a>)
+represents a sequence of content within a
+<a href="#concept-node-tree" title="concept-node-tree">node tree</a>. Each
+<a href="#concept-range" title="concept-range">range</a> has a
+<a href="#concept-range-start" title="concept-range-start">start</a> and an
+<a href="#concept-range-end" title="concept-range-end">end</a> which are
+<a href="#concept-range-bp" title="concept-range-bp">boundary points</a>. A
+<a href="#concept-range-bp" title="concept-range-bp">boundary point</a> is a tuple consisting of
+a <a href="#concept-node" title="concept-node">node</a> and a non-negative numeric
+<a href="#concept-range-bp-offset" title="concept-range-bp-offset">offset</a>. So in other words, a
+<a href="#concept-range" title="concept-range">range</a> represents a piece of content within
+a <a href="#concept-node-tree" title="concept-node-tree">node tree</a> between two
+<a href="#concept-range-bp" title="concept-range-bp">boundary points</a>.
+
+<p><a href="#concept-range" title="concept-range">Ranges</a> are frequently used in editing
+for selecting and copying content.
-<h3 id="interface-range"><span class="secno">6.1 </span>Interface <code><a href="#range">Range</a></code></h3>
+<ul class="domTree">
+ <li class="t1"><a href="#concept-element" title="concept-element">Element</a>: <code>p</code>
+ <ul>
+ <li class="t1"><a href="#concept-element" title="concept-element">Element</a>: <code>img</code> <span class="t2" title=""><code class="attribute name">src</code>="<code class="attribute value">insanity-wolf</code>"</span> <span class="t2" title=""><code class="attribute name">alt</code>="<code class="attribute value">Little-endian BOM; decode as big-endian!</code>"</span>
+ <li class="t3"><code><a href="#text">Text</a></code>: <span title=""> CSS 2.1 syndata is </span>
+ <li class="t1"><a href="#concept-element" title="concept-element">Element</a>: <code>em</code>
+ <ul>
+ <li class="t3"><code><a href="#text">Text</a></code>: <span title="">awesome</span>
+ </ul>
+ <li class="t3"><code><a href="#text">Text</a></code>: <span title="">!</span>
+ </ul>
+</ul>
+<!-- http://w3cmemes.tumblr.com/post/35332222321/css-2-1-syndata-is-awesome -->
+
+<p>In the <a href="#concept-node-tree" title="concept-node-tree">node tree</a> above a
+<a href="#concept-range" title="concept-range">range</a> can be used to represent the sequence
+“syndata is awes”. Assuming <var title="">p</var> is assigned to the
+<code>p</code> <a href="#concept-element" title="concept-element">element</a>, and
+<var title="">em</var> to the <code>em</code>
+<a href="#concept-element" title="concept-element">element</a>, this would be done as follows:
+
+<pre><code>var range = document.createRange(),
+ firstText = p.childNodes[1],
+ secondText = em.firstChild
+range.setStart(firstText, 9) // do not forget the leading space
+range.setEnd(secondText, 4)
+// range now stringifies to the aforementioned quote</code></pre>
+
+<p><a href="#concept-range" title="concept-range">Ranges</a> are affected by mutations to the
+<a href="#concept-node-tree" title="concept-node-tree">node tree</a>. Such mutations will not
+invalidate a <a href="#concept-range" title="concept-range">range</a> and will try to ensure
+that the <a href="#concept-range" title="concept-range">range</a> still represents the same
+piece of content. Necessarily, a <a href="#concept-range" title="concept-range">range</a>
+might itself be modified as part of the mutation to the
+<a href="#concept-node-tree" title="concept-node-tree">node tree</a> when e.g. part of the content
+it represents is mutated.
+
+<p class="note">See the <a href="#concept-node-insert" title="concept-node-insert">insert</a> and
+<a href="#concept-node-remove" title="concept-node-remove">remove</a> algorithms, the
+<code title="concept-node-normalize">normalize()</code> method, and the
+<a href="#concept-cd-replace" title="concept-CD-replace">replace data</a> and
+<a href="#concept-text-split" title="concept-Text-split">split</a> algorithms for the hairy
+details.
+
+
+<h3 id="interface-range"><span class="secno">6.2 </span>Interface <code><a href="#range">Range</a></code></h3>
<pre class="idl">interface <dfn id="range">Range</dfn> {
readonly attribute <a href="#node">Node</a> <a href="#dom-range-startcontainer" title="dom-Range-startContainer">startContainer</a>;
readonly attribute unsigned long <a href="#dom-range-startoffset" title="dom-Range-startOffset">startOffset</a>;

0 comments on commit 5fec971

Please sign in to comment.