- From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
- Date: Sun, 01 Feb 2009 08:59:34 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv6676
Modified Files:
Overview.html
Log Message:
Mark <datagrid> as broken for now. (whatwg r2733)
Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.1902
retrieving revision 1.1903
diff -u -d -r1.1902 -r1.1903
--- Overview.html 1 Feb 2009 08:53:52 -0000 1.1902
+++ Overview.html 1 Feb 2009 08:59:32 -0000 1.1903
@@ -2,8 +2,10 @@
.note { color: green; background: transparent; }
.example { font-style: italic; }
.idl { color: black; background: silver; }
- .issue, .big-issue { color: red; background: transparent; }
+ .XXX { color: red; background: transparent; }
.warning { color: yellow; background: maroon; }
+ .bad { color: gray; }
+ .bad.XXX { color: red; }
</style><link href=http://www.w3.org/StyleSheets/TR/%57%33%43-ED rel=stylesheet type=text/css><!-- ZZZ ED vs WD --><div class=head>
<p><a href=http://www.w3.org/><img alt=W3C height=48 src=http://www.w3.org/Icons/w3c_home width=72></a></p>
<h1>HTML 5</h1>
@@ -24673,7 +24675,12 @@
or some such.</p><!--
Example ideas:
http://mail.gnome.org/archives/usability/2006-June/msg00015.html
---><h4 id=datagrid><span class=secno>4.11.2 </span>The <dfn><code>datagrid</code></dfn> element</h4><dl class=element><dt>Categories</dt>
+--><div class=bad>
+ <h4 id=datagrid><span class=secno>4.11.2 </span>The <dfn><code>datagrid</code></dfn> element</h4>
+
+<p class=XXX>The API here needs rewriting. Don't implement this right now.</p>
+
+ <dl class=element><dt>Categories</dt>
<dd><a href=#flow-content-0>Flow content</a>.</dd>
<dd><a href=#interactive-content-0>Interactive content</a>.</dd>
<dd><a href=#sectioning-root>Sectioning root</a>.</dd>
@@ -24707,57 +24714,107 @@
</dd>
</dl><p class=XXX>One possible thing to be added is a way to
detect when a row/selection has been deleted, activated, etc, by the
- user (delete key, enter key, etc).</p><!-- XXXPA --><p>The <code><a href=#datagrid>datagrid</a></code> element represents an interactive
- representation of tree, list, or tabular data.<p>The data being presented can come either from the content, as
+ user (delete key, enter key, etc).</p> <!-- XXXPA -->
+
+ <p>The <code><a href=#datagrid>datagrid</a></code> element represents an interactive
+ representation of tree, list, or tabular data.</p>
+
+ <p>The data being presented can come either from the content, as
elements given as children of the <code><a href=#datagrid>datagrid</a></code> element, or
- from a scripted data provider given by the <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code> DOM attribute.<p>The <code title=attr-datagrid-multiple><a href=#attr-datagrid-multiple>multiple</a></code> and
+ from a scripted data provider given by the <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code> DOM attribute.</p>
+
+ <p>The <code title=attr-datagrid-multiple><a href=#attr-datagrid-multiple>multiple</a></code> and
<code title=attr-datagrid-disabled><a href=#attr-datagrid-disabled>disabled</a></code> attributes are
<a href=#boolean-attribute title="boolean attribute">boolean attributes</a>. Their
- effects are described in the processing model sections below.<p>The <dfn id=dom-datagrid-multiple title=dom-datagrid-multiple><code>multiple</code></dfn> and <dfn id=dom-datagrid-disabled title=dom-datagrid-disabled><code>disabled</code></dfn> DOM
+ effects are described in the processing model sections below.</p>
+
+ <p>The <dfn id=dom-datagrid-multiple title=dom-datagrid-multiple><code>multiple</code></dfn> and <dfn id=dom-datagrid-disabled title=dom-datagrid-disabled><code>disabled</code></dfn> DOM
attributes must <a href=#reflect>reflect</a> the <code title=attr-datagrid-multiple><a href=#attr-datagrid-multiple>multiple</a></code> and <code title=attr-datagrid-disabled><a href=#attr-datagrid-disabled>disabled</a></code> content attributes
- respectively.<h5 id=the-datagrid-data-model><span class=secno>4.11.2.1 </span>The <code><a href=#datagrid>datagrid</a></code> data model</h5><p><em>This section is non-normative.</em><p>In the <code><a href=#datagrid>datagrid</a></code> data model, data is structured as a
+ respectively.</p>
+
+
+ <h5 id=the-datagrid-data-model><span class=secno>4.11.2.1 </span>The <code><a href=#datagrid>datagrid</a></code> data model</h5>
+
+ <p><em>This section is non-normative.</em></p>
+
+ <p>In the <code><a href=#datagrid>datagrid</a></code> data model, data is structured as a
set of rows representing a tree, each row being split into a number
of columns. The columns are always present in the data model,
- although individual columns may be hidden in the presentation.<p>Each row can have child rows. Child rows may be hidden or
- shown, by closing or opening (respectively) the parent row.<p>Rows are referred to by the path along the tree that one would
+ although individual columns may be hidden in the presentation.</p>
+
+ <p>Each row can have child rows. Child rows may be hidden or
+ shown, by closing or opening (respectively) the parent row.</p>
+
+ <p>Rows are referred to by the path along the tree that one would
take to reach the row, using zero-based indices. Thus, the first row
of a list is row "0", the second row is row "1"; the first child row
of the first row is row "0,0", the second child row of the first row
is row "0,1"; the fourth child of the seventh child of the third
- child of the tenth row is "9,2,6,3", etc.<p>The columns can have captions. Those captions are not considered
- a row in their own right, they are obtained separately.<p>Selection of data in a <code><a href=#datagrid>datagrid</a></code> operates at the row
+ child of the tenth row is "9,2,6,3", etc.</p>
+
+ <p>The columns can have captions. Those captions are not considered
+ a row in their own right, they are obtained separately.</p>
+
+ <p>Selection of data in a <code><a href=#datagrid>datagrid</a></code> operates at the row
level. If the <code title=attr-datagrid-multiple><a href=#attr-datagrid-multiple>multiple</a></code>
attribute is present, multiple rows can be selected at once,
- otherwise the user can only select one row at a time.<p>The <code><a href=#datagrid>datagrid</a></code> element can be disabled entirely by
+ otherwise the user can only select one row at a time.</p>
+
+ <p>The <code><a href=#datagrid>datagrid</a></code> element can be disabled entirely by
setting the <code title=attr-datagrid-disabled><a href=#attr-datagrid-disabled>disabled</a></code>
- attribute.</p><!--XXXDND
+ attribute.</p>
+<!--XXXDND
<p class="XXX">selection draggable [normative definitions are
in the interactive part below]</p>
---><p>Columns, rows, and cells can each have specific flags, known as
+-->
+
+ <p>Columns, rows, and cells can each have specific flags, known as
classes, applied to them by the data provider. These classes <a href=#datagridClassSummary>affect the functionality</a> of the
<code><a href=#datagrid>datagrid</a></code> element, and are also <a href=#datagridPseudos>passed to the style system</a>. They are
similar in concept to the <code title=attr-class><a href=#classes>class</a></code>
attribute, except that they are not specified on elements but are
- given by scripted data providers.</p><!-- XXX check xrefs --><h5 id=how-rows-are-identified><span class=secno>4.11.2.2 </span>How rows are identified</h5><p>The chains of numbers that give a row's path, or identifier, are
+ given by scripted data providers.</p> <!-- XXX check xrefs -->
+
+
+ <h5 id=how-rows-are-identified><span class=secno>4.11.2.2 </span>How rows are identified</h5>
+
+ <p>The chains of numbers that give a row's path, or identifier, are
represented by objects that implement the
- <a href=#rowspecification>RowSpecification</a> interface.<pre class=idl>[NoInterfaceObject] interface <dfn id=rowspecification>RowSpecification</dfn> {
+ <a href=#rowspecification>RowSpecification</a> interface.</p>
+
+ <pre class=idl>[NoInterfaceObject] interface <dfn id=rowspecification>RowSpecification</dfn> {
// binding-specific interface
-};</pre><p>In ECMAScript, two classes of objects are said to implement this
+};</pre>
+
+ <p>In ECMAScript, two classes of objects are said to implement this
interface: Numbers representing non-negative integers, and
homogeneous arrays of Numbers representing non-negative
integers. Thus, <code>[1,0,9]</code> is a
<a href=#rowspecification>RowSpecification</a>, as is <code>1</code> on its
own. However, <code>[1,0.2,9]</code> is not a
<a href=#rowspecification>RowSpecification</a> object, since its second value is not
- an integer.<p>User agents must always represent <code><a href=#rowspecification>RowSpecification</a></code>s
+ an integer.</p>
+
+ <p>User agents must always represent <code><a href=#rowspecification>RowSpecification</a></code>s
in ECMAScript by using arrays, even if the path only has one
- number.<p>The root of the tree is represented by the empty path; in
+ number.</p>
+
+ <p>The root of the tree is represented by the empty path; in
ECMAScript, this is the empty array (<code>[]</code>). Only the
<code title=dom-provider-getRowCount><a href=#dom-provider-getrowcount>getRowCount()</a></code> and
<code title=dom-provider-getChildAtPosition><a href=#dom-provider-getchildatposition>GetChildAtPosition()</a></code>
- methods ever get called with the empty path.<h5 id=the-data-provider-interface><span class=secno>4.11.2.3 </span>The data provider interface</h5><p><em>The conformance criteria in this section apply to any
+ methods ever get called with the empty path.</p>
+
+
+ <h5 id=the-data-provider-interface><span class=secno>4.11.2.3 </span>The data provider interface</h5>
+
+ <p><em>The conformance criteria in this section apply to any
implementation of the <code><a href=#datagriddataprovider>DataGridDataProvider</a></code>, including
- (and most commonly) the content author's implementation(s).</em><pre class=idl>// To be implemented by Web authors as a JS object
+ (and most commonly) the content author's implementation(s).</em></p>
+
+<p class=XXX>The API here needs rewriting. Don't implement this right now.</p>
+
+ <pre class=idl>// To be implemented by Web authors as a JS object
[NoInterfaceObject] interface <dfn id=datagriddataprovider>DataGridDataProvider</dfn> {
void <a href=#dom-provider-initialize title=dom-provider-initialize>initialize</a>(in <a href=#htmldatagridelement>HTMLDataGridElement</a> datagrid);
unsigned long <a href=#dom-provider-getrowcount title=dom-provider-getRowCount>getRowCount</a>(in <a href=#rowspecification>RowSpecification</a> row);
@@ -24781,11 +24838,22 @@
void <span title="dom-provider-performAction">performAction</span>(in DOMString action); // required if .performAction() is ever invoked on the datagrid
void <span title="dom-provider-performActionOnRow">performActionOnRow</span>(in <span>RowSpecification</span> row, in DOMString action); // required if getRowClasses ever includes 'deletable' or if <span title="dom-provider-.performActionOnRow">.performActionOnRow</span>() is ever invoked on the datagrid
void <span title="dom-provider-performActionOnCell">performActionOnCell</span>(in <span>RowSpecification</span> row, in unsigned long column, in DOMString action); // required if .performActionOnCell() is ever invoked on the datagrid
--->};</pre><!-- based on http://lxr.mozilla.org/seamonkey/source/layout/xul/base/src/tree/public/nsITreeView.idl --><p>The <code><a href=#datagriddataprovider>DataGridDataProvider</a></code> interface represents the
+-->};</pre>
+<!-- based on http://lxr.mozilla.org/seamonkey/source/layout/xul/base/src/tree/public/nsITreeView.idl -->
+
+ <p>The <code><a href=#datagriddataprovider>DataGridDataProvider</a></code> interface represents the
interface that objects must implement to be used as custom data
- views for <code><a href=#datagrid>datagrid</a></code> elements.<p>Not all the methods are required. The minimum number of methods
- that must be implemented in a useful view is two: the <code title=dom-provider-getRowCount><a href=#dom-provider-getrowcount>getRowCount()</a></code> and <code title=dom-provider-getCellData><a href=#dom-provider-getcelldata>getCellData()</a></code> methods.<p>Once the object is written, it must be hooked up to the
- <code><a href=#datagrid>datagrid</a></code> using the <dfn id=dom-datagrid-data title=dom-datagrid-data><code>data</code></dfn> DOM attribute.<p>The following methods may be usefully implemented:<dl><dt><dfn id=dom-provider-initialize title=dom-provider-initialize><code>initialize(<var title="">datagrid</var>)</code></dfn></dt>
+ views for <code><a href=#datagrid>datagrid</a></code> elements.</p>
+
+ <p>Not all the methods are required. The minimum number of methods
+ that must be implemented in a useful view is two: the <code title=dom-provider-getRowCount><a href=#dom-provider-getrowcount>getRowCount()</a></code> and <code title=dom-provider-getCellData><a href=#dom-provider-getcelldata>getCellData()</a></code> methods.</p>
+
+ <p>Once the object is written, it must be hooked up to the
+ <code><a href=#datagrid>datagrid</a></code> using the <dfn id=dom-datagrid-data title=dom-datagrid-data><code>data</code></dfn> DOM attribute.</p>
+
+ <p>The following methods may be usefully implemented:</p>
+
+ <dl><dt><dfn id=dom-provider-initialize title=dom-provider-initialize><code>initialize(<var title="">datagrid</var>)</code></dfn></dt>
<dd>Called by the <code><a href=#datagrid>datagrid</a></code> element (the one given by
the <var title="">datagrid</var> argument) after it has first
@@ -24945,7 +25013,9 @@
-->
</dl><p>The following classes (for rows, columns, and cells) may be
- usefully used in conjunction with this interface:<table id=datagridClassSummary><tr><th>Class name</th>
+ usefully used in conjunction with this interface:</p>
+
+ <table id=datagridClassSummary><tr><th>Class name</th>
<th>Applies to</th>
<th>Description</th>
<tr><td><!--checked--><dfn id=datagrid-cell-class-checked title=datagrid-cell-class-checked><code>checked</code></dfn></td>
@@ -25023,10 +25093,16 @@
<td>Rows</td>
<td></td>
</tr>
---></table><h5 id=the-default-data-provider><span class=secno>4.11.2.4 </span>The default data provider</h5><p>The user agent must supply a default data provider for the case
+--></table><h5 id=the-default-data-provider><span class=secno>4.11.2.4 </span>The default data provider</h5>
+
+ <p>The user agent must supply a default data provider for the case
where the <code><a href=#datagrid>datagrid</a></code>'s <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code> attribute is null. It must act
- as described in this section.<p>The behavior of the default data provider depends on the nature
- of the first element child of the <code><a href=#datagrid>datagrid</a></code>.<dl class=switch><!-- XXX some of these entries say "the method must return" and
+ as described in this section.</p>
+
+ <p>The behavior of the default data provider depends on the nature
+ of the first element child of the <code><a href=#datagrid>datagrid</a></code>.</p>
+
+ <dl class=switch><!-- XXX some of these entries say "the method must return" and
other say "the characteristic must be"; this should be rationalized
--><dt>While the first element child is a <code><a href=#the-table-element>table</a></code> element</dt>
@@ -25433,12 +25509,16 @@
</dd>
</dl><h6 id=commonDefaultDataGridMethodDefinitions><span class=secno>4.11.2.4.1 </span>Common default data
- provider method definitions for cells</h6><p>These definitions are used for the cell-specific methods of the
+ provider method definitions for cells</h6>
+
+ <p>These definitions are used for the cell-specific methods of the
default data providers (other than in the
<code><a href=#the-select-element>select</a></code>/<code><a href=#the-datalist-element>datalist</a></code> case). How they behave is
based on the contents of an element that represents the cell given
by their first two arguments. Which element that is is defined in
- the previous section.<dl><dt>Cyclable cells</dt>
+ the previous section.</p>
+
+ <dl><dt>Cyclable cells</dt>
<dd>
@@ -25552,7 +25632,9 @@
</dd>
- </dl><!-- XXX Calculated cells, like in spreadsheets? --><h5 id=populating-the-datagrid-element><span class=secno>4.11.2.5 </span>Populating the <code><a href=#datagrid>datagrid</a></code> element</h5><p>A <code><a href=#datagrid>datagrid</a></code> must be disabled until its end tag has
+ </dl><!-- XXX Calculated cells, like in spreadsheets? --><h5 id=populating-the-datagrid-element><span class=secno>4.11.2.5 </span>Populating the <code><a href=#datagrid>datagrid</a></code> element</h5>
+
+ <p>A <code><a href=#datagrid>datagrid</a></code> must be disabled until its end tag has
been parsed<!-- XXX do we define that? what if the end tag is never
seen, but the element is popped off the stack?--> (in the case of a
<code><a href=#datagrid>datagrid</a></code> element in the original document markup) or
@@ -25560,16 +25642,26 @@
document">inserted into the document</a> (in the case of a
dynamically created element). After that point, the element must
fire a single <code title=event-load><a href=#event-load>load</a></code> event at itself,
- which doesn't bubble and cannot be canceled.<p class=XXX>The end-tag parsing thing should be moved to
- the parsing section.<p>The <code><a href=#datagrid>datagrid</a></code> must then populate itself using the
+ which doesn't bubble and cannot be canceled.</p>
+
+ <p class=XXX>The end-tag parsing thing should be moved to
+ the parsing section.</p>
+
+ <p>The <code><a href=#datagrid>datagrid</a></code> must then populate itself using the
data provided by the data provider assigned to the <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code> DOM attribute. After the view
is populated (using the methods described below), the
<code><a href=#datagrid>datagrid</a></code> must invoke the <code title=dom-provider-initialize><a href=#dom-provider-initialize>initialize()</a></code> method on the
data provider specified by the <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code> attribute, passing itself (the
- <code><a href=#htmldatagridelement>HTMLDataGridElement</a></code> object) as the only argument.<p>When the <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code> attribute is
+ <code><a href=#htmldatagridelement>HTMLDataGridElement</a></code> object) as the only argument.</p>
+
+ <p>When the <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code> attribute is
null, the <code><a href=#datagrid>datagrid</a></code> must use the default data provider
- described in the previous section.<p>To obtain data from the data provider, the element must invoke
- methods on the data provider object in the following ways:<dl><dt>To determine the total number of columns</dt>
+ described in the previous section.</p>
+
+ <p>To obtain data from the data provider, the element must invoke
+ methods on the data provider object in the following ways:</p>
+
+ <dl><dt>To determine the total number of columns</dt>
<dd>Invoke the <code title=dom-provider-getColumnCount><a href=#dom-provider-getcolumncount>getColumnCount()</a></code> method
with no arguments. The return value is the number of columns. If
@@ -25880,7 +25972,9 @@
</dl><p>If the data provider ever raises an exception while the
<code><a href=#datagrid>datagrid</a></code> is invoking one of its methods, the
<code><a href=#datagrid>datagrid</a></code> must act, for the purposes of that particular
- method call, as if the relevant method had not been defined.<p>A <code><a href=#rowspecification>RowSpecification</a></code> object <var title="">p</var> with
+ method call, as if the relevant method had not been defined.</p>
+
+ <p>A <code><a href=#rowspecification>RowSpecification</a></code> object <var title="">p</var> with
<var title="">n</var> path components passed to a method of the data
provider must fulfill the constraint <span>0 ≤ <var title="">p<sub title=""><var title="">i</var></sub></var> < <var title="">m</var>-1</span> for all integer values of <var title="">i</var> in the range <span>0 ≤ <var title="">i</var> < <var title="">n</var>-1</span>,
where <var title="">m</var> is the value that was last returned by
@@ -25890,7 +25984,9 @@
items, where <span><var title="">p<sub title=""><var title="">i</var></sub></var> = <var title="">q<sub title=""><var title="">i</var></sub></var></span> for all integer
values of <var title="">i</var> in the range
<span>0 ≤ <var title="">i</var> < <var title="">n</var>-1</span>, with any changes implied by the update
- methods taken into account.<p id=inconsistentDataProvider>The data model is considered
+ methods taken into account.</p>
+
+ <p id=inconsistentDataProvider>The data model is considered
stable: user agents may assume that subsequent calls to the data
provider methods will return the same data, until one of the update
methods is called on the <code><a href=#datagrid>datagrid</a></code> element. If a user
@@ -25899,62 +25995,102 @@
that do not match the calls made to the update methods, the user
agent may disable the <code><a href=#datagrid>datagrid</a></code>. User agents that do not
disable the <code><a href=#datagrid>datagrid</a></code> in inconsistent cases must honor
- the most recently returned values.<p>User agents may cache returned values so that the data provider
+ the most recently returned values.</p>
+
+ <p>User agents may cache returned values so that the data provider
is never asked for data that could contradict earlier data. User
- agents must not cache the return value of the <code title=dom-provider-getRowMenu><a href=#dom-provider-getrowmenu>getRowMenu</a></code> method.<p>The exact algorithm used to populate the data grid is not defined
+ agents must not cache the return value of the <code title=dom-provider-getRowMenu><a href=#dom-provider-getrowmenu>getRowMenu</a></code> method.</p>
+
+ <p>The exact algorithm used to populate the data grid is not defined
here, since it will differ based on the presentation used. However,
the behavior of user agents must be consistent with the
descriptions above. For example, it would be non-conformant for a
user agent to make cells have both a checkbox and be editable, as
the descriptions above state that cells that have a checkbox cannot
- be edited.</p><!-- XXX speaking of which, do we actually want that
- limitation? --><h5 id=updating-the-datagrid><span class=secno>4.11.2.6 </span>Updating the <code><a href=#datagrid>datagrid</a></code></h5><p>Whenever the <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code>
+ be edited.</p> <!-- XXX speaking of which, do we actually want that
+ limitation? -->
+
+
+ <h5 id=updating-the-datagrid><span class=secno>4.11.2.6 </span>Updating the <code><a href=#datagrid>datagrid</a></code></h5>
+
+ <p>Whenever the <code title=dom-datagrid-data><a href=#dom-datagrid-data>data</a></code>
attribute is set to a new value, the <code><a href=#datagrid>datagrid</a></code> must
clear the current selection, remove all the displayed rows, and plan
to repopulate itself using the information from the new data
- provider at the earliest opportunity.<p>There are a number of update methods that can be invoked on the
+ provider at the earliest opportunity.</p>
+
+ <p>There are a number of update methods that can be invoked on the
<code><a href=#datagrid>datagrid</a></code> element to cause it to refresh itself in
- slightly less drastic ways:<p>When the <dfn id=dom-datagrid-updateeverything title=dom-datagrid-updateEverything><code>updateEverything()</code></dfn>
+ slightly less drastic ways:</p>
+
+ <p>When the <dfn id=dom-datagrid-updateeverything title=dom-datagrid-updateEverything><code>updateEverything()</code></dfn>
method is called, the user agent must repopulate the entire
<code><a href=#datagrid>datagrid</a></code>. If the number of rows decreased, the
selection must be updated appropriately. If the number of rows
- increased, the new rows should be left unselected.<p>When the <dfn id=dom-datagrid-updaterowschanged title=dom-datagrid-updateRowsChanged><code>updateRowsChanged(<var title="">row</var>, <var title="">count</var>)</code></dfn> method
+ increased, the new rows should be left unselected.</p>
+
+ <p>When the <dfn id=dom-datagrid-updaterowschanged title=dom-datagrid-updateRowsChanged><code>updateRowsChanged(<var title="">row</var>, <var title="">count</var>)</code></dfn> method
is called, the user agent must refresh the rendering of the rows
starting from the row specified by <var title="">row</var>, and
including the <var title="">count</var> next siblings of the row (or
- as many next siblings as it has, if that is less than <var title="">count</var>), including all descendant rows.<p>When the <dfn id=dom-datagrid-updaterowsinserted title=dom-datagrid-updateRowsInserted><code>updateRowsInserted(<var title="">row</var>, <var title="">count</var>)</code></dfn> method
+ as many next siblings as it has, if that is less than <var title="">count</var>), including all descendant rows.</p>
+
+ <p>When the <dfn id=dom-datagrid-updaterowsinserted title=dom-datagrid-updateRowsInserted><code>updateRowsInserted(<var title="">row</var>, <var title="">count</var>)</code></dfn> method
is called, the user agent must assume that <var title="">count</var>
new rows have been inserted, such that the first new row is
identified by <var title="">row</var>. The user agent must update
its rendering and the selection accordingly. The new rows should not
- be selected.<p>When the <dfn id=dom-datagrid-updaterowsremoved title=dom-datagrid-updateRowsRemoved><code>updateRowsRemoved(<var title="">row</var>, <var title="">count</var>)</code></dfn> method
+ be selected.</p>
+
+ <p>When the <dfn id=dom-datagrid-updaterowsremoved title=dom-datagrid-updateRowsRemoved><code>updateRowsRemoved(<var title="">row</var>, <var title="">count</var>)</code></dfn> method
is called, the user agent must assume that <var title="">count</var>
rows have been removed starting from the row that used to be
identifier by <var title="">row</var>. The user agent must update
- its rendering and the selection accordingly.<p>The <dfn id=dom-datagrid-updaterowchanged title=dom-datagrid-updateRowChanged><code>updateRowChanged(<var title="">row</var>)</code></dfn> method must be exactly equivalent
- to calling <code title=dom-datagrid-updateRowsChanged><a href=#dom-datagrid-updaterowschanged>updateRowsChanged(<var title="">row</var>, 1)</a></code>.<p>When the <dfn id=dom-datagrid-updatecolumnchanged title=dom-datagrid-updateColumnChanged><code>updateColumnChanged(<var title="">column</var>)</code></dfn> method is called, the user agent
- must refresh the rendering of the specified column <var title="">column</var>, for all rows.<p>When the <dfn id=dom-datagrid-updatecellchanged title=dom-datagrid-updateCellChanged><code>updateCellChanged(<var title="">row</var>, <var title="">column</var>)</code></dfn> method
+ its rendering and the selection accordingly.</p>
+
+ <p>The <dfn id=dom-datagrid-updaterowchanged title=dom-datagrid-updateRowChanged><code>updateRowChanged(<var title="">row</var>)</code></dfn> method must be exactly equivalent
+ to calling <code title=dom-datagrid-updateRowsChanged><a href=#dom-datagrid-updaterowschanged>updateRowsChanged(<var title="">row</var>, 1)</a></code>.</p>
+
+ <p>When the <dfn id=dom-datagrid-updatecolumnchanged title=dom-datagrid-updateColumnChanged><code>updateColumnChanged(<var title="">column</var>)</code></dfn> method is called, the user agent
+ must refresh the rendering of the specified column <var title="">column</var>, for all rows.</p>
+
+ <p>When the <dfn id=dom-datagrid-updatecellchanged title=dom-datagrid-updateCellChanged><code>updateCellChanged(<var title="">row</var>, <var title="">column</var>)</code></dfn> method
is called, the user agent must refresh the rendering of the cell on
- row <var title="">row</var>, in column <var title="">column</var>.<p>Any effects the update methods have on the
+ row <var title="">row</var>, in column <var title="">column</var>.</p>
+
+ <p>Any effects the update methods have on the
<code><a href=#datagrid>datagrid</a></code>'s selection is not considered a change to the
- selection, and must therefore not fire the <code title=event-select><a href=#event-select>select</a></code> event.<p>These update methods should be called only by the data provider,
+ selection, and must therefore not fire the <code title=event-select><a href=#event-select>select</a></code> event.</p>
+
+ <p>These update methods should be called only by the data provider,
or code acting on behalf of the data provider. In particular,
calling the <code title=dom-datagrid-updateRowsInserted><a href=#dom-datagrid-updaterowsinserted>updateRowsInserted()</a></code>
and <code title=dom-datagrid-updateRowsRemoved><a href=#dom-datagrid-updaterowsremoved>updateRowsRemoved()</a></code>
methods without actually inserting or removing rows from the data
provider is <a href=#inconsistentDataProvider>likely to result in
inconsistent renderings</a>, and the user agent is likely to disable
- the data grid.<h5 id=requirements-for-interactive-user-agents><span class=secno>4.11.2.7 </span>Requirements for interactive user agents</h5><p><em>This section only applies to interactive user agents.</em><p>If the <code><a href=#datagrid>datagrid</a></code> element has a <dfn id=attr-datagrid-disabled title=attr-datagrid-disabled><code>disabled</code></dfn>
+ the data grid.</p>
+
+
+ <h5 id=requirements-for-interactive-user-agents><span class=secno>4.11.2.7 </span>Requirements for interactive user agents</h5>
+
+ <p><em>This section only applies to interactive user agents.</em></p>
+
+ <p>If the <code><a href=#datagrid>datagrid</a></code> element has a <dfn id=attr-datagrid-disabled title=attr-datagrid-disabled><code>disabled</code></dfn>
attribute, then the user agent must disable the
<code><a href=#datagrid>datagrid</a></code>, preventing the user from interacting with it.
The <code><a href=#datagrid>datagrid</a></code> element should still continue to update
itself when the data provider signals changes to the data, though.
Obviously, conformance requirements stating that
<code><a href=#datagrid>datagrid</a></code> elements must react to users in particular
- ways do not apply when one is disabled.<p>If <a href=#rowType1>a row is openable</a>, then the user agent
+ ways do not apply when one is disabled.</p>
+
+ <p>If <a href=#rowType1>a row is openable</a>, then the user agent
should offer to the user the option of toggling the row's
open/closed state. When a row's open/closed state changes, the user
- agent must update the rendering to match the new state.<p>If a cell is a cell whose value <a href=#cellType1>can be
+ agent must update the rendering to match the new state.</p>
+
+ <p>If a cell is a cell whose value <a href=#cellType1>can be
cycled between multiple states</a>, then the user agent should allow
the user to activate the cell to cycle its value. When the user
activates this "cycling" behavior of a cell, then the
@@ -25963,7 +26099,9 @@
the first argument and the cell's column index as the second. The
<code><a href=#datagrid>datagrid</a></code> must then act as if the
<code><a href=#datagrid>datagrid</a></code>'s <code title=dom-datagrid-updateCellChanged><a href=#dom-datagrid-updatecellchanged>updateCellChanged()</a></code>
- method had been invoked with those same arguments.<p>When a cell <a href=#cellType2>has a checkbox</a>, the user
+ method had been invoked with those same arguments.</p>
+
+ <p>When a cell <a href=#cellType2>has a checkbox</a>, the user
agent should allow the user to set the checkbox's state. When the
user changes the state of a checkbox in such a cell, the
<code><a href=#datagrid>datagrid</a></code> must invoke the data provider's <code title=dom-provider-setCellCheckedState><a href=#dom-provider-setcellcheckedstate>setCellCheckedState()</a></code>
@@ -25975,16 +26113,26 @@
indeterminate (which must be possible only if the cell has the <code title=datagrid-cell-class-indeterminate><a href=#datagrid-cell-class-indeterminate>indeterminate</a></code> class
set). The <code><a href=#datagrid>datagrid</a></code> must then act as if the
<code><a href=#datagrid>datagrid</a></code>'s <code title=dom-datagrid-updateCellChanged><a href=#dom-datagrid-updatecellchanged>updateCellChanged()</a></code>
- method had been invoked, specifying the same cell.<p>If a cell <a href=#cellType2>is editable</a>, the user agent
+ method had been invoked, specifying the same cell.</p>
+
+ <p>If a cell <a href=#cellType2>is editable</a>, the user agent
should allow the user to edit the data for that cell, and doing so
must cause the user agent to invoke the <code title=dom-provider-editCell><a href=#dom-provider-editcell>editCell()</a></code> method of the data
provider with three arguments: a <code><a href=#rowspecification>RowSpecification</a></code>
object representing the cell's row, the cell's column's index, and
the new text entered by the user. The user agent must then act as if
the <code title=dom-datagrid-updateCellChanged><a href=#dom-datagrid-updatecellchanged>updateCellChanged()</a></code>
- method had been invoked, with the same row and column specified.</p><!-- XXXPA <p class="XXX">define actions (performAction(), etc)</p> --><h5 id=the-selection><span class=secno>4.11.2.8 </span>The selection</h5><p><em>This section only applies to interactive user agents. For
+ method had been invoked, with the same row and column specified.</p>
+
+ <!-- XXXPA <p class="XXX">define actions (performAction(), etc)</p> -->
+
+ <h5 id=the-selection><span class=secno>4.11.2.8 </span>The selection</h5>
+
+ <p><em>This section only applies to interactive user agents. For
other user agents, the <code title=dom-datagrid-selection><a href=#dom-datagrid-selection>selection</a></code> attribute must
- return null.</em><pre class=idl>interface <dfn id=datagridselection>DataGridSelection</dfn> {
+ return null.</em></p>
+
+ <pre class=idl>interface <dfn id=datagridselection>DataGridSelection</dfn> {
readonly attribute unsigned long <span title=dom-DataGridSelection-count>length</span>;
[IndexGetter] <a href=#rowspecification>RowSpecification</a> <span title=dom-DataGridSelection->item</span>(in unsigned long index);
boolean <a href=#dom-datagridselection-isselected title=dom-DataGridSelection-isSelected>isSelected</a>(in <a href=#rowspecification>RowSpecification</a> row);
@@ -25995,57 +26143,87 @@
void <a href=#dom-datagridselection-selectall title=dom-DataGridSelection-selectAll>selectAll</a>();
void <a href=#dom-datagridselection-invert title=dom-DataGridSelection-invert>invert</a>();
void <a href=#dom-datagridselection-clear title=dom-DataGridSelection-clear>clear</a>();
-};</pre><p>Each <code><a href=#datagrid>datagrid</a></code> element must keep track of which rows
+};</pre>
+
+ <p>Each <code><a href=#datagrid>datagrid</a></code> element must keep track of which rows
are currently selected. Initially no rows are selected, but this can
be changed via the methods described in this section. <!--XXX
select-provider-selection The default data provider, for instance,
- changes which rows are selected when it is first initialized.--><p>The selection of a <code><a href=#datagrid>datagrid</a></code> is represented by its
+ changes which rows are selected when it is first initialized.--></p>
+
+ <p>The selection of a <code><a href=#datagrid>datagrid</a></code> is represented by its
<dfn id=dom-datagrid-selection title=dom-datagrid-selection><code>selection</code></dfn> DOM
- attribute, which must be a <code><a href=#datagridselection>DataGridSelection</a></code> object.<p><code><a href=#datagridselection>DataGridSelection</a></code> objects represent the rows in the
+ attribute, which must be a <code><a href=#datagridselection>DataGridSelection</a></code> object.</p>
+
+ <p><code><a href=#datagridselection>DataGridSelection</a></code> objects represent the rows in the
selection. In the selection the rows must be ordered in the natural
order of the data provider (and not, e.g., the rendered order). Rows
that are not rendered because one of their ancestors is closed must
share the same selection state as their nearest rendered
ancestor. Such rows are not considered part of the selection for the
- purposes of iterating over the selection.<p class=note>This selection API doesn't allow for hidden rows to
+ purposes of iterating over the selection.</p>
+
+ <p class=note>This selection API doesn't allow for hidden rows to
be selected because it is trivial to create a data provider that has
infinite depth, which would then require the selection to be
- infinite if every row, including every hidden row, was selected.<p>The <dfn id=dom-datagridselection-length title=dom-DataGridSelection-length><code>length</code></dfn>
+ infinite if every row, including every hidden row, was selected.</p>
+
+ <p>The <dfn id=dom-datagridselection-length title=dom-DataGridSelection-length><code>length</code></dfn>
attribute must return the number of rows currently present in the
- selection. This is the <var title=dom-DataGridSelection-length><a href=#dom-datagridselection-length>length</a></var>.<p>The object's <span>indices of the supported indexed
+ selection. This is the <var title=dom-DataGridSelection-length><a href=#dom-datagridselection-length>length</a></var>.</p>
+
+ <p>The object's <span>indices of the supported indexed
properties</span> are the numbers in the range zero to <span><var title=dom-DataGridSelection-length><a href=#dom-datagridselection-length>length</a></var>-1</span>, unless
the <var title=dom-DataGridSelection-length><a href=#dom-datagridselection-length>length</a></var> is zero,
in which case there are no <span>supported indexed
- properties</span>.<p>The <dfn id=dom-datagridselection-item 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
+ properties</span>.</p>
+
+ <p>The <dfn id=dom-datagridselection-item 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 one), then it must raise an <code><a href=#index_size_err>INDEX_SIZE_ERR</a></code>
- exception. <a href=#references>[DOM3CORE]</a><p>The <dfn id=dom-datagridselection-isselected title=dom-DataGridSelection-isSelected><code>isSelected()</code></dfn>
+ exception. <a href=#references>[DOM3CORE]</a></p>
+
+ <p>The <dfn id=dom-datagridselection-isselected title=dom-DataGridSelection-isSelected><code>isSelected()</code></dfn>
method must return the selected state of the row specified by its
argument. If the specified row exists and is selected, it must
- return true, otherwise it must return false.<p>The <dfn id=dom-datagridselection-setselected title=dom-DataGridSelection-setSelected><code>setSelected()</code></dfn>
+ return true, otherwise it must return false.</p>
+
+ <p>The <dfn id=dom-datagridselection-setselected title=dom-DataGridSelection-setSelected><code>setSelected()</code></dfn>
method takes two arguments, <var title="">row</var> and <var title="">selected</var>. When invoked, it must set the selection
state of row <var title="">row</var> to selected if <var title="">selected</var> is true, and unselected if it is false. If
<var title="">row</var> is not a row in the data grid, the method
must raise an <code><a href=#index_size_err>INDEX_SIZE_ERR</a></code> exception. If the
specified row is not rendered because one of its ancestors is
- closed, the method must do nothing.<p>The <dfn id=dom-datagridselection-selectall title=dom-DataGridSelection-selectAll><code>selectAll()</code></dfn>
+ closed, the method must do nothing.</p>
+
+ <p>The <dfn id=dom-datagridselection-selectall title=dom-DataGridSelection-selectAll><code>selectAll()</code></dfn>
method must mark all the rows in the data grid as selected. After a
call to <code title=dom-DataGridSelection-selectAll><a href=#dom-datagridselection-selectall>selectAll()</a></code>, the
<code title=dom-DataGridSelection-length><a href=#dom-datagridselection-length>length</a></code> attribute
will return the number of rows in the data grid, not counting
- children of closed rows.<p>The <dfn id=dom-datagridselection-invert title=dom-DataGridSelection-invert><code>invert()</code></dfn>
+ children of closed rows.</p>
+
+ <p>The <dfn id=dom-datagridselection-invert title=dom-DataGridSelection-invert><code>invert()</code></dfn>
method must cause all the rows in the selection that were marked as
- selected to now be marked as not selected, and vice versa.<p>The <dfn id=dom-datagridselection-clear title=dom-DataGridSelection-clear><code>clear()</code></dfn>
+ selected to now be marked as not selected, and vice versa.</p>
+
+ <p>The <dfn id=dom-datagridselection-clear title=dom-DataGridSelection-clear><code>clear()</code></dfn>
method must 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=#dom-datagridselection-clear>clear()</a></code>, the <code title=dom-DataGridSelection-length><a href=#dom-datagridselection-length>length</a></code> attribute will
- return zero.<p>If the <code><a href=#datagrid>datagrid</a></code> element has a <dfn id=attr-datagrid-multiple title=attr-datagrid-multiple><code>multiple</code></dfn>
+ return zero.</p>
+
+ <p>If the <code><a href=#datagrid>datagrid</a></code> element has a <dfn id=attr-datagrid-multiple title=attr-datagrid-multiple><code>multiple</code></dfn>
attribute, then the user agent should allow the user to select any
number of rows (zero or more). If the attribute is not present, then
the user agent must not allow the user to select more than a single
row at a time, and selecting another one must unselect all the other
- rows.<p class=note>This only applies to the user. Scripts can select
+ rows.</p>
+
+ <p class=note>This only applies to the user. Scripts can select
multiple rows even when the <code title=attr-datagrid-multiple><a href=#attr-datagrid-multiple>multiple</a></code> attribute is
- absent.<p>Whenever the selection of a <code><a href=#datagrid>datagrid</a></code> changes,
+ absent.</p>
+
+ <p>Whenever the selection of a <code><a href=#datagrid>datagrid</a></code> changes,
whether due to the user interacting with the element, or as a result
of calls to methods of the <code title=dom-datagrid-selection><a href=#dom-datagrid-selection>selection</a></code> object, a <dfn id=event-select title=event-select><code>select</code></dfn><!-- XXX check if we
really should be DFNing this here. It's a DOM3 Core event. What's
@@ -26056,38 +26234,58 @@
script<!-- XXX should xref to a better explanation -->, then the
<code title=event-select><a href=#event-select>select</a></code> events must be coalesced
into one, which must then be fired<!--XXX xref again--> when the
- script execution has completed<!-- XXX xref -->.<p class=note>The <code><a href=#datagridselection>DataGridSelection</a></code> interface has no
- relation to the <code><a href=#selection-0>Selection</a></code> interface.<h5 id=columns-and-captions><span class=secno>4.11.2.9 </span>Columns and captions</h5><p><em>This section only applies to interactive user agents.</em><p>Each <code><a href=#datagrid>datagrid</a></code> element must keep track of which
+ script execution has completed<!-- XXX xref -->.</p>
+
+ <p class=note>The <code><a href=#datagridselection>DataGridSelection</a></code> interface has no
+ relation to the <code><a href=#selection-0>Selection</a></code> interface.</p>
+
+
+ <h5 id=columns-and-captions><span class=secno>4.11.2.9 </span>Columns and captions</h5>
+
+ <p><em>This section only applies to interactive user agents.</em></p>
+
+ <p>Each <code><a href=#datagrid>datagrid</a></code> element must keep track of which
columns are currently being rendered. User agents should initially
show all the columns except those with the <code title=datagrid-column-class-initially-hidden><a href=#datagrid-column-class-initially-hidden>initially-hidden</a></code>
class, but may allow users to hide or show columns. User agents
should initially display the columns in the order given by the data
- provider, but may allow this order to be changed by the user.<p>If columns are not being used, as might be the case if the data
+ provider, but may allow this order to be changed by the user.</p>
+
+ <p>If columns are not being used, as might be the case if the data
grid is being presented in an icon view, or if an overview of data
is being read in an aural context, then the text of the first column
- of each row should be used to represent the row.<p>If none of the columns have any captions (i.e. if the data
+ of each row should be used to represent the row.</p>
+
+ <p>If none of the columns have any captions (i.e. if the data
provider does not provide a <code title=dom-provider-getCaptionText><a href=#dom-provider-getcaptiontext>getCaptionText()</a></code> method),
then user agents may avoid showing the column headers at all. This
may prevent the user from performing actions on the columns (such as
- reordering them, changing the sort column, and so on).<p class=note>Whatever the order used for rendering, and
+ reordering them, changing the sort column, and so on).</p>
+
+ <p class=note>Whatever the order used for rendering, and
irrespective of what columns are being shown or hidden, the "first
column" as referred to in this specification is always the column
with index zero, and the "last column" is always the column with the
index one less than the value returned by the <code title=dom-provider-getcolumnCount><a href=#dom-provider-getcolumncount>getColumnCount()</a></code> method
- of the data provider.<p>If <a href=#columnType2>a column is sortable</a>, then the user
+ of the data provider.</p>
+
+ <p>If <a href=#columnType2>a column is sortable</a>, then the user
agent should allow the user to request that the data be sorted using
that column. When the user does so, then the <code><a href=#datagrid>datagrid</a></code>
must invoke the data provider's <code title=dom-provider-toggleColumnSortState><a href=#dom-provider-togglecolumnsortstate>toggleColumnSortState()</a></code>
method, with the column's index as the only argument. The
<code><a href=#datagrid>datagrid</a></code> must <em>then</em> act as if the
<code><a href=#datagrid>datagrid</a></code>'s <code title=dom-datagrid-updateEverything><a href=#dom-datagrid-updateeverything>updateEverything()</a></code>
- method had been invoked.</p><!--XXXDND
+ method had been invoked.</p>
+
+<!--XXXDND
<h5>Drag and drop in <code>datagrid</code>s</h5>
<p><em>This section only applies to interactive user agents.</em></p>
<p class="XXX">define drag and drop in datagrids; selectiondraggable, etc.</p>
---><h4 id=the-command><span class=secno>4.11.3 </span>The <dfn><code>command</code></dfn> element</h4><dl class=element><dt>Categories</dt>
+-->
+</div><h4 id=the-command><span class=secno>4.11.3 </span>The <dfn><code>command</code></dfn> element</h4><dl class=element><dt>Categories</dt>
<dd><a href=#metadata-content-0>Metadata content</a>.</dd>
<dd><a href=#flow-content-0>Flow content</a>.</dd>
<dd><a href=#phrasing-content-0>Phrasing content</a>.</dd>
Received on Sunday, 1 February 2009 08:59:46 UTC