Skip to content

Commit

Permalink
HTMLOptionsCollection definition
Browse files Browse the repository at this point in the history 
git-svn-id: http://svn.whatwg.org/webapps@147 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Oct 17, 2006
1 parent 98378c9 commit 8663026
Show file tree
Hide file tree
Showing 2 changed files with 193 additions and 61 deletions.
154 changes: 110 additions & 44 deletions index
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@

<h1 id=web-applications>Web Applications 1.0</h1>

<h2 class="no-num no-toc" id=working>Working Draft &mdash; 16 October 2006</h2>
<h2 class="no-num no-toc" id=working>Working Draft &mdash; 17 October 2006</h2>

<p>You can take part in this work. <a
href="http://www.whatwg.org/mailing-list">Join the working group's
Expand Down Expand Up @@ -1459,6 +1459,11 @@ and suggestions on this to the list, btw).
element would be used as well.</p>
<!-- XXX unexpandable entities? -->

<p class=big-issue>A lot of arrays/lists/<span>collection</span>s in this
spec assume zero-based indexes but use the term "<var
title="">index</var>th" liberally. We should define those to be zero-based
and be clearer about this.

<h4 id=dependencies><span class=secno>1.3.1. </span>Dependencies</h4>

<p>This specification relies on several other underlying specifications.
Expand Down Expand Up @@ -1929,15 +1934,16 @@ and suggestions on this to the list, btw).
title=dom-HTMLCollection-length><code>length</code></dfn> attribute must
return the number of nodes <span>represented by the collection</span>.

<p>The <dfn id=itemindex
title=dom-HTMLCollection-item><code>item(<var>index</var>)</code></dfn>
method must return the <var>index</var>th node in the collection.
<p>The <dfn id=itemindex title=dom-HTMLCollection-item><code>item(<var
title="">index</var>)</code></dfn> method must return the <var
title="">index</var>th node in the collection.

<p>The <dfn id=nameditem
title=dom-HTMLCollection-namedItem><code>namedItem(<var>key</var>)</code></dfn>
method must return the first node in the collection that has either an
<code title=attr-id><a href="#id">id</a></code> attribute or a <code
title=attr-name>name</code> attribute equal to the <var>key</var>.
title=dom-HTMLCollection-namedItem><code>namedItem(<var
title="">key</var>)</code></dfn> method must return the first node in the
collection that has either an <code title=attr-id><a
href="#id">id</a></code> attribute or a <code title=attr-name>name</code>
attribute equal to the <var title="">key</var>.

<p>In the ECMAScript binding, objects implementing the <code><a
href="#htmlcollection0">HTMLCollection</a></code> interface must support
Expand Down Expand Up @@ -1968,27 +1974,31 @@ and suggestions on this to the list, btw).
collection</span>.

<p>The <dfn id=itemindex0
title=dom-HTMLFormControlsCollection-item><code>item(<var>index</var>)</code></dfn>
method must return the <var>index</var>th node in the collection.
title=dom-HTMLFormControlsCollection-item><code>item(<var
title="">index</var>)</code></dfn> method must return the <var
title="">index</var>th node in the collection.

<p>The <dfn id=nameditem0
title=dom-HTMLFormControlsCollection-namedItem><code>namedItem(<var>key</var>)</code></dfn>
method must act according to the following algorithm:
title=dom-HTMLFormControlsCollection-namedItem><code>namedItem(<var
title="">key</var>)</code></dfn> method must act according to the
following algorithm:

<ol>
<li>If, at the time the method is called, there is exactly one node in the
collection that has either an <code title=attr-id><a
href="#id">id</a></code> attribute or a <code title=attr-name>name</code>
attribute equal to <var>key</var>, then return that node and stop the
algorithm.
attribute equal to <var title="">key</var>, then return that node and
stop the algorithm.

<li>Otherwise, create a <code>NodeList</code> object representing a live
view of the <code><a
href="#htmlformcontrolscollection0">HTMLFormControlsCollection</a></code>
object, further filtered so that the only nodes in the
<code>NodeList</code> object are those that have either an <code
title=attr-id><a href="#id">id</a></code> attribute or a <code
title=attr-name>name</code> attribute equal to <var>key</var>.
title=attr-name>name</code> attribute equal to <var title="">key</var>.
The nodes in the <code>NodeList</code> object must be sorted in <a
href="#tree-order">tree order</a>.

<li>Return that <code>NodeList</code> object.
</ol>
Expand All @@ -2003,13 +2013,7 @@ and suggestions on this to the list, btw).
title=dom-HTMLFormControlsCollection-namedItem><a
href="#nameditem0">namedItem()</a></code> method with that index.</p>
<!--

