HTML Standard Tracker

Filter

File a bug

SVNBugCommentTime (UTC)
2962<datagrid> mark II, first draft2009-04-18 01:16
@@ -6249,29 +6249,20 @@ interface <dfn>HTMLOptionsCollection</dfn> {
 
   </div>
 
 
   <h4>DOMTokenList</h4>
 
   <p>The <code>DOMTokenList</code> interface represents an interface
   to an underlying string that consists of an <span>unordered set of
   unique space-separated tokens</span>.</p>
 
-  <p>Which string underlies a particular <code>DOMTokenList</code>
-  object is defined when the object is created. It might be a content
-  attribute (e.g. the string that underlies the <code
-  title="dom-classList">classList</code> object is the <code
-  title="attr-class">class</code> attribute), or it might be an
-  anonymous string (e.g. when a <code>DOMTokenList</code> object is
-  passed to an author-implemented callback in the
-  <code>datagrid</code> APIs).</p>
-
   <pre class="idl">[<span title="dom-tokenlist-toString">Stringifies</span>] interface <dfn>DOMTokenList</dfn> {
   readonly attribute unsigned long <span title="dom-tokenlist-length">length</span>;
   [IndexGetter] DOMString <span title="dom-tokenlist-item">item</span>(in unsigned long index);
   boolean <span title="dom-tokenlist-has">has</span>(in DOMString token);
   void <span title="dom-tokenlist-add">add</span>(in DOMString token);
   void <span title="dom-tokenlist-remove">remove</span>(in DOMString token);
   boolean <span title="dom-tokenlist-toggle">toggle</span>(in DOMString token);
 };</pre>
 
   <dl class="domintro">
@@ -6730,21 +6721,21 @@ interface <dfn>DOMStringMap</dfn> {};</pre>
    <li value="13"><dfn><code>INVALID_MODIFICATION_ERR</code></dfn></li>
    <li value="14"><dfn><code>NAMESPACE_ERR</code></dfn></li>
    <li value="15"><dfn><code>INVALID_ACCESS_ERR</code></dfn></li>
    <li value="16"><dfn><code>VALIDATION_ERR</code></dfn></li>
    <li value="17"><dfn><code>TYPE_MISMATCH_ERR</code></dfn></li>
    <li value="18"><dfn><code>SECURITY_ERR</code></dfn></li> <!-- actually in XHR for now -->
    <li value="19"><dfn><code>NETWORK_ERR</code></dfn></li> <!-- actually in XHR for now -->
    <li value="20"><dfn><code>ABORT_ERR</code></dfn></li> <!-- actually in XHR for now -->
    <li value="21"><dfn><code>URL_MISMATCH_ERR</code></dfn></li> <!-- actually in workers for now -->
    <li value="22"><dfn><code>QUOTA_EXCEEDED_ERR</code></dfn></li> <!-- actually defined right here for now -->
-   <li value="23"><dfn><code>UNAVAILABLE_SCRIPT_ERR</code></dfn></li> <!-- actually defined right here for now -->
+   <li value="23"><dfn><code>DATAGRID_MODEL_ERR</code></dfn></li> <!-- actually defined right here for now -->
    <li value="81"><dfn><code>PARSE_ERR</code></dfn></li> <!-- actually defined in dom3ls -->
    <li value="82"><dfn><code>SERIALISE_ERR</code></dfn></li> <!-- actually defined in dom3ls -->
   </ol>
 
 
   <div class="impl">
 
   <h4>Garbage collection</h4>
 
   <p>There is an <dfn>implied strong reference</dfn> from any DOM
@@ -16464,20 +16455,22 @@ and a height of &lt;meter>2cm&lt;/meter>.&lt;/p> &lt;!-- <strong>BAD!</strong> -
 
   <p>All of which will result in the following inequalities all being
   true:</p>
 
   <ul class="brief">
    <li>minimum value &le; actual value &le; maximum value</li>
    <li>minimum value &le; low boundary &le; high boundary &le; maximum value</li>
    <li>minimum value &le; optimum point &le; maximum value</li>
   </ul>
 
+  <!-- next two paragraphs are duplicated in the <datagrid> section -->
+
   <p><strong>UA requirements for regions of the gauge</strong>: If the
   optimum point is equal to the low boundary or the high boundary, or
   anywhere in between them, then the region between the low and high
   boundaries of the gauge must be treated as the optimum region, and
   the low and high parts, if any, must be treated as
   suboptimal. Otherwise, if the optimum point is less than the low
   boundary, then the region between the minimum value and the low
   boundary must be treated as the optimum region, the region between
   the low boundary and the high boundary must be treated as a
   suboptimal region, and the region between the high boundary and the
@@ -17827,21 +17820,21 @@ interface <dfn>HTMLImageElement</dfn> : <span>HTMLElement</span> {
   section</a>.</p>
 
   <p class="XXX">There has been some suggestion that the <code
   title="">longdesc</code> attribute from HTML4 should be
   included. This has been considered and rejected in the past, but if
   new evidence is found showing the attribute to actually help users
   rather than harm them, it may be reconsidered.</p>
 
   <p>The <code>img</code> must not be used as a layout tool. In
   particular, <code>img</code> elements should not be used to display
-  fully transparent images, as they rarely convey meaning and rarely
+   transparent images, as they rarely convey meaning and rarely
   add anything useful to the document.</p>
 
   <div class="impl">
 
   <hr>
 
   <p>Unless the user agent cannot support images, or its support for
   images has been disabled, or the user agent only fetches elements on
   demand, or the element's <code title="attr-img-src">src</code>
   attribute has a value that is an <i>ignored self-reference</i>,
@@ -35501,46 +35494,40 @@ interface <dfn>HTMLFormElement</dfn> : <span>HTMLElement</span> {
   element</dfn> is the first element in the document in <span>tree
   order</span> to have an ID equal to the value of the <code
   title="attr-input-list">list</code> attribute, if that element is a
   <code>datalist</code> element. If there is no <code
   title="attr-input-list">list</code> attribute, or if there is no
   element with that ID, or if the first element with that ID is not a
   <code>datalist</code> element, then there is no <span
   title="concept-input-list">suggestions source element</span>.</p>
 
   <p>If there is a <span title="concept-input-list">suggestions source
-  element</span>, then each <code>option</code> element that is a
-  descendant of the <span title="concept-input-list">suggestions
-  source element</span>, that is not <span
-  title="concept-option-disabled">disabled</span>, and whose <span
-  title="concept-option-value">value</span> is a string that isn't the
-  empty string and that the user would be allowed to enter as the
-  <code>input</code> element's <span
-  title="concept-fe-value">value</span>, represents a suggestion. Each
-  suggestion has a <span title="concept-option-value">value</span> and
-  a <span title="concept-option-label">label</span>.</p>
-
-  <p>When the user agent is allowing the user to edit the
-  <code>input</code> element's <span
+  element</span>, then, when the user agent is allowing the user to
+  edit the <code>input</code> element's <span
   title="concept-fe-value">value</span>, the user agent should offer
-  the suggestions to the user in a manner suitable for the type of
-  control used. The user agent may use the suggestion's <span
+  the suggestions represented by the <span
+  title="concept-input-list">suggestions source element</span> to the
+  user in a manner suitable for the type of control used. The user
+  agent may use the suggestion's <span
   title="concept-option-label">label</span> to identify the suggestion
   if appropriate. If the user selects a suggestion, then the
   <code>input</code> element's <span
   title="concept-fe-value">value</span> must be set to the selected
   suggestion's <span title="concept-option-value">value</span>, as if
   the user had written that value himself.</p>
 
-  <p>User agents should filter the suggestions to hide suggestions
-  that would cause the element to not <span
-  title="concept-fv-valid">satisfy its constraints</span>.</p>
+  <p>User agents must filter the suggestions to hide suggestiosn that
+  the user would not be allowed to enter as the <code>input</code>
+  element's <span title="concept-fe-value">value</span>, and should
+  filter the suggestions to hide suggestions that would cause the
+  element to not <span title="concept-fv-valid">satisfy its
+  constraints</span>.</p>
 
   <hr>
 
   <p>If the <code title="attr-input-list">list</code> attribute does
   not apply, there is no <span title="concept-input-list">suggestions
   source element</span>.</p>
 
   </div>
 
 
@@ -36967,21 +36954,32 @@ interface <dfn>HTMLSelectElement</dfn> : <span>HTMLElement</span> {
   other controls. The contents of the element represents fallback
   content for legacy user agents, intermixed with <code>option</code>
   elements that represent the predefined options. In the rendering,
   the <code>datalist</code> element <span>represents</span>
   nothing<span class="impl"> and it, along with its children, should
   be hidden</span>.</p>
 
   <p>The <code>datalist</code> element is hooked up to an
   <code>input</code> element using the <code
   title="attr-input-list">list</code> attribute on the
-  <code>input</code> element.</p>
+  <code>input</code> element. The <code>datalist</code> element can
+  also be used with a <code>datagrid</code> element, as the source of
+  autocompletion hints for <code
+  title="datagrid-type-editable">editable</code> cells.</p>
+
+  <p>Each <code>option</code> element that is a descendant of the
+  <code>datalist</code> element, that is not <span
+  title="concept-option-disabled">disabled</span>, and whose <span
+  title="concept-option-value">value</span> is a string that isn't the
+  empty string, represents a suggestion. Each suggestion has a <span
+  title="concept-option-value">value</span> and a <span
+  title="concept-option-label">label</span>.
 
   <dl class="domintro">
 
    <dt><var title="">datalist</var> . <code title="dom-datalist-options">options</code></dt>
 
    <dd>
     <p>Returns an <code>HTMLCollection</code> of the <code>options</code> elements of the table.</p>
    </dd>
 
   </dl>
@@ -40140,1998 +40138,2608 @@ interface <dfn>HTMLOptionElement</dfn> : <span>HTMLElement</span> {
   element.</p>
 
   <p>The <dfn title="dom-details-open"><code>open</code></dfn>
   attribute must <span>reflect</span> the <code
   title="attr-details-open">open</code> content attribute.</p>
 
   </div>
 
 
 
-<div class="bad">
   <h4 id="datagrid">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><span>Flow content</span>.</dd>
    <dd><span>Interactive content</span>.</dd>
    <dd><span>Sectioning root</span>.</dd>
    <dt>Contexts in which this element may be used:</dt>
    <dd>Where <span>flow content</span> is expected.</dd>
    <dt>Content model:</dt>
    <dd>Either: Nothing.</dd>
    <dd>Or: <span>Flow content</span>, but where the first element child node, if any, is not a <code>table</code>, <code>select</code>, or <code>datalist</code> element.</dd>
    <dd>Or: A single <code>table</code> element.</dd>
    <dd>Or: A single <code>select</code> element.</dd>
    <dd>Or: A single <code>datalist</code> element.</dd>
    <dt>Content attributes:</dt>
    <dd><span>Global attributes</span></dd>
+<!--v2DGS:
    <dd><code title="attr-datagrid-multiple">multiple</code></dd>
+-->
    <dd><code title="attr-datagrid-disabled">disabled</code></dd>
    <dt>DOM interface:</dt>
    <dd>
 <pre class="idl">interface <dfn>HTMLDataGridElement</dfn> : <span>HTMLElement</span> {
-           attribute <span>DataGridDataProvider</span> <span title="dom-datagrid-data">data</span>;
-  readonly attribute <span>DataGridSelection</span> <span title="dom-datagrid-selection">selection</span>;
            attribute boolean <span title="dom-datagrid-multiple">multiple</span>;
            attribute boolean <span title="dom-datagrid-disabled">disabled</span>;
-  void <span title="dom-datagrid-updateEverything">updateEverything</span>();
-  void <span title="dom-datagrid-updateRowsChanged">updateRowsChanged</span>(in <span>RowSpecification</span> row, in unsigned long count);
-  void <span title="dom-datagrid-updateRowsInserted">updateRowsInserted</span>(in <span>RowSpecification</span> row, in unsigned long count);
-  void <span title="dom-datagrid-updateRowsRemoved">updateRowsRemoved</span>(in <span>RowSpecification</span> row, in unsigned long count);
-  void <span title="dom-datagrid-updateRowChanged">updateRowChanged</span>(in <span>RowSpecification</span> row);
-  void <span title="dom-datagrid-updateColumnChanged">updateColumnChanged</span>(in unsigned long column);
-  void <span title="dom-datagrid-updateCellChanged">updateCellChanged</span>(in <span>RowSpecification</span> row, in unsigned long column);
+           attribute <span>DataGridListener</span> <span title="dom-datagrid-listener">listener</span>;
+<!-- v2DGS:
+  readonly attribute <span>DataGridSelection</span> <span title="dom-datagrid-selection">selection</span>;
+-->
+  // columns
+  void <span title="dom-datagrid-addColumn">addColumn</span>(in <span>Column</span> id, in DOMString label, in DOMString type, [Optional] in HTMLImageElement icon, [Optional] in boolean sortable, [Optional] in boolean visible);
+           attribute DOMString <span title="dom-datagrid-sortColumn">sortColumn</span>;
+           attribute boolean <span title="dom-datagrid-sortAscending">sortAscending</span>;
+  void <span title="dom-datagrid-clearColumns">clearColumns</span>();
+
+  // rows
+  void <span title="dom-datagrid-renotify">renotify</span>();
+  void <span title="dom-datagrid-setRowCount">setRowCount</span>(in long childCount, in long rowCount);
+  void <span title="dom-datagrid-setRows">setRows</span>(in <span>RowList</span> rows);
+  void <span title="dom-datagrid-insertRows">insertRows</span>(in <span>RowList</span> rows);
+  void <span title="dom-datagrid-deleteRows">deleteRows</span>(in <span>RowIDList</span> rows);
+  void <span title="dom-datagrid-repaint">repaint</span>(in <span>RowID</span> row, in DOMString column);
+  void <span title="dom-datagrid-clearRows">clearRows</span>();
+<!--
+ v2: opening and closing a row
+     moving a row's actual ID
+      - imagine new mail moving a thread up; you just want to add the new mail to the thread and move the thread's first mail to the top
+      - though actually that should probably just be done using display sorting
+-->
+};
+
+typedef DOMString <dfn>Column</dfn>;
+typedef sequence&lt;<span>Column</span>> <dfn>ColumnList</dfn>;
+typedef sequence&lt;any> <dfn>Cell</dfn>; // <span>Column</span>, [Variadic] any (exact types expected depend on the column type)
+typedef sequence&lt;<span>Cell</span>> <dfn>CellList</dfn>;
+typedef sequence&lt;any> <dfn>Row</dfn>; // <span>RowID</span>, long, long, <span>CellList</span>, [Optional] boolean, [Optional] long
+typedef sequence&lt;<span>Row</span>> <dfn>RowList</dfn>;
+typedef sequence&lt;unsigned long> <dfn>RowID</dfn>;
+typedef sequence&lt;<span>RowID</span>> <dfn>RowIDList</dfn>;
+
+[Callback=FunctionOnly, NoInterfaceObject]
+interface <dfn>RenderingContext2DCallback</dfn> {
+  DOMString <span title="dom-Rendering2DContextCallback-handleEvent">handleEvent</span>(in <span>CanvasRenderingContext2D</span> context, in unsigned long width, in unsigned long height);
 };</pre>
    </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>datagrid</code> element <span>represents</span> an
+  interactive representation of tree, list, or tabular data.</p>
 
-  <p>The <code>datagrid</code> element <span>represents</span> an interactive
-  representation of tree, list, or tabular data.</p>
+  <p>The data being presented is provided by script using the methods
+  described in the following sections.</p>
 
-  <p>The data being presented can come either from the content, as
-  elements given as children of the <code>datagrid</code> element, or
-  from a scripted data provider given by the <code
-  title="dom-datagrid-data">data</code> DOM attribute.</p>
+<!--v2DGS:
+  <p>The <dfn
+  title="attr-datagrid-multiple"><code>multiple</code></dfn> attribute
+  is a <span>boolean attribute</span>. When set, it indicates that the
+  user can select more than one row at a time.</p>
+-->
 
-  <p>The <code title="attr-datagrid-multiple">multiple</code> and
-  <code title="attr-datagrid-disabled">disabled</code> attributes are
-  <span title="boolean attribute">boolean attributes</span>. Their
-  effects are described in the processing model sections below.</p>
+  <p>The <dfn
+  title="attr-datagrid-disabled"><code>disabled</code></dfn> attribute
+  is a <span>boolean attribute</span> used to disable the
+  control. <span class="impl">When the attribute is set, the user
+  agent must disable the <code>datagrid</code>, preventing the user
+  from interacting with it. The <code>datagrid</code> element should
+  still continue to update itself when the underlying data changes,
+  though, as described in the next few sections. However, conformance
+  requirements stating that <code>datagrid</code> elements must react
+  to users in particular ways do not apply when one is
+  disabled.</span></p>
+
+  <div class="impl">
 
   <p>The <dfn
   title="dom-datagrid-multiple"><code>multiple</code></dfn> and <dfn
   title="dom-datagrid-disabled"><code>disabled</code></dfn> DOM
   attributes must <span>reflect</span> the <code
   title="attr-datagrid-multiple">multiple</code> and <code
   title="attr-datagrid-disabled">disabled</code> content attributes
   respectively.</p>
 
+  </div>
 
-  <h5>The <code>datagrid</code> data model</h5>
+  <!-- v2DGPA: 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). (v2DGPA = <datagrid> Perform Action) -->
+
+
+  <h5>Introduction</h5>
 
   <p><em>This section is non-normative.</em></p>
 
   <p>In the <code>datagrid</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>
+  although individual columns might be hidden in the presentation.</p>
+
+  <hr>
 
   <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>
 
-  <p>The columns can have captions. Those captions are not considered
-  a row in their own right, they are obtained separately.</p>
+  <p>The chains of numbers that give a row's path, or identifier, are
+  represented by arrays of positions, represented in IDL by the
+  <span>RowID</span> interface.</p>
+
+  <p>The root of the tree is represented by an empty array.</p>
+
+  <hr>
+
+  <p>Each column has a string that is used to identify it in the API,
+  a label that is shown to users interacting with the column, a type,
+  and optionally an icon.</p>
+
+  <p>The possible types are as follows:</p>
+
+  <table>
+   <thead>
+    <tr>
+     <td>Keyword
+     <td>Description
+   <tbody>
+    <tr>
+     <td><code title="datagrid-type-text">text</code>
+     <td>Simple text.
+    <tr>
+     <td><code title="datagrid-type-editable">editable</code>
+     <td>Editable text.
+    <tr>
+     <td><code title="datagrid-type-checkable">checkable</code>
+     <td>Text with a check box.
+    <tr>
+     <td><code title="datagrid-type-list">list</code>
+     <td>A list of values that the user can switch between.
+    <tr>
+     <td><code title="datagrid-type-progress">progress</code>
+     <td>A progress bar.
+    <tr>
+     <td><code title="datagrid-type-meter">meter</code>
+     <td>A gauge.
+    <tr>
+     <td><code title="datagrid-type-custom">custom</code>
+     <td>A canvas onto which arbitrary content can be drawn.
+  </table>
+
+  <p>Each column can be flagged as sortable, in which case the user
+  will be able to sort the view using that column.</p>
+
+  <p>Columns are not necessarily visible. A column can be created
+  invisible by default. The user can select which columns are to be
+  shown.</p>
+
+  <p>When no columns have been added to the <code>datagrid</code>, a
+  column with no name, whose identifier is the empty string, whose
+  type is <code title="datagrid-type-text">text</code>, and which is
+  not sortable, is implied. This column is removed if any explicit
+  columns are declared.</p>
+
+  <p>Each cell uses the type given for its column, so all cells in a
+  column present the same type of information.</p>
 
+<!--v2DGS:
   <p>Selection of data in a <code>datagrid</code> operates at the row
   level. If the <code title="attr-datagrid-multiple">multiple</code>
   attribute is present, multiple rows can be selected at once,
   otherwise the user can only select one row at a time.</p>
-
-  <p>The <code>datagrid</code> element can be disabled entirely by
-  setting the <code title="attr-datagrid-disabled">disabled</code>
-  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
-  classes, applied to them by the data provider. These classes <a
-  href="#datagridClassSummary">affect the functionality</a> of the
-  <code>datagrid</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">class</code>
-  attribute, except that they are not specified on elements but are
-  given by scripted data providers.</p> <!-- XXX check xrefs -->
+  <!-- v2DGDND: selection should draggable to and from datagrids -->
 
 
-  <h5>How rows are identified</h5>
+  <h6>Example: a <code>datagrid</code> backed by a static <code>table</code> element</h6>
 
-  <p>The chains of numbers that give a row's path, or identifier, are
-  represented by objects that implement the
-  <span>RowSpecification</span> interface.</p>
+  <p class="XXX">...</p>
 
-  <pre class="idl">[NoInterfaceObject] interface <dfn>RowSpecification</dfn> {
-  // binding-specific interface
-};</pre>
 
-  <p>In JavaScript, 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
-  <span>RowSpecification</span>, as is <code>1</code> on its
-  own. However, <code>[1,0.2,9]</code> is not a
-  <span>RowSpecification</span> object, since its second value is not
-  an integer.</p>
-
-  <p>User agents must always represent <code>RowSpecification</code>s
-  in JavaScript by using arrays, even if the path only has one
-  number.</p>
+  <h6>Example: a <code>datagrid</code> backed by nested <code>ol</code> elements</h6>
 
-  <p>The root of the tree is represented by the empty path; in
-  JavaScript, this is the empty array (<code>[]</code>). Only the
-  <code title="dom-provider-getRowCount">getRowCount()</code> and
-  <code
-  title="dom-provider-getChildAtPosition">GetChildAtPosition()</code>
-  methods ever get called with the empty path.</p>
+  <p class="XXX">...</p>
 
 
-  <h5>The data provider interface</h5>
+  <h6>Example: a <code>datagrid</code> backed by a server</h6>
 
-  <p><em>The conformance criteria in this section apply to any
-  implementation of the <code>DataGridDataProvider</code>, including
-  (and most commonly) the content author's implementation(s).</em></p>
+  <p class="XXX">...</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>DataGridDataProvider</dfn> {
-  void <span title="dom-provider-initialize">initialize</span>(in <span>HTMLDataGridElement</span> datagrid);
-  unsigned long <span title="dom-provider-getRowCount">getRowCount</span>(in <span>RowSpecification</span> row);
-  unsigned long <span title="dom-provider-getChildAtPosition">getChildAtPosition</span>(in <span>RowSpecification</span> parentRow, in unsigned long position);
-  unsigned long <span title="dom-provider-getColumnCount">getColumnCount</span>();
-  DOMString <span title="dom-provider-getCaptionText">getCaptionText</span>(in unsigned long column);
-  void <span title="dom-provider-getCaptionClasses">getCaptionClasses</span>(in unsigned long column, in DOMTokenList classes);
-  DOMString <span title="dom-provider-getRowImage">getRowImage</span>(in <span>RowSpecification</span> row);
-  <span>HTMLMenuElement</span> <span title="dom-provider-getRowMenu">getRowMenu</span>(in <span>RowSpecification</span> row);
-  void <span title="dom-provider-getRowClasses">getRowClasses</span>(in <span>RowSpecification</span> row, in DOMTokenList classes);
-  DOMString <span title="dom-provider-getCellData">getCellData</span>(in <span>RowSpecification</span> row, in unsigned long column);
-  void <span title="dom-provider-getCellClasses">getCellClasses</span>(in <span>RowSpecification</span> row, in unsigned long column, in DOMTokenList classes);
-<!--XXXDND
-  boolean <span title="dom-provider-canDrop">canDrop</span>(in <span>RowSpecification</span> row, in <span>RowSpecification</span> position, data);
-  boolean <span title="dom-provider-dropped">dropped</span>(in <span>RowSpecification</span> row, in <span>RowSpecification</span> position, data);
--->  void <span title="dom-provider-toggleColumnSortState">toggleColumnSortState</span>(in unsigned long column);
-  void <span title="dom-provider-setCellCheckedState">setCellCheckedState</span>(in <span>RowSpecification</span> row, in unsigned long column, in long state);
-  void <span title="dom-provider-cycleCell">cycleCell</span>(in <span>RowSpecification</span> row, in unsigned long column);
-  void <span title="dom-provider-editCell">editCell</span>(in <span>RowSpecification</span> row, in unsigned long column, in DOMString data);
-<!--XXXPA
-  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 -->
+  <h5>Populating the <code>datagrid</code></h5>
 
-  <p>The <code>DataGridDataProvider</code> interface represents the
-  interface that objects must implement to be used as custom data
-  views for <code>datagrid</code> elements.</p>
+  <dl class="domintro">
 
-  <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">getRowCount()</code> and <code
-  title="dom-provider-getCellData">getCellData()</code> methods.</p>
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-listener">listener</code> [ = <var title="">value</var> ]</dt>
+   <dd>
 
-  <p>Once the object is written, it must be hooked up to the
-  <code>datagrid</code> using the <dfn
-  title="dom-datagrid-data"><code>data</code></dfn> DOM attribute.</p>
+    <p>Return the current object that is configured as the
+    <code>datagrid</code> listener, if any. Returns null if there is
+    none.</p>
 
-  <p>The following methods may be usefully implemented:</p>
+    <p>The listener is an object provided by the script author that
+    receives notifications when the <code>datagrid</code> needs row
+    data to render itself, when the user opens and closes rows with
+    children, when the user edits a cell, and when the user invokes a
+    row's context menu. (The <code>DataGridListener</code> interface
+    used for this purpose is described in the next section.)</p>
 
-  <dl>
+    <p>Can be set, to change the current listener.</p>
 
-   <dt><dfn title="dom-provider-initialize"><code>initialize(<var title="">datagrid</var>)</code></dfn></dt>
-
-   <dd>Called by the <code>datagrid</code> element (the one given by
-   the <var title="">datagrid</var> argument) after it has first
-   populated itself. This would typically be used to set the initial
-   selection of the <code>datagrid</code> element when it is first
-   loaded. The data provider could also use this method call to
-   register a <code title="event-select">select</code> event handler
-   on the <code>datagrid</code> in order to monitor selection
-   changes.</dd>
-
-   <dt><dfn title="dom-provider-getRowCount"><code>getRowCount(<var title="">row</var>)</code></dfn></dt>
-
-   <dd>Must return the number of rows that are children of the
-   specified <var title="">row</var>, including rows that are
-   off-screen. If <var title="">row</var> is empty, then the number of
-   rows at the top level must be returned. If the value that this
-   method would return for a given <var title="">row</var> changes,
-   the relevant update methods on the <code>datagrid</code> must be
-   called first. Otherwise, this method must always return the same
-   number. For a list (as opposed to a tree), this method must return
-   0 whenever it is called with a <var title="">row</var> identifier
-   that is not empty.</dd>
-
-   <dt><dfn title="dom-provider-getChildAtPosition"><code>getChildAtPosition(<var title="">parentRow</var>, <var title="">position</var>)</code></dfn></dt>
-
-   <dd>Must return the index of the row that is a child of <var
-   title="">parentRow</var> and that is to be positioned as the <var
-   title="">position</var>th row under <var title="">parentRow</var>
-   when rendering the children of <var title="">parentRow</var>. If
-   <var title="">parentRow</var> is empty, then <var
-   title="">position</var> refers to the <var
-   title="">position</var>th row at the top level of the data
-   grid. May be omitted if the rows are always to be sorted in the
-   natural order. (The natural order is the one where the method
-   always returns <var title="">position</var>.) For a given <var
-   title="">parentRow</var>, this method must never return the same
-   value for different values of <var title="">position</var>. The
-   returned value <var title="">x</var> must be in the range
-   0&nbsp;&le;&nbsp;<var title="">x</var>&nbsp;&lt;&nbsp;<var
-   title="">n</var>, where <var title="">n</var> is the value returned
-   by <code title="dom-provider-getRowCount">getRowCount(<var
-   title="">parentRow</var>)</code>.</dd>
-
-   <dt><dfn title="dom-provider-getColumnCount"><code>getColumnCount()</code></dfn></dt>
-
-   <dd>Must return the number of columns currently in the data model
-   (including columns that might be hidden). May be omitted if there
-   is only one column. If the value that this method would return
-   changes, the <code>datagrid</code>'s <code
-   title="dom-datagrid-updateEverything">updateEverything()</code>
-   method must be called.</dd>
-
-   <dt><dfn title="dom-provider-getCaptionText"><code>getCaptionText(<var title="">column</var>)</code></dfn></dt>
-
-   <dd>Must return the caption, or label, for column <var
-   title="">column</var>. May be omitted if the columns have no
-   captions. If the value that this method would return changes, the
-   <code>datagrid</code>'s <code
-   title="dom-datagrid-updateColumnChanged">updateColumnChanged()</code>
-   method must be called with the appropriate column index.</dd>
-
-   <dt><dfn title="dom-provider-getCaptionClasses"><code>getCaptionClasses(<var title="">column</var>, <var title="">classes</var>)</code></dfn></dt>
-
-   <dd>Must add the classes that apply to column <var
-   title="">column</var> to the <var title="">classes</var> object.
-   May be omitted if the columns have no special classes. If the
-   classes that this method would add changes, the
-   <code>datagrid</code>'s <code
-   title="dom-datagrid-updateColumnChanged">updateColumnChanged()</code>
-   method must be called with the appropriate column index. Some
-   classes have <a href="#datagridClassSummary">predefined
-   meanings</a>.</dd>
-
-   <dt><dfn title="dom-provider-getRowImage"><code>getRowImage(<var title="">row</var>)</code></dfn></dt>
-
-   <dd>Must return a <span>URL</span> giving the address of an image
-   that represents row <var title="">row</var>, or the empty string if
-   there is no applicable image. May be omitted if no rows have
-   associated images. If the value that this method would return
-   changes, the <code>datagrid</code>'s update methods must be called
-   to update the row in question.</dd>
-
-   <dt><dfn title="dom-provider-getRowMenu"><code>getRowMenu(<var title="">row</var>)</code></dfn></dt>
+   </dd>
 
-   <dd>Must return an <code>HTMLMenuElement</code> object that is to
-   be used as a context menu for row <var title="">row</var>, or null
-   if there is no particular context menu. May be omitted if none of
-   the rows have a special context menu. As this method is called
-   immediately before showing the menu in question, no precautions
-   need to be taken if the return value of this method changes.</dd>
 
-   <dt><dfn title="dom-provider-getRowClasses"><code>getRowClasses(<var title="">row</var>, <var title="">classes</var>)</code></dfn></dt>
-
-   <dd>Must add the classes that apply to row <var title="">row</var>
-   to the <var title="">classes</var> object. May be omitted if the
-   rows have no special classes. If the classes that this method would
-   add changes, the <code>datagrid</code>'s update methods must be
-   called to update the row in question. Some classes have <a
-   href="#datagridClassSummary">predefined meanings</a>.</dd>
-
-   <dt><dfn title="dom-provider-getCellData"><code>getCellData(<var title="">row</var>, <var title="">column</var>)</code></dfn></dt>
-
-   <dd>Must return the value of the cell on row <var
-   title="">row</var> in column <var title="">column</var>. For text
-   cells, this must be the text to show for that cell. For <span
-   title="datagrid-cell-class-progress">progress bar cells</span>,
-   this must be either a floating point number in the range 0.0 to 1.0
-   (converted to a string representation<!-- XXX this isn't
-   technically enough to define what the author must be doing here,
-   but let's let that slide until someone notices -->), indicating the
-   fraction of the progress bar to show as full (1.0 meaning
-   complete), or the empty string, indicating an indeterminate
-   progress bar. If the value that this method would return changes,
-   the <code>datagrid</code>'s update methods must be called to update
-   the rows that changed. If only one cell changed, the <code
-   title="dom-datagrid-updateCellChanged">updateCellChanged()</code>
-   method may be used.</dd>
-
-   <dt><dfn title="dom-provider-getCellClasses"><code>getCellClasses(<var title="">row</var>, <var title="">column</var>, <var title="">classes</var>)</code></dfn></dt>
-
-   <dd>Must add the classes that apply to the cell on row <var
-   title="">row</var> in column <var title="">column</var> to the <var
-   title="">classes</var> object. May be omitted if the cells have no
-   special classes. If the classes that this method would add changes,
-   the <code>datagrid</code>'s update methods must be called to update
-   the rows or cells in question. Some classes have <a
-   href="#datagridClassSummary">predefined meanings</a>.</dd>
-
-   <dt><dfn title="dom-provider-toggleColumnSortState"><code>toggleColumnSortState(<var title="">column</var>)</code></dfn></dt>
-
-   <dd>Called by the <code>datagrid</code> when the user tries to sort
-   the data using a particular column <var title="">column</var>. The
-   data provider must update its state so that the <code
-   title="dom-provider-getChildAtPosition">GetChildAtPosition()</code>
-   method returns the new order, and the classes of the columns
-   returned by <code
-   title="dom-provider-getCaptionClasses">getCaptionClasses()</code>
-   represent the new sort status. There is no need to tell the
-   <code>datagrid</code> that it the data has changed, as the
-   <code>datagrid</code> automatically assumes that the entire data
-   model will need updating.</dd>
-
-   <dt><dfn title="dom-provider-setCellCheckedState"><code>setCellCheckedState(<var title="">row</var>, <var title="">column</var>, <var title="">state</var>)</code></dfn></dt>
-
-   <dd>Called by the <code>datagrid</code> when the user changes the
-   state of a checkbox cell on row <var title="">row</var>, column
-   <var title="">column</var>. The checkbox should be toggled to the
-   state given by <var title="">state</var>, which is a positive
-   integer (1) if the checkbox is to be checked, zero (0) if it is to
-   be unchecked, and a negative number (&#x2212;1) if it is to be set to the
-   indeterminate state. There is no need to tell the
-   <code>datagrid</code> that the cell has changed, as the
-   <code>datagrid</code> automatically assumes that the given cell
-   will need updating.</dd>
-
-   <dt><dfn title="dom-provider-cycleCell"><code>cycleCell(<var title="">row</var>, <var title="">column</var>)</code></dfn></dt>
-
-   <dd>Called by the <code>datagrid</code> when the user changes the
-   state of a cyclable cell on row <var title="">row</var>, column
-   <var title="">column</var>. The data provider should change the
-   state of the cell to the new state, as appropriate. There is no
-   need to tell the <code>datagrid</code> that the cell has
-   changed, as the <code>datagrid</code> automatically assumes that
-   the given cell will need updating.</dd>
-
-   <dt><dfn title="dom-provider-editCell"><code>editCell(<var title="">row</var>, <var title="">column</var>, <var title="">data</var>)</code></dfn></dt>
-
-   <dd>Called by the <code>datagrid</code> when the user edits the
-   cell on row <var title="">row</var>, column <var
-   title="">column</var>. The new value of the cell is given by <var
-   title="">data</var>. The data provider should update the cell
-   accordingly. There is no need to tell the <code>datagrid</code>
-   that the cell has changed, as the <code>datagrid</code>
-   automatically assumes that the given cell will need updating.</dd>
-
-<!--XXXPA
-  void performAction(in DOMString action); // required if .performAction() is ever invoked on the datagrid
-  void performActionOnRow(in <span>RowSpecification</span> row, in DOMString action); // required if getRowClasses ever includes 'deletable' or if .performActionOnRow() is ever invoked on the datagrid
-  void performActionOnCell(in <span>RowSpecification</span> row, in unsigned long column, in DOMString action); // required if .performActionOnCell() is ever invoked on the datagrid
--->
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-renotify">renotify</code>()</dt>
+   <dd>
 
-  </dl>
+    <p>Causes the <code>datagrid</code> to resend notifications to the
+    listener (if any) for any rows or cells that the
+    <code>datagrid</code> does not yet have information for.</p>
 
-  <p>The following classes (for rows, columns, and cells) may be
-  usefully used in conjunction with this interface:</p>
+    <!-- useful, e.g., if there is a server error and the script loses
+    track of what rows it's supposed to be reporting. -->
 
-  <table id="datagridClassSummary">
-   <tr>
-    <th>Class name</th>
-    <th>Applies to</th>
-    <th>Description</th>
-   </tr>
+   </dd>
 
-   <tr>
-    <td><!--checked--><dfn title="datagrid-cell-class-checked"><code>checked</code></dfn></td>
-    <td>Cells</td>
-    <td>The cell has a checkbox and it is checked. (The <code
-    title="datagrid-cell-class-cyclable">cyclable</code> and <code
-    title="datagrid-cell-class-progress">progress</code> classes
-    override this, though.)</td>
-   </tr>
 
-   <tr>
-    <td><!--cyclable--><dfn title="datagrid-cell-class-cyclable"><code>cyclable</code></dfn></td>
-    <td>Cells</td>
-    <td>The cell can be cycled through multiple values. (The <code
-    title="datagrid-cell-class-progress">progress</code> class
-    overrides this, though.)</td>
-   </tr>
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-addColumn">addColumn</code>(<var title="">id</var>, <var title="">label</var>, <var title="">type</var> [, <var title="">icon</var> [, <var title="">sortable</var> [, <var title="">visible</var> ] ] ] )</dt>
+   <dd>
 
-   <tr>
-    <td><!--editable--><dfn title="datagrid-cell-class-editable"><code>editable</code></dfn></td>
-    <td>Cells</td>
-    <td>The cell can be edited. (The <code
-    title="datagrid-cell-class-cyclable">cyclable</code>, <code
-    title="datagrid-cell-class-progress">progress</code>, <code
-    title="datagrid-cell-class-checked">checked</code>, <code
-    title="datagrid-cell-class-checked">unchecked</code> and <code
-    title="datagrid-cell-class-checked">indeterminate</code> classes
-    override this, though.)</td>
-   </tr>
+    <p>Adds a column to the <code>datagrid</code>.</p>
 
-   <tr>
-    <td><!--header--><dfn title="datagrid-row-class-header"><code>header</code></dfn></td>
-    <td>Rows</td>
-    <td>The row is a heading, not a data row.</td>
-   </tr>
+    <p>If a column with the given identifier has already been added,
+    it just replaces the information for that column.</p>
 
-   <tr>
-    <td><!--indeterminate--><dfn title="datagrid-cell-class-indeterminate"><code>indeterminate</code></dfn></td>
-    <td>Cells</td>
-    <td>The cell has a checkbox, and it can be set to an indeterminate
-    state. If neither the <code
-    title="datagrid-cell-class-checked">checked</code> nor <code
-    title="datagrid-cell-class-checked">unchecked</code> classes are
-    present, then the checkbox is in that state, too. (The <code
-    title="datagrid-cell-class-cyclable">cyclable</code> and <code
-    title="datagrid-cell-class-progress">progress</code> classes
-    override this, though.)</td>
-   </tr>
+    <p>The possible types are enumerated in the previous section.</p>
 
-   <tr>
-    <td><!--initially-hidden--><dfn title="datagrid-column-class-initially-hidden"><code>initially-hidden</code></dfn></td>
-    <td>Columns</td>
-    <td>The column will not be shown when the <code>datagrid</code> is
-    initially rendered. If this class is not present on the column
-    when the <code>datagrid</code> is initially rendered, the column
-    will be visible if space allows.</td>
-   </tr>
+   </dd>
 
-   <tr>
-    <td><!--initially-closed--><dfn title="datagrid-row-class-initially-closed"><code>initially-closed</code></dfn></td>
-    <td>Rows</td>
-    <td>The row will be closed when the <code>datagrid</code> is
-    initially rendered. If neither this class nor the <code
-    title="datagrid-row-class-initially-open">initially-open</code>
-    class is present on the row when the <code>datagrid</code> is
-    initially rendered, the initial state will depend on platform
-    conventions.</td>
-   </tr>
 
-   <tr>
-    <td><!--initially-open--><dfn title="datagrid-row-class-initially-open"><code>initially-open</code></dfn></td>
-    <td>Rows</td>
-    <td>The row will be opened when the <code>datagrid</code> is
-    initially rendered. If neither this class nor the <code
-    title="datagrid-row-class-initially-closed">initially-closed</code>
-    class is present on the row when the <code>datagrid</code> is
-    initially rendered, the initial state will depend on platform
-    conventions.</td>
-   </tr>
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortColumn">sortColumn</code> [ = <var title="">value</var> ]</dt>
+   <dd>
 
-   <tr>
-    <td><!--progress--><dfn title="datagrid-cell-class-progress"><code>progress</code></dfn></td>
-    <td>Cells</td>
-    <td>The cell is a progress bar.</td>
-   </tr>
+    <p>Returns the identifier of the column by which the data is to be
+    sorted.</p>
 
-   <tr>
-    <td><!--reversed--><dfn title="datagrid-column-class-reversed"><code>reversed</code></dfn></td>
-    <td>Columns</td>
-    <td>If the cell is sorted, the sort direction is descending,
-    instead of ascending.</td>
-   </tr>
+    <p>Can be set, to indicate that the sort order has changed. This
+    will cause the <code>datagrid</code> to clear its position
+    information for rows, so <code
+    title="dom-datagrid-setRows">setRows()</code> will have to be
+    called again with the new sort order.</p>
 
-   <tr>
-    <td><!--selectable-separator--><dfn title="datagrid-row-class-selectable-separator"><code>selectable-separator</code></dfn></td>
-    <td>Rows</td>
-    <td>The row is a normal, selectable, data row, except that instead
-    of having data, it only has a separator. (The <code
-    title="datagrid-row-class-header">header</code> and <code
-    title="datagrid-row-class-separator">separator</code> classes
-    override this, though.)</td>
-   </tr>
+    <p>The columns are not actually sorted by the
+    <code>datagrid</code>; the data has to be sorted by the script
+    that adds the rows to the <code>datagrid</code>.</p>
 
-   <tr>
-    <td><!--separator--><dfn title="datagrid-row-class-separator"><code>separator</code></dfn></td>
-    <td>Rows</td>
-    <td>The row is a separator row, not a data row. (The <code
-    title="datagrid-row-class-header">header</code> class
-    overrides this, though.)</td>
-   </tr>
+   </dd>
 
-   <tr>
-    <td><!--sortable--><dfn title="datagrid-column-class-sortable"><code>sortable</code></dfn></td>
-    <td>Columns</td>
-    <td>The data can be sorted by this column.</td>
-   </tr>
 
-   <tr>
-    <td><!--sorted--><dfn title="datagrid-column-class-sorted"><code>sorted</code></dfn></td>
-    <td>Columns</td>
-    <td>The data is sorted by this column. Unless the <code
-    title="datagrid-column-class-reversed">reversed</code> class is
-    also present, the sort direction is ascending.</td>
-   </tr>
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortAscending">sortAscending</code> [ = <var title="">value</var> ]</dt>
+   <dd>
 
-   <tr>
-    <td><!--unchecked--><dfn title="datagrid-cell-class-unchecked"><code>unchecked</code></dfn></td>
-    <td>Cells</td>
-    <td>The cell has a checkbox and, unless the <code
-    title="datagrid-cell-class-checked">checked</code> class is
-    present as well, it is unchecked. (The <code
-    title="datagrid-cell-class-cyclable">cyclable</code> and <code
-    title="datagrid-cell-class-progress">progress</code> classes
-    override this, though.)</td>
-   </tr>
+    <p>Returns true if the data is to be sorted with small values
+    first; otherwise, returns false, indicating that bigger values are
+    to be put first.</p>
 
-<!--XXXPA
-   <tr>
-    <td><!- -deletable- -><dfn title="datagrid-row-class-deletable"><code>deletable</code></dfn></td>
-    <td>Rows</td>
-    <td></td>
-   </tr>
--->
+    <p>Can be set, to indicate that the order is about to change.</p>
 
-  </table>
+   </dd>
 
 
-  <h5>The default data provider</h5>
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearColumns">clearColumns</code>()</dt>
+   <dd>
 
-  <p>The user agent must supply a default data provider for the case
-  where the <code>datagrid</code>'s <code
-  title="dom-datagrid-data">data</code> attribute is null. It must act
-  as described in this section.</p>
+    <p>Removes all the columns in the <code>datagrid</code>,
+    reinstating the implied column.</p>
 
-  <p>The behavior of the default data provider depends on the nature
-  of the first element child of the <code>datagrid</code>.</p>
+   </dd>
 
-  <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><var title="">datagrid</var> . <code title="dom-datagrid-setRowCount">setRowCount</code>(<var title="">childCount</var>, <var title="">rowCount</var>)</dt>
+   <dd>
 
-   <dt>While the first element child is a <code>table</code> element</dt>
-
-   <dd>
-
-    <p><strong><code
-    title="dom-provider-getRowCount">getRowCount(<var title="">row</var>)</code></strong>:
-    The number of rows returned by the default data provider for the
-    root of the tree (when <var title="">row</var> is empty) must be the total number of <code>tr</code> elements
-    that are children of <code>tbody</code> elements that are children
-    of the <code>table</code>, if there are any such child
-    <code>tbody</code> elements. If there are no such
-    <code>tbody</code> elements then the number of rows returned for
-    the root must be the number of <code>tr</code> elements that are
-    children of the <code>table</code>.</p>
-
-    <p>When <var title="">row</var> is not empty, the number of rows
-    returned must be zero.</p>
-
-    <p class="note">The <code>table</code>-based default data provider
-    cannot represent a tree.</p>
-
-    <p class="note">Rows in <code>thead</code> elements do not
-    contribute to the number of rows returned, although they do affect
-    the columns and column captions. Rows in <code>tfoot</code>
-    elements are <span title="ignore">ignored</span> completely by
-    this algorithm.</p>
-
-    <p id="defaultDataProviderTableMapper"><strong><code
-    title="dom-provider-getChildAtPosition">getChildAtPosition(<var
-    title="">row</var>, <var title="">i</var>)</code></strong>: The
-    default data provider must return the mapping appropriate to the
-    <a href="#defaultDataProviderTableSort">current sort
-    order</a>.</p>
-
-    <p><strong><code
-    title="dom-provider-getColumnCount">getColumnCount()</code></strong>:
-    The number of columns returned must be the number of
-    <code>td</code> element children in the first <code>tr</code>
-    element child of the first <code>tbody</code> element child of the
-    <code>table</code>, if there are any such <code>tbody</code>
-    elements. If there are no such <code>tbody</code> elements, then
-    it must be the number of <code>td</code> element children in the
-    first <code>tr</code> element child of the <code>table</code>, if
-    any, or otherwise 1. If the number that would be returned by these
-    rules is 0, then 1 must be returned instead.</p>
-
-    <p><strong><code
-    title="dom-provider-getCaptionText">getCaptionText(<var
-    title="">i</var>)</code></strong>: If the <code>table</code> has
-    no <code>thead</code> element child, or if its first
-    <code>thead</code> element child has no <code>tr</code> element
-    child, the default data provider must return the empty string for
-    all captions. Otherwise, the value of the <code>textContent</code>
-    attribute of the <var title="">i</var>th <code>th</code> element
-    child of the first <code>tr</code> element child of the first
-    <code>thead</code> element child of the <code>table</code> element
-    must be returned. If there is no such <code>th</code> element, the
-    empty string must be returned.</p>
-
-    <p><strong><code
-    title="dom-provider-getCaptionClasses">getCaptionClasses(<var
-    title="">i</var>, <var title="">classes</var>)</code></strong>: If
-    the <code>table</code> has no <code>thead</code> element child, or
-    if its first <code>thead</code> element child has no
-    <code>tr</code> element child, the default data provider must not
-    add any classes for any of the captions. Otherwise, each class
-    in the <code title="attr-class">class</code> attribute of the <var
-    title="">i</var>th <code>th</code> element child of the first
-    <code>tr</code> element child of the first <code>thead</code>
-    element child of the <code>table</code> element must be added to
-    the <var title="">classes</var>. If there is no such
-    <code>th</code> element, no classes must be added. The user agent
-    must then:</p>
+    <p>Sets the numbers of rows in the <code>datagrid</code>,
+    excluding rows that are descendants of rows that are closed.</p>
 
-    <ol>
+    <p>Throws a <code>DATAGRID_MODEL_ERR</code> exception if the
+    arguments contradict each other or previously declared information
+    (e.g. declaring that the <code>datagrid</code> has three rows when
+    the 12th row has been declared).</p>
+
+   </dd>
+
+
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-setRows">setRows</code>(<var title="">rows</var>)</dt>
+   <dd>
+
+    <p>Updates data for rows in the <code>datagrid</code>, or fills in
+    data for rows previously implied by a call to <code
+    title="dom-datagrid-setRowCount">setRowCount()</code> but not
+    previously declared.</p>
+
+    <p>The <var title="">rows</var> argument is an array of rows, each
+    represented by a further array consisting of:</p>
+
+    <ol class="brief">
 
-     <li>Remove the <code
-     title="datagrid-column-class-sorted">sorted</code> and <code
-     title="datagrid-column-class-reversed">reversed</code>
-     classes.</li>
+     <li>A <code>RowID</code> object identifying the row.</li>
 
-     <li>If the <code>table</code> element has a <code
-     title="attr-class">class</code> attribute that includes the <code
-     title="">sortable</code> class, add the <code
-     title="datagrid-column-class-sortable">sortable</code>
-     class.</li>
+     <li>An integer giving the position of the row in its parent,
+     given the current sort order, or &#x2212;1 to set other row data
+     without setting a position or changing a previously declared
+     position.</li>
 
-     <li>If the column is the one currently being used to
-     sort the data, add the <code
-     title="datagrid-column-class-sorted">sorted</code> class.</li>
+     <li>An integer giving the number of children of the row, or 0 if
+     the row has no children, or &#x2212;1 if the row has children but
+     the count is currently unknown. If the number of children has
+     already been set to 0 or a positive integer, then passing
+     &#x2212;1 leaves the previous count unchanged.</li>
 
-     <li>If the column is the one currently being used to sort the
-     data, and it is sorted in descending order, add the <code
-     title="datagrid-column-class-reversed">reversed</code> class as
-     well.</li>
+     <li>An array giving the data for zero or more cells in the row,
+     as described below.</li>
+
+     <li>A boolean declaring whether the row is open or not. This
+     entry, if omitted, is assumed to be false (closed), unless the
+     row has already been declared as open.</li>
+
+     <li>An integer giving the number of rows that are descendants of
+     this row, excluding those that are descendants of descendants of
+     this row that are closed. This entry can be omitted if the row is
+     closed or if it has already been declared.</li>
 
     </ol>
 
-    <p>The various row- and cell- related methods operate relative to
-    a particular element, the element of the row or cell specified by
-    their arguments.</p>
-
-    <p><strong>For rows</strong>: Since the default data provider for
-    a <code>table</code> always returns 0 as the number of children
-    for any row other than the root, the path to the row passed to
-    these methods will always consist of a single number. In the prose
-    below, this number is referred to as <var title="">i</var>.</p>
-
-    <p>If the <code>table</code> has <code>tbody</code> element
-    children, the element for the <var title="">i</var>th row is the
-    <var title="">i</var>th <code>tr</code> element that is a child of
-    a <code>tbody</code> element that is a child of the
-    <code>table</code> element. If the <code>table</code> does not
-    have <code>tbody</code> element children, then the element for the
-    <var title="">i</var>th real row is the <var title="">i</var>th
-    <code>tr</code> element that is a child of the <code>table</code>
-    element.</p>
+    <p>The array giving the data for the cells in the row consists of
+    a further set of arrays, one per cell. The first item of each of
+    these arrays is the column's identifier; the subsequent values
+    vary based on the type of the column, as follows:</p>
 
-    <p><strong>For cells</strong>: Given a row and its element, the
-    row's <var title="">i</var>th cell's element is the <var
-    title="">i</var>th <code>td</code> element child of the row
-    element.</p>
+    <dl>
 
-    <p class="note">The <code>colspan</code> and <code>rowspan</code>
-    attributes are <span title="ignore">ignored</span> by this
-    algorithm.</p>
+     <dt><code title="datagrid-type-text">text</code></dt>
+     <dd>
+      <ol class="brief">
+       <li>A string giving the cell's value.
+       <li>Optionally, an <code>img</code> element giving an icon for the cell.
+      </ol>
+     </dd>
 
-    <p><strong><code title="dom-provider-getRowImage">getRowImage(<var
-    title="">i</var>)</code></strong>: The <span>URL</span> of the
-    row's image is the <span>absolute URL</span> obtained by <span
-    title="resolve a url">resolving</span> the value of the <code
-    title="attr-img-src">src</code> attribute of the first
-    <code>img</code> element child of the row's first cell's element,
-    relative to that element, if there is one and resolving its
-    attribute is successful. Otherwise, the <span>URL</span> of the
-    row's image is the empty string.</p> <!-- note that if the base
-    URL has changed, this URL can be different than the one that the
-    <img> element fetched when it was created -->
-
-    <p><strong><code title="dom-provider-getRowMenu">getRowMenu(<var
-    title="">i</var>)</code></strong>: If the row's first cell's
-    element has a <code>menu</code> element child, then the row's menu
-    is the first <code>menu</code> element child of the row's first
-    cell's element. Otherwise, the row has no menu.</p>
-
-    <p><strong><code
-    title="dom-provider-getRowClasses">getRowClasses(<var
-    title="">i</var>, <var title="">classes</var>)</code></strong>:
-    The default data provider must never add a class to the row's
-    classes.</p>
-
-    <p id="defaultDataProviderTableSort"><strong><code
-    title="dom-provider-toggleColumnSortState">toggleColumnSortState(<var
-    title="">i</var>)</code></strong>: If the data is already being
-    sorted on the given column, then the user agent must change the
-    current sort mapping to be the inverse of the current sort
-    mapping; if the sort order was ascending before, it is now
-    descending, otherwise it is now ascending. Otherwise, if the
-    current sort column is another column, or the data model is
-    currently not sorted, the user agent must create a new mapping,
-    which maps rows in the data model to rows in the DOM so that the
-    rows in the data model are sorted by the specified column, in
-    ascending order. (Which sort comparison operator to use is left up
-    to the UA to decide.)</p>
-
-    <p>When the sort mapping is changed, the values returned by the
-    <code
-    title="dom-provider-getChildAtPosition">getChildAtPosition()</code>
-    method for the default data provider <a
-    href="#defaultDataProviderTableMapper">will change
-    appropriately</a>.</p>
-
-    <p><strong><code title="dom-provider-getCellData">getCellData(<var
-    title="">i</var>, <var title="">j</var>)</code>, <code
-    title="dom-provider-getCellClasses">getCellClasses(<var
-    title="">i</var>, <var title="">j</var>, <var
-    title="">classes</var>)</code>, <code
-    title="dom-provider-setCellCheckedState">getCellCheckedState(<var
-    title="">i</var>, <var title="">j</var>, <var
-    title="">state</var>)</code>, <code
-    title="dom-provider-cycleCell">cycleCell(<var title="">i</var>,
-    <var title="">j</var>)</code>, and <code
-    title="dom-provider-editCell">editCell(<var title="">i</var>,
-    <var title="">j</var>, <var title="">data</var>)</code></strong>:
-    See <a href="#commonDefaultDataGridMethodDefinitions">the common
-    definitions below</a>.</p>
-
-    <p>The data provider must call the <code>datagrid</code>'s update
-    methods appropriately whenever the descendants of the
-    <code>datagrid</code> mutate. For example, if a <code>tr</code> is
-    removed, then the <code
-    title="dom-datagrid-updateRowsRemoved">updateRowsRemoved()</code>
-    methods would probably need to be invoked, and any change to a
-    cell or its descendants must cause the cell to be updated. If the
-    <code>table</code> element stops being the first child of the
-    <code>datagrid</code>, then the data provider must call the <code
-    title="dom-datagrid-updateEverything">updateEverything()</code>
-    method on the <code>datagrid</code>. Any change to a cell that is
-    in the column that the data provider is currently using as its
-    sort column must also cause the sort to be reperformed, with a
-    call to <code
-    title="dom-datagrid-updateEverything">updateEverything()</code> if
-    the change did affect the sort order.</p>
-
-   </dd>
-
-
-   <dt>While the first element child is a <code>select</code> or <code>datalist</code> element</dt>
-
-   <dd>
-
-    <p>The default data provider must return 1 for the column count,
-    the empty string for the column's caption, and must not add any
-    classes to the column's classes.</p>
-
-    <p>For the rows, assume the existence of a node filter view of the
-    descendants of the first element child of the
-    <code>datagrid</code> element (the <code>select</code> or
-    <code>datalist</code> element), that skips all nodes other than
-    <code>optgroup</code> and <code>option</code> elements, as well as
-    any descendants of any <code>option</code> elements.</p>
-
-    <p>Given a path <var title="">row</var>, the corresponding element
-    is the one obtained by drilling into the view, taking the child
-    given by the path each time.</p>
+     <dt><code title="datagrid-type-editable">editable</code></dt>
+     <dd>
+      <ol class="brief">
+       <li>A string giving the cell's value.
+       <li>Optionally, a <code>datalist</code> element giving a set of predefined options.
+       <li>Optionally, an <code>img</code> element giving an icon for the cell.
+      </ol>
+     </dd>
 
-    <div class="example">
+     <dt><code title="datagrid-type-checkable">checkable</code></dt>
+     <dd>
+      <ol class="brief">
+       <li>A string giving the cell's value.
+       <li>A boolean, indicating whether the cell is checked (true) or not (false).
+       <li>Optionally, a boolean indicating whether the value of the cell is obscured as indeterminate (true), or not (false).
+       <li>Optionally, an <code>img</code> element giving an icon for the cell.
+      </ol>
+     </dd>
 
-     <p>Given the following XML markup:</p>
-
-     <pre>&lt;datagrid>
- &lt;select>
-  &lt;!-- the options and optgroups have had their labels and values removed
-       to make the underlying structure clearer -->
-  &lt;optgroup>
-   &lt;option/>
-   &lt;option/>
-  &lt;/optgroup>
-  &lt;optgroup>
-   &lt;option/>
-   &lt;optgroup id="a">
-    &lt;option/>
-    &lt;option/>
-    &lt;bogus/>
-    &lt;option id="b"/>
-   &lt;/optgroup>
-   &lt;option/>
-  &lt;/optgroup>
- &lt;/select>
-&lt;/datagrid></pre>
-
-     <p>The path "1,1,2" would select the element with ID "b". In the
-     filtered view, the text nodes, comment nodes, and bogus elements
-     are ignored; so for instance, the element with ID "a" (path
-     "1,1") has only 3 child nodes in the view.</p>
+     <dt><code title="datagrid-type-list">list</code></dt>
+     <dd>
+      <ol class="brief">
+       <li>A string giving the cell's current value.
+       <li>A <code>select</code> element giving the <span title="concept-select-option-list">list of options</span>.
+       <li>Optionally, an <code>img</code> element giving an icon for the cell.
+      </ol>
+     </dd>
 
-    </div>
+     <dt><code title="datagrid-type-progress">progress</code></dt>
+     <dd>
+      <ol class="brief">
+       <li>A value in the range 0.0 (no progress) to 1.0 (task complete).
+      </ol>
+     </dd>
 
-    <p><code title="dom-provider-getRowCount">getRowCount(<var
-    title="">row</var>)</code> must drill through the view to find the
-    element corresponding to the method's argument, and return the
-    number of child nodes in the filtered view that the corresponding
-    element has. (If the <var title="">row</var> is empty, the
-    corresponding element is the <code>select</code> element at the
-    root of the filtered view.)</p>
-
-    <p><code
-    title="dom-provider-getChildAtPosition">getChildAtPosition(<var
-    title="">row</var>, <var title="">position</var>)</code> must
-    return <var title="">position</var>. (The
-    <code>select</code>/<code>datalist</code> default data provider
-    does not support sorting the data grid.)</p>
-
-    <p><code title="dom-provider-getRowImage">getRowImage(<var
-    title="">i</var>)</code> must return the empty string, <code
-    title="dom-provider-getRowMenu">getRowMenu(<var
-    title="">i</var>)</code> must return null.</p>
-
-    <p><code title="dom-provider-getRowClasses">getRowClasses(<var
-    title="">row</var>, <var title="">classes</var>)</code> must add the
-    classes from the following list to <var title="">classes</var>
-    when their condition is met:</p>
+     <dt><code title="datagrid-type-meter">meter</code></dt>
+     <dd>
+      <ol class="brief">
+       <li>A number giving the cell's value.
+       <li>Optionally, a number giving the maximum value, if it's not 1.
+       <li>Optionally, a number giving the minimum value, if it's not 0.
+       <li>Optionally, a number giving the highest value that is considered "low".
+       <li>Optionally, a number giving the lowest value that is considered "high".
+       <li>Optionally, a number giving the value that is considered optimal.
+      </ol>
+     </dd>
 
-    <ul>
+     <dt><code title="datagrid-type-custom">custom</code></dt>
+     <dd>
+      <ol class="brief">
+       <li>A number giving the minimum width of the cell, in CSS pixels, that is desired.
+       <li>A number giving the minimum height of the cell, in CSS pixels, that is desired.
+       <li>A function that is passed a <code>CanvasRenderingContext2D</code> object, along with the width and height (in CSS pixels) of the cell that the context will draw on.
+      </ol>
+     </dd>
+
+    </dl>
 
-     <li>If the <var title="">row</var>'s corresponding element is an
-     <code>optgroup</code> element: <code
-     title="datagrid-row-class-header">header</code></li>
+    <p>While the rows in a single call to the <code
+    title="dom-datagrid-setRows">setRows()</code> method can be in any
+    order, for each row, it is important that all its ancestor rows
+    and all its open previous siblings are also declared, either in
+    the same call or in an earlier one.</p>
 
-     <li>If the <var title="">row</var>'s corresponding element
-     contains other elements that are also in the view, and the
-     element's <code title="attr-class">class</code> attribute
-     contains the <code title="">closed</code> class: <code
-     title="datagrid-row-class-initially-closed">initially-closed</code></li>
+    <p>Throws a <code>DATAGRID_MODEL_ERR</code> exception if the
+    arguments contradict each other or previously declared information
+    (e.g. saying that a row's position is 5 when the parent row only
+    has 3 children, or naming a column that doesn't exist, or
+    declaring a row without declaring its parent, or changing the
+    number of children that a row has while that row and its ancestors
+    are all open).</p>
 
-     <li>If the <var title="">row</var>'s corresponding element
-     contains other elements that are also in the view, and the
-     element's <code title="attr-class">class</code> attribute
-     contains the <code title="">open</code> class: <code
-     title="datagrid-row-class-initially-open">initially-open</code></li>
+   </dd>
 
-    </ul>
 
-    <p>The <code title="dom-provider-getCellData">getCellData(<var
-    title="">row</var>, <var title="">cell</var>)</code> method must
-    return the value of the <code
-    title="attr-optgroup-label">label</code> attribute if the <var
-    title="">row</var>'s corresponding element is an
-    <code>optgroup</code> element, otherwise, if the <var
-    title="">row</var>'s corresponding element is an
-    <code>option</code>element, its <code
-    title="attr-option-label">label</code> attribute if it has one,
-    otherwise the value of its <code>textContent</code> DOM
-    attribute.</p>
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-insertRows">insertRows</code>(<var title="">rows</var>)</dt>
+   <dd>
 
-    <p>The <code
-    title="dom-provider-getCellClasses">getCellClasses(<var
-    title="">row</var>, <var title="">cell</var>, <var
-    title="">classes</var>)</code> method must add no classes.</p>
+    <p>Inserts the given rows into the <code>datagrid</code>,
+    increasing the numbers of rows that the <code>datagrid</code>
+    assumes are present.</p>
 
-    <p class="XXX"><!-- select-provider-selection
-    XXX-->autoselect some rows when initialized, reflect the selection
-    in the select, reflect the multiple attribute somehow.</p>
+    <p>The <var title="">rows</var> argument is an array of rows in
+    the same structure as the argument to the <code
+    title="dom-datagrid-setRows">setRows()</code> method described
+    above, with the same expectations of consistency (a given row's
+    ancestors and earlier open siblings being listed either earlier or
+    in the same call as a given row). However, unlike with the <code
+    title="dom-datagrid-setRows">setRows()</code> method, if a row is
+    inserted along with its child, the child is not included in the
+    child and row counts of the parent row; every row in the <var
+    title="">rows</var> argument will increase its parent's counts
+    automatically.</p>
 
-    <p>The data provider must call the <code>datagrid</code>'s update
-    methods appropriately whenever the descendants of the
-    <code>datagrid</code> mutate.</p>
+    <p>Throws a <code>DATAGRID_MODEL_ERR</code> exception if the
+    arguments contradict each other or previously declared
+    information.</p>
 
    </dd>
 
 
-   <dt>While the first element child is another element</dt>
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-deleteRows">deleteRows</code>(<var title="">rows</var>)</dt>
+   <dd>
+
+    <p>Removes the given rows from the <code>datagrid</code>, and
+    updates the number of rows known to be in the
+    <code>datagrid</code> accordingly. The argument is an array of
+    <code>RowID</code> objects identifying the rows to remove.</p>
+
+    <p>Throws a <code>DATAGRID_MODEL_ERR</code> exception if the argument
+    includes a row the <code>datagrid</code> doesn't know about.</p>
+    <!-- since otherwise behaviour might depend on where the user
+    scrolled! -->
+
+   </dd>
+
 
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-repaint">repaint</code>(<var title="">row</var>, <var title="">column</var>)</dt>
    <dd>
 
-    <p>The default data provider must return 1 for the column count,
-    the empty string for the column's caption, and must not add any
-    classes to the column's classes.</p>
+    <p>If the given column's type is <code
+    title="datagrid-type-custom">custom</code>, then causes the
+    <code>datagrid</code> to reinvoke the function that obtains the
+    desired rendering.</p>
 
-    <p>For the rows, assume the existence of a node filter view of the
-    descendants of the <code>datagrid</code> that skips all nodes
-    other than <code>li</code>, <code>h1</code>&ndash;<code>h6</code>, and
-    <code>hr</code> elements, and skips any descendants of
-    <code>menu</code> elements.</p>
+   </dd>
 
-    <p>Given this view, each element in the view represents a row in
-    the data model. The element corresponding to a path <var
-    title="">row</var> is the one obtained by drilling into the view,
-    taking the child given by the path each time. The element of the
-    row of a particular method call is the element given by drilling
-    into the view along the path given by the method's arguments.</p>
 
-    <p><code title="dom-provider-getRowCount">getRowCount(<var
-    title="">row</var>)</code> must return the number of child
-    elements in this view for the given row, or the number of elements
-    at the root of the view if the <var title="">row</var> is
-    empty.</p>
+   <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearRows">clearRows</code>()</dt>
+   <dd>
 
-    <div class="example">
+    <p>Clears the <code>datagrid</code> of all row data, resetting it
+    to empty<!-- v2DGS:, and clears the selection-->.</p>
 
-     <p>In the following example, the elements are identified by the
-     paths given by their child text nodes:</p>
+   </dd>
 
-     <pre>&lt;datagrid>
- &lt;ol>
-  &lt;li> row 0 &lt;/li>
-  &lt;li> row 1
-   &lt;ol>
-    &lt;li> row 1,0 &lt;/li>
-   &lt;/ol>
-  &lt;/li>
-  &lt;li> row 2 &lt;/li>
- &lt;/ol>
-&lt;/datagrid></pre>
+  </dl>
 
-     <p>In this example, only the <code>li</code> elements actually
-     appear in the data grid; the <code>ol</code> element does not
-     affect the data grid's processing model.</p>
 
-    </div>
+  <div class="impl">
 
-    <p><code
-    title="dom-provider-getChildAtPosition">getChildAtPosition(<var
-    title="">row</var>, <var title="">position</var>)</code> must
-    return <var title="">position</var>. (The generic default data
-    provider does not support sorting the data grid.)</p>
-
-    <p><code title="dom-provider-getRowImage">getRowImage(<var
-    title="">i</var>)</code> must return the <span>absolute URL</span>
-    obtained from <span title="resolve a url">resolving</span> the
-    value of the <code title="attr-img-src">src</code> attribute of
-    the first <code>img</code> element descendant (in the real DOM) of
-    the row's element, that is not also a descendant of another
-    element in the filtered view that is a descendant of the row's
-    element, if such an element exists and resolving its attribute
-    relative to the element itself, is successful. Otherwise, it must
-    return the empty string.</p> <!-- note that if the base URL has
-    changed, this URL can be different than the one that the <img>
-    element fetched when it was created -->
+  <h6>The listener</h6>
 
-    <div class="example">
+  <p>The <dfn
+  title="dom-datagrid-listener"><code>listener</code></dfn> DOM
+  attribute allows authors to specify an object that will receive all
+  the notifications from the <code>datagrid</code>. Initially, its
+  value must be null. On getting, it must return its value. On
+  setting, its value must be set to the new value, and then the user
+  agent must <span>queue a task</span> to call the <code
+  title="dom-listener-initialize">initalize()</code> method with the
+  <code>datagrid</code> element as its only argument.</p>
 
-     <p>In the following example, the row with path "1,0" returns
-     "http://example.com/a" as its image URL, and the other rows
-     (including the row with path "1") return the empty string:</p>
 
-     <pre>&lt;datagrid>
- &lt;ol>
-  &lt;li> row 0 &lt;/li>
-  &lt;li> row 1
-   &lt;ol>
-    &lt;li> row 1,0 &lt;img src="http://example.com/a" alt=""> &lt;/li>
-   &lt;/ol>
-  &lt;/li>
-  &lt;li> row 2 &lt;/li>
- &lt;/ol>
-&lt;/datagrid></pre>
+  <h6>The columns</h6>
 
-    </div>
+  <p>The columns are represented by the <dfn>column list</dfn>, an
+  ordered list of entries for columns, each of which consists of:</p>
 
-    <p><code title="dom-provider-getRowMenu">getRowMenu(<var
-    title="">i</var>)</code> must return the first <code>menu</code>
-    element descendant (in the real DOM) of the row's element, that is
-    not also a descendant of another element in the filtered view that
-    is a descendant of the row's element. (This is analogous to the
-    image case above.)</p>
+  <dl>
 
-    <p><code title="dom-provider-getRowClasses">getRowClasses(<var
-    title="">i</var>, <var title="">classes</var>)</code> must add the
-    classes from the following list to <var title="">classes</var>
-    when their condition is met:</p>
+   <dt>An identifier</dt>
 
-    <ul>
+   <dd>A string used to identify the column in the API.</dd>
 
-     <li>If the row's element contains other elements that are also in
-     the view, and the element's <code title="attr-class">class</code>
-     attribute contains the <code title="">closed</code> class: <code
-     title="datagrid-row-class-initially-closed">initially-closed</code></li>
+   <dt>A label</dt>
 
-     <li>If the row's element contains other elements that are also in
-     the view, and the element's <code title="attr-class">class</code>
-     attribute contains the <code title="">open</code> class: <code
-     title="datagrid-row-class-initially-open">initially-open</code></li>
+   <dd>A string used in the user interface.</dd>
 
-     <li>If the row's element is an <code>h1</code>&ndash;<code>h6</code>
-     element: <code
-     title="datagrid-row-class-header">header</code></li>
+   <dt>A type</dt>
 
-     <li>If the row's element is an <code>hr</code> element: <code
-     title="datagrid-row-class-separator">separator</code></li> <!--
-     XXX no way to get selectable-separator -->
+   <dd>One of the types described below.</dd>
 
-    </ul>
+   <dt>An icon</dt>
 
-    <p>The <code title="dom-provider-getCellData">getCellData(<var
-    title="">i</var>, <var title="">j</var>)</code>, <code
-    title="dom-provider-getCellClasses">getCellClasses(<var
-    title="">i</var>, <var title="">j</var>, <var
-    title="">classes</var>)</code>, <code
-    title="dom-provider-setCellCheckedState">getCellCheckedState(<var
-    title="">i</var>, <var title="">j</var>, <var
-    title="">state</var>)</code>, <code
-    title="dom-provider-cycleCell">cycleCell(<var title="">i</var>,
-    <var title="">j</var>)</code>, and <code
-    title="dom-provider-editCell">editCell(<var title="">i</var>, <var
-    title="">j</var>, <var title="">data</var>)</code> methods must
-    act as described in <a
-    href="#commonDefaultDataGridMethodDefinitions">the common
-    definitions below</a>, treating the row's element as being the
-    cell's element.</p>
+   <dd>An image, copied from an <code>img</code> element when the
+   column was declared.</dd>
 
-    <p class="XXX" id="generic-provider-selection">selection
-    handling?</p>
+   <dt>Whether the column is sortable</dt>
 
-    <p>The data provider must call the <code>datagrid</code>'s update
-    methods appropriately whenever the descendants of the
-    <code>datagrid</code> mutate.</p>
+   <dd>A boolean indicating whether the user can request that the data
+   be sorted by this column (true), or not (false).</dd>
 
-   </dd>
+   <dt>Whether the column is visible</dt>
+
+   <dd>A boolean indicating whether the column is part of the
+   <code>datagrid</code>'s rendering.</dd>
+
+  </dl>
+
+  <p>Initially, the <span>column list</span> must have a single
+  column, the <dfn>default column</dfn>, whose identifier is the empty
+  string, whose label is the empty string, whose type is <code
+  title="datagrid-type-text">text</code>, with no icon, which is not
+  sortable, and which <em>is</em> visible.</p>
+
+  <hr>
+
+  <p>The <dfn title="dom-datagrid-addColumn"><code>addColumn(<var
+  title="">id</var>, <var title="">label</var>, <var
+  title="">type</var>, <var title="">icon</var>, <var
+  title="">sortable</var>, <var title="">visible</var>)</code></dfn>
+  method must run the following steps:</p>
+
+  <ol>
+
+   <li><p>If there is already an entry in <span>column list</span>,
+   other than the <span>default column</span>, whose identifier is
+   <var title="">id</var>, throw a <code>DATAGRID_MODEL_ERR</code>
+   exception and abort these steps.</p></li>
+
+   <li>
+
+    <p>If <var title="">type</var> is not a string equal to one of the
+    <span>allowed <code>datagrid</code> column types</span>, then
+    throw a <code>DATAGRID_MODEL_ERR</code> exception and abort these
+    steps.</p>
+
+   </li>
+
+   <li><p>If the <var title="">icon</var> argument is present and not
+   null, and the given <code>img</code> element's <code
+   title="dom-img-complete">complete</code> attribute is false, then
+   throw an <code>INVALID_STATE_ERR</code> exception and abort these
+   steps.</p></li>
+
+   <li><p>If the <var title="">icon</var> argument is present and not
+   null, then copy the image data from that <code>img</code> element,
+   and let <var title="">image</var> be the copy of that image
+   data. Otherwise, let <var title="">image</var> be nothing.</p></li>
+
+   <li><p>Append a new entry to the <span>column list</span>, with
+   <var title="">id</var> as its identifier, <var title="">label</var>
+   as its label, <var title="">type</var> as its type, and <var
+   title="">image</var> as its icon. Let the column be sortable if the
+   <var title="">sortable</var> argument is present and true, and make
+   it visible if the <var title="">visible</var> argument is absent or
+   true.</p></li>
 
+   <li><p>If the <span>column list</span> contains the <span>default
+   column</span>, then remove the <span>default column</span> from the
+   <span>column list</span>, discard any data for cells in that column
+   in any rows in the <code>datagrid</code>, set <code
+   title="dom-datagrid-sortColumn">sortColumn</code> to <var
+   title="">id</var>, set <code
+   title="dom-datagrid-sortAscending">sortAscending</code> to true,
+   and run the <span><code>datagrid</code> resort
+   steps</span>.</p></li>
 
-   <dt>Otherwise, while there is no element child</dt>
+  </ol>
+
+  <hr>
+
+  <p>The <dfn
+  title="dom-datagrid-sortColumn"><code>sortColumn</code></dfn> DOM
+  attribute gives the current column used for sorting.  Initially, its
+  value must be the empty string. On getting, it must return its
+  current value. On setting, if the new value doesn't match the
+  identifier of one of the columns in the <span>column list</span>,
+  then the user agent must throw a <code>DATAGRID_MODEL_ERR</code>
+  exception. Otherwise, if the new value is not the same as its
+  current value, then the user agent must set the attribute to the new
+  value, and then run the <span><code>datagrid</code> resort
+  steps</span>.</p>
+
+  <p>The <dfn
+  title="dom-datagrid-sortAscending"><code>sortAscending</code></dfn>
+  DOM attribute specifies the direction that the tree is sorted in,
+  ascending (true) or descending (false). Initially, its value must be
+  true (ascending). On getting, it must return its current value. On
+  setting, if the new value is not the same as its current value, then
+  the user agent must set the attribute to the new value, and then run
+  the <span><code>datagrid</code> resort steps</span>.</p>
+
+  <p>When a column is marked as being sortable, the user agent should
+  allow the user to select that column to be the column used for
+  sorting, and should allow the user to chose whether the sort order
+  is ascending or descending.</p>
+
+  <p>When the user changes the sort order in this manner, the user
+  agent must update the <code
+  title="dom-datagrid-sortColumn">sortColumn</code> and <code
+  title="dom-datagrid-sortAscending">sortAscending</code> attributes
+  appropriately, and then run the <span><code>datagrid</code> resort
+  steps</span>.</p>
+
+  <p class="note">The <span><code>datagrid</code> resort steps</span>
+  are described in the next section.</p>
+
+  <hr>
+  
+  <p>The <dfn
+  title="dom-datagrid-clearColumns"><code>clearColumns()</code></dfn>
+  method, if the <span>column list</span> doesn't contain the
+  <span>default column</span>, must empty the <span>column
+  list</span>, append the <span>default column</span> to the now empty
+  <span>column list</span>, discard any data for cells in all rows in
+  the <code>datagrid</code>, set <code
+  title="dom-datagrid-sortColumn">sortColumn</code> to the empty
+  string, set <code
+  title="dom-datagrid-sortAscending">sortAscending</code> to true, and
+  run the <span><code>datagrid</code> resort steps</span>. (If the
+  <span>column list</span> is already just the <span>default
+  column</span>, then the method does nothing.)</p>
+
+
+  <h6>The rows</h6>
+
+  <p>A <code>datagrid</code> element is intended to show a
+  representation of a tree, where typically the user only sees a
+  small part of the tree at a time.</p>
+
+  <p>To make this efficent, the <code>datagrid</code> element
+  <em>actually</em> shows a small part of a <em>sparse</em> tree, so
+  that only relevant parts of the data structure need be loaded at any
+  time. Specifically, the model requires only that all the ancestor
+  rows of the displayed rows be loaded, as well as any open earlier
+  siblings (in the displayed sort order) of the displayed rows.</p>
+
+  <p>Conceptually, therefore, a <code>datagrid</code> has a number of
+  related sparse data structures backing it.</p>
+
+  <p>The first is the <dfn>natural order sparse data tree</dfn>. This
+  is the structure in which rows are entered as they are declared, in
+  their natural order. This can differ from the order actually
+  displayed to the user. It consists of nested sparse lists of
+  rows. In the <span>natural order sparse data tree</span>, a row will
+  always have all its parents already declared. Once a row is added to
+  this structure, it can only be removed by the <code
+  title="dom-datagrid-deleteRows">deleteRows()</code> and <code
+  title="dom-datagrid-clearRows">clearRows()</code> methods. The order of
+  nodes in this tree never changes; to move a node in this tree, it
+  has to be removed and then another row (with the same data)
+  reinserted elsewhere.</p>
+
+  <p>The second structure is the <dfn>display order sparse data
+  tree</dfn>. This is a similar structure that contains a subset of
+  the rows in the <span>natural order sparse data tree</span>, ordered
+  in the order given by the <code
+  title="dom-datagrid-sortAscending">sortAscending</code> and <code
+  title="dom-datagrid-sortColumn">sortColumn</code> attributes, and
+  excluding rows with one or more ancestors that are closed. This tree
+  is cleared whenever the <code
+  title="dom-datagrid-sortAscending">sortAscending</code> and <code
+  title="dom-datagrid-sortColumn">sortColumn</code> attributes
+  change.</p>
+
+  <p>The third structure is the <dfn>display order sparse data
+  list</dfn>. This structure is a flattened representation of the
+  <span>display order sparse data tree</span>.</p>
+
+  <p>At any time, a number of consecutive rows in the <span>display
+  order sparse data list</span> are physically visible to the
+  user. The <code>datagrid</code> fires notifications to a <span
+  title="dom-datagrid-listener">listener</span> (provided by script),
+  and the listener, or other some script, is expected to feed the
+  <code>datagrid</code> with the information needed to render the
+  control.</p>
+
+  <p>A <code>datagrid</code> has a <dfn>pending <code>datagrid</code>
+  rows list</dfn>, which is a list of rows in the <span>display order
+  sparse data list</span> for which the <code>datagrid</code> has sent
+  notifications requesting information but not yet received
+  information about.</p>
+
+  <p>A <code>datagrid</code> also has a <dfn>pending
+  <code>datagrid</code> <em>cells</em> list</dfn>, which is a list of
+  row/column pairs (cells) for which the <code>datagrid</code> has
+  sent notifications requesting information but not yet received
+  information about.</p>
+
+  <p>User agents may discard information about rows that are not
+  displayed and that are not ancestors or open earlier siblings of
+  rows or ancestors of rows that are displayed.</p>
+
+  <hr>
+
+  <p>These structures are different views of the collection of rows
+  that form the <code>datagrid</code>. Each row has the following
+  information associated with it:</p>
+
+  <dl>
+
+   <dt>A parent</dt>
+
+   <dd><p>Either another row, or the <code>datagrid</code> itself. This
+   is the parent of the row in the <span>natural order sparse data
+   tree</span> and the <span>display order sparse data tree</span>
+   for the <code>datagrid</code>.</p></dd>
+
+   <dt>A natural order position relative to the other rows with the
+   same parent</dt>
 
    <dd>
 
-    <p>The data provider must return 0 for the number of rows, 1 for
-    the number of columns, the empty string for the first column's
-    caption, and must add no classes when asked for that column's
-    classes. If the <code>datagrid</code>'s child list changes such
-    that there is a first element child, then the data provider must
-    call the <code
-    title="dom-datagrid-updateEverything">updateEverything()</code>
-    method on the <code>datagrid</code>.</p>
+    <p>This is the number of rows that precede this row under the same
+    parent in the <span>natural order sparse data tree</span>. This
+    number can't be changed relative to other rows in the same parent;
+    to change the relative natural order of data in the
+    <code>datagrid</code>, the original rows have to be removed and
+    new rows (with the same data but different natural positions)
+    inserted in their place. (The exact number of a row can change, as
+    new rows can be inserted above it.)</p>
+
+    <p>A row can be identified by a <code>RowID</code> object. This is
+    an array of numbers, consisting of the natural order positions of
+    each ancestor row and the row itself, starting from the furthest
+    ancestor. Thus, for instance, the fourth child row of the first
+    child row of the second row in a <code>datagrid</code> would be
+    identified by a <code>RowID</code> object whose value is <code
+    title="">[1, 0, 3]</code>. A row's identifier changes if rows are
+    <span title="dom-datagrid-insertRows">inserted before it</span> in
+    the <code>datagrid</code>.</p>
 
    </dd>
 
+   <dt>A display order position relative to the other rows with
+   the same parent</dt>
+
+   <dd><p>This is the number of rows that precede this row under the
+   same parent in the <span>display order sparse data
+   tree</span>. This number can be unknown. If the sort order
+   changes, then this information is lost (as the <span>display order
+   sparse data tree</span> is cleared).</p></dd>
+
+   <dt>A child count</dt>
+
+   <dd><p>The number of rows that have this row as a parent. If this is
+   zero, the row cannot be opened. If this is &#x2212;1, then the
+   child count is unknown but the row can be opened. This value can be
+   changed by the <code title="dom-datagrid-setRows">setRows()</code>
+   method only if the current value is &#x2212;1 or if the row or one
+   of its ancestors is closed. Otherwise, it can only be changed
+   indirectly using the <code
+   title="dom-datagrid-insertRows">insertRows()</code> and <code
+   title="dom-datagrid-deleteRows">deleteRows()</code> methods.</p></dd>
+
+   <dt>An open flag</dt>
+
+   <dd><p>A boolean indicating whether the row is open (true) or
+   closed (false). Once set, can only be changed by the user or if one
+   of the row's ancestors is itself closed. A row can also be in a
+   third state, "opening", which is treated as closed for all purposes
+   except that the user agent may indicate that the row is in this
+   special state, and except that when the row is updated to have a
+   row count, the row will switch to being open.</p></dd>
+
+   <dt>A row count</dt>
+
+   <dd><p>The number of rows that have this row as a parent or
+   ancestor, and that do not have an ancestor that is a descendant of
+   this row that is itself closed. If this is &#x2212;1, then the row
+   count is unknown. This value can be changed by the <code
+   title="dom-datagrid-setRows">setRows()</code> method only if the
+   row or one of its ancestors is closed (or opening, but not
+   open). Otherwise, it can only be changed indirectly using the <code
+   title="dom-datagrid-insertRows">insertRows()</code> and <code
+   title="dom-datagrid-deleteRows">deleteRows()</code>
+   methods.</p></dd>
+
+   <dt>Cells</dt>
+
+   <dd><p>The data that applies to this row. Cell data is discussed in
+   more detail below.</p></dd>
+
   </dl>
 
-  <h6 id="commonDefaultDataGridMethodDefinitions">Common default data
-  provider method definitions for cells</h6>
+  <p>The <code>datagrid</code> itself also has a <dfn title="datagrid
+  child count">child count</dfn> and a <dfn title="datagrid row
+  count">row count</dfn>, which are analogous to the child counts and
+  row counts for rows. Initially these must be zero.</p>
 
-  <p>These definitions are used for the cell-specific methods of the
-  default data providers (other than in the
-  <code>select</code>/<code>datalist</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.</p>
+  <hr>
 
-  <dl>
+  <p>The <dfn><code>datagrid</code> resort steps</dfn>, which are
+  invoked when the sort order changes as described in the previous
+  section, are as follows:</p>
 
-   <dt>Cyclable cells</dt>
+  <ol>
 
-   <dd>
+   <li>
+
+    <p>Clear the <span>display order sparse data tree</span>
+    (i.e. mark the display order position of all the rows in the
+    <code>datagrid</code> as unknown).</p>
+
+    <p>User agents may cache the position information of rows for
+    various values of <code
+    title="dom-datagrid-sortColumn">sortColumn</code> and <code
+    title="dom-datagrid-sortAscending">sortAscending</code>, instead
+    of discarding the information altogether. If the user agent caches
+    this information, and has information that applies to the current
+    values of <code title="dom-datagrid-sortColumn">sortColumn</code>
+    and <code title="dom-datagrid-sortAscending">sortAscending</code>,
+    then the user agent may repopulate the <span>display order sparse
+    data tree</span> from this information.</p>
 
-    <p>If the first element child of a cell's element is a
-    <code>select</code> element that has a no <code
-    title="attr-select-multiple">multiple</code> attribute and has at
-    least one <code>option</code> element descendant, then the cell
-    acts as a cyclable cell.</p>
+   </li>
 
-    <p>The "current" <code>option</code> element is the selected
-    <code>option</code> element, or the first <code>option</code>
-    element if none is selected.</p>
+   <li>
 
-    <p>The <code title="dom-provider-getCellData">getCellData()</code>
-    method must return the <code>textContent</code> of the current
-    <code>option</code> element (the <code
-    title="attr-option-label">label</code> attribute is <span
-    title="ignore">ignored</span> in this context as the
-    <code>optgroup</code>s are not displayed).</p>
+    <p>Clear the <span>pending <code>datagrid</code> rows list</span>
+    and the <span>pending <code>datagrid</code> cells list</span>.</p>
 
-    <p>The <code
-    title="dom-provider-getCellClasses">getCellClasses()</code> method
-    must add the <code
-    title="datagrid-cell-class-cyclable">cyclable</code> class and
-    then all the classes of the current <code>option</code>
-    element.</p>
+   </li>
 
-    <p>The <code title="dom-provider-cycleCell">cycleCell()</code>
-    method must change the selection of the <code>select</code>
-    element such that the next <code>option</code> element after the
-    current <code>option</code> element is the only one that is
-    selected (in <span>tree order</span>). If the current <code>option</code>
-    element is the last <code>option</code> element descendant of the
-    <code>select</code>, then the first <code>option</code> element
-    descendant must be selected instead.</p>
+   <li>
 
-    <p>The <code
-    title="dom-provider-setCellCheckedState">setCellCheckedState()</code>
-    and <code title="dom-provider-editCell">editCell()</code> methods
-    must do nothing.</p>
+    <p>Invoke the <span><code>datagrid</code> update display
+    algorithm</span>.</p>
 
-   </dd>
+   </li>
+
+   <!-- v2: queue a task to fire an event, or tell the listener the
+   sort order changed, or something -->
+
+  </ol>
+
+  <hr>
+
+  <p>The <dfn
+  title="dom-datagrid-renotify"><code>renotify()</code></dfn> method
+  must empty the <span>pending <code>datagrid</code> rows list</span>
+  and the <span>pending <code>datagrid</code> cells list</span>, and
+  invoke the <span><code>datagrid</code> update display
+  algorithm</span>.</p>
+
+  <hr>
+
+  <p>The <dfn title="dom-datagrid-setRowCount"><code>setRowCount(<var
+  title="">childCount</var>, <var
+  title="">rowCount</var>)</code></dfn> method must run the following
+  steps:</p>
+
+  <ol>
+
+   <li>
+
+    <p>Set the <span><code>datagrid</code> child count</span> to <var
+    title="">childCount</var>, the <span><code>datagrid</code> row
+    count</span> to <var title="">rowCount</var>.</p>
+
+   </li>
+
+   <li>
+
+    <p><span>Audit the <code>datagrid</code></span>. If this fails,
+    then revert the changes made in the previous step, throw a
+    <code>DATAGRID_MODEL_ERR</code> exception, and abort these
+    steps.</p>
+
+   </li>
+
+   <li>
+
+    <p>Invoke the <span><code>datagrid</code> update display
+    algorithm</span>.</p>
+
+   </li>
+
+  </ol>
+
+  <hr>
+
+  <p>The <dfn title="dom-datagrid-setRows"><code>setRows(<var
+  title="">rows</var>)</code></dfn> method must run the following
+  steps:</p>
+
+  <ol>
+
+   <li>
+
+    <p><span title="type-check a RowList object">Type-check the <var
+    title="">rows</var> argument</span>. If this fails, throw a
+    <code>TypeError</code> exception, and abort these steps.</p>
+
+   </li>
+
+   <li>
+
+    <p><span title="partially sort a RowList object">Partially sort
+    the <var title="">rows</var> argument</span>.</p>
+
+   </li>
+
+   <li>
+
+    <p>For each <code>Row</code> object in the <var
+    title="">rows</var> argument, in order, perform the appropriate
+    steps from the list below.</p>
+
+    <p class="note">The changes made to the <code>datagrid</code>'s
+    data structures in this step get reverted (as required below) if
+    any consistency errors are detected either in this step or the
+    next.</p>
+
+    <dl>
+
+     <dt>If there already exists a row in the <code>datagrid</code>'s
+     <span>natural order sparse data tree</span> with the same
+     identifier as given by the <code>Row</code> object's
+     <code>RowID</code> object, and that row and all its ancestors are
+     open</dt>
+
+     <dd>
+
+      <p>If one of the following conditions is true, then revert all
+      the changes done in this step, throw a
+      <code>DATAGRID_MODEL_ERR</code> exception, and abort these
+      steps:</p>
+
+      <ul>
+
+       <li>The value of the <code>Row</code> object's second entry is
+       neither &#x2212;1 nor equal to the child count of the
+       preexisting row.</li>
+
+       <li>The <code>Row</code> object has fewer than five entries, or
+       its fifth entry is false.</li>
+
+       <li>The <code>Row</code> object has fewer than six entries, or
+       its sixth entry is not equal to the row count of the
+       preexisting row.</li>
+
+      </ul>
+
+     </dd>
+
+     <dt>If there already exists a row in the <code>datagrid</code>'s
+     <span>natural order sparse data tree</span> with the same
+     identifier as given by the <code>Row</code> object's
+     <code>RowID</code> object, but either that row or one of its
+     ancestors is closed</dt>
+
+     <dd>
+
+      <p>Set the preexisting row's child count to the value of the
+      <code>Row</code> object's second entry.</p>
+
+      <p>If the <code>Row</code> object has five or more entries, and
+      either its fifth entry is true and the preexisting row is closed
+      but not opening, or its fifth entry is false and the preexisting
+      row is open, then: if the preexisting row has no ancestor row
+      that is closed, then revert all the changes done in this step,
+      throw a <code>DATAGRID_MODEL_ERR</code> exception, and abort
+      these steps; otherwise, if the fifth entry is false, then close
+      the row; otherwise, open the row.</p>
+
+      <p>If the <code>Row</code> object has six entries, set the
+      preexisting row's row count to the value of the <code>Row</code>
+      object's sixth entry.</p>
+
+      <p>If the preexisting row is opening, then: increase the
+      <span><code>datagrid</code> row count</span> and the row counts
+      of any ancestor rows by the number of rows that the preexisting
+      row now has in its row count, then open the row.</p> <!-- we
+      should also "update the <span>pending <code>datagrid</code> rows
+      list</span> and the <span>pending <code>datagrid</code> cells
+      list</span> accordingly" -->
+
+
+     </dd>
+
+     <dt>There does not exist a row in the <code>datagrid</code>'s
+     <span>natural order sparse data tree</span> with the same
+     identifier as given by the <code>Row</code> object's
+     <code>RowID</code> object</dt>
+
+     <dd>
+
+      <p>If the <code>RowID</code> object has a length greater than 1,
+      then verify that there is a row identified by the
+      <code>RowID</code> consisting of all but the last number in the
+      <code>Row</code> object's <code>RowID</code>. If there is no
+      such row present in the <span>natural order sparse data
+      tree</span>, then revert all the changes done in this step,
+      throw a <code>DATAGRID_MODEL_ERR</code> exception, and abort
+      these steps.</p>
+
+      <p>Create a row and insert it into the <span>natural order
+      sparse data tree</span>, such that its parent is the row
+      identified by the <code>RowID</code> consisting of all but the
+      last number in the <code>Row</code> object's <code>RowID</code>,
+      or the <code>datagrid</code> if the lenght of the
+      <code>Row</code> object's <code>RowID</code> is 1; with its
+      natural order position being the last number of the
+      <code>Row</code> object's <code>RowID</code>; with the child
+      count being the value of the third entry of the <code>Row</code>
+      object; with the row being marked closed unless the
+      <code>Row</code> object has five or more entries and its fifth
+      entry is true, in which case the row is open; and with its row
+      count being &#x2212;1 unless the <code>Row</code> object has six
+      entries, in which case the row count is equal to the value of
+      the <code>Row</code> object's sixth entry.</p>
+
+     </dd>
+
+    </dl>
+
+   </li>
+
+   <li>
+
+    <p><span>Audit the <code>datagrid</code></span>. If this fails,
+    then revert the changes made in the previous step, throw a
+    <code>DATAGRID_MODEL_ERR</code> exception, and abort these
+    steps.</p>
+
+   </li>
+
+   <li>
+
+    <p>For each <code>Row</code> object in the <var
+    title="">rows</var> argument, in order, <span title="apply a Row
+    object">apply the <code>Row</code> object</span>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Invoke the <span><code>datagrid</code> update display
+    algorithm</span>.</p>
+
+   </li>
+
+  </ol>
+
+  <hr>
+
+  <p>The <dfn title="dom-datagrid-insertRows"><code>insertRows(<var
+  title="">rows</var>)</code></dfn> method must run the following
+  steps:</p>
+
+  <ol>
+
+   <li>
+
+    <p><span title="type-check a RowList object">Type-check the <var
+    title="">rows</var> argument</span>. If this fails, throw a
+    <code>TypeError</code> exception, and abort these steps.</p>
+
+   </li>
+
+   <li>
+
+    <p><span title="partially sort a RowList object">Partially sort
+    the <var title="">rows</var> argument</span>.</p>
+
+   </li>
+
+   <li>
+
+    <p>For each <code>Row</code> object in the <var
+    title="">rows</var> argument, in order, run the following
+    steps:</p>
+
+    <p class="note">The changes made to the <code>datagrid</code>'s
+    data structures in this step get reverted (as required below) if
+    any consistency errors are detected either in this step or the
+    next.</p>
+
+    <ol>
+
+     <li>
+
+      <p>Let <var title="">parent</var> be the row identified by the
+      <code>RowID</code> consisting of all but the last number in the
+      <code>Row</code> object's <code>RowID</code>, or the
+      <code>datagrid</code> itself it the <code>Row</code> object's
+      <code>RowID</code> has length 0.</p>
+
+      <p>If there is no such row present in the <span>natural order
+      sparse data tree</span>, then revert all the changes done in
+      this algorithm, throw a <code>DATAGRID_MODEL_ERR</code>
+      exception, and abort these steps.</p>
+
+     </li>
+
+     <li>
+
+      <p>Increment by one the natural order position of all rows whose
+      parent is <var title="">parent</var> and whose natural order
+      position is equal to or greater than the last number of the
+      <code>Row</code> object's <code>RowID</code>.</p>
+
+     </li>
+
+     <li>
+
+      <p>If the value of the <code>Row</code> object's second entry is
+      not &#x2212;1, then increment by one the display order position
+      of all rows whose parent is <var title="">parent</var> and whose
+      display order position is equal to or greater than the value of
+      the <code>Row</code> object's second entry.</p>
+
+     <!--(Not sure how to really say this.)
+      <p>Update the <span>pending <code>datagrid</code> rows
+      list</span> and the <span>pending <code>datagrid</code> cells
+      list</span> accordingly.</p>
+     -->
+
+     </li>
+ 
+     <li>
+
+      <p>Create a row and insert it into the <span>natural order
+      sparse data tree</span>, such that its parent is <var
+      title="">parent</var>; with its natural order position being the
+      last number of the <code>Row</code> object's <code>RowID</code>;
+      with the child count being the value of the third entry of the
+      <code>Row</code> object; with the row being marked closed unless
+      the <code>Row</code> object has five or more entries and its
+      fifth entry is true, in which case the row is open; and with its
+      row count being &#x2212;1 unless the <code>Row</code> object has
+      six entries, in which case the row count is equal to the value
+      of the <code>Row</code> object's sixth entry.</p>
+
+     </li>
+
+    </ol>
+
+   </li>
+
+   <li>
+
+    <p>For each <code>Row</code> object in the <var
+    title="">rows</var> argument, in order, <span title="apply a Row
+    object">apply the <code>Row</code> object</span>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Invoke the <span><code>datagrid</code> update display
+    algorithm</span>.</p>
+
+   </li>
+
+  </ol>
+
+  <hr>
+
+  <p>When an algorithm requires the user agent to <dfn>type-check a
+  <code>RowList</code> object</dfn> (an array), each entry in the
+  object must be checked against the following requirements. If any
+  are false, then the type-check fails, otherwise it passes.</p>
+
+  <ul>
 
-   <dt>Progress bar cells</dt>
+   <li><p>The entry is a <code>Row</code> object (an
+   array).</p></li>
 
+   <li><p>The first value in the <code>Row</code> is a
+   <code>RowID</code> object (also an array), whose length is at least
+   1, and whose values are all integers greater than or equal to
+   zero.</p></li>
+
+   <li><p>The numbers in the <code>RowID</code> object do not exactly
+   match any of the other entries in the <code>RowList</code> object
+   (i.e. no two <code>Row</code> objects have the same
+   identifier).</p></li>
+
+   <li><p>The second value in the <code>Row</code> is an integer that
+   is either &#x2212;1, zero, or a positive integer.</p></li>
+
+   <li><p>The third value in the <code>Row</code> is an integer that
+   is either &#x2212;1, zero, or a positive integer.</p></li>
+
+   <li><p>The fourth value in the <code>Row</code> is a
+   <code>CellList</code> object (yet another array).</p></li>
+
+   <li><p>Each entry in the <span>CellList</span> object is a
+   <code>Cell</code> object (again, an array).</p></li>
+
+   <li><p>Each <code>Cell</code> object in the <span>CellList</span>
+   object has as its first value a <code>Column</code> object (a
+   string), and its value is the identifier of one of the columns in
+   the <span>column list</span>.</p></li>
+
+   <li>
+
+    <p>Each <code>Cell</code> object in the <span>CellList</span>
+    object has as its second and subsequent entries values that match
+    the following requirements, as determined by the type of the
+    column identified by the first entry:</p>
+
+    <dl>
+
+     <dt>If the column's type is <code title="datagrid-type-text">text</code></dt>
+     <dd>
+
+      <p>The second entry's value is a string, and either there are
+      only two entries, or there are three, and the third entry is
+      an <code>img</code> element.</p>
+
+      <p>If there is an <code>img</code> element specified, its <code
+      title="dom-img-complete">complete</code> attribute is true.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-editable">editable</code></dt>
+     <dd>
+
+      <p>The second entry's value is a string, and either there are
+      only two entries, or the third entry is a
+      <code>datalist</code> element, and either there are only three
+      entries, or there are four, and the fourth entry is an
+      <code>img</code> element.</p>
+
+      <p>If there is an <code>img</code> element specified, its <code
+      title="dom-img-complete">complete</code> attribute is true.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-checkable">checkable</code></dt>
+     <dd>
+
+      <p>The second entry's value is a string, the third entry is a
+      boolean, and either there are only three entries, or the
+      fourth entry is also a boolean, and either there are only four
+      entries, or there are five, and the fifth entry is an
+      <code>img</code> element.</p>
+
+      <p>If there is an <code>img</code> element specified, its <code
+      title="dom-img-complete">complete</code> attribute is true.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-list">list</code></dt>
+     <dd>
+
+      <p>The second entry's value is a string, the third entry is a
+      <code>select</code> element, and either there are only three
+      entries, or there are four, and the fourth entry is an
+      <code>img</code> element.</p>
+
+      <p>If there is an <code>img</code> element specified, its <code
+      title="dom-img-complete">complete</code> attribute is true.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-progress">progress</code></dt>
+     <dd>
+
+      <p>There are only two entries, the second entry's value is a
+      number, and the number's value is between 0.0 and 1.0
+      inclusive.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-meter">meter</code></dt>
+     <dd>
+
+      <p>There are at least two, but possibly up to seven, entries,
+      all entries but the first one are numbers, and the following
+      relationships hold:</p>
+
+      <ul class="brief">
+
+       <li>The second entry is less than the third, or less than 1.0
+       if the third is absent.</li>
+
+       <li>The second entry is greater than the fourth, or greater
+       than 0.0 if the fourth is absent.</li>
+
+       <li>If there are at least three entries, the third entry is
+       greater than the fourth, or greater than zero if the fourth
+       is absent.</li>
+
+       <li>If there are at least five entries, the fifth is not
+       greater than the third and not less than the fourth.</li>
+
+       <li>If there are at least six entries, the sixth is not
+       greater than the third and not less than the fifth.</li>
+
+       <li>If there are at least seven entries, the fifth is not
+       greater than the third and not less than the fourth.</li>
+
+      </ul>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-custom">custom</code></dt>
+     <dd>
+
+      <p>There are four entries, the second and third are numbers
+      that are integers greater than zero, and the fourth is a
+      <code>Rendering2DContextCallback</code> object (a
+      function).</p>
+
+     </dd>
+
+    </dl>
+
+   </li>
+
+   <li><p>Either there are only four values in the <code>Row</code>,
+   or the fifth value in the <code>Row</code> is a boolean.</p></li>
+
+   <li><p>Either there are only four or five values in the
+   <code>Row</code>, or there are six, and the sixth value in the
+   <code>Row</code> an integer that is greater than or equal to
+   zero.</p></li>
+
+  </ul>
+
+  <p>Where the above requirements say that a value is to be a string,
+  the user agent must apply the ToString() conversion operator to the
+  value, assume that the value was indeed a string, and use the result
+  in the rest of the algorithm as if it had that had been the value
+  passed to the method. <a href="#refsECMA262">[ECMA262]</a></p>
+
+  <p>Where the above requirements say that a value is to be a number,
+  the user agent must first apply the ToNumber() conversion operator
+  to the value, and then verify that the result is neither the
+  not-a-number NaN value nor an infinite value. If this result is
+  indeed acceptable (i.e. finite), the user agent must use the result
+  in the rest of the algorithm as if it had that had been the value
+  passed to the method. <a href="#refsECMA262">[ECMA262]</a></p>
+
+  <p>Where the above requirements say that a value is to be an
+  integer, the user agent must first apply the ToNumber() conversion
+  operator to the value, and then verify that the result is a finite
+  integer. If so, the user agent must use the result in the rest of
+  the algorithm as if it had that had been the value passed to the
+  method. <a href="#refsECMA262">[ECMA262]</a></p>
+
+  <p>Where the above requirements say that a value is to be a boolean,
+  the user agent must apply the ToBoolean() conversion operator to the
+  value, assume that the value was indeed a boolean, and use the
+  result in the rest of the algorithm as if it had that had been the
+  value passed to the method. <a href="#refsECMA262">[ECMA262]</a></p>
+
+  <hr>
+
+  <p>When an algorithm requires the user agent to <dfn>audit the
+  <code>datagrid</code></dfn>, the <code>datagrid</code> must be
+  checked against the following requirements. If any are false, then
+  the audit fails, otherwise it passes.</p>
+
+  <ul>
+
+   <li>There is no row whose natural order position is greater than or
+   equal to the child count of its parent row in the <span>natural
+   order sparse data tree</span>.</li>
+
+   <li>There is no row whose display order position is greater than or
+   equal to the child count of its parent row in the <span>display
+   order sparse data tree</span>.</li>
+
+   <li>There is no row such that the sum of that row's child count and
+   the row counts all the open rows that are direct children of that
+   row in the <span>natural order sparse data tree</span> is less than
+   that row's row count.</li>
+
+   <li>Of the rows whose child count is equal to the number of rows
+   that are direct children of that row in the <span>natural order
+   sparse data tree</span>, there is none such that the sum of that
+   row's child count and the row counts of all the open rows that are
+   direct children of that row in the <span>natural order sparse data
+   tree</span> is greater than that row's row count.</li>
+
+  </ul>
+
+  <p>For the purposes of this audit, the <code>datagrid</code> must be
+  treated as the parent row of all the rows that are direct children
+  of the <code>datagrid</code> in the <span>natural order sparse data
+  tree</span> and the <span>display order sparse data tree</span>. The
+  child count of this implied row is the <span><code>datagrid</code>
+  child count</span>, and the row count of this implied row is the
+  <span><code>datagrid</code> row count</span>.</p>
+
+  <hr>
+
+  <p>When an algorithm requires the user agent to <dfn>partially sort
+  a <code>RowList</code> object</dfn> (an array), the entries in the
+  object must be resorted such that <code>Row</code> objects are
+  listed after any of their ancestors and after any of their earlier
+  siblings. In other words, for any two <code>Row</code> objects <var
+  title="">a</var> and <var title="">b</var> in the
+  <code>RowList</code>, where <var title="">a</var> is before <var
+  title="">b</var> after the sort, the following conditions must
+  hold:</p>
+
+  <ul>
+
+   <li><p>If their <code>RowID</code> objects are the same length and
+   have values that are equal except for the last value, then the last
+   value of <var title="">a</var>'s <code>RowID</code>'s last value
+   must be less than <var title="">b</var>'s <code>RowID</code>'s last
+   value (i.e. earlier siblings must come before their later
+   siblings).</p></li>
+
+   <li><p>If their <code>RowID</code> objects are not the same length,
+   but the values in the shorter of the two are the same as the first
+   few values in the longer one, then <var title="">a</var>'s
+   <code>RowID</code> must be the shorter one (i.e. ancestors must
+   come before their descendants).</p></li>
+
+  </ul>
+
+  <hr>
+
+  <p>The <dfn title="dom-datagrid-deleteRows"><code>deleteRows(<var
+  title="">rows</var>)</code></dfn> method must run the following
+  steps:</p>
+
+  <ol>
+
+   <li>
+
+    <p>If any of the entries in <var title="">rows</var> are not
+    <code>RowID</code> objects consisting of one or more entries whose
+    values are all integers that are greater than or equal to zero,
+    then throw a <code>TypeError</code> exception and abort these
+    steps.</p>
+
+    <p>To check if a value is an integer, the user agent must first
+    apply the ToNumber() conversion operator to the value, and then
+    verify that the result is a finite integer. If so, the user agent
+    must use the result in the rest of the algorithm as if it had that
+    had been the value passed to the method. <a
+    href="#refsECMA262">[ECMA262]</a></p>
+
+   </li>
+
+   <li>
+
+    <p>If any of the <code>RowID</code> objects in the <var
+    title="">rows</var> argument identify a row that isn't present in
+    the <span>natural order sparse data tree</span>, then throw a
+    <code>DATAGRID_MODEL_ERR</code> exception and abort these
+    steps.</p>
+
+   </li>
+
+   <li>
+
+    <p>If any row is listed twice in the <var title="">rows</var>
+    argument, then throw a <code>DATAGRID_MODEL_ERR</code> exception
+    and abort these steps.</p>
+
+   </li>
+
+   <li>
+
+    <p>Sort the <var title="">rows</var> argument such that the
+    entries are given in the same order as the rows they identify
+    would be visited in a pre-order, depth first traversal of the
+    <span>natural order sparse data tree</span>.</p>
+
+   </li>
+
+   <li>
+
+    <p>For each row identified by entries in <var title="">rows</var>,
+    <em>in reverse order</em>, run the following steps:</p>
+
+    <ol>
+
+     <li>
+
+      <p>Decrement the child count of the row's parent row, if that
+      child count is greater than zero. If the row has no parent,
+      decrement the <span><code>datagrid</code> child
+      count</span>.</p>
+
+      <p>If the row has a parent row, and its child count is now zero,
+      then close that row.</p>
+
+     </li>
+
+     <li>
+
+      <p>Let <var title="">delta</var> be one more than the row's row
+      count if the row is open and its row count is greater than zero;
+      otherwise, let <var title="">delta</var> be one.</p>
+
+     </li>
+
+     <li>
+
+      <p>Let <var title="">ancestor</var> be the row.</p>
+
+     </li>
+
+     <li>
+
+      <p><i>Row count loop:</i> Let <var title="">ancestor</var> be
+      <var title="">ancestor</var>'s parent row, if any, or null if it
+      has none.</p>
+
+     </li>
+
+     <li>
+
+      <p>If <var title="">ancestor</var> is null, then decrement the
+      <span><code>datagrid</code> row count</span> by <var
+      title="">delta</var>. Otherwise, if <var title="">ancestor</var>
+      is open, then decrement its row count by <var
+      title="">delta</var>.</p>
+
+     </li>
+
+     <li>
+
+      <p>If <var title="">ancestor</var> is not null, then jump back
+      to the step labeled <i>row count loop</i> above.</p>
+
+     </li>
+
+     <li>
+
+      <p>Let <var title="">parent</var> be the row's parent, or the
+      <code>datagrid</code> if the row has no parent.</p>
+
+     </li>
+
+     <li>
+
+      <p>Decrement by one the natural order position of all rows whose
+      parent is <var title="">parent</var> and whose natural order
+      position is equal to or greater than the row's own natural order
+      position.</p>
+
+     </li>
+
+     <li>
+
+      <p>If the row is in the <span>display order sparse data
+      tree</span>, then decrement by one the display order position of
+      all rows whose parent is <var title="">parent</var> and whose
+      display order position is equal to or greater than the row's own
+      display order position.</p>
+
+     </li>
+
+     <li>
+
+      <p>Clear the row and its descendants from the
+      <code>Datagrid</code>.</p>
+
+     </li>
+
+    </ol>
+
+   </li>
+
+   <li>
+
+    <p>Invoke the <span><code>datagrid</code> update display
+    algorithm</span>.</p>
+
+   </li>
+
+  </ol>
+
+  <hr>
+
+  <p>The <dfn
+  title="dom-datagrid-clearRows"><code>clearRows()</code></dfn> method
+  must empty the <span>natural order sparse data tree</span>, reset
+  both the <span><code>datagrid</code> child count</span> and the
+  <span><code>datagrid</code> row count</span> to zero, and invoke the
+  <span><code>datagrid</code> update display algorithm</span>.</p>
+
+  <hr>
+
+  <p>The <dfn title="dom-datagrid-repaint"><code>repaint(<var
+  title="">row</var>, <var title="">column</var>)</code></dfn> method
+  must cause the user agent to clear its cache for the cell specified
+  by the identifier <var title="">row</var> and the column <var
+  title="">column</var>, if that column's type is <code
+  title="datagrid-type-custom">custom</code>. If the given column has
+  not been declared, or its type is not <code
+  title="datagrid-type-custom">custom</code>, then the user agent must
+  throw a <code>DATAGRID_MODEL_ERR</code> exception. If the given row
+  is not known, then the method must do nothing. If the cell is indeed
+  cleared, the user agent must reinvoke the previously registered
+  <code>RenderingContext2DCallback</code> callback when it needs to
+  repaint that row.</p>
+
+  <hr>
+
+  <p>If a row has a child count that isn't zero, then the user agent
+  should offer to the user the option of opening and closing the
+  row.</p>
+
+  <p>When a row is opened, if the row's row count is greater than
+  zero, then the user agent must increase the
+  <span><code>datagrid</code> row count</span> and the row counts of
+  any ancestor rows by the number of rows that the newly opened row
+  has in its row count<!-- we should also "update the <span>pending
+  <code>datagrid</code> rows list</span> and the <span>pending
+  <code>datagrid</code> cells list</span> accordingly" -->, then must
+  mark the row as open, then may fill in the <span>display order
+  sparse data tree</span> with any information that the user agent has
+  cached about the display order positions of descendants of the newly
+  opened row, and then must invoke the <code
+  title="dom-listener-rowOpened">rowOpened()</code> method on the
+  current <code title="dom-datagrid-listener">listener</code> with as
+  its first argument a <code>RowID</code> object identifying the row
+  that was opened and as its second argument the boolean false, and
+  then must invoke the <span><code>datagrid</code> update display
+  algorithm</span>.</p>
+
+  <p>On the other hand, when a row is opened and the row's row count
+  is &#x2212;1, then the user agent must mark the row as opening, and
+  then must invoke the <code
+  title="dom-listener-rowOpened">rowOpened()</code> method on the
+  current <code title="dom-datagrid-listener">listener</code> with as
+  its first argument a <code>RowID</code> object identifying the row
+  that was opened and as its second argument the boolean true.</p>
+
+  <p>When a row is closed, the user agent must decrease the
+  <span><code>datagrid</code> row count</span> and the row counts of
+  any ancestor rows by the number of rows that the newly closed row
+  has in its row count, and then must invoke the <code
+  title="dom-listener-rowOpened">rowOpened()</code> method on the
+  current <code title="dom-datagrid-listener">listener</code> with as
+  its first and only argument a <code>RowID</code> object identifying
+  the row that was opened.</p>
+
+
+
+  <h6>The cells</h6>
+
+  <p>Each row has one cell per column. Each cell has the same type as
+  its column. The <dfn>allowed <code>datagrid</code> column
+  types</dfn>, what they represent, and the requirements for when the
+  user interacts with them, are as follows:</p>
+
+  <dl>
+
+   <dt><dfn title="datagrid-type-text"><code>text</code></dfn></dt>
    <dd>
 
-    <p>If the first element child of a cell's element is a
-    <code>progress</code> element, then the cell acts as a progress
-    bar cell.</p>
+    <p>The cell represents some text and an optional image.</p>
 
-    <p>The <code title="dom-provider-getCellData">getCellData()</code>
-    method must return the value returned by the <code>progress</code>
-    element's <code title="dom-progress-position">position</code> DOM
-    attribute.</p>
+   </dd>
+
+   <dt><dfn title="datagrid-type-editable"><code>editable</code></dfn></dt>
+   <dd>
+
+    <p>The cells represents some editable text, an optional
+    <code>datalist</code> giving autocompletion hints, and an
+    optional image.</p>
 
-    <p>The <code
-    title="dom-provider-getCellClasses">getCellClasses()</code> method
-    must add the <code
-    title="datagrid-cell-class-progress">progress</code> class.</p>
+    <p>If there is a <code>datalist</code> element, the user agent
+    should offer the suggestions represented by that element to the
+    user. The user agent may use the suggestion's <span
+    title="concept-option-label">label</span> to identify the
+    suggestion. If the user selects a suggestion, then the editable
+    text must be set to the selected suggestion's <span
+    title="concept-option-value">value</span>, as if the user had
+    written that value himself.</p>
 
-    <p>The <code
-    title="dom-provider-setCellCheckedState">setCellCheckedState()</code>,
-    <code title="dom-provider-cycleCell">cycleCell()</code>, and
-    <code title="dom-provider-editCell">editCell()</code> methods must
-    do nothing.</p>
+    <p>When the user edits the value, either directly or using the
+    <code>datalist</code>, the user agent must invoke the <code
+    title="dom-listener-cellChanged">cellChanged()</code> method on
+    the current <code title="dom-datagrid-listener">listener</code>
+    with as its first argument a <code>RowID</code> identifying the
+    cell's row, as its second argument the identifier of the cell's
+    column, as its third argument the new value, and as its fourth
+    argument the previous value.</p>
 
    </dd>
 
-   <dt>Checkbox cells</dt>
+   <dt><dfn title="datagrid-type-checkable"><code>checkable</code></dfn></dt>
+   <dd>
+
+    <p>The cell represents some text, a check box that optionally has
+    its value obscured as indeterminate, and an optional image.</p>
+
+    <p>When the user checks or unchecks the check box, the user agent
+    must change the check box's state appropriately and stop obscuring
+    the check box as indeterminate (if it is obscuring it), and then
+    must invoke the <code
+    title="dom-listener-cellChanged">cellChanged()</code> method on
+    the current <code title="dom-datagrid-listener">listener</code>
+    with as its first argument a <code>RowID</code> identifying the
+    cell's row, as its second argument the identifier of the cell's
+    column, as its third argument true if the check box is now checked
+    and false otherwise, and as its fourth argument true if the check
+    box was previously checked and false otherwise.</p>
+
+   </dd>
 
+   <dt><dfn title="datagrid-type-list"><code>list</code></dfn></dt>
    <dd>
 
-    <p>If the first element child of a cell's element is an
-    <code>input</code> element that has a <code
-    title="attr-input-type">type</code> attribute with the value <code
-    title="">checkbox</code>, then the cell acts as a check box
-    cell.</p>
+    <p>The cell represents some text giving the current value selected
+    from a dropdown list of options, a <code>select</code> element
+    giving the list of options, and an optional image.</p>
 
-    <p>The <code title="dom-provider-getCellData">getCellData()</code>
-    method must return the <code>textContent</code> of the cell
-    element.</p>
+    <p>The user agent should allow the user to change the value of the
+    cell from its current value to one of the <span
+    title="concept-option-value">values</span> given by
+    <code>option</code> elements in the <span
+    title="concept-select-option-list">list of options</span> (if
+    any). The user agent may use the <code>option</code> elements'
+    <span title="concept-option-label">labels</span> to annotate each
+    option.</p>
 
-    <p>The <code
-    title="dom-provider-getCellClasses">getCellClasses()</code> method
-    must add the <code
-    title="datagrid-cell-class-checked">checked</code> class if the
-    <code>input</code> element's <span
-    title="concept-fe-checked">checkedness</span> is true, and the
-    <code title="datagrid-cell-class-unchecked">unchecked</code> class
-    otherwise.</p>
+    <p>When the user selects a new value from the <code>select</code>
+    element's <span title="concept-select-option-list">list of
+    options</span>, the user agent must invoke the <code
+    title="dom-listener-cellChanged">cellChanged()</code> method on
+    the current <code title="dom-datagrid-listener">listener</code>
+    with as its first argument a <code>RowID</code> identifying the
+    cell's row, as its second argument the identifier of the cell's
+    column, as its third argument the new value, and as its fourth
+    argument the previous value.</p>
 
-    <p>The <code
-    title="dom-provider-setCellCheckedState">setCellCheckedState()</code>
-    method must set the <code>input</code> element's checkbox <span
-    title="concept-fe-checked">checkedness</span> to true if the
-    method's third argument is 1, and to false otherwise.</p>
+   </dd>
 
-    <p>The <code title="dom-provider-cycleCell">cycleCell()</code> and
-    <code title="dom-provider-editCell">editCell()</code> methods must
-    do nothing.</p>
+   <dt><dfn title="datagrid-type-progress"><code>progress</code></dfn></dt>
+   <dd>
+
+    <p>The cell represents a (determinate) progress bar whose value is
+    between 0.0, indicating no progress, and 1.0, indicating the task
+    is complete.</p>
 
    </dd>
 
-   <dt>Editable cells</dt>
+   <dt><dfn title="datagrid-type-meter"><code>meter</code></dfn></dt>
+   <dd>
+
+    <p>The cell represents a gauge, described by one to six
+    numbers.</p>
+
+    <p>The gauge's actual value is given by the first number.</p>
+
+    <p>If there is a second number, then that number is the maximum
+    value. Otherwise, the maximum value is 1.0.</p>
+
+    <p>If there is a third number, then that number is the minimum
+    value. Otherwise, the minimum value is 1.0.</p>
+
+    <p>If there is a fourth number, then that number is the low
+    boundary. Otherwise, the low boundary is the minimum value.</p>
+
+    <p>If there is a fifth number, then that number is the high
+    boundary. Otherwise, the high boundary is the maximum value.</p>
+
+    <p>If there is a sixth number, then the optimal point is the sixth
+    number. Otherwise, the optimum point is the midpoint between the
+    minimum value and the maximum value.</p>
+
+    <!-- next two paragraphs copied from <meter>: -->
 
+    <p>If the optimum point is equal to the low boundary or the high
+    boundary, or anywhere in between them, then the region between the
+    low and high boundaries of the gauge must be treated as the
+    optimum region, and the low and high parts, if any, must be
+    treated as suboptimal. Otherwise, if the optimum point is less
+    than the low boundary, then the region between the minimum value
+    and the low boundary must be treated as the optimum region, the
+    region between the low boundary and the high boundary must be
+    treated as a suboptimal region, and the region between the high
+    boundary and the maximum value must be treated as an even less
+    good region. Finally, if the optimum point is higher than the high
+    boundary, then the situation is reversed; the region between the
+    high boundary and the maximum value must be treated as the optimum
+    region, the region between the high boundary and the low boundary
+    must be treated as a suboptimal region, and the remaining region
+    between the low boundary and the minimum value must be treated as
+    an even less good region.</p>
+
+    <p>User agents should indicate the relative position of the actual
+    actual to the minimum and maximum values, and the relationship
+    between the actual value and the three regions of the gauge.</p>
+
+   </dd>
+
+   <dt><dfn title="datagrid-type-custom"><code>custom</code></dfn></dt>
    <dd>
 
-    <p>If the first element child of a cell's element is an
-    <code>input</code> element that has a <code
-    title="attr-input-type">type</code> attribute with the value <code
-    title="">text</code> or that has no <code
-    title="attr-input-type">type</code> attribute at all, then the
-    cell acts as an editable cell.</p>
+    <p>The cell represents a dynamically generated graphical image.</p>
 
-    <p>The <code title="dom-provider-getCellData">getCellData()</code>
-    method must return the <code title="dom-input-value">value</code>
-    of the <code>input</code> element.</p>
+    <p>The cell will have minimum dimensions (specified in CSS
+    pixels), and a callback (in the form of a
+    <code>RenderingContext2DCallback</code> object) to get a rendering
+    for the cell.</p>
 
-    <p>The <code
-    title="dom-provider-getCellClasses">getCellClasses()</code> method
-    must add the <code
-    title="datagrid-cell-class-editable">editable</code> class.</p>
+    <p>The user agent should not allow the cell to be rendered with
+    dimensions less than the given minimum width and height.</p>
 
-    <p>The <code title="dom-provider-editCell">editCell()</code>
-    method must set the <code>input</code> element's <code
-    title="dom-input-value">value</code> DOM attribute to the value of
-    the third argument to the method.</p>
+    <p>When the user agent needs to render the cell, the user agent
+    must <span>queue a task</span> to invoke the
+    <span>RenderingContext2DCallback</span> callback, passing it a
+    newly created <code>CanvasRenderingContext2D</code> object whose
+    <code title="dom-context-2d-canvas">canvas</code> DOM attribute is
+    null as the first argument, the actual cell width in CSS pixels as
+    the second argument, and the actual cell height in CSS pixels as
+    the third argument.</p>
 
-    <p>The <code
-    title="dom-provider-setCellCheckedState">setCellCheckedState()</code>
-    and <code title="dom-provider-cycleCell">cycleCell()</code>
-    methods must do nothing.</p>
+    <p>If the user agent is able to render graphics, then it must
+    render the graphics commands that the callback executed on the
+    provided <code>CanvasRenderingContext2D</code> object onto the
+    cell once the callback returns. The image must be clipped to the
+    dimensions of the cell. The coordinate space of the cell must be
+    aligned with that used by the 2D context such that the top left
+    corner of the cell is the 0,0 origin, with the coordinate space
+    increasing its <var title="">x</var> dimension towards the right
+    of the cell and its <var title="">y</var> axis towards the bottom
+    of the cell, and with the image not scaled (so that one CSS pixel
+    on the final rendering matches one CSS pixel in the coordinate
+    space usd by the 2D context).</p>
+
+    <p>The user agent must then decouple the
+    <code>CanvasRenderingContext2D</code> object and any objects that
+    it created (such as <code>CanvasPattern</code> objects or
+    <code>ImageData</code> objects) from any real drawing surface.</p>
+
+    <p>If the user agent is unable to render graphics, then it must
+    render the text string returned by the callback instead.</p>
 
    </dd>
 
   </dl>
 
-  <!-- XXX Calculated cells, like in spreadsheets? -->
+  <hr>
+
+  <p>When an algorithm requires the user agent to <dfn>apply a
+  <code>Row</code> object</dfn>, the user agent must run the following
+  steps:</p>
+
+  <ol>
+
+   <li>
+
+    <p>If the value of the <code>Row</code> object's second entry is
+    not &#x2212;1, then run these substeps:</p>
+
+    <ol>
+
+     <li><p>If there is a row with the same parent as the row
+     specified by the <code>Row</code> object's <code>RowID</code>
+     object, whose display order position is currently the same as the
+     value of the <code>Row</code> object's second entry, then remove
+     that row from the <span>display order sparse data
+     tree</span>.</p></li>
+
+     <li><p>Set the display order position of the row specified by the
+     <code>Row</code> object's <code>RowID</code> to the value of the
+     <code>Row</code> object's second entry, updating its position in
+     the <span>display order sparse data tree</span>
+     accordingly.</p></li>
+
+     <li><p>If the row is in the the <span>pending
+     <code>datagrid</code> rows list</span>, remove it.</p></li>
+
+    </ol>
+
+   </li>
+
+   <li>
+
+    <p>If the fourth entry in the <code>Row</code> object (a
+    <code>CellList</code> object, an array) is not empty, then for
+    each <code>Cell</code> object in that array update the cell that
+    corresponds to the column identified by the value of the first
+    entry of the <code>Cell</code> object, by using the appropriate
+    set of steps given below as determined by the type of the
+    column. Then, if the cell is in the the <span>pending
+    <code>datagrid</code> cells list</span>, remove it.</p>
+
+    <dl>
+
+     <dt>If the column's type is <code title="datagrid-type-text">text</code></dt>
+     <dd>
+
+      <p>Update the cell's text to the value given in the
+      <code>Cell</code> object's second entry.</p>
+
+      <p>If the <code>Cell</code> object has three entries, then copy
+      the image data from the <code>img</code> element given in the
+      third entry, and let the cell's image be given by that image
+      data. Otherwise, update the cell to have no image.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-editable">editable</code></dt>
+     <dd>
+
+      <p>Update the cell's text to the value given in the
+      <code>Cell</code> object's second entry.</p>
+
+      <p>If the <code>Cell</code> object has three entries, then let
+      the <code>datalist</code> element given in the third entry be
+      the <code>datalist</code> element giving autocompletion
+      hints. Otherwise, update the cell to have no
+      <code>datalist</code> element.</p>
+
+      <p>If the <code>Cell</code> object has four entries, then copy
+      the image data from the <code>img</code> element given in the
+      fourth entry, and let the cell's image be given by that image
+      data. Otherwise, update the cell to have no image.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-checkable">checkable</code></dt>
+     <dd>
+
+      <p>Update the cell's text to the value given in the
+      <code>Cell</code> object's second entry.</p>
+
+      <p>Update the cell's checked state to match the value of the
+      third entry: checked if true, unchecked otherwise.</p>
+
+      <p>If the <code>Cell</code> object has four entries and the
+      fourth entry is true, then update the cell to be obscured as
+      indeterminate. Otherwise, the cell's state is not obscured.</p>
+
+      <p>If the <code>Cell</code> object has five entries, then copy
+      the image data from the <code>img</code> element given in the
+      fifth entry, and let the cell's image be given by that image
+      data. Otherwise, update the cell to have no image.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-list">list</code></dt>
+     <dd>
+
+      <p>Update the cell's text to the value given in the
+      <code>Cell</code> object's second entry, and the
+      <code>select</code> element to be the one given in the
+      <code>Cell</code> object's third entry</p>
+
+      <p>If the <code>Cell</code> object has four entries, then copy
+      the image data from the <code>img</code> element given in the
+      fourth entry, and let the cell's image be given by that image
+      data. Otherwise, update the cell to have no image.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-progress">progress</code></dt>
+     <dd>
+
+      <p>Update the cell to be a progress bar whose progress, on the
+      scale of 0.0 (no progress) to 1.0 (task complete) is given by
+      the value in the <code>Cell</code> object's second entry.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-meter">meter</code></dt>
+     <dd>
+
+      <p>Update the cell to be a gauge configured with the numbers
+      given by the second and subsequent entries of the
+      <code>Cell</code> object.</p>
+
+     </dd>
+
+     <dt>If the column's type is <code title="datagrid-type-custom">custom</code></dt>
+     <dd>
+
+      <p>Update the cell's minimum width to be the length in CSS
+      pixels given by the <code>Cell</code> object's second entry.</p>
+
+      <p>Update the cell's minimum height to be the length in CSS
+      pixels given by the <code>Cell</code> object's third entry.</p>
+
+      <p>Update the cell's callback to be the
+      <code>RenderingContext2DCallback</code> object given by the
+      <code>Cell</code> object's fourth entry.</p>
+
+     </dd>
+
+    </dl>
+
+   </li>
+
+  </ol>
+
+  <hr>
+
+  <p>When the user agent is to run the <dfn><code>datagrid</code>
+  update display algorithm</dfn>, the user agent must invoke the <code
+  title="dom-listener-getRows">getRows()</code> and <code
+  title="dom-listener-getCells">getCells()</code> methods on the
+  current <code title="dom-datagrid-listener">listener</code> such
+  that all the current visible rows in the <span>display order sparse
+  data list</span>, and all the cells in the currently visible columns
+  on all the currently visible rows, have been covered.</p>
+
+  <p>A row is considered covered if it is present in the <span>pending
+  <code>datagrid</code> rows list</span>, or if the <code
+  title="dom-listener-getRows">getRows()</code> method is invoked with
+  a range that includes the row in question.</p>
+
+  <p>A cell is considered covered if it is present in the
+  <span>pending <code>datagrid</code> cells list</span>, or if the
+  <code title="dom-listener-getRows">getRows()</code> method is
+  invoked with a range that includes the row in question and a list of
+  columns that includes the cell's column, or if the <code
+  title="dom-listener-getCells">getCells()</code> method is invoked
+  with a list of rows and columns that intersects the cell in
+  question. However, the <code
+  title="dom-listener-getCells">getCells()</code> method can only be
+  used if the row is already present in the <span>display order sparse
+  data list</span>.</p>
+
+  <p>The <code title="dom-listener-getRows">getRows()</code> method,
+  if used, must be invoked with five arguments. The first argument
+  must be the index in the <span>display order sparse data list</span>
+  to the first row that the the user agent is requesting, known as the
+  <i>anchor row</i>. The second argument must be the number of
+  consecutive cells for which the user agent is requesting
+  information. The third argument must be the <code>RowID</code> of
+  the row that is the nearest ancestor in the <span>display order
+  sparse data <em>tree</em></span> of the anchor row. If this is the
+  <code>datagrid</code>, then the <code>RowID</code> object must be an
+  empty array. The fourth argument must be the display order position
+  of the anchor row in the <span>display order sparse data
+  tree</span>, assuming that the row identified in the third argument
+  is indeed the anchor row's parent row. The fifth and final argument
+  must be an array of the identifiers of the columns for which the
+  user agent is requesting information, in the order they were added
+  to the <code>datagrid</code>.</p>
+
+  <p>As the <code title="dom-listener-getRows">getRows()</code> method
+  is invoked, the <span>pending <code>datagrid</code> rows list</span>
+  must be updated to include the rows for which information has been
+  requested, excluding rows for which information is already
+  available; and the <span>pending <code>datagrid</code> cells
+  list</span> must be updated to include the cells for which
+  information has been requested on those rows.</p>
+
+  <p>The <code title="dom-listener-getCells">getCells()</code> method,
+  if used, must be invoked with two arguments. The first argument must
+  be an array of <code>RowID</code> objects identifying the rows for
+  which information is being requested. The second argument must be an
+  array of the identifiers of the columns for which the user agent is
+  requesting information, in the order they were added to the
+  <code>datagrid</code>.</p>
+
+  <p>As the <code title="dom-listener-getCells">getCells()</code>
+  method is invoked, the <span>pending <code>datagrid</code> cells
+  list</span> must be updated to include the cells for which
+  information has been requested.</p>
+
+  <p>Calls to these methods should be batched so that the rows and
+  cells to be covered are handled by the fewest number of calls to
+  these methods as possible. To this end, user agents may invoke the
+  <code title="dom-listener-getRows">getRows()</code> method for a set
+  of rows that includes some rows that are already in the
+  <span>display order sparse data list</span>, and similarly may
+  invoke the <code title="dom-listener-getCells">getCells()</code>
+  method with row/column combinations that cover some cells for which
+  data is already known. Generally, however, user agents should avoid
+  invoking these methods with arguments that cause information to be
+  requested when it has already been requested or is already
+  known.</p>
+
+  <div class="example">
+
+   <p>For example, consider a case represented by the following table,
+   where the cells marked "Yes" indicate that the data has already
+   been obtained, the cells marked "Pending" indicate that the data
+   has been previously requested but not yet obtained, and the cells
+   with just a dash indicate that no information has ever been
+   obtained, or any information that had been obtained has now been
+   discarded.</p>
+
+   <table>
+    <tr> <td>        <th> Row   <th> Column A  <th> Column B
+    <tr> <th> Row 1  <td> -     <td> -         <td> -
+    <tr> <th> Row 2  <td> Yes   <td> Yes       <td> Yes
+    <tr> <th> Row 3  <td> Yes   <td> Yes       <td> Yes
+    <tr> <th> Row 4  <td> Yes   <td> Yes       <td> Yes
+    <tr> <th> Row 5  <td> -     <td> -         <td> -
+    <tr> <th> Row 6  <td> -     <td> -         <td> -
+    <tr> <th> Row 7  <td> Yes   <td> Pending   <td> -
+    <tr> <th> Row 8  <td> Yes   <td> Pending   <td> Pending
+   </table>
+
+   <p>Thus, rows 2, 3, 4, 7, and 8 are already covered, as are the
+   cells from those rows except for the cell in column B of row 7.</p>
+
+   <p>Now consider what happens if all of these rows become visible at
+   once. The user agent has several choices, including (but not
+   limited to) the following:</p>
+
+   <ul>
+
+    <li>Fire the <code title="dom-listener-getRows">getRows()</code>
+    method for rows 1 through 8 and columns A and B all at once.</li>
+
+    <li>Fire the <code title="dom-listener-getRows">getRows()</code>
+    method for row 1, then fire it again for rows 5 through 7.</li>
+
+    <li>Fire the <code title="dom-listener-getRows">getRows()</code>
+    method for row 1, then fire it again for rows 5 and 6, and then
+    fire the <code title="dom-listener-getCells">getCells()</code>
+    method for row 7 column B.</li>
+
+   </ul>
+
+   <p>All three options are allowed, but the latter two are preferable
+   to the former, as they minimise the amount of redundant information
+   requested.</p>
+
+   <p>In any case, the data model now looks like this:</p>
+
+   <table>
+    <tr> <td>        <th> Row     <th> Column A  <th> Column B  <th> Column C
+    <tr> <th> Row 1  <td> Pending <td> Pending   <td> Pending   <td> -
+    <tr> <th> Row 2  <td> Yes     <td> Yes       <td> Yes       <td> -
+    <tr> <th> Row 3  <td> Yes     <td> Yes       <td> Yes       <td> -
+    <tr> <th> Row 4  <td> Yes     <td> Yes       <td> Yes       <td> -
+    <tr> <th> Row 5  <td> Pending <td> Pending   <td> Pending   <td> -
+    <tr> <th> Row 6  <td> Pending <td> Pending   <td> Pending   <td> -
+    <tr> <th> Row 7  <td> Yes     <td> Pending   <td> Pending   <td> -
+    <tr> <th> Row 8  <td> Yes     <td> Pending   <td> Pending   <td> -
+   </table>
+
+   <p>Now consider the case where a third column, column C, is added
+   to the data model. The user agent once again has several choices,
+   including (but not limited to) the following:</p>
+
+   <ul>
+
+    <li>Fire the <code title="dom-listener-getRows">getRows()</code>
+    method for rows 1 through 8 again, this time listing just column
+    C.</li>
+
+    <li>Fire the <code title="dom-listener-getRows">getRows()</code>
+    method for row 1, then fire it again for rows 5 and 6, and then
+    fire the <code title="dom-listener-getCells">getCells()</code>
+    method for the other rows (in all three cases, listing just column
+    C).</li>
+
+   </ul>
+
+   <p>The two options here are as bad as each other; the former
+   involves a lot of overlap, but the latter involves a lot of method
+   calls. Unfortunately the user agent can't do the obvious thing,
+   namely just to invoke the <code
+   title="dom-listener-getCells">getCells()</code> method for all the
+   rows listing just column C, because it doesn't have the row
+   information for all the rows yet (rows 1, 5 and 6 are still
+   pending).</p>
+
+   <p>In any case, the data model now looks like this:</p>
+
+   <table>
+    <tr> <td>        <th> Row     <th> Column A  <th> Column B  <th> Column C
+    <tr> <th> Row 1  <td> Pending <td> Pending   <td> Pending   <td> Pending
+    <tr> <th> Row 2  <td> Yes     <td> Yes       <td> Yes       <td> Pending
+    <tr> <th> Row 3  <td> Yes     <td> Yes       <td> Yes       <td> Pending
+    <tr> <th> Row 4  <td> Yes     <td> Yes       <td> Yes       <td> Pending
+    <tr> <th> Row 5  <td> Pending <td> Pending   <td> Pending   <td> Pending
+    <tr> <th> Row 6  <td> Pending <td> Pending   <td> Pending   <td> Pending
+    <tr> <th> Row 7  <td> Yes     <td> Pending   <td> Pending   <td> Pending
+    <tr> <th> Row 8  <td> Yes     <td> Pending   <td> Pending   <td> Pending
+   </table>
+
+   <p>If at this point the user scrolls around anywhere within this
+   <code>datagrid</code>, the user agent won't fire the <code
+   title="dom-listener-getRos">getRos()</code> and <code
+   title="dom-listener-getCells">getCells()</code> methods, because
+   all of the rows and cells are covered.</p>
+
+   <p>Now consider the case where the user agent receives row
+   information, but no cell information, for rows 1, 5, and 6:</p>
+
+   <table>
+    <tr> <td>        <th> Row     <th> Column A  <th> Column B  <th> Column C
+    <tr> <th> Row 1  <td> Yes     <td> Pending   <td> Pending   <td> Pending
+    <tr> <th> Row 2  <td> Yes     <td> Yes       <td> Yes       <td> Pending
+    <tr> <th> Row 3  <td> Yes     <td> Yes       <td> Yes       <td> Pending
+    <tr> <th> Row 4  <td> Yes     <td> Yes       <td> Yes       <td> Pending
+    <tr> <th> Row 5  <td> Yes     <td> Pending   <td> Pending   <td> Pending
+    <tr> <th> Row 6  <td> Yes     <td> Pending   <td> Pending   <td> Pending
+    <tr> <th> Row 7  <td> Yes     <td> Pending   <td> Pending   <td> Pending
+    <tr> <th> Row 8  <td> Yes     <td> Pending   <td> Pending   <td> Pending
+   </table>
 
+   <p>The user agent still won't fire any methods when the user
+   scrolls, because the data is still covered. But if the script then
+   calls the <code title="dom-datagrid-renotify">renotify()</code>
+   method, the "Pending" flags would get reset, and the model would
+   now look like this:</p>
 
-  <h5>Populating the <code>datagrid</code> element</h5>
+   <table>
+    <tr> <td>        <th> Row     <th> Column A  <th> Column B  <th> Column C
+    <tr> <th> Row 1  <td> Yes     <td> -         <td> -         <td> -      
+    <tr> <th> Row 2  <td> Yes     <td> Yes       <td> Yes       <td> -      
+    <tr> <th> Row 3  <td> Yes     <td> Yes       <td> Yes       <td> -      
+    <tr> <th> Row 4  <td> Yes     <td> Yes       <td> Yes       <td> -      
+    <tr> <th> Row 5  <td> Yes     <td> -         <td> -         <td> -      
+    <tr> <th> Row 6  <td> Yes     <td> -         <td> -         <td> -      
+    <tr> <th> Row 7  <td> Yes     <td> -         <td> -         <td> -      
+    <tr> <th> Row 8  <td> Yes     <td> -         <td> -         <td> -      
+   </table>
 
-  <p>A <code>datagrid</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>datagrid</code> element in the original document markup) or
-  until it has been <span title="insert an element into a
-  document">inserted into the document</span> (in the case of a
-  dynamically created element). After that point, the element must
-  fire a single <code title="event-load">load</code> event at itself,
-  which doesn't bubble and cannot be canceled.</p>
+   <p>Now, assuming that all eight rows and all three columns are
+   still visible, the user agent has the following choices (amongst
+   others):</p>
 
-  <p class="XXX">The end-tag parsing thing should be moved to
-  the parsing section.</p>
+   <ul>
 
-  <p>The <code>datagrid</code> must then populate itself using the
-  data provided by the data provider assigned to the <code
-  title="dom-datagrid-data">data</code> DOM attribute. After the view
-  is populated (using the methods described below), the
-  <code>datagrid</code> must invoke the <code
-  title="dom-provider-initialize">initialize()</code> method on the
-  data provider specified by the <code
-  title="dom-datagrid-data">data</code> attribute, passing itself (the
-  <code>HTMLDataGridElement</code> object) as the only argument.</p>
+    <li>Fire the <code title="dom-listener-getRows">getCells()</code>
+    method for rows 1 through 8, listing all three columns.</li>
 
-  <p>When the <code title="dom-datagrid-data">data</code> attribute is
-  null, the <code>datagrid</code> must use the default data provider
-  described in the previous section.</p>
+    <li>Fire the <code title="dom-listener-getRows">getCells()</code>
+    method for rows 1 and 5 through 8, listing all three columns, and
+    then fire the method for rows 2 through 4, listing just column
+    C.</li>
 
-  <p>To obtain data from the data provider, the element must invoke
-  methods on the data provider object in the following ways:</p>
+    <li>Fire the <code title="dom-listener-getRows">getCells()</code>
+    method for rows 1 and 5 through 8, listing just columns A abd B,
+    and then fire the method for rows 1 through 8, listing just column
+    C.</li>
+
+   </ul>
+
+   <p>Here the latter two are preferable because they result in less
+   overlap than the first.</p>
+
+  </div>
+
+  <hr>
+
+  <p>The <span>task source</span> for tasks queued on behalf of a
+  <code>datagrid</code> is the <span>DOM manipulation task
+  source</span>.</p>
+
+  </div>
+
+
+  <h5>Listening to notifications from the <code>datagrid</code></h5>
+
+  <p><em>The conformance criteria in this section apply to any
+  implementation of the <code>DataGridListener</code> interface,
+  including (and most commonly) the content author's
+  implementation(s).</em></p>
+
+  <pre class="idl">// To be implemented by Web authors as a JS object
+[NoInterfaceObject] interface <dfn>DataGridListener</dfn> {
+  void <span title="dom-listener-initialize">initialize</span>(in <span>HTMLDataGridElement</span> datagrid);
+
+  void <span title="dom-listener-getRows">getRows</span>(in unsigned long rowIndex, in unsigned long rowCount, in <span>RowID</span> parentRow, in unsigned long position, in <span>ColumnList</span> columns);
+  void <span title="dom-listener-getCells">getCells</span>(in <span>RowIDList</span> rows, in <span>ColumnList</span> columns);
+  void <span title="dom-listener-rowOpened">rowOpened</span>(in <span>RowID</span> row, in boolean rowCountNeeded);
+  void <span title="dom-listener-rowClosed">rowClosed</span>(in <span>RowID</span> row);
+
+  void <span title="dom-listener-cellChanged">cellChanged</span>(in <span>RowID</span> row, in <span>Column</span> column, in any newValue, in any prevValue);
+  <span>HTMLMenuElement</span> <span title="dom-listener-getRowMenu">getRowMenu</span>(in <span>RowID</span> row);
+<!--vsDGDND
+  boolean <span title="dom-listener-canDrop">canDrop</span>(in <span>RowID</span> row, in <span>RowID</span> position, data);
+  boolean <span title="dom-listener-dropped">dropped</span>(in <span>RowID</span> row, in <span>RowID</span> position, data);
+--><!--v2DGPA
+  void <span title="dom-listener-performAction">performAction</span>(in <span>RowID</span> row, in DOMString action);
+-->};</pre>
+
+  <p>The <code>DataGridDataProvider</code> interface, once implemented
+  by an object in a script and hooked up to a <code>datagrid</code>
+  using the <dfn title="dom-datagrid-data"><code>data</code></dfn> DOM
+  attribute, receives notifications when the <code>datagrid</code>
+  needs information (such as which rows exist) for display.</p>
+
+  <p>The following methods may be usefully implemented:</p>
 
   <dl>
 
-   <dt>To determine the total number of columns</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getColumnCount">getColumnCount()</code> method
-   with no arguments. The return value is the number of columns. If
-   the return value is zero or negative, not an integer, or simply not
-   a numeric type, or if the method is not defined, then 1 must be
-   used instead.</dd>
-
-   <dt>To get the captions to use for the columns</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getCaptionText">getCaptionText()</code> method
-   with the index of the column in question. The index <var
-   title="">i</var> must be in the range 0 &le; <var title="">i</var>
-   &lt; <var title="">N</var>, where <var title="">N</var> is the
-   total number of columns. The return value is the string to use when
-   referring to that column. If the method returns null or the empty
-   string, the column has no caption. If the method is not defined,
-   then none of the columns have any captions.</dd>
-
-   <dt>To establish what classes apply to a column</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getCaptionClasses">getCaptionClasses()</code>
-   method with the index of the column in question, and an object
-   implementing the <code>DOMTokenList</code> interface, associated
-   with an anonymous empty string. The index <var title="">i</var>
-   must be in the range 0 &le; <var title="">i</var> &lt; <var
-   title="">N</var>, where <var title="">N</var> is the total number
-   of columns. The tokens contained in the string underlying
-   <code>DOMTokenList</code> object when the method returns represent
-   the classes that apply to the given column. If the method is not
-   defined, no classes apply to the column.</dd>
-
-   <dt>To establish whether a column should be initially included in
-   the visible columns</dt>
-
-   <dd>Check whether the <code
-   title="datagrid-column-class-initially-hidden">initially-hidden</code>
-   class applies to the column. If it does, then the column should not
-   be initially included; if it does not, then the column should be
-   initially included.</dd>
-
-   <dt id="columnType2">To establish whether the data can be sorted
-   relative to a particular column</dt>
-
-   <dd>Check whether the <code
-   title="datagrid-column-class-sortable">sortable</code> class
-   applies to the column. If it does, then the user agent should offer
-   the user the option to have the data displayed sorted by that
-   column; if it does not, then the user agent must not allow the user
-   to ask for the data to be sorted by that column.</dd>
-
-   <dt>To establish if a column is a sorted column</dt>
-
-   <dd>If the user agent can handle multiple columns being marked as
-   sorted simultaneously: Check whether the <code
-   title="datagrid-column-class-sorted">sorted</code> class applies to
-   the column. If it does, then that column is the sorted column,
-   otherwise it is not.</dd>
-
-   <dd>If the user agent can only handle one column being marked as
-   sorted at a time: Check each column in turn, starting with the
-   first one, to see whether the <code
-   title="datagrid-column-class-sorted">sorted</code> class applies to
-   that column. The first column that has that class, if any, is the
-   sorted column. If none of the columns have that class, there is no
-   sorted column.</dd>
-
-   <dt>To establish the sort direction of a sorted column</dt>
-
-   <dd>Check whether the <code
-   title="datagrid-column-class-reversed">reversed</code> class
-   applies to the column. If it does, then the sort direction is
-   descending (down; first rows have the highest values), otherwise it
-   is ascending (up; first rows have the lowest values).</dd>
-
-   <dt>To determine the total number of rows</dt>
-
-   <dd>Determine the number of rows for the root of the data grid, and
-   determine the number of child rows for each open row. The total
-   number of rows is the sum of all these numbers.</dd>
-
-   <dt>To determine the number of rows for the root of the data grid</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getRowCount">getRowCount()</code> method with a
-   <code>RowSpecification</code> object representing the empty path as
-   its only argument. The return value is the number of rows at the
-   top level of the data grid. If the return value of the method is
-   negative, not an integer, or simply not a numeric type, or if the
-   method is not defined, then zero must be used instead.</dd>
-
-   <dt>To determine the number of child rows for a row</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getRowCount">getRowCount()</code> method with a
-   <code>RowSpecification</code> object representing the path to the
-   row in question. The return value is the number of child rows for
-   the given row. If the return value of the method is negative, not
-   an integer, or simply not a numeric type, or if the method is not
-   defined, then zero must be used instead.</dd>
-
-   <dt>To determine what order to render rows in</dt>
-
-   <dd>
-
-    <p>Invoke the <code
-    title="dom-provider-getChildAtPosition">getChildAtPosition()</code>
-    method with a <code>RowSpecification</code> object representing
-    the path to the parent of the rows that are being rendered as the
-    first argument, and the position that is being rendered as the
-    second argument. The return value is the index of the row to
-    render in that position.</p>
+   <dt><dfn title="dom-listener-initialize"><code>initialize(<var title="">datagrid</var>)</code></dfn></dt>
 
-    <div class="example">
+   <dd>
 
-     <p>If the rows are:</p>
+    <p>Called by the <code>datagrid</code> element (the one given by
+    the <var title="">datagrid</var> argument) when the <code
+    title="dom-datagrid-listener">listener</code> attribute is
+    set.</p>
 
-     <ol>
-      <li> Row "0"
-       <ol>
-        <li> Row "0,0"
-        <li> Row "0,1"
-       </ol>
-      </li>
-      <li> Row "1"
-       <ol>
-        <li> Row "1,0"
-        <li> Row "1,1"
-       </ol>
-      </li>
-     </ol>
+   </dd>
 
-     <p>...and the <code
-    title="dom-provider-getChildAtPosition">getChildAtPosition()</code>
-    method is implemented as follows:</p>
+   <dt><dfn title="dom-listener-getRows"><code>getRows(<var title="">rowIndex</var>, <var title="">rowCount</var>, <var title="">parentRow</var>, <var title="">position</var>, <var title="">columns</var>)</code></dfn></dt>
 
-    <pre>function getChildAtPosition(parent, child) {
-  // always return the reverse order
-  return getRowCount(parent)-child-1;
-}</pre>
+   <dd>
 
-     <p>...then the rendering would actually be:</p>
+    <p>Called by the <code>datagrid</code> element when the user agent
+    finds itself needing to render rows for which it is lacking
+    information.</p>
 
-     <ol>
-      <li> Row "1"
-       <ol>
-        <li> Row "1,1"
-        <li> Row "1,0"
-       </ol>
-      </li>
-      <li> Row "0"
-       <ol>
-        <li> Row "0,1"
-        <li> Row "0,0"
-       </ol>
-      </li>
-     </ol>
+    <p>The <var title="">rowIndex</var> argument gives the flattened
+    index of the first row for which it needs information, ignoring
+    the tree structure of the <code>datagrid</code> model, where zero
+    is the first row of the entire tree.</p>
 
-    </div>
+    <p>The <var title="">rowCount</var> argument gives the number of
+    rows for which the user agent would like information.</p>
 
-    <p>If the return value of the method is negative, larger than the
-    number of rows that the <code
-    title="dom-provider-getRowCount">getRowCount()</code> method
-    reported for that parent, not an integer, or simply not a numeric
-    type, then the entire data grid should be disabled. Similarly, if
-    the method returns the same value for two or more different values
-    for the second argument (with the same first argument, and
-    assuming that the data grid hasn't had relevant update methods
-    invoked in the meantime), then the data grid should be
-    disabled. Instead of disabling the data grid, the user agent may
-    act as if the <code
-    title="dom-provider-getChildAtPosition">getChildAtPosition()</code>
-    method was not defined on the data provider (thus disabling
-    sorting for that data grid, but still letting the user interact
-    with the data). If the method is not defined, then the return
-    value must be assumed to be the same as the second argument (an
-    identity transform; the data is rendered in its natural
-    order).</p>
-
-   </dd>
-
-   <dt>To establish what classes apply to a row</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getRowClasses">getRowClasses()</code> method
-   with a <code>RowSpecification</code> object representing the row in
-   question, and a <code>DOMTokenList</code> associated with an empty
-   string. The tokens contained in the <code>DOMTokenList</code>
-   object's underlying string when the method returns represent the
-   classes that apply to the row in question. If the method is not
-   defined, no classes apply to the row.</dd>
-
-   <dt>To establish whether a row is a data row or a special row</dt>
-
-   <dd>Examine the classes that apply to the row. If the <code
-   title="datagrid-row-class-header">header</code> class applies to
-   the row, then it is not a data row, it is a subheading. The data
-   from the first cell of the row is the text of the subheading, the
-   rest of the cells must be ignored. Otherwise, if the <code
-   title="datagrid-row-class-separator">separator</code> class applies
-   to the row, then in the place of the row, a separator should be
-   shown. Otherwise, if the <code
-   title="datagrid-row-class-selectable-separator">selectable-separator</code>
-   class applies to the row, then the row should be a data row, but
-   represented as a separator. (The difference between a <code
-   title="datagrid-row-class-separator">separator</code> and a <code
-   title="datagrid-row-class-selectable-separator">selectable-separator</code>
-   is that the former is not an item that can be actually selected,
-   whereas the second can be selected and thus has a context menu that
-   applies to it, and so forth.) For both kinds of separator rows, the
-   data of the rows' cells must all be ignored. If none of those three
-   classes apply then the row is a simple data row.</dd>
-
-   <dt id="rowType1">To establish whether a row is openable</dt>
-
-   <dd>Determine the number of child rows for that row. If there are
-   one or more child rows, then the row is openable.</dd>
-
-   <dt>To establish whether a row should be initially open or closed</dt>
-
-   <dd>If <a href="#rowType1">the row is openable</a>, examine the
-   classes that apply to the row. If the <code
-   title="datagrid-row-class-initially-open">initially-open</code>
-   class applies to the row, then it should be initially
-   open. Otherwise, if the <code
-   title="datagrid-row-class-initially-closed">initially-closed</code>
-   class applies to the row, then it must be initially
-   closed. Otherwise, if neither class applies to the row, or if the
-   row is not openable, then the initial state of the row should be
-   based on platform conventions.</dd>
-
-<!-- XXXPA
-   <dt>To establish whether a row is deletable</dt>
-
-   <dd>Check whether the <code
-   title="datagrid-row-class-deletable">deletable</code> class applies
-   to the row. If it does, the row is deletable, and interactive user
-   agents should provide a way for the user to request that the row be
-   deleted. (See the <code
-   title="dom-provider-performActionOnRow">performActionOnRow()</code>
-   method for more details.) Otherwise, the user agent should not
-   provide the user with a method for requesting that the row be
-   deleted.</dd>
--->
+    <p>The <var title="">parentRow</var> argument gives the
+    <code>RowID</code> object identifying the nearest ancestor of the
+    first row that the user agent is aware of. After the sort order
+    has changed, this will typically be the root of the tree
+    (identified by a <code>RowID</code> object consisting of an empty
+    array).
 
-   <dt>To obtain a <span>URL</span> identifying an image representing a row</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getRowImage">getRowImage()</code> method with a
-   <code>RowSpecification</code> object representing the row in
-   question. The return value is a <span>URL</span>. Immediately <span
-   title="resolve a url">resolve</span> that URL, relative to the
-   <code>datagrid</code> element, to obtain an <span>absolute
-   URL</span> identifying the image that represents the row. If the
-   method returns the empty string, null, or if the method is not
-   defined, then the row has no associated image.</dd> <!-- changing
-   the base URL doesn't change the image used later -->
-
-   <dt>To obtain a context menu appropriate for a particular row</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getRowMenu">getRowMenu()</code> method with a
-   <code>RowSpecification</code> object representing the row in
-   question. The return value is a reference to an object implementing
-   the <code>HTMLMenuElement</code> interface, i.e. a
-   <code>menu</code> element DOM node. (This element must then be
-   interpreted as described in the section on context menus to obtain
-   the actual context menu to use.<!-- XXX update once menu section
-   works; with xrefs -->) If the method returns something that is not
-   an <code>HTMLMenuElement</code>, or if the method is not defined,
-   then the row has no associated context menu. User agents may
-   provide their own default context menu, and may add items to the
-   author-provided context menu. For example, such a menu could allow
-   the user to change the presentation of the <code>datagrid</code>
-   element.</dd>
-
-   <dt>To establish the value of a particular cell</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getCellData">getCellData()</code> method with
-   the first argument being a <code>RowSpecification</code> object
-   representing the row of the cell in question and the second
-   argument being the index of the cell's column. The second argument
-   must be a non-negative integer less than the total number of
-   columns. The return value is the value of the cell. If the return
-   value is null or the empty string, or if the method is not defined,
-   then the cell has no data. (For progress bar cells, the cell's
-   value must be further interpreted, as described below.)</dd>
-
-   <dt>To establish what classes apply to a cell</dt>
-
-   <dd>Invoke the <code
-   title="dom-provider-getCellClasses">getCellClasses()</code> method
-   with the first argument being a <code>RowSpecification</code>
-   object representing the row of the cell in question, the second
-   argument being the index of the cell's column, and the third being
-   an object implementing the <code>DOMTokenList</code> interface,
-   associated with an empty string. The second argument must be a
-   non-negative integer less than the total number of columns. The
-   tokens contained in the <code>DOMTokenList</code> object's
-   underlying string when the method returns represent the classes
-   that apply to that cell. If the method is not defined, no classes
-   apply to the cell.</dd>
-
-   <dt id="cellType1">To establish the type of a cell</dt>
-
-   <dd>Examine the classes that apply to the cell. If the <code
-   title="datagrid-cell-class-progress">progress</code> class applies
-   to the cell, it is a progress bar. Otherwise, if the <code
-   title="datagrid-cell-class-cyclable">cyclable</code> class applies
-   to the cell, it is a cycling cell whose value can be cycled between
-   multiple states. Otherwise, none of these classes apply, and the
-   cell is a simple text cell.</dd>
-
-   <dt>To establish the value of a progress bar cell</dt>
-
-   <dd>If the value <var title="">x</var> of the cell is a string that
-   can be <span title="rules for parsing floating point number
-   values">converted to a floating-point number</span> in the range
-   0.0&nbsp;&le;&nbsp;<var title="">x</var>&nbsp;&le;&nbsp;1.0, then
-   the progress bar has that value (0.0 means no progress, 1.0 means
-   complete). Otherwise, the progress bar is an indeterminate progress
-   bar.</dd>
-
-   <dt id="cellType2">To establish how a simple text cell should be presented</dt>
-
-   <dd>Check whether one of the <code
-   title="datagrid-cell-class-checked">checked</code>, <code
-   title="datagrid-cell-class-unchecked">unchecked</code>, or <code
-   title="datagrid-cell-class-indeterminate">indeterminate</code>
-   classes applies to the cell. If any of these are present, then the
-   cell has a checkbox, otherwise none are present and the cell does
-   not have a checkbox. If the cell has no checkbox, check whether the
-   <code title="datagrid-cell-class-editable">editable</code> class
-   applies to the cell. If it does, then the cell value is editable,
-   otherwise the cell value is static.</dd>
-
-   <dt>To establish the state of a cell's checkbox, if it has one</dt>
-
-   <dd>Check whether the <code
-   title="datagrid-cell-class-checked">checked</code> class applies to
-   the cell. If it does, the cell is checked. Otherwise, check whether
-   the <code title="datagrid-cell-class-unchecked">unchecked</code>
-   class applies to the cell. If it does, the cell is unchecked.
-   Otherwise, the <code
-   title="datagrid-cell-class-indeterminate">indeterminate</code>
-   class applies to the cell and the cell's checkbox is in an
-   indeterminate state. When the <code
-   title="datagrid-cell-class-indeterminate">indeterminate</code>
-   class applies to the cell, the checkbox is a tristate checkbox,
-   and the user can set it to the indeterminate state. Otherwise, only
-   the <code title="datagrid-cell-class-checked">checked</code> and/or
-   <code title="datagrid-cell-class-unchecked">unchecked</code>
-   classes apply to the cell, and the cell can only be toggled between
-   those two states.</dd>
+    <p>The <var title="">columns</var> argument gives the columns for
+    which the user agent is lacking information, as an array of column
+    identifiers (as passed to <code
+    title="dom-datagrid-addColumn">addColumn()</code>).</p>
 
-  </dl>
+   </dd>
 
-  <p>If the data provider ever raises an exception while the
-  <code>datagrid</code> is invoking one of its methods, the
-  <code>datagrid</code> must act, for the purposes of that particular
-  method call, as if the relevant method had not been defined.</p>
-
-  <p>A <code>RowSpecification</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&nbsp;&le;&nbsp;<var
-  title="">p<sub title=""><var
-  title="">i</var></sub></var>&nbsp;&lt;&nbsp;<var
-  title="">m</var>-1</span> for all integer values of <var
-  title="">i</var> in the range <span>0&nbsp;&le;&nbsp;<var
-  title="">i</var>&nbsp;&lt;&nbsp;<var title="">n</var>-1</span>,
-  where <var title="">m</var> is the value that was last returned by
-  the <code title="dom-provider-getRowCount">getRowCount()</code>
-  method when it was passed the <code>RowSpecification</code> object
-  <var title="">q</var> with <span title=""><var title="">i</var>-1</span>
-  items, where <span title=""><var title="">p<sub title=""><var
-  title="">i</var></sub></var>&nbsp;=&nbsp;<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&nbsp;&le;&nbsp;<var title="">i</var>&nbsp;&lt;&nbsp;<var
-  title="">n</var>-1</span>, with any changes implied by the update
-  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>datagrid</code> element. If a user
-  agent is returned inconsistent data, for example if the number of
-  rows returned by <code
-  title="dom-provider-getRowCount">getRowCount()</code> varies in ways
-  that do not match the calls made to the update methods, the user
-  agent may disable the <code>datagrid</code>. User agents that do not
-  disable the <code>datagrid</code> in inconsistent cases must honor
-  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">getRowMenu</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>Updating the <code>datagrid</code></h5>
-
-  <p>Whenever the <code title="dom-datagrid-data">data</code>
-  attribute is set to a new value, the <code>datagrid</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>
-
-  <p>There are a number of update methods that can be invoked on the
-  <code>datagrid</code> element to cause it to refresh itself in
-  slightly less drastic ways:</p>
+   <dt><dfn title="dom-listener-getCells"><code>getCells(<var title="">rows</var>, <var title="">columns</var>)</code></dfn></dt>
 
-  <p>When the <dfn
-  title="dom-datagrid-updateEverything"><code>updateEverything()</code></dfn>
-  method is called, the user agent must repopulate the entire
-  <code>datagrid</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>
+   <dd>
 
-  <p>When the <dfn
-  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>
+    <p>Called by the <code>datagrid</code> element when the user agent
+    finds itself needing to render cells for which it is lacking
+    information in rows that it does know about.</p>
 
-  <p>When the <dfn
-  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>
+    <p>The <var title="">rows</var> argument gives an array of
+    <code>RowID</code> objects identifying the various rows for which
+    the user agent is lacking information.</p>
 
-  <p>When the <dfn
-  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>
+    <p>The <var title="">columns</var> argument gives the columns for
+    which the user agent is lacking information, as an array of column
+    identifiers (as passed to <code
+    title="dom-datagrid-addColumn">addColumn()</code>).</p>
 
-  <p>The <dfn
-  title="dom-datagrid-updateRowChanged"><code>updateRowChanged(<var
-  title="">row</var>)</code></dfn> method must be exactly equivalent
-  to calling <code
-  title="dom-datagrid-updateRowsChanged">updateRowsChanged(<var
-  title="">row</var>, 1)</code>.</p>
+   </dd>
 
-  <p>When the <dfn
-  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>
+   <dt><dfn title="dom-listener-rowOpened"><code>rowOpened(<var title="">row</var>, <var title="">rowCountNeeded</var>)</code></dfn></dt>
 
-  <p>When the <dfn
-  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>
-
-  <p>Any effects the update methods have on the
-  <code>datagrid</code>'s selection is not considered a change to the
-  selection, and must therefore not fire the <code
-  title="event-select">select</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">updateRowsInserted()</code>
-  and <code
-  title="dom-datagrid-updateRowsRemoved">updateRowsRemoved()</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.</p>
+   <dd>
 
+    <p>Called by the <code>datagrid</code> element when the user has
+    opened a row.</p>
 
-  <h5>Requirements for interactive user agents</h5>
+    <p>The <var title="">row</var> argument gives an
+    <code>RowID</code> object identifying the row that was opened.</p>
 
-  <p><em>This section only applies to interactive user agents.</em></p>
+    <p>If the user agent also knows how many children that row has,
+    then the <var title="">rowCountNeeded</var> argument will be
+    false. Otherwise, the argument will be true, and the row will
+    remain closed until the <code
+    title="dom-datagrid-setRows">setRows()</code> method is called
+    with an accurate row count.</p>
 
-  <p>If the <code>datagrid</code> element has a <dfn
-  title="attr-datagrid-disabled"><code>disabled</code></dfn>
-  attribute, then the user agent must disable the
-  <code>datagrid</code>, preventing the user from interacting with it.
-  The <code>datagrid</code> element should still continue to update
-  itself when the data provider signals changes to the data, though.
-  Obviously, conformance requirements stating that
-  <code>datagrid</code> elements must react to users in particular
-  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>
-
-  <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
-  <code>datagrid</code> must invoke the data provider's <code
-  title="dom-provider-cycleCell">cycleCell()</code> method, with a
-  <code>RowSpecification</code> object representing the cell's row as
-  the first argument and the cell's column index as the second. The
-  <code>datagrid</code> must then act as if the
-  <code>datagrid</code>'s <code
-  title="dom-datagrid-updateCellChanged">updateCellChanged()</code>
-  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>datagrid</code> must invoke the data provider's <code
-  title="dom-provider-setCellCheckedState">setCellCheckedState()</code>
-  method, with a <code>RowSpecification</code> object representing the
-  cell's row as the first argument, the cell's column index as the
-  second, and the checkbox's new state as the third. The state should
-  be represented by the number 1 if the new state is checked, 0 if the
-  new state is unchecked, and &#x2212;1 if the new state is
-  indeterminate (which must be possible only if the cell has the <code
-  title="datagrid-cell-class-indeterminate">indeterminate</code> class
-  set). The <code>datagrid</code> must then act as if the
-  <code>datagrid</code>'s <code
-  title="dom-datagrid-updateCellChanged">updateCellChanged()</code>
-  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">editCell()</code> method of the data
-  provider with three arguments: a <code>RowSpecification</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">updateCellChanged()</code>
-  method had been invoked, with the same row and column specified.</p>
+   </dd>
 
-  <!-- XXXPA <p class="XXX">define actions (performAction(), etc)</p> -->
+   <dt><dfn title="dom-listener-rowClosed"><code>rowClosed(<var title="">row</var>)</code></dfn></dt>
 
-  <h5>The selection</h5>
+   <dd>
+
+    <p>Called by the <code>datagrid</code> element when the user has
+    opened a row.</p>
+
+    <p>The <var title="">row</var> argument gives an
+    <code>RowID</code> object identifying the row that was closed.</p>
+
+   </dd>
+
+   <dt><dfn title="dom-listener-cellChanged"><code>cellChanged(<var title="">row</var>, <var title="">column</var>, <var title="">newValue</var>, <var title="">prevValue</var>)</code></dfn></dt>
+
+   <dd>
+
+    <p>Called by the <code>datagrid</code> element when the user has
+    edited a cell or checked a check box in a cell.</p>
+
+    <p>The <var title="">row</var> argument gives an
+    <code>RowID</code> object identifying the row of the cell, and the
+    <var title="">column</var> argument gives the identifier of the
+    cell's column.</p>
+
+    <p>The <var title="">newValue</var> argument gives the new value,
+    and the <var title="">prevValue</var> argument gives the previous
+    value.</p>
+
+   </dd>
+
+   <dt><dfn title="dom-listener-getRowMenu"><code>getRowMenu(<var title="">row</var>)</code></dfn></dt>
+
+   <dd>Must return an <code>HTMLMenuElement</code> object that is to
+   be used as a context menu for row <var title="">row</var>, or null
+   if there is no particular context menu. May be omitted if none of
+   the rows have a special context menu. As this method is called
+   immediately before showing the menu in question, no precautions
+   need to be taken if the return value of this method changes.</dd>
 
-  <p><em>This section only applies to interactive user agents. For
-  other user agents, the <code
-  title="dom-datagrid-selection">selection</code> attribute must
-  return null.</em></p>
+   <!--v2DGDND, v2DFPA-->
+
+  </dl>
+
+  <div class="impl">
+
+  <p>Objects that implement the <code>DataGridListener</code>
+  interface may omit any or all of the methods. When a method is
+  omitted, a user agent intending to call that method must instead
+  skip the method call, and must assume that the method's return value
+  is null.</p>
+
+  </div>
+
+
+
+<!-- v2DGS: <datagrid> selection (search for the bits marked "..." to see what needs filling in, at a minimum)
+
+  <h5>The selection</h5>
 
   <pre class="idl">interface <dfn>DataGridSelection</dfn> {
-  readonly attribute unsigned long <span title="dom-DataGridSelection-count">length</span>;
-  [IndexGetter] <span>RowSpecification</span> <span title="dom-DataGridSelection-item">item</span>(in unsigned long index);
-  boolean <span title="dom-DataGridSelection-isSelected">isSelected</span>(in <span>RowSpecification</span> row);
-  void <span title="dom-DataGridSelection-setSelected">setSelected</span>(in <span>RowSpecification</span> row, in boolean selected);
-<!--  void <span title="dom-DataGridSelection-addRange">addRange</span>(in <span>RowSpecification</span> first, in <span>RowSpecification</span> last);
-  void <span title="dom-DataGridSelection-removeRange">removeRange</span>(in <span>RowSpecification</span> first, in <span>RowSpecification</span> last);
-XXX selection ranges -->
+  readonly attribute unsigned long <span title="dom-DataGridSelection-length">length</span>;
+  [IndexGetter] <span>RowID</span> <span title="dom-DataGridSelection-item">item</span>(in unsigned long index);
+  boolean <span title="dom-DataGridSelection-isSelected">isSelected</span>(in <span>RowID</span> row);
+  void <span title="dom-DataGridSelection-setSelected">setSelected</span>(in <span>RowID</span> row, in boolean selected);
   void <span title="dom-DataGridSelection-selectAll">selectAll</span>();
-  void <span title="dom-DataGridSelection-invert">invert</span>();
   void <span title="dom-DataGridSelection-clear">clear</span>();
 };</pre>
 
+  <dl class="domintro">
+
+   ...
+
+  </dl>
+
+  <div class="impl">
+
   <p>Each <code>datagrid</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>
+  be changed via the methods described in this section.</p>
 
   <p>The selection of a <code>datagrid</code> is represented by its
   <dfn title="dom-datagrid-selection"><code>selection</code></dfn> DOM
   attribute, which must be a <code>DataGridSelection</code> object.</p>
 
   <p><code>DataGridSelection</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>
-
-  <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>
+  selection. In the selection the rows must be ordered in their
+  natural order (and not, e.g., the display order). A row with an
+  ancestor that is closed cannot be selected.</p>
 
   <p>The <dfn
   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">length</var>.</p>
 
   <p>The object's <span>indices of the supported indexed
   properties</span> are the numbers in the range zero to <span title=""><var
   title="dom-DataGridSelection-length">length</var>-1</span>, unless
   the <var title="dom-DataGridSelection-length">length</var> is zero,
   in which case there are no <span>supported indexed
   properties</span>.</p>
 
   <p>The <dfn title="dom-DataGridSelection-item"><code>item(<var
-  title="">index</var>)</code></dfn> method must return the <var
+  title="">index</var>)</code></dfn> method must return a
+  <code>RowID</code> object identifying 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>INDEX_SIZE_ERR</code>
   exception. <a href="#refsDOM3CORE">[DOM3CORE]</a></p>
 
   <p>The <dfn
   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>
+  argument. If the specified row is in the <span>natural order sparse
+  data tree</span> and is selected, the method must return true,
+  otherwise it must return false.</p>
 
   <p>The <dfn
   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>INDEX_SIZE_ERR</code> exception. If the
-  specified row is not rendered because one of its ancestors is
-  closed, the method must do nothing.</p>
+  <var title="">row</var> does not specify a row in the <span>natural
+  order sparse data tree</span> ...
 
   <p>The <dfn
   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">selectAll()</code>, the
-  <code title="dom-DataGridSelection-length">length</code> attribute
-  will return the number of rows in the data grid, not counting
-  children of closed rows.</p>
-
-  <p>The <dfn
-  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>
+  method must ...
 
   <p>The <dfn
   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
+  method must mark all the rows in the <code>datagrid</code> as not
+  selected. After a call to <code
   title="dom-DataGridSelection-clear">clear()</code>, the <code
   title="dom-DataGridSelection-length">length</code> attribute will
   return zero.</p>
 
-  <p>If the <code>datagrid</code> element has a <dfn
-  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>
+  <p>If the <code>datagrid</code> element has a <code
+  title="attr-datagrid-multiple">multiple</code> 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
+  should allow the user to select a row, and must not allow the user
+  to select more than a single row at a time; selecting another one
+  must unselect all the other rows.</p>
 
   <p class="note">This only applies to the user. Scripts can select
   multiple rows even when the <code
   title="attr-datagrid-multiple">multiple</code> attribute is
   absent.</p>
 
-  <p>Whenever the selection of a <code>datagrid</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">selection</code> object, a <dfn
-  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
-  our story going to be regarding events and defining them? --> event
-  that bubbles but is not cancelable must be fired on the
-  <code>datagrid</code> element. If changes are made to the selection
-  via calls to the object's methods during the execution of a
-  script<!-- XXX should xref to a better explanation -->, then the
-  <code title="event-select">select</code> events must be coalesced
-  into one, which must then be fired<!--XXX xref again--> when the
-  script execution has completed<!-- XXX xref -->.</p>
+  ...event on selection change?...
+
+  </div>
 
   <p class="note">The <code>DataGridSelection</code> interface has no
   relation to the <code>Selection</code> interface.</p>
 
+-->
 
-  <h5>Columns and captions</h5>
-
-  <p><em>This section only applies to interactive user agents.</em></p>
 
-  <p>Each <code>datagrid</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">initially-hidden</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>
-
-  <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>
-
-  <p>If none of the columns have any captions (i.e. if the data
-  provider does not provide a <code
-  title="dom-provider-getCaptionText">getCaptionText()</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>
-
-  <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">getColumnCount()</code> method
-  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>datagrid</code>
-  must invoke the data provider's <code
-  title="dom-provider-toggleColumnSortState">toggleColumnSortState()</code>
-  method, with the column's index as the only argument. The
-  <code>datagrid</code> must <em>then</em> act as if the
-  <code>datagrid</code>'s <code
-  title="dom-datagrid-updateEverything">updateEverything()</code>
-  method had been invoked.</p>
-
-<!--XXXDND
+<!--vsDGDND
   <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>
+  ...define drag and drop in datagrids; selectiondraggable...
 -->
-</div>
 
 
   <h4 id="the-command">The <dfn><code>command</code></dfn> element</h4>
 
   <dl class="element">
    <dt>Categories</dt>
    <dd><span>Metadata content</span>.</dd>
    <dd><span>Flow content</span>.</dd>
    <dd><span>Phrasing content</span>.</dd>
    <dt>Contexts in which this element may be used:</dt>
@@ -74599,15 +75207,16 @@ TODO (or delay):
  XXX * become more consistent about what markup we use to mark up
        productions (nothing? <i>? <code>?)
  XXX * expose the value of a radio button group
         - either on the NodeList returned by HTMLFormControlCollection
         - or on the radio button itself
         - or both, so it works even when the form controls have names
           that vary more than HTMLFormControlCollection allows?
  XXX * should check all cases of 'active document' and change the
        relevant ones to 'fully active document'.
  XXX * use <code>Document</code> consistently instead of 'document'.
+ XXX * s/raise/throw/g
 -->
 
  </body>
 </html>
 <!--END html5-->

|