[html5] r5644 - [e] (0) Drop <datagrid> entirely for now.
whatwg at whatwg.org
whatwg at whatwg.org
Fri Oct 22 16:12:27 PDT 2010
Author: ianh
Date: 2010-10-22 16:12:13 -0700 (Fri, 22 Oct 2010)
New Revision: 5644
Modified:
complete.html
index
source
Log:
[e] (0) Drop <datagrid> entirely for now.
Modified: complete.html
===================================================================
--- complete.html 2010-10-22 23:07:42 UTC (rev 5643)
+++ complete.html 2010-10-22 23:12:13 UTC (rev 5644)
@@ -7924,7 +7924,6 @@
<li value=24><dfn id=not_readable_err><code>NOT_READABLE_ERR</code></dfn></li> <!-- File API -->
<li value=25><dfn id=data_clone_err><code>DATA_CLONE_ERR</code></dfn></li> <!-- actually defined right here for now -->
<li value=26><dfn id=encoding_err><code>ENCODING_ERR</code></dfn></li> <!-- File API -->
-<!--v2DATAGRID <li value=".."><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>SERIALIZE_ERR</code></dfn></li> <!- - actually defined in dom3ls - ->
@@ -10224,7 +10223,6 @@
<li><code><a href=#the-cite-element>cite</a></code></li>
<li><code><a href=#the-code-element>code</a></code></li>
<li><code><a href=#the-command>command</a></code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code><a href=#the-datalist-element>datalist</a></code></li>
<li><code><a href=#the-del-element>del</a></code></li>
<li><code><a href=#the-details-element>details</a></code></li>
@@ -10473,7 +10471,6 @@
<ul class="brief category-list"><li><code><a href=#the-a-element>a</a></code></li>
<li><code><a href=#audio>audio</a></code> (if the <code title=attr-media-controls><a href=#attr-media-controls>controls</a></code> attribute is present)</li>
<li><code><a href=#the-button-element>button</a></code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code><a href=#the-details-element>details</a></code></li>
<li><code><a href=#the-embed-element>embed</a></code></li>
<li><code><a href=#the-iframe-element>iframe</a></code></li>
@@ -16364,7 +16361,6 @@
<!-- when updating this also update the category index -->
<ul class="brief category-list"><li><code><a href=#the-blockquote-element>blockquote</a></code></li>
<li><code><a href=#the-body-element-0>body</a></code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code><a href=#the-details-element>details</a></code></li>
<li><code><a href=#the-fieldset-element>fieldset</a></code></li>
<li><code><a href=#the-figure-element>figure</a></code></li>
@@ -44081,11 +44077,7 @@
<p>The <code><a href=#the-datalist-element>datalist</a></code> element is hooked up to an
<code><a href=#the-input-element>input</a></code> element using the <code title=attr-input-list><a href=#attr-input-list>list</a></code> attribute on the
- <code><a href=#the-input-element>input</a></code> element. <!-- v2DATAGRID 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>
+ <code><a href=#the-input-element>input</a></code> element.</p>
<p>Each <code><a href=#the-option-element>option</a></code> element that is a descendant of the
<code><a href=#the-datalist-element>datalist</a></code> element, that is not <a href=#concept-option-disabled title=concept-option-disabled>disabled</a>, and whose <a href=#concept-option-value title=concept-option-value>value</a> is a string that isn't the
@@ -45628,7 +45620,7 @@
<ul class=brief><li>minimum value ≤ actual value ≤ maximum value</li>
<li>minimum value ≤ low boundary ≤ high boundary ≤ maximum value</li>
<li>minimum value ≤ optimum point ≤ maximum value</li>
- </ul><!-- next two paragraphs are duplicated in the <datagrid> section [v2DATAGRID] --><p><strong>UA requirements for regions of the gauge</strong>: If the
+ </ul><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
@@ -47753,2601 +47745,7 @@
-<!-- v2DATAGRID
- <h4 id="datagrid">The <dfn><code>datagrid</code></dfn> element</h4>
- <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 can be used:</dt>
- <dd>Where <span>flow content</span> is expected.</dd>
- <dt>Content model:</dt>
- <dd><span>Flow content</span>.</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> {
-<!- -v2DGS:
- attribute boolean <span title="dom-datagrid-multiple">multiple</span>;
-- -> attribute boolean <span title="dom-datagrid-disabled">disabled</span>;
- 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, in optional HTMLImageElement icon, in optional boolean sortable, in optional boolean hidden);
- 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<<span>Column</span>> <dfn>ColumnList</dfn>;
-typedef sequence<any> <dfn>Cell</dfn>; // <span>Column</span>, any... (exact types expected depend on the column type)
-typedef sequence<<span>Cell</span>> <dfn>CellList</dfn>;
-typedef sequence<any> <dfn>Row</dfn>; // <span>RowID</span>, long, long, <span>CellList</span>, optional boolean, optional long
-typedef sequence<<span>Row</span>> <dfn>RowList</dfn>;
-typedef sequence<unsigned long> <dfn>RowID</dfn>;
-typedef sequence<<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>
-
- <!- - v2:
- * datagrid: cells that are links (<a href=""></a>)
- - ->
-
- <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>
-
-<!- -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 <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 the
- <code>datagrid</code> is disabled.</span></p>
-
- <div class="impl">
-
- <!- -vsDGS: multiple - ->
-
- <p>The <dfn
- title="dom-datagrid-disabled"><code>disabled</code></dfn> IDL
- attribute must <span>reflect</span> the content attribute of the
- same name.</p>
-
- </div>
-
- <!- - 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><i>This section is non-normative.</i></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 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 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>
-- ->
-
- <!- - v2DGDND: selection should draggable to and from datagrids - ->
-
-
- <h6>Example: a <code>datagrid</code> backed by a static <code>table</code> element</h6>
-
- ...
-
-
- <h6>Example: a <code>datagrid</code> backed by nested <code>ol</code> elements</h6>
-
- ...
-
-
- <h6>Example: a <code>datagrid</code> backed by a server</h6>
-
- ...
-
-
- <h5>Populating the <code>datagrid</code></h5>
-
- <dl class="domintro">
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-listener">listener</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <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 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>
-
- <p>Can be set, to change the current listener.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-renotify">renotify</code>()</dt>
- <dd>
-
- <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>
-
- <!- - useful, e.g., if there is a server error and the script loses
- track of what rows it's supposed to be reporting. - ->
-
- </dd>
-
-
- <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="">hidden</var> ] ] ] )</dt>
- <dd>
-
- <p>Adds a column to the <code>datagrid</code>.</p>
-
- <p>If a column with the given identifier has already been added,
- it just replaces the information for that column.</p>
-
- <p>The possible types are enumerated in the previous section.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortColumn">sortColumn</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <p>Returns the identifier of the column by which the data is to be
- sorted.</p>
-
- <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>
-
- <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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortAscending">sortAscending</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <p>Returns true if the data is to be sorted with smaller values
- first; otherwise, returns false, indicating that bigger values are
- to be put first.</p>
-
- <p>Can be set, to indicate that the order is about to change.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearColumns">clearColumns</code>()</dt>
- <dd>
-
- <p>Removes all the columns in the <code>datagrid</code>,
- reinstating the implied column.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-setRowCount">setRowCount</code>(<var title="">childCount</var>, <var title="">rowCount</var>)</dt>
- <dd>
-
- <p>Sets the numbers of rows in the <code>datagrid</code>,
- excluding rows that are descendants of rows that are closed.</p>
-
- <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>A <code>RowID</code> object identifying the row.</li>
-
- <li>An integer giving the position of the row in its parent,
- given the current sort order, or −1 to set other row data
- without setting a position or changing a previously declared
- position.</li>
-
- <li>An integer giving the number of children of the row, or 0 if
- the row has no children, or −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
- −1 leaves the previous count unchanged.</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 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>
-
- <dl>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-insertRows">insertRows</code>(<var title="">rows</var>)</dt>
- <dd>
-
- <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>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>Throws a <code>DATAGRID_MODEL_ERR</code> exception if the
- arguments contradict each other or previously declared
- information.</p>
-
- </dd>
-
-
- <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>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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearRows">clearRows</code>()</dt>
- <dd>
-
- <p>Clears the <code>datagrid</code> of all row data, resetting it
- to empty<!- - v2DGS:, and clears the selection- ->.</p>
-
- </dd>
-
- </dl>
-
-
- <div class="impl">
-
- <h6>The listener</h6>
-
- <p>The <dfn
- title="dom-datagrid-listener"><code>listener</code></dfn> IDL
- 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">initialize()</code> method with the
- <code>datagrid</code> element as its only argument.</p>
-
-
- <h6>The columns</h6>
-
- <p>The columns are represented by the <dfn>column list</dfn>, an
- ordered list of entries for columns, each of which consists of:</p>
-
- <dl>
-
- <dt>An identifier</dt>
-
- <dd>A string used to identify the column in the API.</dd>
-
- <dt>A label</dt>
-
- <dd>A string used in the user interface.</dd>
-
- <dt>A type</dt>
-
- <dd>One of the types described below.</dd>
-
- <dt>An icon</dt>
-
- <dd>An image, copied from an <code>img</code> element when the
- column was declared.</dd>
-
- <dt>Whether the column is sortable</dt>
-
- <dd>A boolean indicating whether the user can request that the data
- be sorted by this column (true), or not (false).</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="">hidden</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, but the given <code>img</code> element is not in the <span
- title="img-all">completely available</span> state, then let <var
- title="">icon</var> be null.</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 unless the <var title="">hidden</var> argument is
- present and 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>
-
- </ol>
-
- <hr>
-
- <p>The <dfn
- title="dom-datagrid-sortColumn"><code>sortColumn</code></dfn> IDL
- 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>
- IDL 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 efficient, 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>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 −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 −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, the flag can only be changed by the user
- or while 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 −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>
-
- <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>
-
- <hr>
-
- <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>
-
- <ol>
-
- <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>
-
- </li>
-
- <li>
-
- <p>Clear the <span>pending <code>datagrid</code> rows list</span>
- and the <span>pending <code>datagrid</code> cells list</span>.</p>
-
- </li>
-
- <li>
-
- <p>Invoke the <span><code>datagrid</code> update display
- algorithm</span>.</p>
-
- </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 −1 nor equal to the child count of the
- preexisting row.</li>
-
- <li>The <code>Row</code> object has fewer than four
- entries or more than six entries.</li>
-
- <li>The <code>Row</code> object has five or more entries, and
- its fifth entry is false.</li>
-
- <li>The <code>Row</code> object has six entries, and 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 length 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 −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 if 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 −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 −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>
-
- <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 −1, zero, or a positive integer.</p></li>
-
- <li><p>The third value in the <code>Row</code> is an integer that
- is either −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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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() abstract operation 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() abstract operation
- to the value, and then verify that the result is neither an Infinity
- value nor a Not-a-Number (NaN) 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() abstract
- operation 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() abstract operation 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() abstract operation 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 −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>The cell represents some text and an optional image.</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>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>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><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>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 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>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>
-
- </dd>
-
- <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><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
- value 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>The cell represents a dynamically generated graphical image.</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 user agent should not allow the cell to be rendered with
- dimensions less than the given minimum width and height.</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> IDL 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>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 used 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>
-
- <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 −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 <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 <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 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-getRows">getRows()</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>
-
- <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>Now, assuming that all eight rows and all three columns are
- still visible, the user agent has the following choices (amongst
- others):</p>
-
- <ul>
-
- <li>Fire the <code title="dom-listener-getRows">getCells()</code>
- method for rows 1 through 8, listing all three columns.</li>
-
- <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>
-
- <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><i>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).</i></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>DataGridListener</code> interface, once implemented by
- an object in a script and hooked up to a <code>datagrid</code> using
- the <code title="dom-datagrid-listener">listener</code> IDL
- 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><dfn title="dom-listener-initialize"><code>initialize(<var title="">datagrid</var>)</code></dfn></dt>
-
- <dd>
-
- <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>
-
- </dd>
-
- <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>
-
- <dd>
-
- <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>
-
- <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>
-
- <p>The <var title="">rowCount</var> argument gives the number of
- rows for which the user agent would like information.</p>
-
- <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).
-
- <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>
-
- </dd>
-
- <dt><dfn title="dom-listener-getCells"><code>getCells(<var title="">rows</var>, <var title="">columns</var>)</code></dfn></dt>
-
- <dd>
-
- <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>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>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>
-
- </dd>
-
- <dt><dfn title="dom-listener-rowOpened"><code>rowOpened(<var title="">row</var>, <var title="">rowCountNeeded</var>)</code></dfn></dt>
-
- <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 opened.</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>
-
- </dd>
-
- <dt><dfn title="dom-listener-rowClosed"><code>rowClosed(<var title="">row</var>)</code></dfn></dt>
-
- <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>
-
- <!- -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-length">length</span>;
- getter <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-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. This can be
- changed using 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> IDL
- 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 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>supported property indices</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 property
- indices</span>.</p>
-
- <p>The <dfn title="dom-DataGridSelection-item"><code>item(<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="#refsDOMCORE">[DOMCORE]</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 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> 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 ...
-
- <p>The <dfn
- title="dom-DataGridSelection-clear"><code>clear()</code></dfn>
- 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 <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>
-
- ...event on selection change?...
-
- </div>
-
- <p class="note">The <code>DataGridSelection</code> interface has no
- relation to the <code>Selection</code> interface.</p>
-
-- ->
-
-
-<!- -vsDGDND
- <h5>Drag and drop in <code>datagrid</code>s</h5>
-
- <p><i>This section only applies to interactive user agents.</i></p>
-
- ...define drag and drop in datagrids; selectiondraggable...
-- ->
-
--->
-
<h4 id=the-command><span class=secno>4.11.3 </span>The <dfn><code>command</code></dfn> element</h4>
<dl class=element><dt>Categories</dt>
@@ -75949,13 +73347,12 @@
tag</a> may be omitted if the <code><a href=#the-p-element>p</a></code> element is
immediately followed by an <code><a href=#the-address-element>address</a></code>,
<code><a href=#the-article-element>article</a></code>, <code><a href=#the-aside-element>aside</a></code>, <code><a href=#the-blockquote-element>blockquote</a></code>,
- <!--v2DATAGRID <code>datagrid</code>,--> <code><a href=#dir>dir</a></code>,
- <code><a href=#the-div-element>div</a></code>, <code><a href=#the-dl-element>dl</a></code>, <code><a href=#the-fieldset-element>fieldset</a></code>,
- <code><a href=#the-footer-element>footer</a></code>, <code><a href=#the-form-element>form</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>,
- <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h2</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h3</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h4</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h5</a></code>,
- <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h6</a></code>, <code><a href=#the-header-element>header</a></code>, <code><a href=#the-hgroup-element>hgroup</a></code>,
- <code><a href=#the-hr-element>hr</a></code>, <code><a href=#menus>menu</a></code>, <code><a href=#the-nav-element>nav</a></code>,
- <code><a href=#the-ol-element>ol</a></code>, <code><a href=#the-p-element>p</a></code>, <code><a href=#the-pre-element>pre</a></code>,
+ <code><a href=#dir>dir</a></code>, <code><a href=#the-div-element>div</a></code>, <code><a href=#the-dl-element>dl</a></code>,
+ <code><a href=#the-fieldset-element>fieldset</a></code>, <code><a href=#the-footer-element>footer</a></code>, <code><a href=#the-form-element>form</a></code>,
+ <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h2</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h3</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h4</a></code>,
+ <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h5</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h6</a></code>, <code><a href=#the-header-element>header</a></code>,
+ <code><a href=#the-hgroup-element>hgroup</a></code>, <code><a href=#the-hr-element>hr</a></code>, <code><a href=#menus>menu</a></code>,
+ <code><a href=#the-nav-element>nav</a></code>, <code><a href=#the-ol-element>ol</a></code>, <code><a href=#the-p-element>p</a></code>, <code><a href=#the-pre-element>pre</a></code>,
<code><a href=#the-section-element>section</a></code>, <code><a href=#the-table-element>table</a></code>, or <code><a href=#the-ul-element>ul</a></code>,
element, or if there is no more content in the parent element and
the parent element is not an <code><a href=#the-a-element>a</a></code> element.</p>
@@ -77323,10 +74720,9 @@
<code><a href=#the-blockquote-element>blockquote</a></code>, <code><a href=#the-body-element-0>body</a></code>, <code><a href=#the-br-element>br</a></code>,
<code><a href=#the-button-element>button</a></code>, <code><a href=#the-caption-element>caption</a></code>, <code><a href=#center>center</a></code>,
<code><a href=#the-col-element>col</a></code>, <code><a href=#the-colgroup-element>colgroup</a></code>, <code><a href=#the-command>command</a></code>,
- <!--v2DDATAGRID <code>datagrid</code>,--> <code><a href=#the-dd-element>dd</a></code>,
- <code><a href=#the-details-element>details</a></code>, <code><a href=#dir>dir</a></code>, <code><a href=#the-div-element>div</a></code>,
- <code><a href=#the-dl-element>dl</a></code>, <code><a href=#the-dt-element>dt</a></code>, <code><a href=#the-embed-element>embed</a></code>,
- <code><a href=#the-fieldset-element>fieldset</a></code>, <code><a href=#the-figcaption-element>figcaption</a></code>,
+ <code><a href=#the-dd-element>dd</a></code>, <code><a href=#the-details-element>details</a></code>, <code><a href=#dir>dir</a></code>,
+ <code><a href=#the-div-element>div</a></code>, <code><a href=#the-dl-element>dl</a></code>, <code><a href=#the-dt-element>dt</a></code>,
+ <code><a href=#the-embed-element>embed</a></code>, <code><a href=#the-fieldset-element>fieldset</a></code>, <code><a href=#the-figcaption-element>figcaption</a></code>,
<code><a href=#the-figure-element>figure</a></code>, <code><a href=#the-footer-element>footer</a></code>, <code><a href=#the-form-element>form</a></code>,
<code><a href=#frame>frame</a></code>, <code><a href=#frameset>frameset</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>,
<code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h2</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h3</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h4</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h5</a></code>,
@@ -80763,10 +78159,9 @@
<!-- the normal ones -->
<dt>A start tag whose tag name is one of: "address", "article",
- "aside", "blockquote", "center", <!--v2DATAGRID"datagrid",-->
- "details", "dir", "div", "dl", "fieldset", "figcaption", "figure",
- "footer", "header", "hgroup", "menu", "nav", "ol", "p", "section",
- "summary", "ul"</dt>
+ "aside", "blockquote", "center", "details", "dir", "div", "dl",
+ "fieldset", "figcaption", "figure", "footer", "header", "hgroup",
+ "menu", "nav", "ol", "p", "section", "summary", "ul"</dt>
<dd>
<!-- As of May 2008 this doesn't match any browser exactly, but is
@@ -80985,11 +78380,10 @@
<!-- the normal ones -->
<dt>An end tag whose tag name is one of: "address", "article",
- "aside", "blockquote", "button", "center",
- <!--v2DATAGRID"datagrid",--> "details", "dir", "div", "dl",
- "fieldset", "figcaption", "figure", "footer", "header", "hgroup",
- "listing", "menu", "nav", "ol", "pre", "section", "summary",
- "ul"</dt>
+ "aside", "blockquote", "button", "center", "details", "dir", "div",
+ "dl", "fieldset", "figcaption", "figure", "footer", "header",
+ "hgroup", "listing", "menu", "nav", "ol", "pre", "section",
+ "summary", "ul"</dt>
<dd>
<p>If the <a href=#stack-of-open-elements>stack of open elements</a> does not <a href=#has-an-element-in-scope title="has an element in scope">have an element in scope</a>
@@ -86779,20 +84173,6 @@
</div>
-<!--v2DATAGRID
- <div class="impl">
-
- <h4>The <code>datagrid</code> element</h4>
-
- This section will probably include details on how to render DATAGRID
- (including <span id="datagridPseudos">its pseudo-elements</span>),
- drag-and-drop, etc, in a visual medium, in concert with
- CSS. Implementation experience is desired before this section is
- filled in.
-
- </div>
--->
-
<div class=impl>
<h4 id=the-details-element-0><span class=secno>14.4.3 </span>The <code><a href=#the-details-element>details</a></code> element</h4>
@@ -91126,7 +88506,6 @@
<code><a href=#the-cite-element>cite</a></code>;
<code><a href=#the-code-element>code</a></code>;
<code><a href=#the-command>command</a></code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code><a href=#the-datalist-element>datalist</a></code>;
<code><a href=#the-del-element>del</a></code>;
<code><a href=#the-details-element>details</a></code>;
@@ -91299,7 +88678,6 @@
<td>
<code><a href=#the-a-element>a</a></code>;
<code><a href=#the-button-element>button</a></code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code><a href=#the-details-element>details</a></code>;
<code><a href=#the-embed-element>embed</a></code>;
<code><a href=#the-iframe-element>iframe</a></code>;
@@ -91319,7 +88697,6 @@
<td>
<code><a href=#the-blockquote-element>blockquote</a></code>;
<code><a href=#the-body-element-0>body</a></code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code><a href=#the-details-element>details</a></code>;
<code><a href=#the-fieldset-element>fieldset</a></code>;
<code><a href=#the-figure-element>figure</a></code>;
Modified: index
===================================================================
--- index 2010-10-22 23:07:42 UTC (rev 5643)
+++ index 2010-10-22 23:12:13 UTC (rev 5644)
@@ -7901,7 +7901,6 @@
<li value=24><dfn id=not_readable_err><code>NOT_READABLE_ERR</code></dfn></li> <!-- File API -->
<li value=25><dfn id=data_clone_err><code>DATA_CLONE_ERR</code></dfn></li> <!-- actually defined right here for now -->
<li value=26><dfn id=encoding_err><code>ENCODING_ERR</code></dfn></li> <!-- File API -->
-<!--v2DATAGRID <li value=".."><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>SERIALIZE_ERR</code></dfn></li> <!- - actually defined in dom3ls - ->
@@ -10201,7 +10200,6 @@
<li><code><a href=#the-cite-element>cite</a></code></li>
<li><code><a href=#the-code-element>code</a></code></li>
<li><code><a href=#the-command>command</a></code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code><a href=#the-datalist-element>datalist</a></code></li>
<li><code><a href=#the-del-element>del</a></code></li>
<li><code><a href=#the-details-element>details</a></code></li>
@@ -10450,7 +10448,6 @@
<ul class="brief category-list"><li><code><a href=#the-a-element>a</a></code></li>
<li><code><a href=#audio>audio</a></code> (if the <code title=attr-media-controls><a href=#attr-media-controls>controls</a></code> attribute is present)</li>
<li><code><a href=#the-button-element>button</a></code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code><a href=#the-details-element>details</a></code></li>
<li><code><a href=#the-embed-element>embed</a></code></li>
<li><code><a href=#the-iframe-element>iframe</a></code></li>
@@ -16341,7 +16338,6 @@
<!-- when updating this also update the category index -->
<ul class="brief category-list"><li><code><a href=#the-blockquote-element>blockquote</a></code></li>
<li><code><a href=#the-body-element-0>body</a></code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code><a href=#the-details-element>details</a></code></li>
<li><code><a href=#the-fieldset-element>fieldset</a></code></li>
<li><code><a href=#the-figure-element>figure</a></code></li>
@@ -44061,11 +44057,7 @@
<p>The <code><a href=#the-datalist-element>datalist</a></code> element is hooked up to an
<code><a href=#the-input-element>input</a></code> element using the <code title=attr-input-list><a href=#attr-input-list>list</a></code> attribute on the
- <code><a href=#the-input-element>input</a></code> element. <!-- v2DATAGRID 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>
+ <code><a href=#the-input-element>input</a></code> element.</p>
<p>Each <code><a href=#the-option-element>option</a></code> element that is a descendant of the
<code><a href=#the-datalist-element>datalist</a></code> element, that is not <a href=#concept-option-disabled title=concept-option-disabled>disabled</a>, and whose <a href=#concept-option-value title=concept-option-value>value</a> is a string that isn't the
@@ -45608,7 +45600,7 @@
<ul class=brief><li>minimum value ≤ actual value ≤ maximum value</li>
<li>minimum value ≤ low boundary ≤ high boundary ≤ maximum value</li>
<li>minimum value ≤ optimum point ≤ maximum value</li>
- </ul><!-- next two paragraphs are duplicated in the <datagrid> section [v2DATAGRID] --><p><strong>UA requirements for regions of the gauge</strong>: If the
+ </ul><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
@@ -47733,2601 +47725,7 @@
-<!-- v2DATAGRID
- <h4 id="datagrid">The <dfn><code>datagrid</code></dfn> element</h4>
- <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 can be used:</dt>
- <dd>Where <span>flow content</span> is expected.</dd>
- <dt>Content model:</dt>
- <dd><span>Flow content</span>.</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> {
-<!- -v2DGS:
- attribute boolean <span title="dom-datagrid-multiple">multiple</span>;
-- -> attribute boolean <span title="dom-datagrid-disabled">disabled</span>;
- 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, in optional HTMLImageElement icon, in optional boolean sortable, in optional boolean hidden);
- 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<<span>Column</span>> <dfn>ColumnList</dfn>;
-typedef sequence<any> <dfn>Cell</dfn>; // <span>Column</span>, any... (exact types expected depend on the column type)
-typedef sequence<<span>Cell</span>> <dfn>CellList</dfn>;
-typedef sequence<any> <dfn>Row</dfn>; // <span>RowID</span>, long, long, <span>CellList</span>, optional boolean, optional long
-typedef sequence<<span>Row</span>> <dfn>RowList</dfn>;
-typedef sequence<unsigned long> <dfn>RowID</dfn>;
-typedef sequence<<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>
-
- <!- - v2:
- * datagrid: cells that are links (<a href=""></a>)
- - ->
-
- <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>
-
-<!- -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 <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 the
- <code>datagrid</code> is disabled.</span></p>
-
- <div class="impl">
-
- <!- -vsDGS: multiple - ->
-
- <p>The <dfn
- title="dom-datagrid-disabled"><code>disabled</code></dfn> IDL
- attribute must <span>reflect</span> the content attribute of the
- same name.</p>
-
- </div>
-
- <!- - 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><i>This section is non-normative.</i></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 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 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>
-- ->
-
- <!- - v2DGDND: selection should draggable to and from datagrids - ->
-
-
- <h6>Example: a <code>datagrid</code> backed by a static <code>table</code> element</h6>
-
- ...
-
-
- <h6>Example: a <code>datagrid</code> backed by nested <code>ol</code> elements</h6>
-
- ...
-
-
- <h6>Example: a <code>datagrid</code> backed by a server</h6>
-
- ...
-
-
- <h5>Populating the <code>datagrid</code></h5>
-
- <dl class="domintro">
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-listener">listener</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <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 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>
-
- <p>Can be set, to change the current listener.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-renotify">renotify</code>()</dt>
- <dd>
-
- <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>
-
- <!- - useful, e.g., if there is a server error and the script loses
- track of what rows it's supposed to be reporting. - ->
-
- </dd>
-
-
- <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="">hidden</var> ] ] ] )</dt>
- <dd>
-
- <p>Adds a column to the <code>datagrid</code>.</p>
-
- <p>If a column with the given identifier has already been added,
- it just replaces the information for that column.</p>
-
- <p>The possible types are enumerated in the previous section.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortColumn">sortColumn</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <p>Returns the identifier of the column by which the data is to be
- sorted.</p>
-
- <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>
-
- <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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortAscending">sortAscending</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <p>Returns true if the data is to be sorted with smaller values
- first; otherwise, returns false, indicating that bigger values are
- to be put first.</p>
-
- <p>Can be set, to indicate that the order is about to change.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearColumns">clearColumns</code>()</dt>
- <dd>
-
- <p>Removes all the columns in the <code>datagrid</code>,
- reinstating the implied column.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-setRowCount">setRowCount</code>(<var title="">childCount</var>, <var title="">rowCount</var>)</dt>
- <dd>
-
- <p>Sets the numbers of rows in the <code>datagrid</code>,
- excluding rows that are descendants of rows that are closed.</p>
-
- <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>A <code>RowID</code> object identifying the row.</li>
-
- <li>An integer giving the position of the row in its parent,
- given the current sort order, or −1 to set other row data
- without setting a position or changing a previously declared
- position.</li>
-
- <li>An integer giving the number of children of the row, or 0 if
- the row has no children, or −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
- −1 leaves the previous count unchanged.</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 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>
-
- <dl>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-insertRows">insertRows</code>(<var title="">rows</var>)</dt>
- <dd>
-
- <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>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>Throws a <code>DATAGRID_MODEL_ERR</code> exception if the
- arguments contradict each other or previously declared
- information.</p>
-
- </dd>
-
-
- <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>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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearRows">clearRows</code>()</dt>
- <dd>
-
- <p>Clears the <code>datagrid</code> of all row data, resetting it
- to empty<!- - v2DGS:, and clears the selection- ->.</p>
-
- </dd>
-
- </dl>
-
-
- <div class="impl">
-
- <h6>The listener</h6>
-
- <p>The <dfn
- title="dom-datagrid-listener"><code>listener</code></dfn> IDL
- 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">initialize()</code> method with the
- <code>datagrid</code> element as its only argument.</p>
-
-
- <h6>The columns</h6>
-
- <p>The columns are represented by the <dfn>column list</dfn>, an
- ordered list of entries for columns, each of which consists of:</p>
-
- <dl>
-
- <dt>An identifier</dt>
-
- <dd>A string used to identify the column in the API.</dd>
-
- <dt>A label</dt>
-
- <dd>A string used in the user interface.</dd>
-
- <dt>A type</dt>
-
- <dd>One of the types described below.</dd>
-
- <dt>An icon</dt>
-
- <dd>An image, copied from an <code>img</code> element when the
- column was declared.</dd>
-
- <dt>Whether the column is sortable</dt>
-
- <dd>A boolean indicating whether the user can request that the data
- be sorted by this column (true), or not (false).</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="">hidden</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, but the given <code>img</code> element is not in the <span
- title="img-all">completely available</span> state, then let <var
- title="">icon</var> be null.</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 unless the <var title="">hidden</var> argument is
- present and 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>
-
- </ol>
-
- <hr>
-
- <p>The <dfn
- title="dom-datagrid-sortColumn"><code>sortColumn</code></dfn> IDL
- 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>
- IDL 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 efficient, 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>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 −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 −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, the flag can only be changed by the user
- or while 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 −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>
-
- <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>
-
- <hr>
-
- <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>
-
- <ol>
-
- <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>
-
- </li>
-
- <li>
-
- <p>Clear the <span>pending <code>datagrid</code> rows list</span>
- and the <span>pending <code>datagrid</code> cells list</span>.</p>
-
- </li>
-
- <li>
-
- <p>Invoke the <span><code>datagrid</code> update display
- algorithm</span>.</p>
-
- </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 −1 nor equal to the child count of the
- preexisting row.</li>
-
- <li>The <code>Row</code> object has fewer than four
- entries or more than six entries.</li>
-
- <li>The <code>Row</code> object has five or more entries, and
- its fifth entry is false.</li>
-
- <li>The <code>Row</code> object has six entries, and 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 length 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 −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 if 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 −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 −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>
-
- <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 −1, zero, or a positive integer.</p></li>
-
- <li><p>The third value in the <code>Row</code> is an integer that
- is either −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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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() abstract operation 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() abstract operation
- to the value, and then verify that the result is neither an Infinity
- value nor a Not-a-Number (NaN) 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() abstract
- operation 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() abstract operation 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() abstract operation 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 −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>The cell represents some text and an optional image.</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>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>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><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>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 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>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>
-
- </dd>
-
- <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><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
- value 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>The cell represents a dynamically generated graphical image.</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 user agent should not allow the cell to be rendered with
- dimensions less than the given minimum width and height.</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> IDL 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>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 used 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>
-
- <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 −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 <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 <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 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-getRows">getRows()</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>
-
- <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>Now, assuming that all eight rows and all three columns are
- still visible, the user agent has the following choices (amongst
- others):</p>
-
- <ul>
-
- <li>Fire the <code title="dom-listener-getRows">getCells()</code>
- method for rows 1 through 8, listing all three columns.</li>
-
- <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>
-
- <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><i>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).</i></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>DataGridListener</code> interface, once implemented by
- an object in a script and hooked up to a <code>datagrid</code> using
- the <code title="dom-datagrid-listener">listener</code> IDL
- 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><dfn title="dom-listener-initialize"><code>initialize(<var title="">datagrid</var>)</code></dfn></dt>
-
- <dd>
-
- <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>
-
- </dd>
-
- <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>
-
- <dd>
-
- <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>
-
- <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>
-
- <p>The <var title="">rowCount</var> argument gives the number of
- rows for which the user agent would like information.</p>
-
- <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).
-
- <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>
-
- </dd>
-
- <dt><dfn title="dom-listener-getCells"><code>getCells(<var title="">rows</var>, <var title="">columns</var>)</code></dfn></dt>
-
- <dd>
-
- <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>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>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>
-
- </dd>
-
- <dt><dfn title="dom-listener-rowOpened"><code>rowOpened(<var title="">row</var>, <var title="">rowCountNeeded</var>)</code></dfn></dt>
-
- <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 opened.</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>
-
- </dd>
-
- <dt><dfn title="dom-listener-rowClosed"><code>rowClosed(<var title="">row</var>)</code></dfn></dt>
-
- <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>
-
- <!- -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-length">length</span>;
- getter <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-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. This can be
- changed using 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> IDL
- 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 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>supported property indices</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 property
- indices</span>.</p>
-
- <p>The <dfn title="dom-DataGridSelection-item"><code>item(<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="#refsDOMCORE">[DOMCORE]</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 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> 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 ...
-
- <p>The <dfn
- title="dom-DataGridSelection-clear"><code>clear()</code></dfn>
- 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 <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>
-
- ...event on selection change?...
-
- </div>
-
- <p class="note">The <code>DataGridSelection</code> interface has no
- relation to the <code>Selection</code> interface.</p>
-
-- ->
-
-
-<!- -vsDGDND
- <h5>Drag and drop in <code>datagrid</code>s</h5>
-
- <p><i>This section only applies to interactive user agents.</i></p>
-
- ...define drag and drop in datagrids; selectiondraggable...
-- ->
-
--->
-
<h4 id=the-command><span class=secno>4.11.3 </span>The <dfn><code>command</code></dfn> element</h4>
<dl class=element><dt>Categories</dt>
@@ -71863,13 +69261,12 @@
tag</a> may be omitted if the <code><a href=#the-p-element>p</a></code> element is
immediately followed by an <code><a href=#the-address-element>address</a></code>,
<code><a href=#the-article-element>article</a></code>, <code><a href=#the-aside-element>aside</a></code>, <code><a href=#the-blockquote-element>blockquote</a></code>,
- <!--v2DATAGRID <code>datagrid</code>,--> <code><a href=#dir>dir</a></code>,
- <code><a href=#the-div-element>div</a></code>, <code><a href=#the-dl-element>dl</a></code>, <code><a href=#the-fieldset-element>fieldset</a></code>,
- <code><a href=#the-footer-element>footer</a></code>, <code><a href=#the-form-element>form</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>,
- <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h2</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h3</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h4</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h5</a></code>,
- <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h6</a></code>, <code><a href=#the-header-element>header</a></code>, <code><a href=#the-hgroup-element>hgroup</a></code>,
- <code><a href=#the-hr-element>hr</a></code>, <code><a href=#menus>menu</a></code>, <code><a href=#the-nav-element>nav</a></code>,
- <code><a href=#the-ol-element>ol</a></code>, <code><a href=#the-p-element>p</a></code>, <code><a href=#the-pre-element>pre</a></code>,
+ <code><a href=#dir>dir</a></code>, <code><a href=#the-div-element>div</a></code>, <code><a href=#the-dl-element>dl</a></code>,
+ <code><a href=#the-fieldset-element>fieldset</a></code>, <code><a href=#the-footer-element>footer</a></code>, <code><a href=#the-form-element>form</a></code>,
+ <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h2</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h3</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h4</a></code>,
+ <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h5</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h6</a></code>, <code><a href=#the-header-element>header</a></code>,
+ <code><a href=#the-hgroup-element>hgroup</a></code>, <code><a href=#the-hr-element>hr</a></code>, <code><a href=#menus>menu</a></code>,
+ <code><a href=#the-nav-element>nav</a></code>, <code><a href=#the-ol-element>ol</a></code>, <code><a href=#the-p-element>p</a></code>, <code><a href=#the-pre-element>pre</a></code>,
<code><a href=#the-section-element>section</a></code>, <code><a href=#the-table-element>table</a></code>, or <code><a href=#the-ul-element>ul</a></code>,
element, or if there is no more content in the parent element and
the parent element is not an <code><a href=#the-a-element>a</a></code> element.</p>
@@ -73237,10 +70634,9 @@
<code><a href=#the-blockquote-element>blockquote</a></code>, <code><a href=#the-body-element-0>body</a></code>, <code><a href=#the-br-element>br</a></code>,
<code><a href=#the-button-element>button</a></code>, <code><a href=#the-caption-element>caption</a></code>, <code><a href=#center>center</a></code>,
<code><a href=#the-col-element>col</a></code>, <code><a href=#the-colgroup-element>colgroup</a></code>, <code><a href=#the-command>command</a></code>,
- <!--v2DDATAGRID <code>datagrid</code>,--> <code><a href=#the-dd-element>dd</a></code>,
- <code><a href=#the-details-element>details</a></code>, <code><a href=#dir>dir</a></code>, <code><a href=#the-div-element>div</a></code>,
- <code><a href=#the-dl-element>dl</a></code>, <code><a href=#the-dt-element>dt</a></code>, <code><a href=#the-embed-element>embed</a></code>,
- <code><a href=#the-fieldset-element>fieldset</a></code>, <code><a href=#the-figcaption-element>figcaption</a></code>,
+ <code><a href=#the-dd-element>dd</a></code>, <code><a href=#the-details-element>details</a></code>, <code><a href=#dir>dir</a></code>,
+ <code><a href=#the-div-element>div</a></code>, <code><a href=#the-dl-element>dl</a></code>, <code><a href=#the-dt-element>dt</a></code>,
+ <code><a href=#the-embed-element>embed</a></code>, <code><a href=#the-fieldset-element>fieldset</a></code>, <code><a href=#the-figcaption-element>figcaption</a></code>,
<code><a href=#the-figure-element>figure</a></code>, <code><a href=#the-footer-element>footer</a></code>, <code><a href=#the-form-element>form</a></code>,
<code><a href=#frame>frame</a></code>, <code><a href=#frameset>frameset</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>,
<code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h2</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h3</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h4</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h5</a></code>,
@@ -76677,10 +74073,9 @@
<!-- the normal ones -->
<dt>A start tag whose tag name is one of: "address", "article",
- "aside", "blockquote", "center", <!--v2DATAGRID"datagrid",-->
- "details", "dir", "div", "dl", "fieldset", "figcaption", "figure",
- "footer", "header", "hgroup", "menu", "nav", "ol", "p", "section",
- "summary", "ul"</dt>
+ "aside", "blockquote", "center", "details", "dir", "div", "dl",
+ "fieldset", "figcaption", "figure", "footer", "header", "hgroup",
+ "menu", "nav", "ol", "p", "section", "summary", "ul"</dt>
<dd>
<!-- As of May 2008 this doesn't match any browser exactly, but is
@@ -76899,11 +74294,10 @@
<!-- the normal ones -->
<dt>An end tag whose tag name is one of: "address", "article",
- "aside", "blockquote", "button", "center",
- <!--v2DATAGRID"datagrid",--> "details", "dir", "div", "dl",
- "fieldset", "figcaption", "figure", "footer", "header", "hgroup",
- "listing", "menu", "nav", "ol", "pre", "section", "summary",
- "ul"</dt>
+ "aside", "blockquote", "button", "center", "details", "dir", "div",
+ "dl", "fieldset", "figcaption", "figure", "footer", "header",
+ "hgroup", "listing", "menu", "nav", "ol", "pre", "section",
+ "summary", "ul"</dt>
<dd>
<p>If the <a href=#stack-of-open-elements>stack of open elements</a> does not <a href=#has-an-element-in-scope title="has an element in scope">have an element in scope</a>
@@ -82693,20 +80087,6 @@
</div>
-<!--v2DATAGRID
- <div class="impl">
-
- <h4>The <code>datagrid</code> element</h4>
-
- This section will probably include details on how to render DATAGRID
- (including <span id="datagridPseudos">its pseudo-elements</span>),
- drag-and-drop, etc, in a visual medium, in concert with
- CSS. Implementation experience is desired before this section is
- filled in.
-
- </div>
--->
-
<div class=impl>
<h4 id=the-details-element-0><span class=secno>12.4.3 </span>The <code><a href=#the-details-element>details</a></code> element</h4>
@@ -87040,7 +84420,6 @@
<code><a href=#the-cite-element>cite</a></code>;
<code><a href=#the-code-element>code</a></code>;
<code><a href=#the-command>command</a></code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code><a href=#the-datalist-element>datalist</a></code>;
<code><a href=#the-del-element>del</a></code>;
<code><a href=#the-details-element>details</a></code>;
@@ -87213,7 +84592,6 @@
<td>
<code><a href=#the-a-element>a</a></code>;
<code><a href=#the-button-element>button</a></code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code><a href=#the-details-element>details</a></code>;
<code><a href=#the-embed-element>embed</a></code>;
<code><a href=#the-iframe-element>iframe</a></code>;
@@ -87233,7 +84611,6 @@
<td>
<code><a href=#the-blockquote-element>blockquote</a></code>;
<code><a href=#the-body-element-0>body</a></code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code><a href=#the-details-element>details</a></code>;
<code><a href=#the-fieldset-element>fieldset</a></code>;
<code><a href=#the-figure-element>figure</a></code>;
Modified: source
===================================================================
--- source 2010-10-22 23:07:42 UTC (rev 5643)
+++ source 2010-10-22 23:12:13 UTC (rev 5644)
@@ -7802,7 +7802,6 @@
<li value="24"><dfn><code>NOT_READABLE_ERR</code></dfn></li> <!-- File API -->
<li value="25"><dfn><code>DATA_CLONE_ERR</code></dfn></li> <!-- actually defined right here for now -->
<li value="26"><dfn><code>ENCODING_ERR</code></dfn></li> <!-- File API -->
-<!--v2DATAGRID <li value=".."><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>SERIALIZE_ERR</code></dfn></li> <!- - actually defined in dom3ls - ->
@@ -10430,7 +10429,6 @@
<li><code>cite</code></li>
<li><code>code</code></li>
<li><code>command</code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code>datalist</code></li>
<li><code>del</code></li>
<li><code>details</code></li>
@@ -10699,7 +10697,6 @@
<li><code>a</code></li>
<li><code>audio</code> (if the <code title="attr-media-controls">controls</code> attribute is present)</li>
<li><code>button</code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code>details</code></li>
<li><code>embed</code></li>
<li><code>iframe</code></li>
@@ -17365,7 +17362,6 @@
<ul class="brief category-list">
<li><code>blockquote</code></li>
<li><code>body</code></li>
-<!-- v2DATAGRID <li><code>datagrid</code></li> -->
<li><code>details</code></li>
<li><code>fieldset</code></li>
<li><code>figure</code></li>
@@ -49337,11 +49333,7 @@
<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. <!-- v2DATAGRID 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>
+ <code>input</code> element.</p>
<p>Each <code>option</code> element that is a descendant of the
<code>datalist</code> element, that is not <span
@@ -51163,8 +51155,6 @@
<li>minimum value ≤ optimum point ≤ maximum value</li>
</ul>
- <!-- next two paragraphs are duplicated in the <datagrid> section [v2DATAGRID] -->
-
<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
@@ -53715,2601 +53705,7 @@
-<!-- v2DATAGRID
- <h4 id="datagrid">The <dfn><code>datagrid</code></dfn> element</h4>
- <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 can be used:</dt>
- <dd>Where <span>flow content</span> is expected.</dd>
- <dt>Content model:</dt>
- <dd><span>Flow content</span>.</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> {
-<!- -v2DGS:
- attribute boolean <span title="dom-datagrid-multiple">multiple</span>;
-- -> attribute boolean <span title="dom-datagrid-disabled">disabled</span>;
- 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, in optional HTMLImageElement icon, in optional boolean sortable, in optional boolean hidden);
- 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<<span>Column</span>> <dfn>ColumnList</dfn>;
-typedef sequence<any> <dfn>Cell</dfn>; // <span>Column</span>, any... (exact types expected depend on the column type)
-typedef sequence<<span>Cell</span>> <dfn>CellList</dfn>;
-typedef sequence<any> <dfn>Row</dfn>; // <span>RowID</span>, long, long, <span>CellList</span>, optional boolean, optional long
-typedef sequence<<span>Row</span>> <dfn>RowList</dfn>;
-typedef sequence<unsigned long> <dfn>RowID</dfn>;
-typedef sequence<<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>
-
- <!- - v2:
- * datagrid: cells that are links (<a href=""></a>)
- - ->
-
- <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>
-
-<!- -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 <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 the
- <code>datagrid</code> is disabled.</span></p>
-
- <div class="impl">
-
- <!- -vsDGS: multiple - ->
-
- <p>The <dfn
- title="dom-datagrid-disabled"><code>disabled</code></dfn> IDL
- attribute must <span>reflect</span> the content attribute of the
- same name.</p>
-
- </div>
-
- <!- - 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><i>This section is non-normative.</i></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 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 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>
-- ->
-
- <!- - v2DGDND: selection should draggable to and from datagrids - ->
-
-
- <h6>Example: a <code>datagrid</code> backed by a static <code>table</code> element</h6>
-
- ...
-
-
- <h6>Example: a <code>datagrid</code> backed by nested <code>ol</code> elements</h6>
-
- ...
-
-
- <h6>Example: a <code>datagrid</code> backed by a server</h6>
-
- ...
-
-
- <h5>Populating the <code>datagrid</code></h5>
-
- <dl class="domintro">
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-listener">listener</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <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 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>
-
- <p>Can be set, to change the current listener.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-renotify">renotify</code>()</dt>
- <dd>
-
- <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>
-
- <!- - useful, e.g., if there is a server error and the script loses
- track of what rows it's supposed to be reporting. - ->
-
- </dd>
-
-
- <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="">hidden</var> ] ] ] )</dt>
- <dd>
-
- <p>Adds a column to the <code>datagrid</code>.</p>
-
- <p>If a column with the given identifier has already been added,
- it just replaces the information for that column.</p>
-
- <p>The possible types are enumerated in the previous section.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortColumn">sortColumn</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <p>Returns the identifier of the column by which the data is to be
- sorted.</p>
-
- <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>
-
- <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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortAscending">sortAscending</code> [ = <var title="">value</var> ]</dt>
- <dd>
-
- <p>Returns true if the data is to be sorted with smaller values
- first; otherwise, returns false, indicating that bigger values are
- to be put first.</p>
-
- <p>Can be set, to indicate that the order is about to change.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearColumns">clearColumns</code>()</dt>
- <dd>
-
- <p>Removes all the columns in the <code>datagrid</code>,
- reinstating the implied column.</p>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-setRowCount">setRowCount</code>(<var title="">childCount</var>, <var title="">rowCount</var>)</dt>
- <dd>
-
- <p>Sets the numbers of rows in the <code>datagrid</code>,
- excluding rows that are descendants of rows that are closed.</p>
-
- <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>A <code>RowID</code> object identifying the row.</li>
-
- <li>An integer giving the position of the row in its parent,
- given the current sort order, or −1 to set other row data
- without setting a position or changing a previously declared
- position.</li>
-
- <li>An integer giving the number of children of the row, or 0 if
- the row has no children, or −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
- −1 leaves the previous count unchanged.</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 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>
-
- <dl>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-insertRows">insertRows</code>(<var title="">rows</var>)</dt>
- <dd>
-
- <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>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>Throws a <code>DATAGRID_MODEL_ERR</code> exception if the
- arguments contradict each other or previously declared
- information.</p>
-
- </dd>
-
-
- <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>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>
-
- </dd>
-
-
- <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearRows">clearRows</code>()</dt>
- <dd>
-
- <p>Clears the <code>datagrid</code> of all row data, resetting it
- to empty<!- - v2DGS:, and clears the selection- ->.</p>
-
- </dd>
-
- </dl>
-
-
- <div class="impl">
-
- <h6>The listener</h6>
-
- <p>The <dfn
- title="dom-datagrid-listener"><code>listener</code></dfn> IDL
- 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">initialize()</code> method with the
- <code>datagrid</code> element as its only argument.</p>
-
-
- <h6>The columns</h6>
-
- <p>The columns are represented by the <dfn>column list</dfn>, an
- ordered list of entries for columns, each of which consists of:</p>
-
- <dl>
-
- <dt>An identifier</dt>
-
- <dd>A string used to identify the column in the API.</dd>
-
- <dt>A label</dt>
-
- <dd>A string used in the user interface.</dd>
-
- <dt>A type</dt>
-
- <dd>One of the types described below.</dd>
-
- <dt>An icon</dt>
-
- <dd>An image, copied from an <code>img</code> element when the
- column was declared.</dd>
-
- <dt>Whether the column is sortable</dt>
-
- <dd>A boolean indicating whether the user can request that the data
- be sorted by this column (true), or not (false).</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="">hidden</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, but the given <code>img</code> element is not in the <span
- title="img-all">completely available</span> state, then let <var
- title="">icon</var> be null.</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 unless the <var title="">hidden</var> argument is
- present and 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>
-
- </ol>
-
- <hr>
-
- <p>The <dfn
- title="dom-datagrid-sortColumn"><code>sortColumn</code></dfn> IDL
- 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>
- IDL 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 efficient, 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>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 −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 −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, the flag can only be changed by the user
- or while 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 −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>
-
- <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>
-
- <hr>
-
- <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>
-
- <ol>
-
- <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>
-
- </li>
-
- <li>
-
- <p>Clear the <span>pending <code>datagrid</code> rows list</span>
- and the <span>pending <code>datagrid</code> cells list</span>.</p>
-
- </li>
-
- <li>
-
- <p>Invoke the <span><code>datagrid</code> update display
- algorithm</span>.</p>
-
- </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 −1 nor equal to the child count of the
- preexisting row.</li>
-
- <li>The <code>Row</code> object has fewer than four
- entries or more than six entries.</li>
-
- <li>The <code>Row</code> object has five or more entries, and
- its fifth entry is false.</li>
-
- <li>The <code>Row</code> object has six entries, and 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 length 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 −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 if 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 −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 −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>
-
- <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 −1, zero, or a positive integer.</p></li>
-
- <li><p>The third value in the <code>Row</code> is an integer that
- is either −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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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, it is in
- the <span title="img-all">completely available</span> state.</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() abstract operation 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() abstract operation
- to the value, and then verify that the result is neither an Infinity
- value nor a Not-a-Number (NaN) 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() abstract
- operation 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() abstract operation 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() abstract operation 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 −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>The cell represents some text and an optional image.</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>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>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><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>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 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>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>
-
- </dd>
-
- <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><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
- value 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>The cell represents a dynamically generated graphical image.</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 user agent should not allow the cell to be rendered with
- dimensions less than the given minimum width and height.</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> IDL 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>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 used 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>
-
- <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 −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 <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 <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 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-getRows">getRows()</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>
-
- <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>Now, assuming that all eight rows and all three columns are
- still visible, the user agent has the following choices (amongst
- others):</p>
-
- <ul>
-
- <li>Fire the <code title="dom-listener-getRows">getCells()</code>
- method for rows 1 through 8, listing all three columns.</li>
-
- <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>
-
- <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><i>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).</i></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>DataGridListener</code> interface, once implemented by
- an object in a script and hooked up to a <code>datagrid</code> using
- the <code title="dom-datagrid-listener">listener</code> IDL
- 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><dfn title="dom-listener-initialize"><code>initialize(<var title="">datagrid</var>)</code></dfn></dt>
-
- <dd>
-
- <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>
-
- </dd>
-
- <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>
-
- <dd>
-
- <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>
-
- <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>
-
- <p>The <var title="">rowCount</var> argument gives the number of
- rows for which the user agent would like information.</p>
-
- <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).
-
- <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>
-
- </dd>
-
- <dt><dfn title="dom-listener-getCells"><code>getCells(<var title="">rows</var>, <var title="">columns</var>)</code></dfn></dt>
-
- <dd>
-
- <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>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>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>
-
- </dd>
-
- <dt><dfn title="dom-listener-rowOpened"><code>rowOpened(<var title="">row</var>, <var title="">rowCountNeeded</var>)</code></dfn></dt>
-
- <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 opened.</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>
-
- </dd>
-
- <dt><dfn title="dom-listener-rowClosed"><code>rowClosed(<var title="">row</var>)</code></dfn></dt>
-
- <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>
-
- <!- -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-length">length</span>;
- getter <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-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. This can be
- changed using 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> IDL
- 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 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>supported property indices</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 property
- indices</span>.</p>
-
- <p>The <dfn title="dom-DataGridSelection-item"><code>item(<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="#refsDOMCORE">[DOMCORE]</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 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> 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 ...
-
- <p>The <dfn
- title="dom-DataGridSelection-clear"><code>clear()</code></dfn>
- 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 <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>
-
- ...event on selection change?...
-
- </div>
-
- <p class="note">The <code>DataGridSelection</code> interface has no
- relation to the <code>Selection</code> interface.</p>
-
-- ->
-
-
-<!- -vsDGDND
- <h5>Drag and drop in <code>datagrid</code>s</h5>
-
- <p><i>This section only applies to interactive user agents.</i></p>
-
- ...define drag and drop in datagrids; selectiondraggable...
-- ->
-
--->
-
<h4 id="the-command">The <dfn><code>command</code></dfn> element</h4>
<dl class="element">
@@ -86760,13 +84156,12 @@
tag</span> may be omitted if the <code>p</code> element is
immediately followed by an <code>address</code>,
<code>article</code>, <code>aside</code>, <code>blockquote</code>,
- <!--v2DATAGRID <code>datagrid</code>,--> <code>dir</code>,
- <code>div</code>, <code>dl</code>, <code>fieldset</code>,
- <code>footer</code>, <code>form</code>, <code>h1</code>,
- <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>,
- <code>h6</code>, <code>header</code>, <code>hgroup</code>,
- <code>hr</code>, <code>menu</code>, <code>nav</code>,
- <code>ol</code>, <code>p</code>, <code>pre</code>,
+ <code>dir</code>, <code>div</code>, <code>dl</code>,
+ <code>fieldset</code>, <code>footer</code>, <code>form</code>,
+ <code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>,
+ <code>h5</code>, <code>h6</code>, <code>header</code>,
+ <code>hgroup</code>, <code>hr</code>, <code>menu</code>,
+ <code>nav</code>, <code>ol</code>, <code>p</code>, <code>pre</code>,
<code>section</code>, <code>table</code>, or <code>ul</code>,
element, or if there is no more content in the parent element and
the parent element is not an <code>a</code> element.</p>
@@ -88347,10 +85742,9 @@
<code>blockquote</code>, <code>body</code>, <code>br</code>,
<code>button</code>, <code>caption</code>, <code>center</code>,
<code>col</code>, <code>colgroup</code>, <code>command</code>,
- <!--v2DDATAGRID <code>datagrid</code>,--> <code>dd</code>,
- <code>details</code>, <code>dir</code>, <code>div</code>,
- <code>dl</code>, <code>dt</code>, <code>embed</code>,
- <code>fieldset</code>, <code>figcaption</code>,
+ <code>dd</code>, <code>details</code>, <code>dir</code>,
+ <code>div</code>, <code>dl</code>, <code>dt</code>,
+ <code>embed</code>, <code>fieldset</code>, <code>figcaption</code>,
<code>figure</code>, <code>footer</code>, <code>form</code>,
<code>frame</code>, <code>frameset</code>, <code>h1</code>,
<code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>,
@@ -92298,10 +89692,9 @@
<!-- the normal ones -->
<dt>A start tag whose tag name is one of: "address", "article",
- "aside", "blockquote", "center", <!--v2DATAGRID"datagrid",-->
- "details", "dir", "div", "dl", "fieldset", "figcaption", "figure",
- "footer", "header", "hgroup", "menu", "nav", "ol", "p", "section",
- "summary", "ul"</dt>
+ "aside", "blockquote", "center", "details", "dir", "div", "dl",
+ "fieldset", "figcaption", "figure", "footer", "header", "hgroup",
+ "menu", "nav", "ol", "p", "section", "summary", "ul"</dt>
<dd>
<!-- As of May 2008 this doesn't match any browser exactly, but is
@@ -92528,11 +89921,10 @@
<!-- the normal ones -->
<dt>An end tag whose tag name is one of: "address", "article",
- "aside", "blockquote", "button", "center",
- <!--v2DATAGRID"datagrid",--> "details", "dir", "div", "dl",
- "fieldset", "figcaption", "figure", "footer", "header", "hgroup",
- "listing", "menu", "nav", "ol", "pre", "section", "summary",
- "ul"</dt>
+ "aside", "blockquote", "button", "center", "details", "dir", "div",
+ "dl", "fieldset", "figcaption", "figure", "footer", "header",
+ "hgroup", "listing", "menu", "nav", "ol", "pre", "section",
+ "summary", "ul"</dt>
<dd>
<p>If the <span>stack of open elements</span> does not <span
@@ -99089,22 +96481,8 @@
</div>
-<!--v2DATAGRID
<div class="impl">
- <h4>The <code>datagrid</code> element</h4>
-
- This section will probably include details on how to render DATAGRID
- (including <span id="datagridPseudos">its pseudo-elements</span>),
- drag-and-drop, etc, in a visual medium, in concert with
- CSS. Implementation experience is desired before this section is
- filled in.
-
- </div>
--->
-
- <div class="impl">
-
<h4>The <code>details</code> element</h4>
<pre class="css">@namespace url(http://www.w3.org/1999/xhtml);
@@ -104291,7 +101669,6 @@
<code>cite</code>;
<code>code</code>;
<code>command</code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code>datalist</code>;
<code>del</code>;
<code>details</code>;
@@ -104469,7 +101846,6 @@
<td>
<code>a</code>;
<code>button</code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code>details</code>;
<code>embed</code>;
<code>iframe</code>;
@@ -104490,7 +101866,6 @@
<td>
<code>blockquote</code>;
<code>body</code>;
- <!-- v2DATAGRID <code>datagrid</code>; -->
<code>details</code>;
<code>fieldset</code>;
<code>figure</code>;
More information about the Commit-Watchers
mailing list