namedItem() returns a new NodeList which is a filter over the
HTMLFormControlsCollection containing only elements with either id=""
or name="" equal to argument, or just an Element, if only one matches at the time of the call.

http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E...%0A%3Cform%20name%3D%22a%22%3E%3Cinput%20id%3D%22x%22%20name%3D%22y%22%3E%3Cinput%20name%3D%22x%22%20id%3D%22y%22%3E%3C/form%3E%0A%3Cscript%3E%0A%20%20var%20x%3B%0A%20%20w%28x%20%3D%20document.forms%5B%27a%27%5D%5B%27x%27%5D%29%3B%0A%20%20w%28x.length%29%3B%0A%20%20x%5B0%5D.parentNode.removeChild%28x%5B0%5D%29%3B%0A%20%20w%28x.length%29%3B%0A%20%20w%28x%20%3D%3D%20document.forms%5B%27a%27%5D%5B%27x%27%5D%29%3B%0A%3C/script%3E%0A

-->

<h5 id=htmloptionscollection><span class=secno>2.3.1.3.
Expand All @@ -2021,13 +2025,75 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..

<pre
class=idl>interface <dfn id=htmloptionscollection0>HTMLOptionsCollection</dfn> {
attribute unsigned long <span title=dom-HTMLOptionsCollection-length>length</span>;
HTMLOptionElement <span title=dom-HTMLOptionsCollection-item>item</span>(in unsigned long index);
HTMLOptionElement <span title=dom-HTMLOptionsCollection-namedItem>namedItem</span>(in DOMString name);
attribute unsigned long <a href="#length1" title=dom-HTMLOptionsCollection-length>length</a>;
HTMLOptionElement <a href="#itemindex1" title=dom-HTMLOptionsCollection-item>item</a>(in unsigned long index);
Object <a href="#nameditem1" title=dom-HTMLOptionsCollection-namedItem>namedItem</a>(in DOMString name);
};</pre>

<p class=big-issue>Need to define <code><a
href="#htmloptionscollection0">HTMLOptionsCollection</a></code>.
<p>On getting, the <dfn id=length1
title=dom-HTMLOptionsCollection-length><code>length</code></dfn> attribute
must return the number of nodes <span>represented by the
collection</span>.

<p>On setting, the behaviour depends on whether the new value is equal to,
greater than, or less than the number of nodes <span>represented by the
collection</span> at that time. If the number is the same, then setting
the attribute must do nothing. If the new value is greater, then <var
title="">n</var> new <code>option</code> elements with no attributes and
no child nodes must be appended to the <code>select</code> element on
which the <code><a
href="#htmloptionscollection0">HTMLOptionsCollection</a></code> is rooted,
where <var title="">n</var> is the difference between the two numbers (new
value minus old value). If the new value is lower, then the last <var
title="">n</var> nodes in the collection must be removed from their parent
nodes, where <var title="">n</var> is the difference between the two
numbers (old value minus new value).

<p class=note>Setting <code title=dom-HTMLOptionsCollection-length><a
href="#length1">length</a></code> never removes or adds any
<code>optgroup</code> elements, and never adds new children to existing
<code>optgroup</code> elements (though it can remove children from them).

<p>The <dfn id=itemindex1
title=dom-HTMLOptionsCollection-item><code>item(<var
title="">index</var>)</code></dfn> method must return the <var
title="">index</var>th node in the collection.

<p>The <dfn id=nameditem1
title=dom-HTMLOptionsCollection-namedItem><code>namedItem(<var
title="">key</var>)</code></dfn> method must act according to the
following algorithm:

<ol>
<li>If, at the time the method is called, there is exactly one node in the
collection that has either an <code title=attr-id><a
href="#id">id</a></code> attribute or a <code title=attr-name>name</code>
attribute equal to <var title="">key</var>, then return that node and
stop the algorithm.

<li>Otherwise, create a <code>NodeList</code> object representing a live
view of the <code><a
href="#htmloptionscollection0">HTMLOptionsCollection</a></code> object,
further filtered so that the only nodes in the <code>NodeList</code>
object are those that have either an <code title=attr-id><a
href="#id">id</a></code> attribute or a <code
title=attr-option-name>name</code> attribute equal to <var
title="">key</var>. The nodes in the <code>NodeList</code> object must be
sorted in <a href="#tree-order">tree order</a>.

<li>Return that <code>NodeList</code> object.
</ol>

<p>In the ECMAScript binding, objects implementing the <code><a
href="#htmloptionscollection0">HTMLOptionsCollection</a></code> interface
must support being dereferenced using the square bracket notation, such
that dereferencing with an integer index is equivalent to invoking the
<code title=dom-HTMLOptionsCollection-item><a
href="#itemindex1">item()</a></code> method with that index, and such that
dereferencing with a string index is equivalent to invoking the <code
title=dom-HTMLOptionsCollection-namedItem><a
href="#nameditem1">namedItem()</a></code> method with that index.</p>
<!-- see also http://ln.hixie.ch/?start=1161042744&count=1 -->

<h4 id=domtokenstring><span class=secno>2.3.2. </span>DOMTokenString</h4>

Expand Down Expand Up @@ -10317,10 +10383,10 @@ XXX selection ranges -->
depth, which would then require the selection to be infinite if every row,
including every hidden row, was selected.

<p>The <dfn id=length1
<p>The <dfn id=length2
title=dom-DataGridSelection-length><code>length</code></dfn> attribute
must return the number of rows currently present in the selection. The
<dfn id=itemindex1 title=dom-DataGridSelection-item><code>item(<var
<dfn id=itemindex2 title=dom-DataGridSelection-item><code>item(<var
title="">index</var>)</code></dfn> method must return the <var
title="">index</var>th row in the selection. If the argument is out of
range (less than zero or greater than the number of selected rows minus
Expand Down Expand Up @@ -10348,7 +10414,7 @@ XXX selection ranges -->
method must mark all the rows in the data grid as selected. After a call
to <code title=dom-DataGridSelection-selectAll><a
href="#selectall">selectAll()</a></code>, the <code
title=dom-DataGridSelection-length><a href="#length1">length</a></code>
title=dom-DataGridSelection-length><a href="#length2">length</a></code>
attribute will return the number of rows in the data grid, not counting
children of closed rows.

Expand All @@ -10362,7 +10428,7 @@ XXX selection ranges -->
mark all the rows in the data grid to be marked as not selected. After a
call to <code title=dom-DataGridSelection-clear><a
href="#clear">clear()</a></code>, the <code
title=dom-DataGridSelection-length><a href="#length1">length</a></code>
title=dom-DataGridSelection-length><a href="#length2">length</a></code>
attribute will return zero.

<p>If the <code><a href="#datagrid1">datagrid</a></code> element has a <dfn
Expand Down Expand Up @@ -12266,7 +12332,7 @@ XXX selection ranges -->
href="#history1">History</a></code> interface</h4>

<pre class=idl>interface <dfn id=history1>History</dfn> {
readonly attribute long <a href="#length2" title=dom-history-length>length</a>;
readonly attribute long <a href="#length3" title=dom-history-length>length</a>;
<!-- DOMString <span title="dom-history-item">item</span>(in unsigned long index);
readonly attribute DOMString <span title="dom-history-current">current</span>;
readonly attribute DOMString <span title="dom-history-previous">previous</span>;
Expand All @@ -12279,7 +12345,7 @@ XXX selection ranges -->
void <a href="#clearstate" title=dom-history-clearState>clearState</a>();
};</pre>

<p>The <dfn id=length2 title=dom-history-length><code>length</code></dfn>
<p>The <dfn id=length3 title=dom-history-length><code>length</code></dfn>
attribute of the <code><a href="#history1">History</a></code> interface
must return the number of entries in this session history.

Expand All @@ -12302,7 +12368,7 @@ XXX selection ranges -->

<p>If the index of the <a href="#current">current entry</a> plus <var
title="">delta</var> is less than zero or greater than or equal to the <a
href="#length2" title=dom-history-length>number of items in the session
href="#length3" title=dom-history-length>number of items in the session
history</a>, then the user agent must do nothing.

<p>If the <var title="">delta</var> is zero, then the user agent must act
Expand Down Expand Up @@ -14424,7 +14490,7 @@ http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSPr
void <a href="#clearundo" title=dom-UndoManager-clearUndo>clearUndo</a>();
void <a href="#clearredo" title=dom-UndoManager-clearRedo>clearRedo</a>();
DOMObject <a href="#itemn" title=dom-UndoManager-item>item</a>(in unsigned long index);
readonly attribute unsigned long <a href="#length3" title=dom-UndoManager-length>length</a>;
readonly attribute unsigned long <a href="#length4" title=dom-UndoManager-length>length</a>;
readonly attribute unsigned long <a href="#position0" title=dom-UndoManager-position>position</a>;
};</pre>

Expand All @@ -14448,7 +14514,7 @@ http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSPr
entries are absent from the <a href="#undo-transaction">undo transaction
history</a>.

<p>The <dfn id=length3
<p>The <dfn id=length4
title=dom-UndoManager-length><code>length</code></dfn> attribute must
return the number of <a href="#undo-object">undo object</a> entries in the
<a href="#undo-transaction">undo transaction history</a>.
Expand All @@ -14472,7 +14538,7 @@ http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSPr
nearest to the <a href="#current2">undo position</a>, on the "redo" side.
If there are no <a href="#undo-object">undo object</a> entries on the
"redo" side, then the attribute must return the same as the <code
title=dom-UndoManager-length><a href="#length3">length</a></code>
title=dom-UndoManager-length><a href="#length4">length</a></code>
attribute. If there are no <a href="#undo-object">undo object</a> entries
on the "undo" side of the <a href="#current2">undo position</a>, the <code
title=dom-UndoManager-position><a href="#position0">position</a></code>
Expand Down Expand Up @@ -14519,7 +14585,7 @@ http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSPr
href="#undo-object">undo object</a> entry with the specified <var
title="">index</var>. If the index is less than zero or greater than or
equal to <code title=dom-UndoManager-length><a
href="#length3">length</a></code> then the method must raise an
href="#length4">length</a></code> then the method must raise an
<code>INDEX_SIZE_ERR</code> exception. <a href="#dom-changes">DOM
changes</a> entries are unaffected by this method.

Expand Down Expand Up @@ -15319,7 +15385,7 @@ http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSPr

<pre class=idl>
interface <dfn id=storage1>Storage</dfn> {
readonly attribute unsigned long <a href="#length4" title=dom-Storage-length>length</a>;
readonly attribute unsigned long <a href="#length5" title=dom-Storage-length>length</a>;
DOMString <a href="#keyn" title=dom-Storage-key>key</a>(in unsigned long index);
<a href="#storageitem">StorageItem</a> <a href="#getitem" title=dom-Storage-getItem>getItem</a>(in DOMString key);
void <a href="#setitem" title=dom-Storage-setItem>setItem</a>(in DOMString key, in DOMString data);
Expand Down Expand Up @@ -15351,7 +15417,7 @@ interface <dfn id=storage1>Storage</dfn> {
the script in question is running in a <span title="secure scripting
contexts">secure scripting context</span>.

<p>The <dfn id=length4 title=dom-Storage-length><code>length</code></dfn>
<p>The <dfn id=length5 title=dom-Storage-length><code>length</code></dfn>
attribute must return the number of key/value pairs currently present and
<a href="#accessible" title="accessible keys">accessible</a> in the list
associated with the object.
Expand Down Expand Up @@ -15597,7 +15663,7 @@ interface <dfn id=storageitem>StorageItem</dfn> {
attribute</h4>

<pre class=idl>interface <dfn id=storagelist>StorageList</dfn> {
<a href="#storage1">Storage</a> <a href="#nameditem1" title=dom-Storagelist-namedItem>namedItem</a>(in DOMString domain);
<a href="#storage1">Storage</a> <a href="#nameditem2" title=dom-Storagelist-namedItem>namedItem</a>(in DOMString domain);
};</pre>

<p>The <dfn id=globalstorage
Expand All @@ -15611,7 +15677,7 @@ interface <dfn id=storageitem>StorageItem</dfn> {
href="#storagelist">StorageList</a></code> interface nor of
<code>Object</code>) must invoke the <code
title=dom-Storagelist-namedItem><a
href="#nameditem1">namedItem()</a></code> method with the property's name
href="#nameditem2">namedItem()</a></code> method with the property's name
as the argument.

<p>User agents must have a set of global storage areas, one for each
Expand All @@ -15624,7 +15690,7 @@ interface <dfn id=storageitem>StorageItem</dfn> {
potentially user-critical. It is expected that Web applications will use
the global storage areas for storing user-written documents.

<p>The <dfn id=nameditem1
<p>The <dfn id=nameditem2
title=dom-Storagelist-namedItem><code>namedItem(<var
title="">domain</var>)</code></dfn> method tries to returns a <code><a
href="#storage1">Storage</a></code> object associated with the given
Expand Down Expand Up @@ -15739,7 +15805,7 @@ interface <dfn id=storageitem>StorageItem</dfn> {
href="#sessionstorage">globalStorage</a></code> attribute's <code><a
href="#storagelist">StorageList</a></code> object's <code
title=dom-Storagelist-namedItem><a
href="#nameditem1">namedItem()</a></code> method would not raise a
href="#nameditem2">namedItem()</a></code> method would not raise a
<span>security exception</span> according to the rules above if it was
invoked with the domain <var title="">d</var>.
</ul>
Expand Down Expand Up @@ -15849,7 +15915,7 @@ interface <dfn id=storageitem>StorageItem</dfn> {
detect any concurrent script execution.

<p>This is required to guarentee that the <code title=dom-Storage-length><a
href="#length4">length</a></code> attribute of a <code><a
href="#length5">length</a></code> attribute of a <code><a
href="#storage1">Storage</a></code> object never changes while a script is
executing, other than in a way that is predictable by the script itself.

Expand Down
Loading

0 comments on commit 8663026

Please sign in to comment.