Annotation of html5/spec/interactive-elements.html, revision 1.18
1.2 mike 1: <!DOCTYPE HTML>
1.6 mike 2: <html lang="en-US-x-Hixie"><head><title>4.11 Interactive elements — HTML 5</title><style type="text/css">
1.1 mike 3: pre { margin-left: 2em; white-space: pre-wrap; }
4: h2 { margin: 3em 0 1em 0; }
5: h3 { margin: 2.5em 0 1em 0; }
6: h4 { margin: 2.5em 0 0.75em 0; }
7: h5, h6 { margin: 2.5em 0 1em; }
8: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
9: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
10: p { margin: 1em 0; }
11: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
12: dl, dd { margin-top: 0; margin-bottom: 0; }
13: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
14: dt + dt { margin-top: 0; }
15: dd dt { margin-top: 0.25em; margin-bottom: 0; }
16: dd p { margin-top: 0; }
17: dd dl + p { margin-top: 1em; }
18: dd table + p { margin-top: 1em; }
19: p + * > li, dd li { margin: 1em 0; }
20: dt, dfn { font-weight: bold; font-style: normal; }
21: dt dfn { font-style: italic; }
22: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
23: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
24: pre em { font-weight: bolder; font-style: normal; }
25: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
26: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
27: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
28: table thead { border-bottom: solid; }
29: table tbody th:first-child { border-left: solid; }
30: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
31: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
32:
33: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
34: .matrix, .matrix td { border: none; text-align: right; }
35: .matrix { margin-left: 2em; }
36: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
37: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
38: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
1.2 mike 39: .applies th > * { display: block; }
1.1 mike 40: .applies thead code { display: block; }
41: .applies td { text-align: center; }
42: .applies .yes { background: yellow; }
43:
44: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
45: img.extra { float: right; }
46: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
47: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
48: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
49: pre.css:first-line { color: #AAAA50; }
50: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #EEFFEE; }
51: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
52: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
53: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
54: dl.domintro dd p { margin: 0.5em 0; }
55: dl.switch { padding-left: 2em; }
56: dl.switch > dt { text-indent: -1.5em; }
57: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
58: dl.triple { padding: 0 0 0 1em; }
59: dl.triple dt, dl.triple dd { margin: 0; display: inline }
60: dl.triple dt:after { content: ':'; }
61: dl.triple dd:after { content: '\A'; white-space: pre; }
62: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
63: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
64: a .diff-new { border-bottom: 1px blue solid; }
65:
66: h2 { page-break-before: always; }
67: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
68: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
69:
70: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]), li > span:not([title=""]):not([class="XXX"]):not([class="impl"]) { border-bottom: solid #9999CC; }
71:
72: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
73: div.head p { margin: 0; }
74: div.head h1 { margin: 0; }
75: div.head .logo { float: right; margin: 0 1em; }
76: div.head .logo img { border: none } /* remove border from top image */
77: div.head dl { margin: 1em 0; }
78: p.copyright { font-size: x-small; font-style: oblique; margin: 0; }
79:
80: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
81: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
82: body > .toc > li > * { margin-bottom: 0.5em; }
83: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
84: .toc, .toc li { list-style: none; }
85:
86: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
87: .brief li { margin: 0; padding: 0; }
88: .brief li p { margin: 0; padding: 0; }
89:
90: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
91: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
92: .category-list li { display: inline; }
93: .category-list li:not(:last-child)::after { content: ', '; }
94: .category-list li > span, .category-list li > a { text-transform: lowercase; }
95: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
96:
97: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
98: .XXX > :first-child { margin-top: 0; }
99: p .XXX { line-height: 3em; }
100: .note { color: green; background: transparent; font-family: sans-serif; }
101: .warning { color: red; background: transparent; }
102: .note, .warning { font-weight: bolder; font-style: italic; }
103: p.note, div.note { padding: 0.5em 2em; }
104: span.note { padding: 0 2em; }
105: .note p:first-child, .warning p:first-child { margin-top: 0; }
106: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
107: .warning:before { font-style: normal; }
108: p.note:before { content: 'Note: '; }
109: p.warning:before { content: '\26A0 Warning! '; }
110:
111: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
112: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
113: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
114:
115: h4 { position: relative; z-index: 3; }
116: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
117: .element {
118: background: #EEEEFF;
119: color: black;
120: margin: 0 0 1em 0.15em;
121: padding: 0 1em 0.25em 0.75em;
122: border-left: solid #9999FF 0.25em;
123: position: relative;
124: z-index: 1;
125: }
126: .element:before {
127: position: absolute;
128: z-index: 2;
129: top: 0;
130: left: -1.15em;
131: height: 2em;
132: width: 0.9em;
133: background: #EEEEFF;
134: content: ' ';
135: border-style: none none solid solid;
136: border-color: #9999FF;
137: border-width: 0.25em;
138: }
139:
140: .example {
141: display: block;
142: color: #222222;
143: background: #FCFCFC;
144: border-left: double;
145: margin-left: 2em;
146: padding-left: 1em;
147: }
148:
149: .tall-and-narrow {
150: font-size: 0.6em;
151: column-width: 25em;
152: column-gap: 1em;
153: -moz-column-width: 25em;
154: -moz-column-gap: 1em;
155: -webkit-column-width: 25em;
156: -webkit-column-gap: 1em;
157: }
158:
159: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
160: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
161: ul.domTree li li { list-style: none; }
162: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
163: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
164: ul.domTree span { font-style: italic; font-family: serif; }
165: ul.domTree .t1 code { color: purple; font-weight: bold; }
166: ul.domTree .t2 { font-style: normal; font-family: monospace; }
167: ul.domTree .t2 .name { color: black; font-weight: bold; }
168: ul.domTree .t2 .value { color: blue; font-weight: normal; }
169: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
170: ul.domTree .t7 code, .domTree .t8 code { color: green; }
171: ul.domTree .t10 code { color: teal; }
172:
1.2 mike 173: </style><link href="data:text/css," rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D" rel="alternate stylesheet" title="Highlight implementation requirements"><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><!-- ZZZ ED vs WD -->
174: <script src="link-fixup.js"></script>
175: <link href="forms.html" title="4.10 Forms" rel="prev">
176: <link href="spec.html#contents" title="Table of contents" rel="index">
1.3 mike 177: <link href="microdata-0.html" title="5 Microdata" rel="next">
1.10 mike 178: </head><body onload="fixBrokenLink(); fixBrokenLink()"><div class="head">
1.1 mike 179: <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
180: <h1>HTML 5</h1>
181: <h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2>
1.2 mike 182: </div><nav>
1.1 mike 183: <a href="forms.html">← 4.10 Forms</a> –
1.2 mike 184: <a href="spec.html#contents">Table of contents</a> –
1.3 mike 185: <a href="microdata-0.html">5 Microdata →</a>
1.18 ! mike 186: </nav><p>This is revision 1.2680.</p>
1.5 mike 187:
1.1 mike 188:
189: <h3 id="interactive-elements"><span class="secno">4.11 </span>Interactive elements</h3><h4 id="the-details-element"><span class="secno">4.11.1 </span>The <dfn><code>details</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
190: <dd><a href="dom.html#flow-content-0">Flow content</a>.</dd>
191: <dd><a href="dom.html#interactive-content-0">Interactive content</a>.</dd>
192: <dt>Contexts in which this element may be used:</dt>
193: <dd>Where <a href="dom.html#flow-content-0">flow content</a> is expected.</dd>
194: <dt>Content model:</dt>
195: <dd>One <code><a href="#the-legend-element">legend</a></code> element followed by <a href="dom.html#flow-content-0">flow content</a>.</dd>
196: <dt>Content attributes:</dt>
197: <dd><a href="dom.html#global-attributes">Global attributes</a></dd>
198: <dd><code title="attr-details-open"><a href="#attr-details-open">open</a></code></dd>
199: <dt>DOM interface:</dt>
200: <dd>
201: <pre class="idl">interface <dfn id="htmldetailselement">HTMLDetailsElement</dfn> : <a href="dom.html#htmlelement">HTMLElement</a> {
202: attribute boolean <a href="#dom-details-open" title="dom-details-open">open</a>;
203: };</pre>
204: </dd>
205: </dl><p>The <code><a href="#the-details-element">details</a></code> element <a href="the-xhtml-syntax.html#represents">represents</a> additional
206: information or controls which the user can obtain on demand.</p><p class="note">The <code><a href="#the-details-element">details</a></code> element is not appropriate
207: for footnotes. Please see <a href="text-level-semantics.html#footnotes">the section on
208: footnotes</a> for details on how to mark up footnotes.</p><p>The first element child of a <code><a href="#the-details-element">details</a></code> element, <span class="impl">if it is</span> a <code><a href="#the-legend-element">legend</a></code> element,
209: <a href="the-xhtml-syntax.html#represents">represents</a> the summary of the details.</p><div class="impl">
210:
211: <p>If the first element is not a <code><a href="#the-legend-element">legend</a></code> element, the
212: UA should provide its own legend (e.g. "Details").</p>
213:
214: </div><p>The <dfn id="attr-details-open" title="attr-details-open"><code>open</code></dfn>
215: content attribute is a <a href="infrastructure.html#boolean-attribute">boolean attribute</a>. If present,
216: it indicates that the details are to be shown to the user. If the
217: attribute is absent, the details are not to be shown.</p><div class="impl">
218:
219: <p>If the attribute is removed, then the details should be
220: hidden. If the attribute is added, the details should be shown.</p>
221:
222: <p>The user agent should allow the user to request that the details
223: be shown or hidden. To honor a request for the details to be shown,
224: the user agent must set the <code title="attr-details-open"><a href="#attr-details-open">open</a></code> attribute on the element to
225: the value <code title="">open</code>. To honor a request for the
226: details to be hidden, the user agent must remove the <code title="attr-details-open"><a href="#attr-details-open">open</a></code> attribute from the
227: element.</p>
228:
229: <p>The <dfn id="dom-details-open" title="dom-details-open"><code>open</code></dfn>
230: attribute must <a href="infrastructure.html#reflect">reflect</a> the <code title="attr-details-open"><a href="#attr-details-open">open</a></code> content attribute.</p>
231:
232: </div><h4 id="datagrid"><span class="secno">4.11.2 </span>The <dfn><code>datagrid</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
233: <dd><a href="dom.html#flow-content-0">Flow content</a>.</dd>
234: <dd><a href="dom.html#interactive-content-0">Interactive content</a>.</dd>
235: <dd><a href="semantics.html#sectioning-root">Sectioning root</a>.</dd>
236: <dt>Contexts in which this element may be used:</dt>
237: <dd>Where <a href="dom.html#flow-content-0">flow content</a> is expected.</dd>
238: <dt>Content model:</dt>
239: <dd><a href="dom.html#flow-content-0">Flow content</a>.</dd>
240: <dt>Content attributes:</dt>
241: <dd><a href="dom.html#global-attributes">Global attributes</a></dd>
242: <!--v2DGS:
243: <dd><code title="attr-datagrid-multiple">multiple</code></dd>
244: -->
245: <dd><code title="attr-datagrid-disabled"><a href="#attr-datagrid-disabled">disabled</a></code></dd>
246: <dt>DOM interface:</dt>
247: <dd>
248: <pre class="idl">interface <dfn id="htmldatagridelement">HTMLDataGridElement</dfn> : <a href="dom.html#htmlelement">HTMLElement</a> {
249: <!--v2DGS:
250: attribute boolean <span title="dom-datagrid-multiple">multiple</span>;
251: --> attribute boolean <a href="#dom-datagrid-disabled" title="dom-datagrid-disabled">disabled</a>;
252: attribute <a href="#datagridlistener">DataGridListener</a> <a href="#dom-datagrid-listener" title="dom-datagrid-listener">listener</a>;
253: <!-- v2DGS:
254: readonly attribute <span>DataGridSelection</span> <span title="dom-datagrid-selection">selection</span>;
255: -->
256: // columns
257: void <a href="#dom-datagrid-addcolumn" title="dom-datagrid-addColumn">addColumn</a>(in <a href="#column">Column</a> id, in DOMString label, in DOMString type, [Optional] in HTMLImageElement icon, [Optional] in boolean sortable, [Optional] in boolean hidden);
258: attribute DOMString <a href="#dom-datagrid-sortcolumn" title="dom-datagrid-sortColumn">sortColumn</a>;
259: attribute boolean <a href="#dom-datagrid-sortascending" title="dom-datagrid-sortAscending">sortAscending</a>;
260: void <a href="#dom-datagrid-clearcolumns" title="dom-datagrid-clearColumns">clearColumns</a>();
261:
262: // rows
263: void <a href="#dom-datagrid-renotify" title="dom-datagrid-renotify">renotify</a>();
264: void <a href="#dom-datagrid-setrowcount" title="dom-datagrid-setRowCount">setRowCount</a>(in long childCount, in long rowCount);
265: void <a href="#dom-datagrid-setrows" title="dom-datagrid-setRows">setRows</a>(in <a href="#rowlist">RowList</a> rows);
266: void <a href="#dom-datagrid-insertrows" title="dom-datagrid-insertRows">insertRows</a>(in <a href="#rowlist">RowList</a> rows);
267: void <a href="#dom-datagrid-deleterows" title="dom-datagrid-deleteRows">deleteRows</a>(in <a href="#rowidlist">RowIDList</a> rows);
268: void <a href="#dom-datagrid-repaint" title="dom-datagrid-repaint">repaint</a>(in <a href="#rowid">RowID</a> row, in DOMString column);
269: void <a href="#dom-datagrid-clearrows" title="dom-datagrid-clearRows">clearRows</a>();
270: <!--
271: v2: opening and closing a row
272: moving a row's actual ID
273: - 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
274: - though actually that should probably just be done using display sorting
275: -->
276: };
277:
278: typedef DOMString <dfn id="column">Column</dfn>;
279: typedef sequence<<a href="#column">Column</a>> <dfn id="columnlist">ColumnList</dfn>;
280: typedef sequence<any> <dfn id="cell">Cell</dfn>; // <a href="#column">Column</a>, [Variadic] any (exact types expected depend on the column type)
281: typedef sequence<<a href="#cell">Cell</a>> <dfn id="celllist">CellList</dfn>;
282: typedef sequence<any> <dfn id="row">Row</dfn>; // <a href="#rowid">RowID</a>, long, long, <a href="#celllist">CellList</a>, [Optional] boolean, [Optional] long
283: typedef sequence<<a href="#row">Row</a>> <dfn id="rowlist">RowList</dfn>;
284: typedef sequence<unsigned long> <dfn id="rowid">RowID</dfn>;
285: typedef sequence<<a href="#rowid">RowID</a>> <dfn id="rowidlist">RowIDList</dfn>;
286:
287: [Callback=FunctionOnly, NoInterfaceObject]
288: interface <dfn id="renderingcontext2dcallback">RenderingContext2DCallback</dfn> {
289: DOMString <span title="dom-Rendering2DContextCallback-handleEvent">handleEvent</span>(in <a href="the-canvas-element.html#canvasrenderingcontext2d">CanvasRenderingContext2D</a> context, in unsigned long width, in unsigned long height);
290: };</pre>
291: </dd>
292: </dl><p>The <code><a href="#datagrid">datagrid</a></code> element <a href="the-xhtml-syntax.html#represents">represents</a> an
293: interactive representation of tree, list, or tabular data.</p><p>The data being presented is provided by script using the methods
294: described in the following sections.</p><!--v2DGS:
295: <p>The <dfn
296: title="attr-datagrid-multiple"><code>multiple</code></dfn> attribute
297: is a <span>boolean attribute</span>. When set, it indicates that the
298: user can select more than one row at a time.</p>
299: --><p>The <dfn id="attr-datagrid-disabled" title="attr-datagrid-disabled"><code>disabled</code></dfn> attribute
300: is a <a href="infrastructure.html#boolean-attribute">boolean attribute</a> used to disable the
301: control. <span class="impl">When the attribute is set, the user
302: agent must disable the <code><a href="#datagrid">datagrid</a></code>, preventing the user
303: from interacting with it. The <code><a href="#datagrid">datagrid</a></code> element should
304: still continue to update itself when the underlying data changes,
305: though, as described in the next few sections. However, conformance
306: requirements stating that <code><a href="#datagrid">datagrid</a></code> elements must react
307: to users in particular ways do not apply when the
308: <code><a href="#datagrid">datagrid</a></code> is disabled.</span></p><div class="impl">
309:
310: <!--vsDGS: multiple -->
311:
312: <p>The <dfn id="dom-datagrid-disabled" title="dom-datagrid-disabled"><code>disabled</code></dfn> DOM
313: attribute must <a href="infrastructure.html#reflect">reflect</a> the content attribute of the
314: same name.</p>
315:
316: </div><!-- v2DGPA: One possible thing to be added is a way to detect when a
317: row/selection has been deleted, activated, etc, by the user (delete
318: key, enter key, etc). (v2DGPA = <datagrid> Perform Action) --><h5 id="introduction-1"><span class="secno">4.11.2.1 </span>Introduction</h5><p><i>This section is non-normative.</i></p><p>In the <code><a href="#datagrid">datagrid</a></code> data model, data is structured as a
319: set of rows representing a tree, each row being split into a number
320: of columns. The columns are always present in the data model,
321: although individual columns might be hidden in the presentation.</p><hr><p>Each row can have child rows. Child rows may be hidden or
322: shown, by closing or opening (respectively) the parent row.</p><p>Rows are referred to by the path along the tree that one would
323: take to reach the row, using zero-based indices. Thus, the first row
324: of a list is row "0", the second row is row "1"; the first child row
325: of the first row is row "0,0", the second child row of the first row
326: is row "0,1"; the fourth child of the seventh child of the third
327: 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
328: represented by arrays of positions, represented in IDL by the
329: <a href="#rowid">RowID</a> 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,
330: a label that is shown to users interacting with the column, a type,
331: and optionally an icon.</p><p>The possible types are as follows:</p><table><thead><tr><td>Keyword
332: </td><td>Description
333: </td></tr></thead><tbody><tr><td><code title="datagrid-type-text"><a href="#datagrid-type-text">text</a></code>
334: </td><td>Simple text.
335: </td></tr><tr><td><code title="datagrid-type-editable"><a href="#datagrid-type-editable">editable</a></code>
336: </td><td>Editable text.
337: </td></tr><tr><td><code title="datagrid-type-checkable"><a href="#datagrid-type-checkable">checkable</a></code>
338: </td><td>Text with a check box.
339: </td></tr><tr><td><code title="datagrid-type-list"><a href="#datagrid-type-list">list</a></code>
340: </td><td>A list of values that the user can switch between.
341: </td></tr><tr><td><code title="datagrid-type-progress"><a href="#datagrid-type-progress">progress</a></code>
342: </td><td>A progress bar.
343: </td></tr><tr><td><code title="datagrid-type-meter"><a href="#datagrid-type-meter">meter</a></code>
344: </td><td>A gauge.
345: </td></tr><tr><td><code title="datagrid-type-custom"><a href="#datagrid-type-custom">custom</a></code>
346: </td><td>A canvas onto which arbitrary content can be drawn.
347: </td></tr></tbody></table><p>Each column can be flagged as sortable, in which case the user
348: will be able to sort the view using that column.</p><p>Columns are not necessarily visible. A column can be created
349: invisible by default. The user can select which columns are to be
350: shown.</p><p>When no columns have been added to the <code><a href="#datagrid">datagrid</a></code>, a
351: column with no name, whose identifier is the empty string, whose
352: type is <code title="datagrid-type-text"><a href="#datagrid-type-text">text</a></code>, and which is
353: not sortable, is implied. This column is removed if any explicit
354: columns are declared.</p><p>Each cell uses the type given for its column, so all cells in a
355: column present the same type of information.</p><!--v2DGS:
356: <p>Selection of data in a <code>datagrid</code> operates at the row
357: level. If the <code title="attr-datagrid-multiple">multiple</code>
358: attribute is present, multiple rows can be selected at once,
359: otherwise the user can only select one row at a time.</p>
360: --><!-- v2DGDND: selection should draggable to and from datagrids --><h6 id="example:-a-datagrid-backed-by-a-static-table-element"><span class="secno">4.11.2.1.1 </span>Example: a <code><a href="#datagrid">datagrid</a></code> backed by a static <code><a href="tabular-data.html#the-table-element">table</a></code> element</h6><p class="XXX">...</p><h6 id="example:-a-datagrid-backed-by-nested-ol-elements"><span class="secno">4.11.2.1.2 </span>Example: a <code><a href="#datagrid">datagrid</a></code> backed by nested <code><a href="semantics.html#the-ol-element">ol</a></code> elements</h6><p class="XXX">...</p><h6 id="example:-a-datagrid-backed-by-a-server"><span class="secno">4.11.2.1.3 </span>Example: a <code><a href="#datagrid">datagrid</a></code> backed by a server</h6><p class="XXX">...</p><h5 id="populating-the-datagrid"><span class="secno">4.11.2.2 </span>Populating the <code><a href="#datagrid">datagrid</a></code></h5><dl class="domintro"><dt><var title="">datagrid</var> . <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code> [ = <var title="">value</var> ]</dt>
361: <dd>
362:
363: <p>Return the current object that is configured as the
364: <code><a href="#datagrid">datagrid</a></code> listener, if any. Returns null if there is
365: none.</p>
366:
367: <p>The listener is an object provided by the script author that
368: receives notifications when the <code><a href="#datagrid">datagrid</a></code> needs row
369: data to render itself, when the user opens and closes rows with
370: children, when the user edits a cell, and when the user invokes a
371: row's context menu. (The <code><a href="#datagridlistener">DataGridListener</a></code> interface
372: used for this purpose is described in the next section.)</p>
373:
374: <p>Can be set, to change the current listener.</p>
375:
376: </dd>
377:
378:
379: <dt><var title="">datagrid</var> . <code title="dom-datagrid-renotify"><a href="#dom-datagrid-renotify">renotify</a></code>()</dt>
380: <dd>
381:
382: <p>Causes the <code><a href="#datagrid">datagrid</a></code> to resend notifications to the
383: listener (if any) for any rows or cells that the
384: <code><a href="#datagrid">datagrid</a></code> does not yet have information for.</p>
385:
386: <!-- useful, e.g., if there is a server error and the script loses
387: track of what rows it's supposed to be reporting. -->
388:
389: </dd>
390:
391:
392: <dt><var title="">datagrid</var> . <code title="dom-datagrid-addColumn"><a href="#dom-datagrid-addcolumn">addColumn</a></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>
393: <dd>
394:
395: <p>Adds a column to the <code><a href="#datagrid">datagrid</a></code>.</p>
396:
397: <p>If a column with the given identifier has already been added,
398: it just replaces the information for that column.</p>
399:
400: <p>The possible types are enumerated in the previous section.</p>
401:
402: </dd>
403:
404:
405: <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortColumn"><a href="#dom-datagrid-sortcolumn">sortColumn</a></code> [ = <var title="">value</var> ]</dt>
406: <dd>
407:
408: <p>Returns the identifier of the column by which the data is to be
409: sorted.</p>
410:
411: <p>Can be set, to indicate that the sort order has changed. This
412: will cause the <code><a href="#datagrid">datagrid</a></code> to clear its position
413: information for rows, so <code title="dom-datagrid-setRows"><a href="#dom-datagrid-setrows">setRows()</a></code> will have to be
414: called again with the new sort order.</p>
415:
416: <p>The columns are not actually sorted by the
417: <code><a href="#datagrid">datagrid</a></code>; the data has to be sorted by the script
418: that adds the rows to the <code><a href="#datagrid">datagrid</a></code>.</p>
419:
420: </dd>
421:
422:
423: <dt><var title="">datagrid</var> . <code title="dom-datagrid-sortAscending"><a href="#dom-datagrid-sortascending">sortAscending</a></code> [ = <var title="">value</var> ]</dt>
424: <dd>
425:
426: <p>Returns true if the data is to be sorted with smaller values
427: first; otherwise, returns false, indicating that bigger values are
428: to be put first.</p>
429:
430: <p>Can be set, to indicate that the order is about to change.</p>
431:
432: </dd>
433:
434:
435: <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearColumns"><a href="#dom-datagrid-clearcolumns">clearColumns</a></code>()</dt>
436: <dd>
437:
438: <p>Removes all the columns in the <code><a href="#datagrid">datagrid</a></code>,
439: reinstating the implied column.</p>
440:
441: </dd>
442:
443:
444: <dt><var title="">datagrid</var> . <code title="dom-datagrid-setRowCount"><a href="#dom-datagrid-setrowcount">setRowCount</a></code>(<var title="">childCount</var>, <var title="">rowCount</var>)</dt>
445: <dd>
446:
447: <p>Sets the numbers of rows in the <code><a href="#datagrid">datagrid</a></code>,
448: excluding rows that are descendants of rows that are closed.</p>
449:
450: <p>Throws a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception if the
451: arguments contradict each other or previously declared information
452: (e.g. declaring that the <code><a href="#datagrid">datagrid</a></code> has three rows when
453: the 12th row has been declared).</p>
454:
455: </dd>
456:
457:
458: <dt><var title="">datagrid</var> . <code title="dom-datagrid-setRows"><a href="#dom-datagrid-setrows">setRows</a></code>(<var title="">rows</var>)</dt>
459: <dd>
460:
461: <p>Updates data for rows in the <code><a href="#datagrid">datagrid</a></code>, or fills in
462: data for rows previously implied by a call to <code title="dom-datagrid-setRowCount"><a href="#dom-datagrid-setrowcount">setRowCount()</a></code> but not
463: previously declared.</p>
464:
465: <p>The <var title="">rows</var> argument is an array of rows, each
466: represented by a further array consisting of:</p>
467:
468: <ol class="brief"><li>A <code><a href="#rowid">RowID</a></code> object identifying the row.</li>
469:
470: <li>An integer giving the position of the row in its parent,
471: given the current sort order, or −1 to set other row data
472: without setting a position or changing a previously declared
473: position.</li>
474:
475: <li>An integer giving the number of children of the row, or 0 if
476: the row has no children, or −1 if the row has children but
477: the count is currently unknown. If the number of children has
478: already been set to 0 or a positive integer, then passing
479: −1 leaves the previous count unchanged.</li>
480:
481: <li>An array giving the data for zero or more cells in the row,
482: as described below.</li>
483:
484: <li>A boolean declaring whether the row is open or not. This
485: entry, if omitted, is assumed to be false (closed), unless the
486: row has already been declared as open.</li>
487:
488: <li>An integer giving the number of rows that are descendants of
489: this row, excluding those that are descendants of descendants of
490: this row that are closed. This entry can be omitted if the row is
491: closed or if it has already been declared.</li>
492:
493: </ol><p>The array giving the data for the cells in the row consists of
494: a further set of arrays, one per cell. The first item of each of
495: these arrays is the column's identifier; the subsequent values
496: vary based on the type of the column, as follows:</p>
497:
498: <dl><dt><code title="datagrid-type-text"><a href="#datagrid-type-text">text</a></code></dt>
499: <dd>
500: <ol class="brief"><li>A string giving the cell's value.
501: </li><li>Optionally, an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element giving an icon for the cell.
502: </li></ol></dd>
503:
504: <dt><code title="datagrid-type-editable"><a href="#datagrid-type-editable">editable</a></code></dt>
505: <dd>
506: <ol class="brief"><li>A string giving the cell's value.
507: </li><li>Optionally, a <code><a href="forms.html#the-datalist-element">datalist</a></code> element giving a set of predefined options.
508: </li><li>Optionally, an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element giving an icon for the cell.
509: </li></ol></dd>
510:
511: <dt><code title="datagrid-type-checkable"><a href="#datagrid-type-checkable">checkable</a></code></dt>
512: <dd>
513: <ol class="brief"><li>A string giving the cell's value.
514: </li><li>A boolean, indicating whether the cell is checked (true) or not (false).
515: </li><li>Optionally, a boolean indicating whether the value of the cell is obscured as indeterminate (true), or not (false).
516: </li><li>Optionally, an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element giving an icon for the cell.
517: </li></ol></dd>
518:
519: <dt><code title="datagrid-type-list"><a href="#datagrid-type-list">list</a></code></dt>
520: <dd>
521: <ol class="brief"><li>A string giving the cell's current value.
522: </li><li>A <code><a href="forms.html#the-select-element">select</a></code> element giving the <a href="forms.html#concept-select-option-list" title="concept-select-option-list">list of options</a>.
523: </li><li>Optionally, an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element giving an icon for the cell.
524: </li></ol></dd>
525:
526: <dt><code title="datagrid-type-progress"><a href="#datagrid-type-progress">progress</a></code></dt>
527: <dd>
528: <ol class="brief"><li>A value in the range 0.0 (no progress) to 1.0 (task complete).
529: </li></ol></dd>
530:
531: <dt><code title="datagrid-type-meter"><a href="#datagrid-type-meter">meter</a></code></dt>
532: <dd>
533: <ol class="brief"><li>A number giving the cell's value.
534: </li><li>Optionally, a number giving the maximum value, if it's not 1.
535: </li><li>Optionally, a number giving the minimum value, if it's not 0.
536: </li><li>Optionally, a number giving the highest value that is considered "low".
537: </li><li>Optionally, a number giving the lowest value that is considered "high".
538: </li><li>Optionally, a number giving the value that is considered optimal.
539: </li></ol></dd>
540:
541: <dt><code title="datagrid-type-custom"><a href="#datagrid-type-custom">custom</a></code></dt>
542: <dd>
543: <ol class="brief"><li>A number giving the minimum width of the cell, in CSS pixels, that is desired.
544: </li><li>A number giving the minimum height of the cell, in CSS pixels, that is desired.
545: </li><li>A function that is passed a <code><a href="the-canvas-element.html#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object, along with the width and height (in CSS pixels) of the cell that the context will draw on.
546: </li></ol></dd>
547:
548: </dl><p>While the rows in a single call to the <code title="dom-datagrid-setRows"><a href="#dom-datagrid-setrows">setRows()</a></code> method can be in any
549: order, for each row, it is important that all its ancestor rows
550: and all its open previous siblings are also declared, either in
551: the same call or in an earlier one.</p>
552:
553: <p>Throws a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception if the
554: arguments contradict each other or previously declared information
555: (e.g. saying that a row's position is 5 when the parent row only
556: has 3 children, or naming a column that doesn't exist, or
557: declaring a row without declaring its parent, or changing the
558: number of children that a row has while that row and its ancestors
559: are all open).</p>
560:
561: </dd>
562:
563:
564: <dt><var title="">datagrid</var> . <code title="dom-datagrid-insertRows"><a href="#dom-datagrid-insertrows">insertRows</a></code>(<var title="">rows</var>)</dt>
565: <dd>
566:
567: <p>Inserts the given rows into the <code><a href="#datagrid">datagrid</a></code>,
568: increasing the numbers of rows that the <code><a href="#datagrid">datagrid</a></code>
569: assumes are present.</p>
570:
571: <p>The <var title="">rows</var> argument is an array of rows in
572: the same structure as the argument to the <code title="dom-datagrid-setRows"><a href="#dom-datagrid-setrows">setRows()</a></code> method described
573: above, with the same expectations of consistency (a given row's
574: ancestors and earlier open siblings being listed either earlier or
575: in the same call as a given row). However, unlike with the <code title="dom-datagrid-setRows"><a href="#dom-datagrid-setrows">setRows()</a></code> method, if a row is
576: inserted along with its child, the child is not included in the
577: child and row counts of the parent row; every row in the <var title="">rows</var> argument will increase its parent's counts
578: automatically.</p>
579:
580: <p>Throws a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception if the
581: arguments contradict each other or previously declared
582: information.</p>
583:
584: </dd>
585:
586:
587: <dt><var title="">datagrid</var> . <code title="dom-datagrid-deleteRows"><a href="#dom-datagrid-deleterows">deleteRows</a></code>(<var title="">rows</var>)</dt>
588: <dd>
589:
590: <p>Removes the given rows from the <code><a href="#datagrid">datagrid</a></code>, and
591: updates the number of rows known to be in the
592: <code><a href="#datagrid">datagrid</a></code> accordingly. The argument is an array of
593: <code><a href="#rowid">RowID</a></code> objects identifying the rows to remove.</p>
594:
595: <p>Throws a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception if the argument
596: includes a row the <code><a href="#datagrid">datagrid</a></code> doesn't know about.</p>
597: <!-- since otherwise behaviour might depend on where the user
598: scrolled! -->
599:
600: </dd>
601:
602:
603: <dt><var title="">datagrid</var> . <code title="dom-datagrid-repaint"><a href="#dom-datagrid-repaint">repaint</a></code>(<var title="">row</var>, <var title="">column</var>)</dt>
604: <dd>
605:
606: <p>If the given column's type is <code title="datagrid-type-custom"><a href="#datagrid-type-custom">custom</a></code>, then causes the
607: <code><a href="#datagrid">datagrid</a></code> to reinvoke the function that obtains the
608: desired rendering.</p>
609:
610: </dd>
611:
612:
613: <dt><var title="">datagrid</var> . <code title="dom-datagrid-clearRows"><a href="#dom-datagrid-clearrows">clearRows</a></code>()</dt>
614: <dd>
615:
616: <p>Clears the <code><a href="#datagrid">datagrid</a></code> of all row data, resetting it
617: to empty<!-- v2DGS:, and clears the selection-->.</p>
618:
619: </dd>
620:
621: </dl><div class="impl">
622:
623: <h6 id="the-listener"><span class="secno">4.11.2.2.1 </span>The listener</h6>
624:
625: <p>The <dfn id="dom-datagrid-listener" title="dom-datagrid-listener"><code>listener</code></dfn> DOM
626: attribute allows authors to specify an object that will receive all
627: the notifications from the <code><a href="#datagrid">datagrid</a></code>. Initially, its
628: value must be null. On getting, it must return its value. On
629: setting, its value must be set to the new value, and then the user
630: agent must <a href="browsers.html#queue-a-task">queue a task</a> to call the <code title="dom-listener-initialize"><a href="#dom-listener-initialize">initialize()</a></code> method with the
631: <code><a href="#datagrid">datagrid</a></code> element as its only argument.</p>
632:
633:
634: <h6 id="the-columns"><span class="secno">4.11.2.2.2 </span>The columns</h6>
635:
636: <p>The columns are represented by the <dfn id="column-list">column list</dfn>, an
637: ordered list of entries for columns, each of which consists of:</p>
638:
639: <dl><dt>An identifier</dt>
640:
641: <dd>A string used to identify the column in the API.</dd>
642:
643: <dt>A label</dt>
644:
645: <dd>A string used in the user interface.</dd>
646:
647: <dt>A type</dt>
648:
649: <dd>One of the types described below.</dd>
650:
651: <dt>An icon</dt>
652:
653: <dd>An image, copied from an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element when the
654: column was declared.</dd>
655:
656: <dt>Whether the column is sortable</dt>
657:
658: <dd>A boolean indicating whether the user can request that the data
659: be sorted by this column (true), or not (false).</dd>
660:
661: <dt>Whether the column is visible</dt>
662:
663: <dd>A boolean indicating whether the column is part of the
664: <code><a href="#datagrid">datagrid</a></code>'s rendering.</dd>
665:
666: </dl><p>Initially, the <a href="#column-list">column list</a> must have a single
667: column, the <dfn id="default-column">default column</dfn>, whose identifier is the empty
668: string, whose label is the empty string, whose type is <code title="datagrid-type-text"><a href="#datagrid-type-text">text</a></code>, with no icon, which is not
669: sortable, and which <em>is</em> visible.</p>
670:
671: <hr><p>The <dfn id="dom-datagrid-addcolumn" 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>
672: method must run the following steps:</p>
673:
674: <ol><li><p>If there is already an entry in <a href="#column-list">column list</a>,
675: other than the <a href="#default-column">default column</a>, whose identifier is
676: <var title="">id</var>, throw a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code>
677: exception and abort these steps.</p></li>
678:
679: <li>
680:
681: <p>If <var title="">type</var> is not a string equal to one of the
682: <a href="#allowed-datagrid-column-types">allowed <code>datagrid</code> column types</a>, then
683: throw a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception and abort these
684: steps.</p>
685:
686: </li>
687:
688: <li><p>If the <var title="">icon</var> argument is present and not
689: null, but the given <code><a href="embedded-content-0.html#the-img-element">img</a></code> element's <code title="dom-img-complete"><a href="embedded-content-0.html#dom-img-complete">complete</a></code> attribute is false, then
690: let <var title="">icon</var> be null.</p></li>
691:
692: <li><p>If the <var title="">icon</var> argument is present and not
693: null, then copy the image data from that <code><a href="embedded-content-0.html#the-img-element">img</a></code> element,
694: and let <var title="">image</var> be the copy of that image
695: data. Otherwise, let <var title="">image</var> be nothing.</p></li>
696:
697: <li><p>Append a new entry to the <a href="#column-list">column list</a>, with
698: <var title="">id</var> as its identifier, <var title="">label</var>
699: 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
700: <var title="">sortable</var> argument is present and true, and make
701: it visible unless the <var title="">hidden</var> argument is
702: present and true.</p></li>
703:
704: <li><p>If the <a href="#column-list">column list</a> contains the <a href="#default-column">default
705: column</a>, then remove the <a href="#default-column">default column</a> from the
706: <a href="#column-list">column list</a>, discard any data for cells in that column
707: in any rows in the <code><a href="#datagrid">datagrid</a></code>, set <code title="dom-datagrid-sortColumn"><a href="#dom-datagrid-sortcolumn">sortColumn</a></code> to <var title="">id</var>, set <code title="dom-datagrid-sortAscending"><a href="#dom-datagrid-sortascending">sortAscending</a></code> to true,
708: and run the <a href="#datagrid-resort-steps"><code>datagrid</code> resort
709: steps</a>.</p></li>
710:
711: </ol><hr><p>The <dfn id="dom-datagrid-sortcolumn" title="dom-datagrid-sortColumn"><code>sortColumn</code></dfn> DOM
712: attribute gives the current column used for sorting. Initially, its
713: value must be the empty string. On getting, it must return its
714: current value. On setting, if the new value doesn't match the
715: identifier of one of the columns in the <a href="#column-list">column list</a>,
716: then the user agent must throw a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code>
717: exception. Otherwise, if the new value is not the same as its
718: current value, then the user agent must set the attribute to the new
719: value, and then run the <a href="#datagrid-resort-steps"><code>datagrid</code> resort
720: steps</a>.</p>
721:
722: <p>The <dfn id="dom-datagrid-sortascending" title="dom-datagrid-sortAscending"><code>sortAscending</code></dfn>
723: DOM attribute specifies the direction that the tree is sorted in,
724: ascending (true) or descending (false). Initially, its value must be
725: true (ascending). On getting, it must return its current value. On
726: setting, if the new value is not the same as its current value, then
727: the user agent must set the attribute to the new value, and then run
728: the <a href="#datagrid-resort-steps"><code>datagrid</code> resort steps</a>.</p>
729:
730: <p>When a column is marked as being sortable, the user agent should
731: allow the user to select that column to be the column used for
732: sorting, and should allow the user to chose whether the sort order
733: is ascending or descending.</p>
734:
735: <p>When the user changes the sort order in this manner, the user
736: agent must update the <code title="dom-datagrid-sortColumn"><a href="#dom-datagrid-sortcolumn">sortColumn</a></code> and <code title="dom-datagrid-sortAscending"><a href="#dom-datagrid-sortascending">sortAscending</a></code> attributes
737: appropriately, and then run the <a href="#datagrid-resort-steps"><code>datagrid</code> resort
738: steps</a>.</p>
739:
740: <p class="note">The <a href="#datagrid-resort-steps"><code>datagrid</code> resort steps</a>
741: are described in the next section.</p>
742:
743: <hr><p>The <dfn id="dom-datagrid-clearcolumns" title="dom-datagrid-clearColumns"><code>clearColumns()</code></dfn>
744: method, if the <a href="#column-list">column list</a> doesn't contain the
745: <a href="#default-column">default column</a>, must empty the <a href="#column-list">column
746: list</a>, append the <a href="#default-column">default column</a> to the now empty
747: <a href="#column-list">column list</a>, discard any data for cells in all rows in
748: the <code><a href="#datagrid">datagrid</a></code>, set <code title="dom-datagrid-sortColumn"><a href="#dom-datagrid-sortcolumn">sortColumn</a></code> to the empty
749: string, set <code title="dom-datagrid-sortAscending"><a href="#dom-datagrid-sortascending">sortAscending</a></code> to true, and
750: run the <a href="#datagrid-resort-steps"><code>datagrid</code> resort steps</a>. (If the
751: <a href="#column-list">column list</a> is already just the <a href="#default-column">default
752: column</a>, then the method does nothing.)</p>
753:
754:
755: <h6 id="the-rows"><span class="secno">4.11.2.2.3 </span>The rows</h6>
756:
757: <p>A <code><a href="#datagrid">datagrid</a></code> element is intended to show a
758: representation of a tree, where typically the user only sees a
759: small part of the tree at a time.</p>
760:
761: <p>To make this efficient, the <code><a href="#datagrid">datagrid</a></code> element
762: <em>actually</em> shows a small part of a <em>sparse</em> tree, so
763: that only relevant parts of the data structure need be loaded at any
764: time. Specifically, the model requires only that all the ancestor
765: rows of the displayed rows be loaded, as well as any open earlier
766: siblings (in the displayed sort order) of the displayed rows.</p>
767:
768: <p>Conceptually, therefore, a <code><a href="#datagrid">datagrid</a></code> has a number of
769: related sparse data structures backing it.</p>
770:
771: <p>The first is the <dfn id="natural-order-sparse-data-tree">natural order sparse data tree</dfn>. This
772: is the structure in which rows are entered as they are declared, in
773: their natural order. This can differ from the order actually
774: displayed to the user. It consists of nested sparse lists of
775: rows. In the <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a>, a row will
776: always have all its parents already declared. Once a row is added to
777: this structure, it can only be removed by the <code title="dom-datagrid-deleteRows"><a href="#dom-datagrid-deleterows">deleteRows()</a></code> and <code title="dom-datagrid-clearRows"><a href="#dom-datagrid-clearrows">clearRows()</a></code> methods. The order of
778: nodes in this tree never changes; to move a node in this tree, it
779: has to be removed and then another row (with the same data)
780: reinserted elsewhere.</p>
781:
782: <p>The second structure is the <dfn id="display-order-sparse-data-tree">display order sparse data
783: tree</dfn>. This is a similar structure that contains a subset of
784: the rows in the <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a>, ordered
785: in the order given by the <code title="dom-datagrid-sortAscending"><a href="#dom-datagrid-sortascending">sortAscending</a></code> and <code title="dom-datagrid-sortColumn"><a href="#dom-datagrid-sortcolumn">sortColumn</a></code> attributes, and
786: excluding rows with one or more ancestors that are closed. This tree
787: is cleared whenever the <code title="dom-datagrid-sortAscending"><a href="#dom-datagrid-sortascending">sortAscending</a></code> and <code title="dom-datagrid-sortColumn"><a href="#dom-datagrid-sortcolumn">sortColumn</a></code> attributes
788: change.</p>
789:
790: <p>The third structure is the <dfn id="display-order-sparse-data-list">display order sparse data
791: list</dfn>. This structure is a flattened representation of the
792: <a href="#display-order-sparse-data-tree">display order sparse data tree</a>.</p>
793:
794: <p>At any time, a number of consecutive rows in the <a href="#display-order-sparse-data-list">display
795: order sparse data list</a> are physically visible to the
796: user. The <code><a href="#datagrid">datagrid</a></code> fires notifications to a <a href="#dom-datagrid-listener" title="dom-datagrid-listener">listener</a> (provided by script),
797: and the listener, or other some script, is expected to feed the
798: <code><a href="#datagrid">datagrid</a></code> with the information needed to render the
799: control.</p>
800:
801: <p>A <code><a href="#datagrid">datagrid</a></code> has a <dfn id="pending-datagrid-rows-list">pending <code>datagrid</code>
802: rows list</dfn>, which is a list of rows in the <a href="#display-order-sparse-data-list">display order
803: sparse data list</a> for which the <code><a href="#datagrid">datagrid</a></code> has sent
804: notifications requesting information but not yet received
805: information about.</p>
806:
807: <p>A <code><a href="#datagrid">datagrid</a></code> also has a <dfn id="pending-datagrid-cells-list">pending
808: <code>datagrid</code> <em>cells</em> list</dfn>, which is a list of
809: row/column pairs (cells) for which the <code><a href="#datagrid">datagrid</a></code> has
810: sent notifications requesting information but not yet received
811: information about.</p>
812:
813: <p>User agents may discard information about rows that are not
814: displayed and that are not ancestors or open earlier siblings of
815: rows or ancestors of rows that are displayed.</p>
816:
817: <hr><p>These structures are different views of the collection of rows
818: that form the <code><a href="#datagrid">datagrid</a></code>. Each row has the following
819: information associated with it:</p>
820:
821: <dl><dt>A parent</dt>
822:
823: <dd><p>Either another row, or the <code><a href="#datagrid">datagrid</a></code> itself. This
824: is the parent of the row in the <a href="#natural-order-sparse-data-tree">natural order sparse data
825: tree</a> and the <a href="#display-order-sparse-data-tree">display order sparse data tree</a>
826: for the <code><a href="#datagrid">datagrid</a></code>.</p></dd>
827:
828: <dt>A natural order position relative to the other rows with the
829: same parent</dt>
830:
831: <dd>
832:
833: <p>This is the number of rows that precede this row under the same
834: parent in the <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a>. This
835: number can't be changed relative to other rows in the same parent;
836: to change the relative natural order of data in the
837: <code><a href="#datagrid">datagrid</a></code>, the original rows have to be removed and
838: new rows (with the same data but different natural positions)
839: inserted in their place. (The exact number of a row can change, as
840: new rows can be inserted above it.)</p>
841:
842: <p>A row can be identified by a <code><a href="#rowid">RowID</a></code> object. This is
843: an array of numbers, consisting of the natural order positions of
844: each ancestor row and the row itself, starting from the furthest
845: ancestor. Thus, for instance, the fourth child row of the first
846: child row of the second row in a <code><a href="#datagrid">datagrid</a></code> would be
847: identified by a <code><a href="#rowid">RowID</a></code> object whose value is <code title="">[1, 0, 3]</code>. A row's identifier changes if rows are
848: <a href="#dom-datagrid-insertrows" title="dom-datagrid-insertRows">inserted before it</a> in
849: the <code><a href="#datagrid">datagrid</a></code>.</p>
850:
851: </dd>
852:
853: <dt>A display order position relative to the other rows with
854: the same parent</dt>
855:
856: <dd><p>This is the number of rows that precede this row under the
857: same parent in the <a href="#display-order-sparse-data-tree">display order sparse data
858: tree</a>. This number can be unknown. If the sort order
859: changes, then this information is lost (as the <a href="#display-order-sparse-data-tree">display order
860: sparse data tree</a> is cleared).</p></dd>
861:
862: <dt>A child count</dt>
863:
864: <dd><p>The number of rows that have this row as a parent. If this is
865: zero, the row cannot be opened. If this is −1, then the
866: child count is unknown but the row can be opened. This value can be
867: changed by the <code title="dom-datagrid-setRows"><a href="#dom-datagrid-setrows">setRows()</a></code>
868: method only if the current value is −1 or if the row or one
869: of its ancestors is closed. Otherwise, it can only be changed
870: indirectly using the <code title="dom-datagrid-insertRows"><a href="#dom-datagrid-insertrows">insertRows()</a></code> and <code title="dom-datagrid-deleteRows"><a href="#dom-datagrid-deleterows">deleteRows()</a></code> methods.</p></dd>
871:
872: <dt>An open flag</dt>
873:
874: <dd><p>A boolean indicating whether the row is open (true) or
875: closed (false). Once set, the flag can only be changed by the user
876: or while one of the row's ancestors is itself closed. A row can
877: also be in a third state, "opening", which is treated as closed for
878: all purposes except that the user agent may indicate that the row
879: is in this special state, and except that when the row is updated
880: to have a row count, the row will switch to being open.</p></dd>
881:
882: <dt>A row count</dt>
883:
884: <dd><p>The number of rows that have this row as a parent or
885: ancestor, and that do not have an ancestor that is a descendant of
886: this row that is itself closed. If this is −1, then the row
887: count is unknown. This value can be changed by the <code title="dom-datagrid-setRows"><a href="#dom-datagrid-setrows">setRows()</a></code> method only if the
888: row or one of its ancestors is closed (or opening, but not
889: open). Otherwise, it can only be changed indirectly using the <code title="dom-datagrid-insertRows"><a href="#dom-datagrid-insertrows">insertRows()</a></code> and <code title="dom-datagrid-deleteRows"><a href="#dom-datagrid-deleterows">deleteRows()</a></code>
890: methods.</p></dd>
891:
892: <dt>Cells</dt>
893:
894: <dd><p>The data that applies to this row. Cell data is discussed in
895: more detail below.</p></dd>
896:
897: </dl><p>The <code><a href="#datagrid">datagrid</a></code> itself also has a <dfn id="datagrid-child-count" title="datagrid
898: child count">child count</dfn> and a <dfn id="datagrid-row-count" title="datagrid row
899: count">row count</dfn>, which are analogous to the child counts and
900: row counts for rows. Initially, these must be zero.</p>
901:
902: <hr><p>The <dfn id="datagrid-resort-steps"><code>datagrid</code> resort steps</dfn>, which are
903: invoked when the sort order changes as described in the previous
904: section, are as follows:</p>
905:
906: <ol><li>
907:
908: <p>Clear the <a href="#display-order-sparse-data-tree">display order sparse data tree</a>
909: (i.e. mark the display order position of all the rows in the
910: <code><a href="#datagrid">datagrid</a></code> as unknown).</p>
911:
912: <p>User agents may cache the position information of rows for
913: various values of <code title="dom-datagrid-sortColumn"><a href="#dom-datagrid-sortcolumn">sortColumn</a></code> and <code title="dom-datagrid-sortAscending"><a href="#dom-datagrid-sortascending">sortAscending</a></code>, instead
914: of discarding the information altogether. If the user agent caches
915: this information, and has information that applies to the current
916: values of <code title="dom-datagrid-sortColumn"><a href="#dom-datagrid-sortcolumn">sortColumn</a></code>
917: and <code title="dom-datagrid-sortAscending"><a href="#dom-datagrid-sortascending">sortAscending</a></code>,
918: then the user agent may repopulate the <a href="#display-order-sparse-data-tree">display order sparse
919: data tree</a> from this information.</p>
920:
921: </li>
922:
923: <li>
924:
925: <p>Clear the <a href="#pending-datagrid-rows-list">pending <code>datagrid</code> rows list</a>
926: and the <a href="#pending-datagrid-cells-list">pending <code>datagrid</code> cells list</a>.</p>
927:
928: </li>
929:
930: <li>
931:
932: <p>Invoke the <a href="#datagrid-update-display-algorithm"><code>datagrid</code> update display
933: algorithm</a>.</p>
934:
935: </li>
936:
937: <!-- v2: queue a task to fire an event, or tell the listener the
938: sort order changed, or something -->
939:
940: </ol><hr><p>The <dfn id="dom-datagrid-renotify" title="dom-datagrid-renotify"><code>renotify()</code></dfn> method
941: must empty the <a href="#pending-datagrid-rows-list">pending <code>datagrid</code> rows list</a>
942: and the <a href="#pending-datagrid-cells-list">pending <code>datagrid</code> cells list</a>, and
943: invoke the <a href="#datagrid-update-display-algorithm"><code>datagrid</code> update display
944: algorithm</a>.</p>
945:
946: <hr><p>The <dfn id="dom-datagrid-setrowcount" title="dom-datagrid-setRowCount"><code>setRowCount(<var title="">childCount</var>, <var title="">rowCount</var>)</code></dfn> method must run the following
947: steps:</p>
948:
949: <ol><li>
950:
951: <p>Set the <a href="#datagrid-child-count"><code>datagrid</code> child count</a> to <var title="">childCount</var>, the <a href="#datagrid-row-count"><code>datagrid</code> row
952: count</a> to <var title="">rowCount</var>.</p>
953:
954: </li>
955:
956: <li>
957:
958: <p><a href="#audit-the-datagrid">Audit the <code>datagrid</code></a>. If this fails,
959: then revert the changes made in the previous step, throw a
960: <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception, and abort these
961: steps.</p>
962:
963: </li>
964:
965: <li>
966:
967: <p>Invoke the <a href="#datagrid-update-display-algorithm"><code>datagrid</code> update display
968: algorithm</a>.</p>
969:
970: </li>
971:
972: </ol><hr><p>The <dfn id="dom-datagrid-setrows" title="dom-datagrid-setRows"><code>setRows(<var title="">rows</var>)</code></dfn> method must run the following
973: steps:</p>
974:
975: <ol><li>
976:
977: <p><a href="#type-check-a-rowlist-object" title="type-check a RowList object">Type-check the <var title="">rows</var> argument</a>. If this fails, throw a
978: <code>TypeError</code> exception, and abort these steps.</p>
979:
980: </li>
981:
982: <li>
983:
984: <p><a href="#partially-sort-a-rowlist-object" title="partially sort a RowList object">Partially sort
985: the <var title="">rows</var> argument</a>.</p>
986:
987: </li>
988:
989: <li>
990:
991: <p>For each <code><a href="#row">Row</a></code> object in the <var title="">rows</var> argument, in order, perform the appropriate
992: steps from the list below.</p>
993:
994: <p class="note">The changes made to the <code><a href="#datagrid">datagrid</a></code>'s
995: data structures in this step get reverted (as required below) if
996: any consistency errors are detected either in this step or the
997: next.</p>
998:
999: <dl><dt>If there already exists a row in the <code><a href="#datagrid">datagrid</a></code>'s
1000: <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a> with the same
1001: identifier as given by the <code><a href="#row">Row</a></code> object's
1002: <code><a href="#rowid">RowID</a></code> object, and that row and all its ancestors are
1003: open</dt>
1004:
1005: <dd>
1006:
1007: <p>If one of the following conditions is true, then revert all
1008: the changes done in this step, throw a
1009: <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception, and abort these
1010: steps:</p>
1011:
1012: <ul><li>The value of the <code><a href="#row">Row</a></code> object's second entry is
1013: neither −1 nor equal to the child count of the
1014: preexisting row.</li>
1015:
1016: <li>The <code><a href="#row">Row</a></code> object has fewer than four
1017: entries or more than six entries.</li>
1018:
1019: <li>The <code><a href="#row">Row</a></code> object has five or more entries, and
1020: its fifth entry is false.</li>
1021:
1022: <li>The <code><a href="#row">Row</a></code> object has six entries, and its sixth
1023: entry is not equal to the row count of the preexisting
1024: row.</li>
1025:
1026: </ul></dd>
1027:
1028: <dt>If there already exists a row in the <code><a href="#datagrid">datagrid</a></code>'s
1029: <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a> with the same
1030: identifier as given by the <code><a href="#row">Row</a></code> object's
1031: <code><a href="#rowid">RowID</a></code> object, but either that row or one of its
1032: ancestors is closed</dt>
1033:
1034: <dd>
1035:
1036: <p>Set the preexisting row's child count to the value of the
1037: <code><a href="#row">Row</a></code> object's second entry.</p>
1038:
1039: <p>If the <code><a href="#row">Row</a></code> object has five or more entries, and
1040: either its fifth entry is true and the preexisting row is closed
1041: but not opening, or its fifth entry is false and the preexisting
1042: row is open, then: if the preexisting row has no ancestor row
1043: that is closed, then revert all the changes done in this step,
1044: throw a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception, and abort
1045: these steps; otherwise, if the fifth entry is false, then close
1046: the row; otherwise, open the row.</p>
1047:
1048: <p>If the <code><a href="#row">Row</a></code> object has six entries, set the
1049: preexisting row's row count to the value of the <code><a href="#row">Row</a></code>
1050: object's sixth entry.</p>
1051:
1052: <p>If the preexisting row is opening, then: increase the
1053: <a href="#datagrid-row-count"><code>datagrid</code> row count</a> and the row counts
1054: of any ancestor rows by the number of rows that the preexisting
1055: row now has in its row count, then open the row.</p> <!-- we
1056: should also "update the <span>pending <code>datagrid</code> rows
1057: list</span> and the <span>pending <code>datagrid</code> cells
1058: list</span> accordingly" -->
1059:
1060:
1061: </dd>
1062:
1063: <dt>There does not exist a row in the <code><a href="#datagrid">datagrid</a></code>'s
1064: <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a> with the same
1065: identifier as given by the <code><a href="#row">Row</a></code> object's
1066: <code><a href="#rowid">RowID</a></code> object</dt>
1067:
1068: <dd>
1069:
1070: <p>If the <code><a href="#rowid">RowID</a></code> object has a length greater than 1,
1071: then verify that there is a row identified by the
1072: <code><a href="#rowid">RowID</a></code> consisting of all but the last number in the
1073: <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code>. If there is no
1074: such row present in the <a href="#natural-order-sparse-data-tree">natural order sparse data
1075: tree</a>, then revert all the changes done in this step,
1076: throw a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception, and abort
1077: these steps.</p>
1078:
1079: <p>Create a row and insert it into the <a href="#natural-order-sparse-data-tree">natural order
1080: sparse data tree</a>, such that its parent is the row
1081: identified by the <code><a href="#rowid">RowID</a></code> consisting of all but the
1082: last number in the <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code>,
1083: or the <code><a href="#datagrid">datagrid</a></code> if the length of the
1084: <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code> is 1; with its
1085: natural order position being the last number of the
1086: <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code>; with the child
1087: count being the value of the third entry of the <code><a href="#row">Row</a></code>
1088: object; with the row being marked closed unless the
1089: <code><a href="#row">Row</a></code> object has five or more entries and its fifth
1090: entry is true, in which case the row is open; and with its row
1091: count being −1 unless the <code><a href="#row">Row</a></code> object has six
1092: entries, in which case the row count is equal to the value of
1093: the <code><a href="#row">Row</a></code> object's sixth entry.</p>
1094:
1095: </dd>
1096:
1097: </dl></li>
1098:
1099: <li>
1100:
1101: <p><a href="#audit-the-datagrid">Audit the <code>datagrid</code></a>. If this fails,
1102: then revert the changes made in the previous step, throw a
1103: <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception, and abort these
1104: steps.</p>
1105:
1106: </li>
1107:
1108: <li>
1109:
1110: <p>For each <code><a href="#row">Row</a></code> object in the <var title="">rows</var> argument, in order, <a href="#apply-a-row-object" title="apply a Row
1111: object">apply the <code>Row</code> object</a>.</p>
1112:
1113: </li>
1114:
1115: <li>
1116:
1117: <p>Invoke the <a href="#datagrid-update-display-algorithm"><code>datagrid</code> update display
1118: algorithm</a>.</p>
1119:
1120: </li>
1121:
1122: </ol><hr><p>The <dfn id="dom-datagrid-insertrows" title="dom-datagrid-insertRows"><code>insertRows(<var title="">rows</var>)</code></dfn> method must run the following
1123: steps:</p>
1124:
1125: <ol><li>
1126:
1127: <p><a href="#type-check-a-rowlist-object" title="type-check a RowList object">Type-check the <var title="">rows</var> argument</a>. If this fails, throw a
1128: <code>TypeError</code> exception, and abort these steps.</p>
1129:
1130: </li>
1131:
1132: <li>
1133:
1134: <p><a href="#partially-sort-a-rowlist-object" title="partially sort a RowList object">Partially sort
1135: the <var title="">rows</var> argument</a>.</p>
1136:
1137: </li>
1138:
1139: <li>
1140:
1141: <p>For each <code><a href="#row">Row</a></code> object in the <var title="">rows</var> argument, in order, run the following
1142: steps:</p>
1143:
1144: <p class="note">The changes made to the <code><a href="#datagrid">datagrid</a></code>'s
1145: data structures in this step get reverted (as required below) if
1146: any consistency errors are detected either in this step or the
1147: next.</p>
1148:
1149: <ol><li>
1150:
1151: <p>Let <var title="">parent</var> be the row identified by the
1152: <code><a href="#rowid">RowID</a></code> consisting of all but the last number in the
1153: <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code>, or the
1154: <code><a href="#datagrid">datagrid</a></code> itself if the <code><a href="#row">Row</a></code> object's
1155: <code><a href="#rowid">RowID</a></code> has length 0.</p>
1156:
1157: <p>If there is no such row present in the <a href="#natural-order-sparse-data-tree">natural order
1158: sparse data tree</a>, then revert all the changes done in
1159: this algorithm, throw a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code>
1160: exception, and abort these steps.</p>
1161:
1162: </li>
1163:
1164: <li>
1165:
1166: <p>Increment by one the natural order position of all rows whose
1167: parent is <var title="">parent</var> and whose natural order
1168: position is equal to or greater than the last number of the
1169: <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code>.</p>
1170:
1171: </li>
1172:
1173: <li>
1174:
1175: <p>If the value of the <code><a href="#row">Row</a></code> object's second entry is
1176: not −1, then increment by one the display order position
1177: of all rows whose parent is <var title="">parent</var> and whose
1178: display order position is equal to or greater than the value of
1179: the <code><a href="#row">Row</a></code> object's second entry.</p>
1180:
1181: <!--(Not sure how to really say this.)
1182: <p>Update the <span>pending <code>datagrid</code> rows
1183: list</span> and the <span>pending <code>datagrid</code> cells
1184: list</span> accordingly.</p>
1185: -->
1186:
1187: </li>
1188:
1189: <li>
1190:
1191: <p>Create a row and insert it into the <a href="#natural-order-sparse-data-tree">natural order
1192: sparse data tree</a>, such that its parent is <var title="">parent</var>; with its natural order position being the
1193: last number of the <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code>;
1194: with the child count being the value of the third entry of the
1195: <code><a href="#row">Row</a></code> object; with the row being marked closed unless
1196: the <code><a href="#row">Row</a></code> object has five or more entries and its
1197: fifth entry is true, in which case the row is open; and with its
1198: row count being −1 unless the <code><a href="#row">Row</a></code> object has
1199: six entries, in which case the row count is equal to the value
1200: of the <code><a href="#row">Row</a></code> object's sixth entry.</p>
1201:
1202: </li>
1203:
1204: </ol></li>
1205:
1206: <li>
1207:
1208: <p>For each <code><a href="#row">Row</a></code> object in the <var title="">rows</var> argument, in order, <a href="#apply-a-row-object" title="apply a Row
1209: object">apply the <code>Row</code> object</a>.</p>
1210:
1211: </li>
1212:
1213: <li>
1214:
1215: <p>Invoke the <a href="#datagrid-update-display-algorithm"><code>datagrid</code> update display
1216: algorithm</a>.</p>
1217:
1218: </li>
1219:
1220: </ol><hr><p>When an algorithm requires the user agent to <dfn id="type-check-a-rowlist-object">type-check a
1221: <code>RowList</code> object</dfn> (an array), each entry in the
1222: object must be checked against the following requirements. If any
1223: are false, then the type-check fails, otherwise it passes.</p>
1224:
1225: <ul><li><p>The entry is a <code><a href="#row">Row</a></code> object (an
1226: array).</p></li>
1227:
1228: <li><p>The first value in the <code><a href="#row">Row</a></code> is a
1229: <code><a href="#rowid">RowID</a></code> object (also an array), whose length is at least
1230: 1, and whose values are all integers greater than or equal to
1231: zero.</p></li>
1232:
1233: <li><p>The numbers in the <code><a href="#rowid">RowID</a></code> object do not exactly
1234: match any of the other entries in the <code><a href="#rowlist">RowList</a></code> object
1235: (i.e. no two <code><a href="#row">Row</a></code> objects have the same
1236: identifier).</p></li>
1237:
1238: <li><p>The second value in the <code><a href="#row">Row</a></code> is an integer that
1239: is either −1, zero, or a positive integer.</p></li>
1240:
1241: <li><p>The third value in the <code><a href="#row">Row</a></code> is an integer that
1242: is either −1, zero, or a positive integer.</p></li>
1243:
1244: <li><p>The fourth value in the <code><a href="#row">Row</a></code> is a
1245: <code><a href="#celllist">CellList</a></code> object (yet another array).</p></li>
1246:
1247: <li><p>Each entry in the <a href="#celllist">CellList</a> object is a
1248: <code><a href="#cell">Cell</a></code> object (again, an array).</p></li>
1249:
1250: <li><p>Each <code><a href="#cell">Cell</a></code> object in the <a href="#celllist">CellList</a>
1251: object has as its first value a <code><a href="#column">Column</a></code> object (a
1252: string), and its value is the identifier of one of the columns in
1253: the <a href="#column-list">column list</a>.</p></li>
1254:
1255: <li>
1256:
1257: <p>Each <code><a href="#cell">Cell</a></code> object in the <a href="#celllist">CellList</a>
1258: object has as its second and subsequent entries values that match
1259: the following requirements, as determined by the type of the
1260: column identified by the first entry:</p>
1261:
1262: <dl><dt>If the column's type is <code title="datagrid-type-text"><a href="#datagrid-type-text">text</a></code></dt>
1263: <dd>
1264:
1265: <p>The second entry's value is a string, and either there are
1266: only two entries, or there are three, and the third entry is
1267: an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element.</p>
1268:
1269: <p>If there is an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element specified, its <code title="dom-img-complete"><a href="embedded-content-0.html#dom-img-complete">complete</a></code> attribute is true.</p>
1270:
1271: </dd>
1272:
1273: <dt>If the column's type is <code title="datagrid-type-editable"><a href="#datagrid-type-editable">editable</a></code></dt>
1274: <dd>
1275:
1276: <p>The second entry's value is a string, and either there are
1277: only two entries, or the third entry is a
1278: <code><a href="forms.html#the-datalist-element">datalist</a></code> element, and either there are only three
1279: entries, or there are four, and the fourth entry is an
1280: <code><a href="embedded-content-0.html#the-img-element">img</a></code> element.</p>
1281:
1282: <p>If there is an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element specified, its <code title="dom-img-complete"><a href="embedded-content-0.html#dom-img-complete">complete</a></code> attribute is true.</p>
1283:
1284: </dd>
1285:
1286: <dt>If the column's type is <code title="datagrid-type-checkable"><a href="#datagrid-type-checkable">checkable</a></code></dt>
1287: <dd>
1288:
1289: <p>The second entry's value is a string, the third entry is a
1290: boolean, and either there are only three entries, or the
1291: fourth entry is also a boolean, and either there are only four
1292: entries, or there are five, and the fifth entry is an
1293: <code><a href="embedded-content-0.html#the-img-element">img</a></code> element.</p>
1294:
1295: <p>If there is an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element specified, its <code title="dom-img-complete"><a href="embedded-content-0.html#dom-img-complete">complete</a></code> attribute is true.</p>
1296:
1297: </dd>
1298:
1299: <dt>If the column's type is <code title="datagrid-type-list"><a href="#datagrid-type-list">list</a></code></dt>
1300: <dd>
1301:
1302: <p>The second entry's value is a string, the third entry is a
1303: <code><a href="forms.html#the-select-element">select</a></code> element, and either there are only three
1304: entries, or there are four, and the fourth entry is an
1305: <code><a href="embedded-content-0.html#the-img-element">img</a></code> element.</p>
1306:
1307: <p>If there is an <code><a href="embedded-content-0.html#the-img-element">img</a></code> element specified, its <code title="dom-img-complete"><a href="embedded-content-0.html#dom-img-complete">complete</a></code> attribute is true.</p>
1308:
1309: </dd>
1310:
1311: <dt>If the column's type is <code title="datagrid-type-progress"><a href="#datagrid-type-progress">progress</a></code></dt>
1312: <dd>
1313:
1314: <p>There are only two entries, the second entry's value is a
1315: number, and the number's value is between 0.0 and 1.0
1316: inclusive.</p>
1317:
1318: </dd>
1319:
1320: <dt>If the column's type is <code title="datagrid-type-meter"><a href="#datagrid-type-meter">meter</a></code></dt>
1321: <dd>
1322:
1323: <p>There are at least two, but possibly up to seven, entries,
1324: all entries but the first one are numbers, and the following
1325: relationships hold:</p>
1326:
1327: <ul class="brief"><li>The second entry is less than the third, or less than 1.0
1328: if the third is absent.</li>
1329:
1330: <li>The second entry is greater than the fourth, or greater
1331: than 0.0 if the fourth is absent.</li>
1332:
1333: <li>If there are at least three entries, the third entry is
1334: greater than the fourth, or greater than zero if the fourth
1335: is absent.</li>
1336:
1337: <li>If there are at least five entries, the fifth is not
1338: greater than the third and not less than the fourth.</li>
1339:
1340: <li>If there are at least six entries, the sixth is not
1341: greater than the third and not less than the fifth.</li>
1342:
1343: <li>If there are at least seven entries, the fifth is not
1344: greater than the third and not less than the fourth.</li>
1345:
1346: </ul></dd>
1347:
1348: <dt>If the column's type is <code title="datagrid-type-custom"><a href="#datagrid-type-custom">custom</a></code></dt>
1349: <dd>
1350:
1351: <p>There are four entries, the second and third are numbers
1352: that are integers greater than zero, and the fourth is a
1353: <code>Rendering2DContextCallback</code> object (a
1354: function).</p>
1355:
1356: </dd>
1357:
1358: </dl></li>
1359:
1360: <li><p>Either there are only four values in the <code><a href="#row">Row</a></code>,
1361: or the fifth value in the <code><a href="#row">Row</a></code> is a boolean.</p></li>
1362:
1363: <li><p>Either there are only four or five values in the
1364: <code><a href="#row">Row</a></code>, or there are six, and the sixth value in the
1365: <code><a href="#row">Row</a></code> an integer that is greater than or equal to
1366: zero.</p></li>
1367:
1368: </ul><p>Where the above requirements say that a value is to be a string,
1369: the user agent must apply the ToString() conversion operator to the
1370: value, assume that the value was indeed a string, and use the result
1371: in the rest of the algorithm as if it had that had been the value
1372: passed to the method. <a href="references.html#references">[ECMA262]</a></p>
1373:
1374: <p>Where the above requirements say that a value is to be a number,
1375: the user agent must first apply the ToNumber() conversion operator
1376: to the value, and then verify that the result is neither the
1377: not-a-number NaN value nor an infinite value. If this result is
1378: indeed acceptable (i.e. finite), the user agent must use the result
1379: in the rest of the algorithm as if it had that had been the value
1380: passed to the method. <a href="references.html#references">[ECMA262]</a></p>
1381:
1382: <p>Where the above requirements say that a value is to be an
1383: integer, the user agent must first apply the ToNumber() conversion
1384: operator to the value, and then verify that the result is a finite
1385: integer. If so, the user agent must use the result in the rest of
1386: the algorithm as if it had that had been the value passed to the
1387: method. <a href="references.html#references">[ECMA262]</a></p>
1388:
1389: <p>Where the above requirements say that a value is to be a boolean,
1390: the user agent must apply the ToBoolean() conversion operator to the
1391: value, assume that the value was indeed a boolean, and use the
1392: result in the rest of the algorithm as if it had that had been the
1393: value passed to the method. <a href="references.html#references">[ECMA262]</a></p>
1394:
1395: <hr><p>When an algorithm requires the user agent to <dfn id="audit-the-datagrid">audit the
1396: <code>datagrid</code></dfn>, the <code><a href="#datagrid">datagrid</a></code> must be
1397: checked against the following requirements. If any are false, then
1398: the audit fails, otherwise it passes.</p>
1399:
1400: <ul><li>There is no row whose natural order position is greater than or
1401: equal to the child count of its parent row in the <a href="#natural-order-sparse-data-tree">natural
1402: order sparse data tree</a>.</li>
1403:
1404: <li>There is no row whose display order position is greater than or
1405: equal to the child count of its parent row in the <a href="#display-order-sparse-data-tree">display
1406: order sparse data tree</a>.</li>
1407:
1408: <li>There is no row such that the sum of that row's child count and
1409: the row counts all the open rows that are direct children of that
1410: row in the <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a> is less than
1411: that row's row count.</li>
1412:
1413: <li>Of the rows whose child count is equal to the number of rows
1414: that are direct children of that row in the <a href="#natural-order-sparse-data-tree">natural order
1415: sparse data tree</a>, there is none such that the sum of that
1416: row's child count and the row counts of all the open rows that are
1417: direct children of that row in the <a href="#natural-order-sparse-data-tree">natural order sparse data
1418: tree</a> is greater than that row's row count.</li>
1419:
1420: </ul><p>For the purposes of this audit, the <code><a href="#datagrid">datagrid</a></code> must be
1421: treated as the parent row of all the rows that are direct children
1422: of the <code><a href="#datagrid">datagrid</a></code> in the <a href="#natural-order-sparse-data-tree">natural order sparse data
1423: tree</a> and the <a href="#display-order-sparse-data-tree">display order sparse data tree</a>. The
1424: child count of this implied row is the <a href="#datagrid-child-count"><code>datagrid</code>
1425: child count</a>, and the row count of this implied row is the
1426: <a href="#datagrid-row-count"><code>datagrid</code> row count</a>.</p>
1427:
1428: <hr><p>When an algorithm requires the user agent to <dfn id="partially-sort-a-rowlist-object">partially sort
1429: a <code>RowList</code> object</dfn> (an array), the entries in the
1430: object must be resorted such that <code><a href="#row">Row</a></code> objects are
1431: listed after any of their ancestors and after any of their earlier
1432: siblings. In other words, for any two <code><a href="#row">Row</a></code> objects <var title="">a</var> and <var title="">b</var> in the
1433: <code><a href="#rowlist">RowList</a></code>, where <var title="">a</var> is before <var title="">b</var> after the sort, the following conditions must
1434: hold:</p>
1435:
1436: <ul><li><p>If their <code><a href="#rowid">RowID</a></code> objects are the same length and
1437: have values that are equal except for the last value, then the last
1438: value of <var title="">a</var>'s <code><a href="#rowid">RowID</a></code>'s last value
1439: must be less than <var title="">b</var>'s <code><a href="#rowid">RowID</a></code>'s last
1440: value (i.e. earlier siblings must come before their later
1441: siblings).</p></li>
1442:
1443: <li><p>If their <code><a href="#rowid">RowID</a></code> objects are not the same length,
1444: but the values in the shorter of the two are the same as the first
1445: few values in the longer one, then <var title="">a</var>'s
1446: <code><a href="#rowid">RowID</a></code> must be the shorter one (i.e. ancestors must
1447: come before their descendants).</p></li>
1448:
1449: </ul><hr><p>The <dfn id="dom-datagrid-deleterows" title="dom-datagrid-deleteRows"><code>deleteRows(<var title="">rows</var>)</code></dfn> method must run the following
1450: steps:</p>
1451:
1452: <ol><li>
1453:
1454: <p>If any of the entries in <var title="">rows</var> are not
1455: <code><a href="#rowid">RowID</a></code> objects consisting of one or more entries whose
1456: values are all integers that are greater than or equal to zero,
1457: then throw a <code>TypeError</code> exception and abort these
1458: steps.</p>
1459:
1460: <p>To check if a value is an integer, the user agent must first
1461: apply the ToNumber() conversion operator to the value, and then
1462: verify that the result is a finite integer. If so, the user agent
1463: must use the result in the rest of the algorithm as if it had that
1464: had been the value passed to the method. <a href="references.html#references">[ECMA262]</a></p>
1465:
1466: </li>
1467:
1468: <li>
1469:
1470: <p>If any of the <code><a href="#rowid">RowID</a></code> objects in the <var title="">rows</var> argument identify a row that isn't present in
1471: the <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a>, then throw a
1472: <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception and abort these
1473: steps.</p>
1474:
1475: </li>
1476:
1477: <li>
1478:
1479: <p>If any row is listed twice in the <var title="">rows</var>
1480: argument, then throw a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception
1481: and abort these steps.</p>
1482:
1483: </li>
1484:
1485: <li>
1486:
1487: <p>Sort the <var title="">rows</var> argument such that the
1488: entries are given in the same order as the rows they identify
1489: would be visited in a pre-order, depth first traversal of the
1490: <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a>.</p>
1491:
1492: </li>
1493:
1494: <li>
1495:
1496: <p>For each row identified by entries in <var title="">rows</var>,
1497: <em>in reverse order</em>, run the following steps:</p>
1498:
1499: <ol><li>
1500:
1501: <p>Decrement the child count of the row's parent row, if that
1502: child count is greater than zero. If the row has no parent,
1503: decrement the <a href="#datagrid-child-count"><code>datagrid</code> child
1504: count</a>.</p>
1505:
1506: <p>If the row has a parent row, and its child count is now zero,
1507: then close that row.</p>
1508:
1509: </li>
1510:
1511: <li>
1512:
1513: <p>Let <var title="">delta</var> be one more than the row's row
1514: count if the row is open and its row count is greater than zero;
1515: otherwise, let <var title="">delta</var> be one.</p>
1516:
1517: </li>
1518:
1519: <li>
1520:
1521: <p>Let <var title="">ancestor</var> be the row.</p>
1522:
1523: </li>
1524:
1525: <li>
1526:
1527: <p><i>Row count loop</i>: Let <var title="">ancestor</var> be
1528: <var title="">ancestor</var>'s parent row, if any, or null if it
1529: has none.</p>
1530:
1531: </li>
1532:
1533: <li>
1534:
1535: <p>If <var title="">ancestor</var> is null, then decrement the
1536: <a href="#datagrid-row-count"><code>datagrid</code> row count</a> by <var title="">delta</var>. Otherwise, if <var title="">ancestor</var>
1537: is open, then decrement its row count by <var title="">delta</var>.</p>
1538:
1539: </li>
1540:
1541: <li>
1542:
1543: <p>If <var title="">ancestor</var> is not null, then jump back
1544: to the step labeled <i>row count loop</i> above.</p>
1545:
1546: </li>
1547:
1548: <li>
1549:
1550: <p>Let <var title="">parent</var> be the row's parent, or the
1551: <code><a href="#datagrid">datagrid</a></code> if the row has no parent.</p>
1552:
1553: </li>
1554:
1555: <li>
1556:
1557: <p>Decrement by one the natural order position of all rows whose
1558: parent is <var title="">parent</var> and whose natural order
1559: position is equal to or greater than the row's own natural order
1560: position.</p>
1561:
1562: </li>
1563:
1564: <li>
1565:
1566: <p>If the row is in the <a href="#display-order-sparse-data-tree">display order sparse data
1567: tree</a>, then decrement by one the display order position of
1568: all rows whose parent is <var title="">parent</var> and whose
1569: display order position is equal to or greater than the row's own
1570: display order position.</p>
1571:
1572: </li>
1573:
1574: <li>
1575:
1576: <p>Clear the row and its descendants from the
1577: <code><a href="#datagrid">Datagrid</a></code>.</p>
1578:
1579: </li>
1580:
1581: </ol></li>
1582:
1583: <li>
1584:
1585: <p>Invoke the <a href="#datagrid-update-display-algorithm"><code>datagrid</code> update display
1586: algorithm</a>.</p>
1587:
1588: </li>
1589:
1590: </ol><hr><p>The <dfn id="dom-datagrid-clearrows" title="dom-datagrid-clearRows"><code>clearRows()</code></dfn> method
1591: must empty the <a href="#natural-order-sparse-data-tree">natural order sparse data tree</a>, reset
1592: both the <a href="#datagrid-child-count"><code>datagrid</code> child count</a> and the
1593: <a href="#datagrid-row-count"><code>datagrid</code> row count</a> to zero, and invoke the
1594: <a href="#datagrid-update-display-algorithm"><code>datagrid</code> update display algorithm</a>.</p>
1595:
1596: <hr><p>The <dfn id="dom-datagrid-repaint" title="dom-datagrid-repaint"><code>repaint(<var title="">row</var>, <var title="">column</var>)</code></dfn> method
1597: must cause the user agent to clear its cache for the cell specified
1598: 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"><a href="#datagrid-type-custom">custom</a></code>. If the given column has
1599: not been declared, or its type is not <code title="datagrid-type-custom"><a href="#datagrid-type-custom">custom</a></code>, then the user agent must
1600: throw a <code><a href="infrastructure.html#datagrid_model_err">DATAGRID_MODEL_ERR</a></code> exception. If the given row
1601: is not known, then the method must do nothing. If the cell is indeed
1602: cleared, the user agent must reinvoke the previously registered
1603: <code><a href="#renderingcontext2dcallback">RenderingContext2DCallback</a></code> callback when it needs to
1604: repaint that row.</p>
1605:
1606: <hr><p>If a row has a child count that isn't zero, then the user agent
1607: should offer to the user the option of opening and closing the
1608: row.</p>
1609:
1610: <p>When a row is opened, if the row's row count is greater than
1611: zero, then the user agent must increase the
1612: <a href="#datagrid-row-count"><code>datagrid</code> row count</a> and the row counts of
1613: any ancestor rows by the number of rows that the newly opened row
1614: has in its row count<!-- we should also "update the <span>pending
1615: <code>datagrid</code> rows list</span> and the <span>pending
1616: <code>datagrid</code> cells list</span> accordingly" -->, then must
1617: mark the row as open, then may fill in the <a href="#display-order-sparse-data-tree">display order
1618: sparse data tree</a> with any information that the user agent has
1619: cached about the display order positions of descendants of the newly
1620: opened row, and then must invoke the <code title="dom-listener-rowOpened"><a href="#dom-listener-rowopened">rowOpened()</a></code> method on the
1621: current <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code> with as
1622: its first argument a <code><a href="#rowid">RowID</a></code> object identifying the row
1623: that was opened and as its second argument the boolean false, and
1624: then must invoke the <a href="#datagrid-update-display-algorithm"><code>datagrid</code> update display
1625: algorithm</a>.</p>
1626:
1627: <p>On the other hand, when a row is opened and the row's row count
1628: is −1, then the user agent must mark the row as opening, and
1629: then must invoke the <code title="dom-listener-rowOpened"><a href="#dom-listener-rowopened">rowOpened()</a></code> method on the
1630: current <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code> with as
1631: its first argument a <code><a href="#rowid">RowID</a></code> object identifying the row
1632: that was opened and as its second argument the boolean true.</p>
1633:
1634: <p>When a row is closed, the user agent must decrease the
1635: <a href="#datagrid-row-count"><code>datagrid</code> row count</a> and the row counts of
1636: any ancestor rows by the number of rows that the newly closed row
1637: has in its row count, and then must invoke the <code title="dom-listener-rowOpened"><a href="#dom-listener-rowopened">rowOpened()</a></code> method on the
1638: current <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code> with as
1639: its first and only argument a <code><a href="#rowid">RowID</a></code> object identifying
1640: the row that was opened.</p>
1641:
1642:
1643:
1644: <h6 id="the-cells"><span class="secno">4.11.2.2.4 </span>The cells</h6>
1645:
1646: <p>Each row has one cell per column. Each cell has the same type as
1647: its column. The <dfn id="allowed-datagrid-column-types">allowed <code>datagrid</code> column
1648: types</dfn>, what they represent, and the requirements for when the
1649: user interacts with them, are as follows:</p>
1650:
1651: <dl><dt><dfn id="datagrid-type-text" title="datagrid-type-text"><code>text</code></dfn></dt>
1652: <dd>
1653:
1654: <p>The cell represents some text and an optional image.</p>
1655:
1656: </dd>
1657:
1658: <dt><dfn id="datagrid-type-editable" title="datagrid-type-editable"><code>editable</code></dfn></dt>
1659: <dd>
1660:
1661: <p>The cells represents some editable text, an optional
1662: <code><a href="forms.html#the-datalist-element">datalist</a></code> giving autocompletion hints, and an
1663: optional image.</p>
1664:
1665: <p>If there is a <code><a href="forms.html#the-datalist-element">datalist</a></code> element, the user agent
1666: should offer the suggestions represented by that element to the
1667: user. The user agent may use the suggestion's <a href="forms.html#concept-option-label" title="concept-option-label">label</a> to identify the
1668: suggestion. If the user selects a suggestion, then the editable
1669: text must be set to the selected suggestion's <a href="forms.html#concept-option-value" title="concept-option-value">value</a>, as if the user had
1670: written that value himself.</p>
1671:
1672: <p>When the user edits the value, either directly or using the
1673: <code><a href="forms.html#the-datalist-element">datalist</a></code>, the user agent must invoke the <code title="dom-listener-cellChanged"><a href="#dom-listener-cellchanged">cellChanged()</a></code> method on
1674: the current <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code>
1675: with as its first argument a <code><a href="#rowid">RowID</a></code> identifying the
1676: cell's row, as its second argument the identifier of the cell's
1677: column, as its third argument the new value, and as its fourth
1678: argument the previous value.</p>
1679:
1680: </dd>
1681:
1682: <dt><dfn id="datagrid-type-checkable" title="datagrid-type-checkable"><code>checkable</code></dfn></dt>
1683: <dd>
1684:
1685: <p>The cell represents some text, a check box that optionally has
1686: its value obscured as indeterminate, and an optional image.</p>
1687:
1688: <p>When the user checks or unchecks the check box, the user agent
1689: must change the check box's state appropriately and stop obscuring
1690: the check box as indeterminate (if it is obscuring it), and then
1691: must invoke the <code title="dom-listener-cellChanged"><a href="#dom-listener-cellchanged">cellChanged()</a></code> method on
1692: the current <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code>
1693: with as its first argument a <code><a href="#rowid">RowID</a></code> identifying the
1694: cell's row, as its second argument the identifier of the cell's
1695: column, as its third argument true if the check box is now checked
1696: and false otherwise, and as its fourth argument true if the check
1697: box was previously checked and false otherwise.</p>
1698:
1699: </dd>
1700:
1701: <dt><dfn id="datagrid-type-list" title="datagrid-type-list"><code>list</code></dfn></dt>
1702: <dd>
1703:
1704: <p>The cell represents some text giving the current value selected
1705: from a dropdown list of options, a <code><a href="forms.html#the-select-element">select</a></code> element
1706: giving the list of options, and an optional image.</p>
1707:
1708: <p>The user agent should allow the user to change the value of the
1709: cell from its current value to one of the <a href="forms.html#concept-option-value" title="concept-option-value">values</a> given by
1710: <code><a href="forms.html#the-option-element">option</a></code> elements in the <a href="forms.html#concept-select-option-list" title="concept-select-option-list">list of options</a> (if
1711: any). The user agent may use the <code><a href="forms.html#the-option-element">option</a></code> elements'
1712: <a href="forms.html#concept-option-label" title="concept-option-label">labels</a> to annotate each
1713: option.</p>
1714:
1715: <p>When the user selects a new value from the <code><a href="forms.html#the-select-element">select</a></code>
1716: element's <a href="forms.html#concept-select-option-list" title="concept-select-option-list">list of
1717: options</a>, the user agent must invoke the <code title="dom-listener-cellChanged"><a href="#dom-listener-cellchanged">cellChanged()</a></code> method on
1718: the current <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code>
1719: with as its first argument a <code><a href="#rowid">RowID</a></code> identifying the
1720: cell's row, as its second argument the identifier of the cell's
1721: column, as its third argument the new value, and as its fourth
1722: argument the previous value.</p>
1723:
1724: </dd>
1725:
1726: <dt><dfn id="datagrid-type-progress" title="datagrid-type-progress"><code>progress</code></dfn></dt>
1727: <dd>
1728:
1729: <p>The cell represents a (determinate) progress bar whose value is
1730: between 0.0, indicating no progress, and 1.0, indicating the task
1731: is complete.</p>
1732:
1733: </dd>
1734:
1735: <dt><dfn id="datagrid-type-meter" title="datagrid-type-meter"><code>meter</code></dfn></dt>
1736: <dd>
1737:
1738: <p>The cell represents a gauge, described by one to six
1739: numbers.</p>
1740:
1741: <p>The gauge's actual value is given by the first number.</p>
1742:
1743: <p>If there is a second number, then that number is the maximum
1744: value. Otherwise, the maximum value is 1.0.</p>
1745:
1746: <p>If there is a third number, then that number is the minimum
1747: value. Otherwise, the minimum value is 1.0.</p>
1748:
1749: <p>If there is a fourth number, then that number is the low
1750: boundary. Otherwise, the low boundary is the minimum value.</p>
1751:
1752: <p>If there is a fifth number, then that number is the high
1753: boundary. Otherwise, the high boundary is the maximum value.</p>
1754:
1755: <p>If there is a sixth number, then the optimal point is the sixth
1756: number. Otherwise, the optimum point is the midpoint between the
1757: minimum value and the maximum value.</p>
1758:
1759: <!-- next two paragraphs copied from <meter>: -->
1760:
1761: <p>If the optimum point is equal to the low boundary or the high
1762: boundary, or anywhere in between them, then the region between the
1763: low and high boundaries of the gauge must be treated as the
1764: optimum region, and the low and high parts, if any, must be
1765: treated as suboptimal. Otherwise, if the optimum point is less
1766: than the low boundary, then the region between the minimum value
1767: and the low boundary must be treated as the optimum region, the
1768: region between the low boundary and the high boundary must be
1769: treated as a suboptimal region, and the region between the high
1770: boundary and the maximum value must be treated as an even less
1771: good region. Finally, if the optimum point is higher than the high
1772: boundary, then the situation is reversed; the region between the
1773: high boundary and the maximum value must be treated as the optimum
1774: region, the region between the high boundary and the low boundary
1775: must be treated as a suboptimal region, and the remaining region
1776: between the low boundary and the minimum value must be treated as
1777: an even less good region.</p>
1778:
1779: <p>User agents should indicate the relative position of the actual
1780: value to the minimum and maximum values, and the relationship
1781: between the actual value and the three regions of the gauge.</p>
1782:
1783: </dd>
1784:
1785: <dt><dfn id="datagrid-type-custom" title="datagrid-type-custom"><code>custom</code></dfn></dt>
1786: <dd>
1787:
1788: <p>The cell represents a dynamically generated graphical image.</p>
1789:
1790: <p>The cell will have minimum dimensions (specified in CSS
1791: pixels), and a callback (in the form of a
1792: <code><a href="#renderingcontext2dcallback">RenderingContext2DCallback</a></code> object) to get a rendering
1793: for the cell.</p>
1794:
1795: <p>The user agent should not allow the cell to be rendered with
1796: dimensions less than the given minimum width and height.</p>
1797:
1798: <p>When the user agent needs to render the cell, the user agent
1799: must <a href="browsers.html#queue-a-task">queue a task</a> to invoke the
1800: <a href="#renderingcontext2dcallback">RenderingContext2DCallback</a> callback, passing it a
1801: newly created <code><a href="the-canvas-element.html#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object whose
1802: <code title="dom-context-2d-canvas"><a href="the-canvas-element.html#dom-context-2d-canvas">canvas</a></code> DOM attribute is
1803: null as the first argument, the actual cell width in CSS pixels as
1804: the second argument, and the actual cell height in CSS pixels as
1805: the third argument.</p>
1806:
1807: <p>If the user agent is able to render graphics, then it must
1808: render the graphics commands that the callback executed on the
1809: provided <code><a href="the-canvas-element.html#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object onto the
1810: cell once the callback returns. The image must be clipped to the
1811: dimensions of the cell. The coordinate space of the cell must be
1812: aligned with that used by the 2D context such that the top left
1813: corner of the cell is the 0,0 origin, with the coordinate space
1814: increasing its <var title="">x</var> dimension towards the right
1815: of the cell and its <var title="">y</var> axis towards the bottom
1816: of the cell, and with the image not scaled (so that one CSS pixel
1817: on the final rendering matches one CSS pixel in the coordinate
1818: space used by the 2D context).</p>
1819:
1820: <p>The user agent must then decouple the
1821: <code><a href="the-canvas-element.html#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object and any objects that
1822: it created (such as <code><a href="the-canvas-element.html#canvaspattern">CanvasPattern</a></code> objects or
1823: <code><a href="the-canvas-element.html#imagedata">ImageData</a></code> objects) from any real drawing surface.</p>
1824:
1825: <p>If the user agent is unable to render graphics, then it must
1826: render the text string returned by the callback instead.</p>
1827:
1828: </dd>
1829:
1830: </dl><hr><p>When an algorithm requires the user agent to <dfn id="apply-a-row-object">apply a
1831: <code>Row</code> object</dfn>, the user agent must run the following
1832: steps:</p>
1833:
1834: <ol><li>
1835:
1836: <p>If the value of the <code><a href="#row">Row</a></code> object's second entry is
1837: not −1, then run these substeps:</p>
1838:
1839: <ol><li><p>If there is a row with the same parent as the row
1840: specified by the <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code>
1841: object, whose display order position is currently the same as the
1842: value of the <code><a href="#row">Row</a></code> object's second entry, then remove
1843: that row from the <a href="#display-order-sparse-data-tree">display order sparse data
1844: tree</a>.</p></li>
1845:
1846: <li><p>Set the display order position of the row specified by the
1847: <code><a href="#row">Row</a></code> object's <code><a href="#rowid">RowID</a></code> to the value of the
1848: <code><a href="#row">Row</a></code> object's second entry, updating its position in
1849: the <a href="#display-order-sparse-data-tree">display order sparse data tree</a>
1850: accordingly.</p></li>
1851:
1852: <li><p>If the row is in the <a href="#pending-datagrid-rows-list">pending
1853: <code>datagrid</code> rows list</a>, remove it.</p></li>
1854:
1855: </ol></li>
1856:
1857: <li>
1858:
1859: <p>If the fourth entry in the <code><a href="#row">Row</a></code> object (a
1860: <code><a href="#celllist">CellList</a></code> object, an array) is not empty, then for
1861: each <code><a href="#cell">Cell</a></code> object in that array update the cell that
1862: corresponds to the column identified by the value of the first
1863: entry of the <code><a href="#cell">Cell</a></code> object, by using the appropriate
1864: set of steps given below as determined by the type of the
1865: column. Then, if the cell is in the <a href="#pending-datagrid-cells-list">pending
1866: <code>datagrid</code> cells list</a>, remove it.</p>
1867:
1868: <dl><dt>If the column's type is <code title="datagrid-type-text"><a href="#datagrid-type-text">text</a></code></dt>
1869: <dd>
1870:
1871: <p>Update the cell's text to the value given in the
1872: <code><a href="#cell">Cell</a></code> object's second entry.</p>
1873:
1874: <p>If the <code><a href="#cell">Cell</a></code> object has three entries, then copy
1875: the image data from the <code><a href="embedded-content-0.html#the-img-element">img</a></code> element given in the
1876: third entry, and let the cell's image be given by that image
1877: data. Otherwise, update the cell to have no image.</p>
1878:
1879: </dd>
1880:
1881: <dt>If the column's type is <code title="datagrid-type-editable"><a href="#datagrid-type-editable">editable</a></code></dt>
1882: <dd>
1883:
1884: <p>Update the cell's text to the value given in the
1885: <code><a href="#cell">Cell</a></code> object's second entry.</p>
1886:
1887: <p>If the <code><a href="#cell">Cell</a></code> object has three entries, then let
1888: the <code><a href="forms.html#the-datalist-element">datalist</a></code> element given in the third entry be
1889: the <code><a href="forms.html#the-datalist-element">datalist</a></code> element giving autocompletion
1890: hints. Otherwise, update the cell to have no
1891: <code><a href="forms.html#the-datalist-element">datalist</a></code> element.</p>
1892:
1893: <p>If the <code><a href="#cell">Cell</a></code> object has four entries, then copy
1894: the image data from the <code><a href="embedded-content-0.html#the-img-element">img</a></code> element given in the
1895: fourth entry, and let the cell's image be given by that image
1896: data. Otherwise, update the cell to have no image.</p>
1897:
1898: </dd>
1899:
1900: <dt>If the column's type is <code title="datagrid-type-checkable"><a href="#datagrid-type-checkable">checkable</a></code></dt>
1901: <dd>
1902:
1903: <p>Update the cell's text to the value given in the
1904: <code><a href="#cell">Cell</a></code> object's second entry.</p>
1905:
1906: <p>Update the cell's checked state to match the value of the
1907: third entry: checked if true, unchecked otherwise.</p>
1908:
1909: <p>If the <code><a href="#cell">Cell</a></code> object has four entries and the
1910: fourth entry is true, then update the cell to be obscured as
1911: indeterminate. Otherwise, the cell's state is not obscured.</p>
1912:
1913: <p>If the <code><a href="#cell">Cell</a></code> object has five entries, then copy
1914: the image data from the <code><a href="embedded-content-0.html#the-img-element">img</a></code> element given in the
1915: fifth entry, and let the cell's image be given by that image
1916: data. Otherwise, update the cell to have no image.</p>
1917:
1918: </dd>
1919:
1920: <dt>If the column's type is <code title="datagrid-type-list"><a href="#datagrid-type-list">list</a></code></dt>
1921: <dd>
1922:
1923: <p>Update the cell's text to the value given in the
1924: <code><a href="#cell">Cell</a></code> object's second entry, and the
1925: <code><a href="forms.html#the-select-element">select</a></code> element to be the one given in the
1926: <code><a href="#cell">Cell</a></code> object's third entry</p>
1927:
1928: <p>If the <code><a href="#cell">Cell</a></code> object has four entries, then copy
1929: the image data from the <code><a href="embedded-content-0.html#the-img-element">img</a></code> element given in the
1930: fourth entry, and let the cell's image be given by that image
1931: data. Otherwise, update the cell to have no image.</p>
1932:
1933: </dd>
1934:
1935: <dt>If the column's type is <code title="datagrid-type-progress"><a href="#datagrid-type-progress">progress</a></code></dt>
1936: <dd>
1937:
1938: <p>Update the cell to be a progress bar whose progress, on the
1939: scale of 0.0 (no progress) to 1.0 (task complete) is given by
1940: the value in the <code><a href="#cell">Cell</a></code> object's second entry.</p>
1941:
1942: </dd>
1943:
1944: <dt>If the column's type is <code title="datagrid-type-meter"><a href="#datagrid-type-meter">meter</a></code></dt>
1945: <dd>
1946:
1947: <p>Update the cell to be a gauge configured with the numbers
1948: given by the second and subsequent entries of the
1949: <code><a href="#cell">Cell</a></code> object.</p>
1950:
1951: </dd>
1952:
1953: <dt>If the column's type is <code title="datagrid-type-custom"><a href="#datagrid-type-custom">custom</a></code></dt>
1954: <dd>
1955:
1956: <p>Update the cell's minimum width to be the length in CSS
1957: pixels given by the <code><a href="#cell">Cell</a></code> object's second entry.</p>
1958:
1959: <p>Update the cell's minimum height to be the length in CSS
1960: pixels given by the <code><a href="#cell">Cell</a></code> object's third entry.</p>
1961:
1962: <p>Update the cell's callback to be the
1963: <code><a href="#renderingcontext2dcallback">RenderingContext2DCallback</a></code> object given by the
1964: <code><a href="#cell">Cell</a></code> object's fourth entry.</p>
1965:
1966: </dd>
1967:
1968: </dl></li>
1969:
1970: </ol><hr><p>When the user agent is to run the <dfn id="datagrid-update-display-algorithm"><code>datagrid</code>
1971: update display algorithm</dfn>, the user agent must invoke the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code> and <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code> methods on the
1972: current <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code> such
1973: that all the current visible rows in the <a href="#display-order-sparse-data-list">display order sparse
1974: data list</a>, and all the cells in the currently visible columns
1975: on all the currently visible rows, have been covered.</p>
1976:
1977: <p>A row is considered covered if it is present in the <a href="#pending-datagrid-rows-list">pending
1978: <code>datagrid</code> rows list</a>, or if the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code> method is invoked with
1979: a range that includes the row in question.</p>
1980:
1981: <p>A cell is considered covered if it is present in the
1982: <a href="#pending-datagrid-cells-list">pending <code>datagrid</code> cells list</a>, or if the
1983: <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code> method is
1984: invoked with a range that includes the row in question and a list of
1985: columns that includes the cell's column, or if the <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code> method is invoked
1986: with a list of rows and columns that intersects the cell in
1987: question. However, the <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code> method can only be
1988: used if the row is already present in the <a href="#display-order-sparse-data-list">display order sparse
1989: data list</a>.</p>
1990:
1991: <p>The <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code> method,
1992: if used, must be invoked with five arguments. The first argument
1993: must be the index in the <a href="#display-order-sparse-data-list">display order sparse data list</a>
1994: to the first row that the user agent is requesting, known as the
1995: <i>anchor row</i>. The second argument must be the number of
1996: consecutive cells for which the user agent is requesting
1997: information. The third argument must be the <code><a href="#rowid">RowID</a></code> of
1998: the row that is the nearest ancestor in the <a href="#display-order-sparse-data-tree">display order
1999: sparse data <em>tree</em></a> of the anchor row. If this is the
2000: <code><a href="#datagrid">datagrid</a></code>, then the <code><a href="#rowid">RowID</a></code> object must be an
2001: empty array. The fourth argument must be the display order position
2002: of the anchor row in the <a href="#display-order-sparse-data-tree">display order sparse data
2003: tree</a>, assuming that the row identified in the third argument
2004: is indeed the anchor row's parent row. The fifth and final argument
2005: must be an array of the identifiers of the columns for which the
2006: user agent is requesting information, in the order they were added
2007: to the <code><a href="#datagrid">datagrid</a></code>.</p>
2008:
2009: <p>As the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code> method
2010: is invoked, the <a href="#pending-datagrid-rows-list">pending <code>datagrid</code> rows list</a>
2011: must be updated to include the rows for which information has been
2012: requested, excluding rows for which information is already
2013: available; and the <a href="#pending-datagrid-cells-list">pending <code>datagrid</code> cells
2014: list</a> must be updated to include the cells for which
2015: information has been requested on those rows.</p>
2016:
2017: <p>The <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code> method,
2018: if used, must be invoked with two arguments. The first argument must
2019: be an array of <code><a href="#rowid">RowID</a></code> objects identifying the rows for
2020: which information is being requested. The second argument must be an
2021: array of the identifiers of the columns for which the user agent is
2022: requesting information, in the order they were added to the
2023: <code><a href="#datagrid">datagrid</a></code>.</p>
2024:
2025: <p>As the <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code>
2026: method is invoked, the <a href="#pending-datagrid-cells-list">pending <code>datagrid</code> cells
2027: list</a> must be updated to include the cells for which
2028: information has been requested.</p>
2029:
2030: <p>Calls to these methods should be batched so that the rows and
2031: cells to be covered are handled by the fewest number of calls to
2032: these methods as possible. To this end, user agents may invoke the
2033: <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code> method for a set
2034: of rows that includes some rows that are already in the
2035: <a href="#display-order-sparse-data-list">display order sparse data list</a>, and similarly may
2036: invoke the <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code>
2037: method with row/column combinations that cover some cells for which
2038: data is already known. Generally, however, user agents should avoid
2039: invoking these methods with arguments that cause information to be
2040: requested when it has already been requested or is already
2041: known.</p>
2042:
2043: <div class="example">
2044:
2045: <p>For example, consider a case represented by the following table,
2046: where the cells marked "Yes" indicate that the data has already
2047: been obtained, the cells marked "Pending" indicate that the data
2048: has been previously requested but not yet obtained, and the cells
2049: with just a dash indicate that no information has ever been
2050: obtained, or any information that had been obtained has now been
2051: discarded.</p>
2052:
2053: <table><tr><td> </td><th> Row </th><th> Column A </th><th> Column B
2054: </th></tr><tr><th> Row 1 </th><td> - </td><td> - </td><td> -
2055: </td></tr><tr><th> Row 2 </th><td> Yes </td><td> Yes </td><td> Yes
2056: </td></tr><tr><th> Row 3 </th><td> Yes </td><td> Yes </td><td> Yes
2057: </td></tr><tr><th> Row 4 </th><td> Yes </td><td> Yes </td><td> Yes
2058: </td></tr><tr><th> Row 5 </th><td> - </td><td> - </td><td> -
2059: </td></tr><tr><th> Row 6 </th><td> - </td><td> - </td><td> -
2060: </td></tr><tr><th> Row 7 </th><td> Yes </td><td> Pending </td><td> -
2061: </td></tr><tr><th> Row 8 </th><td> Yes </td><td> Pending </td><td> Pending
2062: </td></tr></table><p>Thus, rows 2, 3, 4, 7, and 8 are already covered, as are the
2063: cells from those rows except for the cell in column B of row 7.</p>
2064:
2065: <p>Now consider what happens if all of these rows become visible at
2066: once. The user agent has several choices, including (but not
2067: limited to) the following:</p>
2068:
2069: <ul><li>Fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code>
2070: method for rows 1 through 8 and columns A and B all at once.</li>
2071:
2072: <li>Fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code>
2073: method for row 1, then fire it again for rows 5 through 7.</li>
2074:
2075: <li>Fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code>
2076: method for row 1, then fire it again for rows 5 and 6, and then
2077: fire the <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code>
2078: method for row 7 column B.</li>
2079:
2080: </ul><p>All three options are allowed, but the latter two are preferable
2081: to the former, as they minimise the amount of redundant information
2082: requested.</p>
2083:
2084: <p>In any case, the data model now looks like this:</p>
2085:
2086: <table><tr><td> </td><th> Row </th><th> Column A </th><th> Column B </th><th> Column C
2087: </th></tr><tr><th> Row 1 </th><td> Pending </td><td> Pending </td><td> Pending </td><td> -
2088: </td></tr><tr><th> Row 2 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> -
2089: </td></tr><tr><th> Row 3 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> -
2090: </td></tr><tr><th> Row 4 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> -
2091: </td></tr><tr><th> Row 5 </th><td> Pending </td><td> Pending </td><td> Pending </td><td> -
2092: </td></tr><tr><th> Row 6 </th><td> Pending </td><td> Pending </td><td> Pending </td><td> -
2093: </td></tr><tr><th> Row 7 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> -
2094: </td></tr><tr><th> Row 8 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> -
2095: </td></tr></table><p>Now consider the case where a third column, column C, is added
2096: to the data model. The user agent once again has several choices,
2097: including (but not limited to) the following:</p>
2098:
2099: <ul><li>Fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code>
2100: method for rows 1 through 8 again, this time listing just column
2101: C.</li>
2102:
2103: <li>Fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code>
2104: method for row 1, then fire it again for rows 5 and 6, and then
2105: fire the <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code>
2106: method for the other rows (in all three cases, listing just column
2107: C).</li>
2108:
2109: </ul><p>The two options here are as bad as each other; the former
2110: involves a lot of overlap, but the latter involves a lot of method
2111: calls. Unfortunately the user agent can't do the obvious thing,
2112: namely just to invoke the <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code> method for all the
2113: rows listing just column C, because it doesn't have the row
2114: information for all the rows yet (rows 1, 5 and 6 are still
2115: pending).</p>
2116:
2117: <p>In any case, the data model now looks like this:</p>
2118:
2119: <table><tr><td> </td><th> Row </th><th> Column A </th><th> Column B </th><th> Column C
2120: </th></tr><tr><th> Row 1 </th><td> Pending </td><td> Pending </td><td> Pending </td><td> Pending
2121: </td></tr><tr><th> Row 2 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> Pending
2122: </td></tr><tr><th> Row 3 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> Pending
2123: </td></tr><tr><th> Row 4 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> Pending
2124: </td></tr><tr><th> Row 5 </th><td> Pending </td><td> Pending </td><td> Pending </td><td> Pending
2125: </td></tr><tr><th> Row 6 </th><td> Pending </td><td> Pending </td><td> Pending </td><td> Pending
2126: </td></tr><tr><th> Row 7 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> Pending
2127: </td></tr><tr><th> Row 8 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> Pending
2128: </td></tr></table><p>If at this point the user scrolls around anywhere within this
2129: <code><a href="#datagrid">datagrid</a></code>, the user agent won't fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getRows()</a></code> and <code title="dom-listener-getCells"><a href="#dom-listener-getcells">getCells()</a></code> methods, because
2130: all of the rows and cells are covered.</p>
2131:
2132: <p>Now consider the case where the user agent receives row
2133: information, but no cell information, for rows 1, 5, and 6:</p>
2134:
2135: <table><tr><td> </td><th> Row </th><th> Column A </th><th> Column B </th><th> Column C
2136: </th></tr><tr><th> Row 1 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> Pending
2137: </td></tr><tr><th> Row 2 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> Pending
2138: </td></tr><tr><th> Row 3 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> Pending
2139: </td></tr><tr><th> Row 4 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> Pending
2140: </td></tr><tr><th> Row 5 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> Pending
2141: </td></tr><tr><th> Row 6 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> Pending
2142: </td></tr><tr><th> Row 7 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> Pending
2143: </td></tr><tr><th> Row 8 </th><td> Yes </td><td> Pending </td><td> Pending </td><td> Pending
2144: </td></tr></table><p>The user agent still won't fire any methods when the user
2145: scrolls, because the data is still covered. But if the script then
2146: calls the <code title="dom-datagrid-renotify"><a href="#dom-datagrid-renotify">renotify()</a></code>
2147: method, the "Pending" flags would get reset, and the model would
2148: now look like this:</p>
2149:
2150: <table><tr><td> </td><th> Row </th><th> Column A </th><th> Column B </th><th> Column C
2151: </th></tr><tr><th> Row 1 </th><td> Yes </td><td> - </td><td> - </td><td> -
2152: </td></tr><tr><th> Row 2 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> -
2153: </td></tr><tr><th> Row 3 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> -
2154: </td></tr><tr><th> Row 4 </th><td> Yes </td><td> Yes </td><td> Yes </td><td> -
2155: </td></tr><tr><th> Row 5 </th><td> Yes </td><td> - </td><td> - </td><td> -
2156: </td></tr><tr><th> Row 6 </th><td> Yes </td><td> - </td><td> - </td><td> -
2157: </td></tr><tr><th> Row 7 </th><td> Yes </td><td> - </td><td> - </td><td> -
2158: </td></tr><tr><th> Row 8 </th><td> Yes </td><td> - </td><td> - </td><td> -
2159: </td></tr></table><p>Now, assuming that all eight rows and all three columns are
2160: still visible, the user agent has the following choices (amongst
2161: others):</p>
2162:
2163: <ul><li>Fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getCells()</a></code>
2164: method for rows 1 through 8, listing all three columns.</li>
2165:
2166: <li>Fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getCells()</a></code>
2167: method for rows 1 and 5 through 8, listing all three columns, and
2168: then fire the method for rows 2 through 4, listing just column
2169: C.</li>
2170:
2171: <li>Fire the <code title="dom-listener-getRows"><a href="#dom-listener-getrows">getCells()</a></code>
2172: method for rows 1 and 5 through 8, listing just columns A abd B,
2173: and then fire the method for rows 1 through 8, listing just column
2174: C.</li>
2175:
2176: </ul><p>Here the latter two are preferable because they result in less
2177: overlap than the first.</p>
2178:
2179: </div>
2180:
2181: <hr><p>The <a href="browsers.html#task-source">task source</a> for tasks queued on behalf of a
2182: <code><a href="#datagrid">datagrid</a></code> is the <a href="browsers.html#dom-manipulation-task-source">DOM manipulation task
2183: source</a>.</p>
2184:
2185: </div><h5 id="listening-to-notifications-from-the-datagrid"><span class="secno">4.11.2.3 </span>Listening to notifications from the <code><a href="#datagrid">datagrid</a></code></h5><p><i>The conformance criteria in this section apply to any
2186: implementation of the <code><a href="#datagridlistener">DataGridListener</a></code> interface,
2187: including (and most commonly) the content author's
2188: implementation(s).</i></p><pre class="idl">// To be implemented by Web authors as a JS object
2189: [NoInterfaceObject] interface <dfn id="datagridlistener">DataGridListener</dfn> {
2190: void <a href="#dom-listener-initialize" title="dom-listener-initialize">initialize</a>(in <a href="#htmldatagridelement">HTMLDataGridElement</a> datagrid);
2191:
2192: void <a href="#dom-listener-getrows" title="dom-listener-getRows">getRows</a>(in unsigned long rowIndex, in unsigned long rowCount, in <a href="#rowid">RowID</a> parentRow, in unsigned long position, in <a href="#columnlist">ColumnList</a> columns);
2193: void <a href="#dom-listener-getcells" title="dom-listener-getCells">getCells</a>(in <a href="#rowidlist">RowIDList</a> rows, in <a href="#columnlist">ColumnList</a> columns);
2194: void <a href="#dom-listener-rowopened" title="dom-listener-rowOpened">rowOpened</a>(in <a href="#rowid">RowID</a> row, in boolean rowCountNeeded);
2195: void <a href="#dom-listener-rowclosed" title="dom-listener-rowClosed">rowClosed</a>(in <a href="#rowid">RowID</a> row);
2196:
2197: void <a href="#dom-listener-cellchanged" title="dom-listener-cellChanged">cellChanged</a>(in <a href="#rowid">RowID</a> row, in <a href="#column">Column</a> column, in any newValue, in any prevValue);
2198: <a href="#htmlmenuelement">HTMLMenuElement</a> <a href="#dom-listener-getrowmenu" title="dom-listener-getRowMenu">getRowMenu</a>(in <a href="#rowid">RowID</a> row);
2199: <!--vsDGDND
2200: boolean <span title="dom-listener-canDrop">canDrop</span>(in <span>RowID</span> row, in <span>RowID</span> position, data);
2201: boolean <span title="dom-listener-dropped">dropped</span>(in <span>RowID</span> row, in <span>RowID</span> position, data);
2202: --><!--v2DGPA
2203: void <span title="dom-listener-performAction">performAction</span>(in <span>RowID</span> row, in DOMString action);
2204: -->};</pre><p>The <code><a href="#datagridlistener">DataGridListener</a></code> interface, once implemented by
2205: an object in a script and hooked up to a <code><a href="#datagrid">datagrid</a></code> using
2206: the <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code> DOM
2207: attribute, receives notifications when the <code><a href="#datagrid">datagrid</a></code>
2208: needs information (such as which rows exist) for display.</p><p>The following methods may be usefully implemented:</p><dl><dt><dfn id="dom-listener-initialize" title="dom-listener-initialize"><code>initialize(<var title="">datagrid</var>)</code></dfn></dt>
2209:
2210: <dd>
2211:
2212: <p>Called by the <code><a href="#datagrid">datagrid</a></code> element (the one given by
2213: the <var title="">datagrid</var> argument) when the <code title="dom-datagrid-listener"><a href="#dom-datagrid-listener">listener</a></code> attribute is
2214: set.</p>
2215:
2216: </dd>
2217:
2218: <dt><dfn id="dom-listener-getrows" 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>
2219:
2220: <dd>
2221:
2222: <p>Called by the <code><a href="#datagrid">datagrid</a></code> element when the user agent
2223: finds itself needing to render rows for which it is lacking
2224: information.</p>
2225:
2226: <p>The <var title="">rowIndex</var> argument gives the flattened
2227: index of the first row for which it needs information, ignoring
2228: the tree structure of the <code><a href="#datagrid">datagrid</a></code> model, where zero
2229: is the first row of the entire tree.</p>
2230:
2231: <p>The <var title="">rowCount</var> argument gives the number of
2232: rows for which the user agent would like information.</p>
2233:
2234: <p>The <var title="">parentRow</var> argument gives the
2235: <code><a href="#rowid">RowID</a></code> object identifying the nearest ancestor of the
2236: first row that the user agent is aware of. After the sort order
2237: has changed, this will typically be the root of the tree
2238: (identified by a <code><a href="#rowid">RowID</a></code> object consisting of an empty
2239: array).
2240:
2241: </p><p>The <var title="">columns</var> argument gives the columns for
2242: which the user agent is lacking information, as an array of column
2243: identifiers (as passed to <code title="dom-datagrid-addColumn"><a href="#dom-datagrid-addcolumn">addColumn()</a></code>).</p>
2244:
2245: </dd>
2246:
2247: <dt><dfn id="dom-listener-getcells" title="dom-listener-getCells"><code>getCells(<var title="">rows</var>, <var title="">columns</var>)</code></dfn></dt>
2248:
2249: <dd>
2250:
2251: <p>Called by the <code><a href="#datagrid">datagrid</a></code> element when the user agent
2252: finds itself needing to render cells for which it is lacking
2253: information in rows that it does know about.</p>
2254:
2255: <p>The <var title="">rows</var> argument gives an array of
2256: <code><a href="#rowid">RowID</a></code> objects identifying the various rows for which
2257: the user agent is lacking information.</p>
2258:
2259: <p>The <var title="">columns</var> argument gives the columns for
2260: which the user agent is lacking information, as an array of column
2261: identifiers (as passed to <code title="dom-datagrid-addColumn"><a href="#dom-datagrid-addcolumn">addColumn()</a></code>).</p>
2262:
2263: </dd>
2264:
2265: <dt><dfn id="dom-listener-rowopened" title="dom-listener-rowOpened"><code>rowOpened(<var title="">row</var>, <var title="">rowCountNeeded</var>)</code></dfn></dt>
2266:
2267: <dd>
2268:
2269: <p>Called by the <code><a href="#datagrid">datagrid</a></code> element when the user has
2270: opened a row.</p>
2271:
2272: <p>The <var title="">row</var> argument gives an
2273: <code><a href="#rowid">RowID</a></code> object identifying the row that was opened.</p>
2274:
2275: <p>If the user agent also knows how many children that row has,
2276: then the <var title="">rowCountNeeded</var> argument will be
2277: false. Otherwise, the argument will be true, and the row will
2278: remain closed until the <code title="dom-datagrid-setRows"><a href="#dom-datagrid-setrows">setRows()</a></code> method is called
2279: with an accurate row count.</p>
2280:
2281: </dd>
2282:
2283: <dt><dfn id="dom-listener-rowclosed" title="dom-listener-rowClosed"><code>rowClosed(<var title="">row</var>)</code></dfn></dt>
2284:
2285: <dd>
2286:
2287: <p>Called by the <code><a href="#datagrid">datagrid</a></code> element when the user has
2288: opened a row.</p>
2289:
2290: <p>The <var title="">row</var> argument gives an
2291: <code><a href="#rowid">RowID</a></code> object identifying the row that was closed.</p>
2292:
2293: </dd>
2294:
2295: <dt><dfn id="dom-listener-cellchanged" 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>
2296:
2297: <dd>
2298:
2299: <p>Called by the <code><a href="#datagrid">datagrid</a></code> element when the user has
2300: edited a cell or checked a check box in a cell.</p>
2301:
2302: <p>The <var title="">row</var> argument gives an
2303: <code><a href="#rowid">RowID</a></code> object identifying the row of the cell, and the
2304: <var title="">column</var> argument gives the identifier of the
2305: cell's column.</p>
2306:
2307: <p>The <var title="">newValue</var> argument gives the new value,
2308: and the <var title="">prevValue</var> argument gives the previous
2309: value.</p>
2310:
2311: </dd>
2312:
2313: <dt><dfn id="dom-listener-getrowmenu" title="dom-listener-getRowMenu"><code>getRowMenu(<var title="">row</var>)</code></dfn></dt>
2314:
2315: <dd>Must return an <code><a href="#htmlmenuelement">HTMLMenuElement</a></code> object that is to
2316: be used as a context menu for row <var title="">row</var>, or null
2317: if there is no particular context menu. May be omitted if none of
2318: the rows have a special context menu. As this method is called
2319: immediately before showing the menu in question, no precautions
2320: need to be taken if the return value of this method changes.</dd>
2321:
2322: <!--v2DGDND, v2DFPA-->
2323:
2324: </dl><div class="impl">
2325:
2326: <p>Objects that implement the <code><a href="#datagridlistener">DataGridListener</a></code>
2327: interface may omit any or all of the methods. When a method is
2328: omitted, a user agent intending to call that method must instead
2329: skip the method call, and must assume that the method's return value
2330: is null.</p>
2331:
2332: </div><!-- v2DGS: <datagrid> selection (search for the bits marked "..." to see what needs filling in, at a minimum)
2333:
2334: <h5>The selection</h5>
2335:
2336: <pre class="idl">interface <dfn>DataGridSelection</dfn> {
2337: readonly attribute unsigned long <span title="dom-DataGridSelection-length">length</span>;
2338: [IndexGetter] <span>RowID</span> <span title="dom-DataGridSelection-item">item</span>(in unsigned long index);
2339: boolean <span title="dom-DataGridSelection-isSelected">isSelected</span>(in <span>RowID</span> row);
2340: void <span title="dom-DataGridSelection-setSelected">setSelected</span>(in <span>RowID</span> row, in boolean selected);
2341: void <span title="dom-DataGridSelection-selectAll">selectAll</span>();
2342: void <span title="dom-DataGridSelection-clear">clear</span>();
2343: };</pre>
2344:
2345: <dl class="domintro">
2346:
2347: ...
2348:
2349: </dl>
2350:
2351: <div class="impl">
2352:
2353: <p>Each <code>datagrid</code> element must keep track of which rows
2354: are currently selected. Initially, no rows are selected. This can be
2355: changed using the methods described in this section.</p>
2356:
2357: <p>The selection of a <code>datagrid</code> is represented by its
2358: <dfn title="dom-datagrid-selection"><code>selection</code></dfn> DOM
2359: attribute, which must be a <code>DataGridSelection</code> object.</p>
2360:
2361: <p><code>DataGridSelection</code> objects represent the rows in the
2362: selection. In the selection the rows must be ordered in their
2363: natural order (and not, e.g., the display order). A row with an
2364: ancestor that is closed cannot be selected.</p>
2365:
2366: <p>The <dfn
2367: title="dom-DataGridSelection-length"><code>length</code></dfn>
2368: attribute must return the number of rows currently present in the
2369: selection. This is the <var
2370: title="dom-DataGridSelection-length">length</var>.</p>
2371:
2372: <p>The object's <span>indices of the supported indexed
2373: properties</span> are the numbers in the range zero to <span title=""><var
2374: title="dom-DataGridSelection-length">length</var>-1</span>, unless
2375: the <var title="dom-DataGridSelection-length">length</var> is zero,
2376: in which case there are no <span>supported indexed
2377: properties</span>.</p>
2378:
2379: <p>The <dfn title="dom-DataGridSelection-item"><code>item(<var
2380: title="">index</var>)</code></dfn> method must return a
2381: <code>RowID</code> object identifying the <var
2382: title="">index</var>th row in the selection. If the argument is out
2383: of range (less than zero or greater than the number of selected rows
2384: minus one), then it must raise an <code>INDEX_SIZE_ERR</code>
2385: exception. <a href="#references">[DOM3CORE]</a></p>
2386:
2387: <p>The <dfn
2388: title="dom-DataGridSelection-isSelected"><code>isSelected()</code></dfn>
2389: method must return the selected state of the row specified by its
2390: argument. If the specified row is in the <span>natural order sparse
2391: data tree</span> and is selected, the method must return true,
2392: otherwise it must return false.</p>
2393:
2394: <p>The <dfn
2395: title="dom-DataGridSelection-setSelected"><code>setSelected()</code></dfn>
2396: method takes two arguments, <var title="">row</var> and <var
2397: title="">selected</var>. When invoked, it must set the selection
2398: state of row <var title="">row</var> to selected if <var
2399: title="">selected</var> is true, and unselected if it is false. If
2400: <var title="">row</var> does not specify a row in the <span>natural
2401: order sparse data tree</span> ...
2402:
2403: <p>The <dfn
2404: title="dom-DataGridSelection-selectAll"><code>selectAll()</code></dfn>
2405: method must ...
2406:
2407: <p>The <dfn
2408: title="dom-DataGridSelection-clear"><code>clear()</code></dfn>
2409: method must mark all the rows in the <code>datagrid</code> as not
2410: selected. After a call to <code
2411: title="dom-DataGridSelection-clear">clear()</code>, the <code
2412: title="dom-DataGridSelection-length">length</code> attribute will
2413: return zero.</p>
2414:
2415: <p>If the <code>datagrid</code> element has a <code
2416: title="attr-datagrid-multiple">multiple</code> attribute, then the
2417: user agent should allow the user to select any number of rows (zero
2418: or more). If the attribute is not present, then the user agent
2419: should allow the user to select a row, and must not allow the user
2420: to select more than a single row at a time; selecting another one
2421: must unselect all the other rows.</p>
2422:
2423: <p class="note">This only applies to the user. Scripts can select
2424: multiple rows even when the <code
2425: title="attr-datagrid-multiple">multiple</code> attribute is
2426: absent.</p>
2427:
2428: ...event on selection change?...
2429:
2430: </div>
2431:
2432: <p class="note">The <code>DataGridSelection</code> interface has no
2433: relation to the <code>Selection</code> interface.</p>
2434:
2435: --><!--vsDGDND
2436: <h5>Drag and drop in <code>datagrid</code>s</h5>
2437:
2438: <p><i>This section only applies to interactive user agents.</i></p>
2439:
2440: ...define drag and drop in datagrids; selectiondraggable...
2441: --><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>
2442: <dd><a href="dom.html#metadata-content-0">Metadata content</a>.</dd>
2443: <dd><a href="dom.html#flow-content-0">Flow content</a>.</dd>
2444: <dd><a href="dom.html#phrasing-content-0">Phrasing content</a>.</dd>
2445: <dt>Contexts in which this element may be used:</dt>
2446: <dd>Where <a href="dom.html#metadata-content-0">metadata content</a> is expected.</dd>
2447: <dd>Where <a href="dom.html#phrasing-content-0">phrasing content</a> is expected.</dd>
2448: <dt>Content model:</dt>
2449: <dd>Empty.</dd>
2450: <dt>Content attributes:</dt>
2451: <dd><a href="dom.html#global-attributes">Global attributes</a></dd>
2452: <dd><code title="attr-command-type"><a href="#attr-command-type">type</a></code></dd>
2453: <dd><code title="attr-command-label"><a href="#attr-command-label">label</a></code></dd>
2454: <dd><code title="attr-command-icon"><a href="#attr-command-icon">icon</a></code></dd>
2455: <dd><code title="attr-command-disabled"><a href="#attr-command-disabled">disabled</a></code></dd>
2456: <dd><code title="attr-command-checked"><a href="#attr-command-checked">checked</a></code></dd>
2457: <dd><code title="attr-command-radiogroup"><a href="#attr-command-radiogroup">radiogroup</a></code></dd>
2458: <!--<dd><code title="attr-command-default">default</code></dd>-->
2459: <dd>Also, the <code title="attr-command-title"><a href="#attr-command-title">title</a></code> attribute has special semantics on this element.</dd>
2460: <dt>DOM interface:</dt>
2461: <dd>
2462: <pre class="idl">interface <dfn id="htmlcommandelement">HTMLCommandElement</dfn> : <a href="dom.html#htmlelement">HTMLElement</a> {
2463: attribute DOMString <a href="#dom-command-type" title="dom-command-type">type</a>;
2464: attribute DOMString <a href="#dom-command-label" title="dom-command-label">label</a>;
2465: attribute DOMString <a href="#dom-command-icon" title="dom-command-icon">icon</a>;
2466: attribute boolean <a href="#dom-command-disabled" title="dom-command-disabled">disabled</a>;
2467: attribute boolean <a href="#dom-command-checked" title="dom-command-checked">checked</a>;
2468: attribute DOMString <a href="#dom-command-radiogroup" title="dom-command-radiogroup">radiogroup</a>;<!--
2469: attribute boolean <span title="dom-command-default">default</span>;-->
2470: };</pre>
2471: </dd>
2472: </dl><p>The <code><a href="#the-command">command</a></code> element represents a command that the user
2473: can invoke.</p><p>The <dfn id="attr-command-type" title="attr-command-type"><code>type</code></dfn>
2474: attribute indicates the kind of command: either a normal command
2475: with an associated action, or a state or option that can be toggled,
2476: or a selection of one item from a list of items.</p><p>The attribute is an <a href="infrastructure.html#enumerated-attribute">enumerated attribute</a> with three
2477: keywords and states. The keyword "<dfn id="attr-command-type-keyword-command" title="attr-command-type-keyword-command"><code>command</code></dfn>"
2478: maps to the <a href="#attr-command-type-state-command" title="attr-command-type-state-command">Command</a> state, the
2479: <dfn id="attr-command-type-keyword-checkbox" title="attr-command-type-keyword-checkbox"><code>checkbox</code></dfn>"
2480: maps to the <a href="#attr-command-type-state-checkbox" title="attr-command-type-state-checkbox">Checkbox</a>, and the
2481: "<dfn id="attr-command-type-keyword-radio" title="attr-command-type-keyword-radio"><code>radio</code></dfn>"
2482: keyword maps to the <a href="#attr-command-type-state-radio" title="attr-command-type-state-radio">Radio</a> state. The
2483: <i>missing value default</i> is the <a href="#attr-command-type-state-command" title="attr-command-type-state-command">Command</a> state.</p><dl><dt>The <dfn id="attr-command-type-state-command" title="attr-command-type-state-command">Command</dfn> state</dt>
2484:
2485: <dd><p>The element <a href="the-xhtml-syntax.html#represents">represents</a> a normal command with an associated action.</p></dd>
2486:
2487: <dt>The <dfn id="attr-command-type-state-checkbox" title="attr-command-type-state-checkbox">Checkbox</dfn> state</dt>
2488:
2489: <dd><p>The element <a href="the-xhtml-syntax.html#represents">represents</a> a state or option that can be toggled.</p></dd>
2490:
2491: <dt>The <dfn id="attr-command-type-state-radio" title="attr-command-type-state-radio">Radio</dfn> state</dt>
2492:
2493: <dd><p>The element <a href="the-xhtml-syntax.html#represents">represents</a> a selection of one item from a list of items.</p></dd>
2494:
2495: </dl><p>The <dfn id="attr-command-label" title="attr-command-label"><code>label</code></dfn>
2496: attribute gives the name of the command, as shown to the user.</p><p>The <dfn id="attr-command-title" title="attr-command-title"><code>title</code></dfn>
2497: attribute gives a hint describing the command, which might be shown
2498: to the user to help him.</p><p>The <dfn id="attr-command-icon" title="attr-command-icon"><code>icon</code></dfn>
2499: attribute gives a picture that represents the command. If the
2500: attribute is specified, the attribute's value must contain a
2501: <a href="infrastructure.html#valid-url">valid URL</a>. <span class="impl">To obtain the
2502: <a href="infrastructure.html#absolute-url">absolute URL</a> of the icon, the attribute's value must be
2503: <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolved</a> relative to the
2504: element.</span></p><!-- this is affected by the base URL being
2505: changed, so users of this should cache the image once they've
2506: fetched it once, at least until the relative url changes again --><p>The <dfn id="attr-command-disabled" title="attr-command-disabled"><code>disabled</code></dfn> attribute
2507: is a <a href="infrastructure.html#boolean-attribute">boolean attribute</a> that, if present, indicates that
2508: the command is not available in the current state.</p><p class="note">The distinction between <code title="attr-command-disabled"><a href="#attr-command-disabled">disabled</a></code> and <code title="attr-hidden"><a href="editing.html#the-hidden-attribute">hidden</a></code> is subtle. A command would be
2509: disabled if, in the same context, it could be enabled if only
2510: certain aspects of the situation were changed. A command would be
2511: marked as hidden if, in that situation, the command will never be
2512: enabled. For example, in the context menu for a water faucet, the
2513: command "open" might be disabled if the faucet is already open, but
2514: the command "eat" would be marked hidden since the faucet could
2515: never be eaten.</p><p>The <dfn id="attr-command-checked" title="attr-command-checked"><code>checked</code></dfn>
2516: attribute is a <a href="infrastructure.html#boolean-attribute">boolean attribute</a> that, if present,
2517: indicates that the command is selected. The attribute must be
2518: omitted unless the <code title="attr-command-type"><a href="#attr-command-type">type</a></code>
2519: attribute is in either the <a href="#attr-command-type-state-checkbox" title="attr-command-type-state-checkbox">Checkbox</a> state or
2520: the <a href="#attr-command-type-state-radio" title="attr-command-type-state-radio">Radio</a>
2521: state.</p><p>The <dfn id="attr-command-radiogroup" title="attr-command-radiogroup"><code>radiogroup</code></dfn>
2522: attribute gives the name of the group of commands that will be
2523: toggled when the command itself is toggled, for commands whose <code title="attr-command-type"><a href="#attr-command-type">type</a></code> attribute has the value "<code title="">radio</code>". The scope of the name is the child list of
2524: the parent element. The attribute must be omitted unless the <code title="attr-command-type"><a href="#attr-command-type">type</a></code> attribute is in the <a href="#attr-command-type-state-radio" title="attr-command-type-state-radio">Radio</a> state.</p><!--
2525: <p>If the <code>command</code> element is used when <span
2526: title="menu generation">generating</span> a <span>context
2527: menu</span>, then the <dfn
2528: title="attr-command-default"><code>default</code></dfn> attribute
2529: indicates, if present, that the command is the one that would have
2530: been invoked if the user had directly activated the menu's subject
2531: instead of using its context menu. The <code
2532: title="attr-command-default">default</code> attribute is a
2533: <span>boolean attribute</span>. The attribute must be omitted unless
2534: the <code title="attr-command-type">type</code> attribute is in the
2535: <span title="attr-command-type-state-command">Command</span>
2536: state.</p>
2537:
2538: <div class="example">
2539:
2540: ...an example that shows an element that, if double-clicked,
2541: invokes an action, but that also has a context menu, showing the
2542: various <code>command</code> attributes off, and that has a default
2543: command...
2544:
2545: </div>
2546: --><div class="impl">
2547:
2548: <p>The <dfn id="dom-command-type" title="dom-command-type"><code>type</code></dfn>, <dfn id="dom-command-label" title="dom-command-label"><code>label</code></dfn>, <dfn id="dom-command-icon" title="dom-command-icon"><code>icon</code></dfn>, <dfn id="dom-command-disabled" title="dom-command-disabled"><code>disabled</code></dfn>, <dfn id="dom-command-checked" title="dom-command-checked"><code>checked</code></dfn>, and <dfn id="dom-command-radiogroup" title="dom-command-radiogroup"><code>radiogroup</code></dfn><!--,
2549: and <dfn title="dom-command-default"><code>default</code></dfn>-->
2550: DOM attributes must <a href="infrastructure.html#reflect">reflect</a> the respective content
2551: attributes of the same name.</p>
2552:
2553: <p>The element's <a href="dom.html#activation-behavior">activation behavior</a> depends on the
2554: value of the <code title="attr-command-type"><a href="#attr-command-type">type</a></code> attribute
2555: of the element, as follows:</p>
2556:
2557: <dl class="switch"><dt>If the <code title="attr-command-type"><a href="#attr-command-type">type</a></code> attribute is
2558: in the <a href="#attr-command-type-state-checkbox" title="attr-command-type-state-checkbox">Checkbox</a> state</dt>
2559:
2560: <dd><p>If the element has a <code title="attr-command-checked"><a href="#attr-command-checked">checked</a></code> attribute, the UA must
2561: remove that attribute. Otherwise, the UA must add a <code title="attr-command-checked"><a href="#attr-command-checked">checked</a></code> attribute, with the
2562: literal value <code title="">checked</code>. The UA must then
2563: <a href="browsers.html#fire-a-click-event">fire a <code title="event-click">click</code> event</a> at the
2564: element.</p></dd>
2565:
2566:
2567: <dt>If the <code title="attr-command-type"><a href="#attr-command-type">type</a></code> attribute is
2568: in the <a href="#attr-command-type-state-radio" title="attr-command-type-state-radio">Radio</a> state</dt>
2569:
2570: <dd><p>If the element has a parent, then the UA must walk the list
2571: of child nodes of that parent element, and for each node that is a
2572: <code><a href="#the-command">command</a></code> element, if that element has a <code title="attr-command-radiogroup"><a href="#attr-command-radiogroup">radiogroup</a></code> attribute whose
2573: value exactly matches the current element's (treating missing <code title="attr-command-radiogroup"><a href="#attr-command-radiogroup">radiogroup</a></code> attributes as if
2574: they were the empty string), and has a <code title="attr-command-checked"><a href="#attr-command-checked">checked</a></code> attribute, must remove
2575: that attribute.</p>
2576:
2577: <p>Then, the element's <code title="attr-command-checked"><a href="#attr-command-checked">checked</a></code> attribute attribute
2578: must be set to the literal value <code title="">checked</code> and
2579: the user agent must <a href="browsers.html#fire-a-click-event">fire a <code title="event-click">click</code>
2580: event</a> at the element.</p></dd>
2581:
2582:
2583: <dt>Otherwise</dt>
2584:
2585: <dd><p>The element has no <a href="dom.html#activation-behavior">activation behavior</a>.</p></dd>
2586:
2587: </dl><p class="note">Firing a synthetic <code title="event-click">click</code> event at the element does not cause
2588: any of the actions described above to happen.</p>
2589:
2590: <!-- v2COMMAND: the command="" attribute to make a <command> element
2591: reflect the state of another command, so that the script can update
2592: one place in the page and have context menus, toolbars, shortcuts,
2593: etc, automatically update. Once we add this, expose the Triggers
2594: facet again. -->
2595:
2596: </div><p class="note"><code><a href="#the-command">command</a></code> elements are not rendered
2597: unless they <a href="#menus" title="menu">form part of a menu</a>.</p><h4 id="the-bb-element"><span class="secno">4.11.4 </span>The <dfn><code>bb</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
2598: <dd><a href="dom.html#flow-content-0">Flow content</a>.</dd>
2599: <dd><a href="dom.html#phrasing-content-0">Phrasing content</a>.</dd>
2600: <dd><a href="dom.html#interactive-content-0">Interactive content</a>.</dd>
2601: <dt>Contexts in which this element may be used:</dt>
2602: <dd>Where <a href="dom.html#phrasing-content-0">phrasing content</a> is expected.</dd>
2603: <dt>Content model:</dt>
2604: <dd><a href="dom.html#phrasing-content-0">Phrasing content</a>, but there must be no <a href="dom.html#interactive-content-0">interactive content</a> descendant.</dd>
2605: <dt>Content attributes:</dt>
2606: <dd><a href="dom.html#global-attributes">Global attributes</a></dd>
2607: <dd><code title="attr-command-type"><a href="#attr-command-type">type</a></code></dd>
2608: <dt>DOM interface:</dt>
2609: <dd>
2610: <pre class="idl">interface <dfn id="htmlbrowserbuttonelement">HTMLBrowserButtonElement</dfn> : <a href="dom.html#htmlelement">HTMLElement</a> {
2611: attribute DOMString <a href="#dom-bb-type" title="dom-bb-type">type</a>;
2612: readonly attribute boolean <a href="#dom-bb-supported" title="dom-bb-supported">supported</a>;
2613: readonly attribute boolean <a href="#dom-bb-disabled" title="dom-bb-disabled">disabled</a>;
2614: };</pre>
2615: </dd>
2616: </dl><p>The <code><a href="#the-bb-element">bb</a></code> element represents a user agent command that
2617: the user can invoke.</p><p>The <dfn id="attr-bb-type" title="attr-bb-type"><code>type</code></dfn> attribute
2618: indicates the kind of command. The <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute is an <a href="infrastructure.html#enumerated-attribute">enumerated
2619: attribute</a>. The following table lists the keywords and states
2620: for the attribute — the keywords in the left column map to the
2621: states listed in the cell in the second column on the same row as
2622: the keyword.</p><table><thead><tr><th> Keyword </th><th> State
2623: </th></tr></thead><tbody><tr><td> <dfn id="attr-bb-type-makeapp" title="attr-bb-type-makeapp"><code>makeapp</code></dfn>
2624: </td><td> <i title="attr-bb-type-makeapp-state"><a href="#the-make-application-state">make application</a></i>
2625: </td></tr></tbody></table><p>The <i>missing value default</i> state is the <i title="attr-bb-type-null-state"><a href="#attr-bb-type-null-state">null</a></i> state.</p><p>Each state has an <i>action</i> and a <i>relevance</i>, defined
2626: in the following sections.</p><p>When the attribute is in the <dfn id="attr-bb-type-null-state" title="attr-bb-type-null-state"><i>null</i></dfn> state, the
2627: <i>action</i> is to not do anything, and the <i>relevance</i> is
2628: unconditionally false.</p><div class="impl">
2629:
2630: <p>A <code><a href="#the-bb-element">bb</a></code> element whose <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute is in a state whose
2631: <i>relevance</i> is true must be enabled. Conversely, a
2632: <code><a href="#the-bb-element">bb</a></code> element whose <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code>
2633: attribute is in a state whose <i>relevance</i> is false must be
2634: disabled.</p>
2635:
2636: <p class="note">If a <code><a href="#the-bb-element">bb</a></code> element is enabled, it will
2637: match the <code title="selector-enabled"><a href="#selector-enabled">:enabled</a></code>
2638: pseudo-class; otherwise, it will match the <code title="selector-disabled"><a href="#selector-disabled">:disabled</a></code> pseudo-class.</p>
2639:
2640: <p>User agents should allow users to invoke <code><a href="#the-bb-element">bb</a></code> elements
2641: when they are enabled. When a user invokes a <code><a href="#the-bb-element">bb</a></code>
2642: element, its <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's
2643: state's <i>action</i> must be invoked.</p>
2644:
2645: </div><p>When the element has no descendant element children and has no
2646: descendant <a href="infrastructure.html#text-node">text node</a> children of non-zero length, the
2647: element <a href="the-xhtml-syntax.html#represents">represents</a> a browser button with a
2648: user-agent-defined icon or text representing the <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's state's <i>action</i>
2649: and <i>relevance</i> (enabled vs disabled). Otherwise, the element
2650: <a href="the-xhtml-syntax.html#represents">represents</a> its children.</p><dl class="domintro"><dt><var title="">bb</var> . <code title="dom-bb-supported"><a href="#dom-bb-supported">supported</a></code></dt>
2651:
2652: <dd>
2653:
2654: <p>Returns true if the value in the <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute is a value that the
2655: user agent supports. Otherwise, returns false.</p>
2656:
2657: </dd>
2658:
2659: <dt><var title="">bb</var> . <code title="dom-bb-disabled"><a href="#dom-bb-disabled">disabled</a></code></dt>
2660:
2661: <dd>
2662:
2663: <p>Returns false if the user can invoke the element's
2664: <i>action</i> (i.e. if the element's <i>relevance</i> is
2665: true). Otherwise, returns true.</p>
2666:
2667: </dd>
2668:
2669: </dl><div class="impl">
2670:
2671: <p>The <dfn id="dom-bb-type" title="dom-bb-type"><code>type</code></dfn> DOM
2672: attribute must <a href="infrastructure.html#reflect">reflect</a> the content attribute of the
2673: same name.</p>
2674:
2675: <p>The <dfn id="dom-bb-supported" title="dom-bb-supported"><code>supported</code></dfn>
2676: DOM attribute must return true if the <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute is in a state other than
2677: the <i title="attr-bb-type-null-state"><a href="#attr-bb-type-null-state">null</a></i> state and the user
2678: agent supports that state's <i>action</i> (i.e. when the attribute's
2679: value is one that the user agent recognizes and supports), and false
2680: otherwise.</p>
2681:
2682: <p>The <dfn id="dom-bb-disabled" title="dom-bb-disabled"><code>disabled</code></dfn> DOM
2683: attribute must return true if the element is disabled, and false
2684: otherwise (i.e. it returns the opposite of the <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's state's
2685: <i>relevance</i>).</p>
2686:
2687: </div><h5 id="browser-button-types"><span class="secno">4.11.4.1 </span>Browser button types</h5><h6 id="the-make-application-state"><span class="secno">4.11.4.1.1 </span>The <dfn title="attr-bb-type-makeapp-state"><i>make application</i></dfn> state</h6><p>Some user agents support making sites accessible as independent
2688: applications, as if they were not Web sites at all. The <i title="attr-bb-type-makeapp-state"><a href="#the-make-application-state">make application</a></i> state exists
2689: to allow Web pages to offer themselves to the user as targets for
2690: this mode of operation.</p><p>The <i>action</i> of the <i title="attr-bb-type-makeapp-state"><a href="#the-make-application-state">make application</a></i> state is to
2691: confirm the user's intent to use the current site in a standalone
2692: fashion, and, provided the user's intent is confirmed, offer the
2693: user a way to make the resource identified by <a href="dom.html#the-document-s-address">the document's
2694: address</a> available in such a fashion.</p><div class="impl">
2695:
2696: <p class="warning">The confirmation is needed because it is
2697: relatively easy to trick users into activating buttons. The
2698: confirmation could, e.g. take the form of asking the user where to
2699: "save" the application, or non-modal information panel that is
2700: clearly from the user agent and gives the user the opportunity to
2701: drag an icon to their system's application launcher.</p>
2702:
2703: </div><p>The <i>relevance</i> of the <i title="attr-bb-type-makeapp-state"><a href="#the-make-application-state">make application</a></i> state is
2704: false if the user agent is already handling the site in such a
2705: fashion, or if the user agent doesn't support making the site
2706: available in that fashion, and true otherwise.</p><div class="example">
2707:
2708: <p>In the following example, a few links are listed on an
2709: application's page, to allow the user perform certain actions,
2710: including making the application standalone:</p>
2711:
2712: <pre><menu>
2713: <li><a href="settings.html" onclick="panels.show('settings')">Settings</a>
2714: <li><bb type="makeapp">Download standalone application</bb>
2715: <li><a href="help.html" onclick="panels.show('help')">Help</a>
2716: <li><a href="logout.html" onclick="panels.show('logout')">Sign out</a>
2717: </menu></pre>
2718:
2719: <p>With the following stylesheet, it could be make to look like a
2720: single line of text with vertical bars separating the options, with
2721: the "make app" option disappearing when it's not supported or
2722: relevant:</p>
2723:
2724: <pre>menu li { display: none; }
2725: menu li:enabled { display: inline; }
2726: menu li:not(:first-child)::before { content: ' | '; }</pre>
2727:
2728: <p>This could look like this:</p>
2729:
2730: <p><img alt='"Settings | Download standalone application | Help | Sign out"' src="images/sample-makeapp.png"></p>
2731:
2732: </div><div class="example">
2733:
2734: <p>The following example shows another way to do the same thing as
2735: the previous one, this time not relying on CSS support to hide the
2736: "make app" link if it doesn't apply:</p>
2737:
2738: <pre><menu>
2739: <a href="settings.html" onclick="panels.show('settings')">Settings</a> |
2740: <bb type="makeapp" id="makeapp"> </bb>
2741: <a href="help.html" onclick="panels.show('help')">Help</a> |
2742: <a href="logout.html" onclick="panels.show('logout')">Sign out</a>
2743: </menu>
2744: <script>
2745: var bb = document.getElementById('makeapp');
2746: if (bb.supported && bb.enabled) {
2747: bb.parentNode.nextSibling.textContent = ' | ';
2748: bb.textContent = 'Download standalone application';
2749: } else {
2750: bb.parentNode.removeChild(bb);
2751: }
2752: </script></pre>
2753:
2754: </div><h4 id="menus"><span class="secno">4.11.5 </span>The <dfn><code>menu</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
2755: <dd><a href="dom.html#flow-content-0">Flow content</a>.</dd>
2756: <dd>If the element's <code title="attr-menu-type"><a href="#attr-menu-type">type</a></code> attribute is in the <a href="#tool-bar-state" title="tool bar state">tool bar</a> state: <a href="dom.html#interactive-content-0">Interactive content</a>.</dd>
2757: <dt>Contexts in which this element may be used:</dt>
2758: <dd>Where <a href="dom.html#flow-content-0">flow content</a> is expected.</dd>
2759: <dt>Content model:</dt>
2760: <dd>Either: Zero or more <code><a href="semantics.html#the-li-element">li</a></code> elements.</dd>
2761: <dd>Or: <a href="dom.html#flow-content-0">Flow content</a>.</dd>
2762: <dt>Content attributes:</dt>
2763: <dd><a href="dom.html#global-attributes">Global attributes</a></dd>
2764: <dd><code title="attr-menu-type"><a href="#attr-menu-type">type</a></code></dd>
2765: <dd><code title="attr-menu-label"><a href="#attr-menu-label">label</a></code></dd>
2766: <dt>DOM interface:</dt>
2767: <dd>
2768: <pre class="idl">interface <dfn id="htmlmenuelement">HTMLMenuElement</dfn> : <a href="dom.html#htmlelement">HTMLElement</a> {
2769: attribute DOMString <a href="#dom-menu-type" title="dom-menu-type">type</a>;
2770: attribute DOMString <a href="#dom-menu-label" title="dom-menu-label">label</a>;
2771: };</pre>
2772: </dd></dl><p>The <code><a href="#menus">menu</a></code> element represents a list of commands.</p><!-- v2 idea: <menu> should get an icon, like <command> --><p>The <dfn id="attr-menu-type" title="attr-menu-type"><code>type</code></dfn> attribute
2773: is an <a href="infrastructure.html#enumerated-attribute">enumerated attribute</a> indicating the kind of menu
2774: being declared. The attribute has three states. The <code title="attr-menu-type-context">context</code> keyword maps to the
2775: <dfn id="context-menu-state" title="context menu state">context menu</dfn> state, in which
2776: the element is declaring a context menu. The <code title="attr-menu-type-toolbar">toolbar</code> keyword maps to the
2777: <dfn id="tool-bar-state" title="tool bar state">tool bar</dfn> state, in which the
2778: element is declaring a tool bar. The attribute may also be
2779: omitted. The <i>missing value default</i> is the <dfn id="list-state" title="list
2780: state">list</dfn> state, which indicates that the element is merely
2781: a list of commands that is neither declaring a context menu nor
2782: defining a tool bar.</p><p>If a <code><a href="#menus">menu</a></code> element's <code title="attr-menu-type"><a href="#attr-menu-type">type</a></code> attribute is in the <a href="#context-menu-state" title="context menu state">context menu</a> state, then the
2783: element <a href="the-xhtml-syntax.html#represents">represents</a> the commands of a context menu, and
2784: the user can only interact with the commands if that context menu is
2785: activated.</p><p>If a <code><a href="#menus">menu</a></code> element's <code title="attr-menu-type"><a href="#attr-menu-type">type</a></code> attribute is in the <a href="#tool-bar-state" title="tool bar state">tool bar</a> state, then the element
2786: <a href="the-xhtml-syntax.html#represents">represents</a> a list of active commands that the user can
2787: immediately interact with.</p><p>If a <code><a href="#menus">menu</a></code> element's <code title="attr-menu-type"><a href="#attr-menu-type">type</a></code> attribute is in the <a href="#list-state" title="list state">list</a> state, then the element either
2788: <a href="the-xhtml-syntax.html#represents">represents</a> an unordered list of items (each represented
2789: by an <code><a href="semantics.html#the-li-element">li</a></code> element), each of which represents a command
2790: that the user can perform or activate, or, if the element has no
2791: <code><a href="semantics.html#the-li-element">li</a></code> element children, <a href="dom.html#flow-content-0">flow content</a>
2792: describing available commands.</p><p>The <dfn id="attr-menu-label" title="attr-menu-label"><code>label</code></dfn>
2793: attribute gives the label of the menu. It is used by user agents to
2794: display nested menus in the UI. For example, a context menu
2795: containing another menu would use the nested menu's <code title="attr-menu-label"><a href="#attr-menu-label">label</a></code> attribute for the submenu's
2796: menu label.</p><div class="impl">
2797:
2798: <p>The <dfn id="dom-menu-type" title="dom-menu-type"><code>type</code></dfn> and <dfn id="dom-menu-label" title="dom-menu-label"><code>label</code></dfn> DOM attributes must
2799: <a href="infrastructure.html#reflect">reflect</a> the respective content attributes of the same
2800: name.</p>
2801:
2802: </div><h5 id="menus-intro"><span class="secno">4.11.5.1 </span>Introduction</h5><p><i>This section is non-normative.</i></p><p class="XXX">...</p><!--
2803:
2804:
2805: <pre><menu type="commands">
2806: <li>
2807: <menu label="File">
2808: <button type="button" onclick="fnew()">New...</button>
2809: <button type="button" onclick="fopen()">Open...</button>
2810: <button type="button" onclick="fsave()" id="save">Save</button>
2811: <button type="button" onclick="fsaveas()">Save as...</button>
2812: </menu>
2813: </li>
2814: <li>
2815: <menu label="Edit">
2816: <button type="button" onclick="ecopy()">Copy</button>
2817: <button type="button" onclick="ecut()">Cut</button>
2818: <button type="button" onclick="epaste()">Paste</button>
2819: </menu>
2820: </li>
2821: <li>
2822: <menu label="Help">
2823: <li><a href="help.html">Help</a></li>
2824: <li><a href="about.html">About</a></li>
2825: </menu>
2826: </li>
2827: </menu>
2828:
2829: ...
2830:
2831: <input command="save"/> <!- - This will act exactly like the
2832: Save button above, including reflecting
2833: its <code>disabled</code> state dynamically - ->
2834:
2835: </pre>
2836:
2837: <p>Here's some markup that falls back on the traditional abuse of
2838: the <code>select</code> element as a navigation menu, but which is
2839: implemented as a semi-correct menu using the new techniques of this
2840: document:</p>
2841:
2842: <pre><form action="redirect.cgi">
2843: <menu type="commands">
2844: <label for="goto">Go to...</label>
2845: <menu label="Go">
2846: <select id="goto"
2847: onchange="if (this.options[this.selectedIndex].value)
2848: window.location = this.options[this.selectedIndex].value">
2849: <option value="" selected="selected"> Select site: </option>
2850: <option value="http://www.apple.com/"> Apple </option>
2851: <option value="http://www.mozilla.org/"> Mozilla </option>
2852: <option value="http://www.opera.com/"> Opera </option>
2853: </select>
2854: <span><input type="submit" value="Go"></span>
2855: </menu>
2856: </menu>
2857: </form></pre>
2858:
2859: <form ...>
2860: <menu type="toolbar">
2861: <li>
2862: <select name="foo" onchange="form.submit()">
2863: ...
2864: </select>
2865: <button>Go</button>
2866: </li>
2867: <li>
2868: <select name="bar" onchange="form.submit()">
2869: ...
2870: </select>
2871: <button>Go</button>
2872: </li>
2873: </menu>
2874: </form>
2875:
2876: <form ...>
2877: <menu type="toolbar">
2878: <menu label="Foo">
2879: <select name="foo" onchange="form.submit()">
2880: ...
2881: </select>
2882: <button>Go</button>
2883: </menu>
2884: <menu label="Bar">
2885: <select name="bar" onchange="form.submit()">
2886: ...
2887: </select>
2888: <button>Go</button>
2889: </menu>
2890: </menu>
2891: </form>
2892:
2893:
2894: explain that only direct children of the <menu> matter
2895:
2896: --><div class="impl">
2897:
2898: <h5 id="building-menus-and-tool-bars"><span class="secno">4.11.5.2 </span><dfn>Building menus and tool bars</dfn></h5>
2899:
2900: <p>A menu (or tool bar) consists of a list of zero or more of the
2901: following components:</p>
2902:
2903: <ul class="brief"><li><a href="#concept-command" title="concept-command">Commands</a>, which can be marked as default commands</li>
2904: <li>Separators</li>
2905: <li>Other menus (which allows the list to be nested)</li>
2906: </ul><p>The list corresponding to a particular <code><a href="#menus">menu</a></code> element
2907: is built by iterating over its child nodes. For each child node in
2908: <a href="infrastructure.html#tree-order">tree order</a>, the required behavior depends on what the
2909: node is, as follows:</p>
2910:
2911: <dl class="switch"><dt>An element that <a href="#concept-command" title="concept-command">defines a command</a></dt>
2912:
2913: <dd>Append the command to the menu, respecting its <a href="#concept-facet" title="concept-facet">facets</a><!-- we might need to be
2914: explicit about what this means for each facet, if testing shows
2915: this isn't well-implemented. e.g.: If there's an Icon facet for the
2916: command, it should be <span title="fetch">fetched</span>, and then
2917: that image should be associated with the command, such that each
2918: command only has its image fetched once, to prevent changes to the
2919: base URL from having effects after the image has been fetched
2920: once. (no need to resolve the Icon facet, it's an absolute URL)
2921: -->. <!--If the element is a <code>command</code> element with a
2922: <code title="attr-command-default">default</code> attribute, mark
2923: the command as being a default command.--></dd>
2924:
2925:
2926: <dt>An <code><a href="semantics.html#the-hr-element">hr</a></code> element</dt>
2927: <dt>An <code><a href="forms.html#the-option-element">option</a></code> element that has a <code title="attr-option-value"><a href="forms.html#attr-option-value">value</a></code> attribute set to the empty
2928: string, and has a <code title="attr-option-disabled"><a href="forms.html#attr-option-disabled">disabled</a></code> attribute, and whose
2929: <code>textContent</code> consists of a string of one or more
2930: hyphens (U+002D HYPHEN-MINUS)</dt>
2931:
2932: <dd>Append a separator to the menu.</dd>
2933:
2934:
2935: <dt>An <code><a href="semantics.html#the-li-element">li</a></code> element</dt>
2936: <dt>A <code><a href="forms.html#the-label-element">label</a></code> element</dt>
2937:
2938: <dd>Iterate over the children of the element.</dd>
2939:
2940:
2941: <dt>A <code><a href="#menus">menu</a></code> element with no <code title="attr-menu-label"><a href="#attr-menu-label">label</a></code> attribute</dt>
2942: <dt>A <code><a href="forms.html#the-select-element">select</a></code> element</dt>
2943:
2944: <dd>Append a separator to the menu, then iterate over the children
2945: of the <code><a href="#menus">menu</a></code> or <code><a href="forms.html#the-select-element">select</a></code> element, then
2946: append another separator.</dd>
2947:
2948: <!-- v2: we might want to support <select> in <label> as giving a named submenu -->
2949:
2950:
2951: <dt>A <code><a href="#menus">menu</a></code> element with a <code title="attr-menu-label"><a href="#attr-menu-label">label</a></code> attribute</dt>
2952: <dt>An <code><a href="forms.html#the-optgroup-element">optgroup</a></code> element with a <code title="attr-menu-label"><a href="#attr-menu-label">label</a></code> attribute</dt>
2953:
2954: <dd>Append a submenu to the menu, using the value of the element's
2955: <code title="">label</code> attribute as the label of the menu. The
2956: submenu must be constructed by taking the element and creating a
2957: new menu for it using the complete process described in this
2958: section.</dd>
2959:
2960:
2961: <dt>Any other node</dt>
2962:
2963: <dd><a href="infrastructure.html#ignore">Ignore</a> the node.</dd>
2964:
2965: </dl><p>Once all the nodes have been processed as described above, the
2966: user agent must the post-process the menu as follows:</p>
2967:
2968: <ol><li>Any menu item with no label, or whose label is the empty string, must be removed.</li>
2969:
2970: <li>Any sequence of two or more separators in a row must be collapsed to a single separator.</li>
2971:
2972: <li>Any separator at the start or end of the menu must be removed.</li>
2973:
2974: </ol></div><h5 id="context-menus"><span class="secno">4.11.5.3 </span><dfn>Context menus</dfn></h5><p>The <dfn id="attr-contextmenu" title="attr-contextmenu"><code>contextmenu</code></dfn>
2975: attribute gives the element's <a href="#context-menus" title="context menus">context
2976: menu</a>. The value must be the ID of a <code><a href="#menus">menu</a></code> element
2977: in the DOM. <span class="impl">If the node that would be obtained by
2978: the invoking the <code>getElementById()</code> method using the
2979: attribute's value as the only argument is null or not a
2980: <code><a href="#menus">menu</a></code> element, then the element has no assigned context
2981: menu. Otherwise, the element's assigned context menu is the element
2982: so identified.</span></p><div class="impl">
2983:
2984: <p>When an element's context menu is requested (e.g. by the user
2985: right-clicking the element, or pressing a context menu key), the UA
2986: must <a href="browsers.html#fire-a-simple-event">fire a simple event</a> called <code title="event-contextmenu">contextmenu</code> that bubbles and is
2987: cancelable at the element for which the menu was requested.</p>
2988:
2989: <p class="note">Typically, therefore, the firing of the <code title="event-contextmenu">contextmenu</code> event will be the
2990: default action of a <code title="mouseup">mouseup</code> or <code title="event-keyup">keyup</code> event. The exact sequence of events
2991: is UA-dependent, as it will vary based on platform conventions.</p>
2992:
2993: <p>The default action of the <code title="event-contextmenu">contextmenu</code> event depends on
2994: whether the element or one of its ancestors has a context menu
2995: assigned (using the <code title="attr-contextmenu"><a href="#attr-contextmenu">contextmenu</a></code> attribute) or not. If
2996: there is no context menu assigned, the default action must be for
2997: the user agent to show its default context menu, if it has one.</p>
2998:
2999: <p>If the element or one of its ancestors <em>does</em> have a
3000: context menu assigned, then the user agent must <a href="browsers.html#fire-a-simple-event">fire a simple
3001: event</a> called <code title="event-show">show</code> at the
3002: <code><a href="#menus">menu</a></code> element of the context menu of the nearest
3003: ancestor (including the element itself) with one assigned.</p>
3004: <!-- v2: include modifier key information -->
3005:
3006: <p>The default action of <em>this</em> event is that the user agent
3007: must show a context menu <a href="#building-menus-and-tool-bars" title="building menus and tool
3008: bars">built</a> from the <code><a href="#menus">menu</a></code> element.</p>
3009:
3010: <p>The user agent may also provide access to its default context
3011: menu, if any, with the context menu shown. For example, it could
3012: merge the menu items from the two menus together, or provide the
3013: page's context menu as a submenu of the default menu.</p>
3014:
3015: <p>If the user dismisses the menu without making a selection,
3016: nothing in particular happens.</p>
3017:
3018: <p>If the user selects a menu item that represents a <span title="concept-commands">command</span>, then the UA must invoke
3019: that command's <a href="#command-facet-action" title="command-facet-Action">Action</a>.</p>
3020:
3021: <p>Context menus must not, while being shown, reflect changes in the
3022: DOM; they are constructed as the default action of the <code title="event-show">show</code> event and must remain like that until
3023: dismissed.</p>
3024:
3025: <p>User agents may provide means for bypassing the context menu
3026: processing model, ensuring that the user can always access the UA's
3027: default context menus. For example, the user agent could handle
3028: right-clicks that have the Shift key depressed in such a way that it
3029: does not fire the <code title="event-contextmenu">contextmenu</code>
3030: event and instead always shows the default context menu.</p>
3031:
3032: <p>The <dfn id="dom-contextmenu" title="dom-contextMenu"><code>contextMenu</code></dfn>
3033: attribute must <a href="infrastructure.html#reflect">reflect</a> the <code title="attr-contextmenu"><a href="#attr-contextmenu">contextmenu</a></code> content attribute.</p>
3034:
3035: </div><div class="impl">
3036:
3037: <h5 id="tool-bars"><span class="secno">4.11.5.4 </span><dfn>Tool bars</dfn></h5>
3038:
3039: <p>When a <code><a href="#menus">menu</a></code> element has a <code title="attr-menu-type"><a href="#attr-menu-type">type</a></code> attribute in the <a href="#tool-bar-state" title="tool bar state">tool bar</a> state, then the user agent
3040: must <a href="#building-menus-and-tool-bars" title="building menus and tool bars">build</a> the
3041: menu for that <code><a href="#menus">menu</a></code> element, and use the result in the
3042: rendering.</p>
3043:
3044: <p>The user agent must reflect changes made to the
3045: <code><a href="#menus">menu</a></code>'s DOM, by immediately <a href="#building-menus-and-tool-bars" title="building menus
3046: and tool bars">rebuilding</a> the menu.</p>
3047:
3048: </div><h4 id="commands"><span class="secno">4.11.6 </span>Commands</h4><p>A <dfn id="concept-command" title="concept-command">command</dfn> is the abstraction
3049: behind menu items, buttons, and links. Once a command is defined,
3050: other parts of the interface can refer to the same command, allowing
3051: many access points to a single feature to share aspects such as the
3052: disabled state.</p><p id="facets">Commands are defined to have the following
3053: <dfn id="concept-facet" title="concept-facet">facets</dfn>:</p><dl><dt><dfn id="command-facet-type" title="command-facet-Type">Type</dfn></dt>
3054:
3055: <dd>The kind of command: "command", meaning it is a normal command;
3056: "radio", meaning that triggering the command will, amongst other
3057: things, set the <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked
3058: State</a> to true (and probably uncheck some other commands); or
3059: "checkbox", meaning that triggering the command will, amongst other
3060: things, toggle the value of the <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>.</dd>
3061:
3062: <dt><dfn id="command-facet-id" title="command-facet-ID">ID</dfn></dt>
3063:
3064: <dd>The name of the command, for referring to the command from the
3065: markup or from script. If a command has no ID, it is an
3066: <dfn id="anonymous-command">anonymous command</dfn>.</dd>
3067:
3068: <dt><dfn id="command-facet-label" title="command-facet-Label">Label</dfn></dt>
3069:
3070: <dd>The name of the command as seen by the user.</dd>
3071:
3072: <dt><dfn id="command-facet-hint" title="command-facet-Hint">Hint</dfn></dt>
3073:
3074: <dd>A helpful or descriptive string that can be shown to the
3075: user.</dd>
3076:
3077: <dt><dfn id="command-facet-icon" title="command-facet-Icon">Icon</dfn></dt>
3078:
3079: <dd>An <a href="infrastructure.html#absolute-url">absolute URL</a> identifying a graphical image that
3080: represents the action. A command might not have an Icon.</dd> <!--
3081: changing base URLs might change the icon -->
3082:
3083: <dt><dfn id="command-facet-accesskey" title="command-facet-AccessKey">Access Key</dfn></dt>
3084:
3085: <dd>A key combination selected by the user agent that triggers the
3086: command. A command might not have an Access Key.</dd>
3087:
3088: <dt><dfn id="command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</dfn></dt>
3089:
3090: <dd>Whether the command is hidden or not (basically, whether it
3091: should be shown in menus).</dd>
3092:
3093: <dt><dfn id="command-facet-disabledstate" title="command-facet-DisabledState">Disabled State</dfn></dt>
3094:
3095: <dd>Whether the command is relevant and can be triggered or not.</dd>
3096:
3097: <dt><dfn id="command-facet-checkedstate" title="command-facet-CheckedState">Checked State</dfn></dt>
3098:
3099: <dd>Whether the command is checked or not.</dd>
3100:
3101: <dt><dfn id="command-facet-action" title="command-facet-Action">Action</dfn></dt>
3102:
3103: <dd>The actual effect that triggering the command will have. This
3104: could be a scripted event handler, a <a href="infrastructure.html#url">URL</a> to which to
3105: <a href="history.html#navigate">navigate</a>, or a form submission.</dd>
3106:
3107: <!-- v2COMMAND
3108: <dt><dfn title="command-facet-Triggers">Triggers</dfn></dt>
3109:
3110: <dd>The list of elements that can trigger the command. The element
3111: defining a command is always in the list of elements that can
3112: trigger the command. For anonymous commands, only the element
3113: defining the command is on the list, since other elements have no
3114: way to refer to it.</dd>
3115: -->
3116:
3117: </dl><p>These facets are exposed on elements using the <dfn id="command-api">command
3118: API</dfn>:</p><dl class="domintro"><dt><var title="">element</var> . <code title="dom-command-ro-commandType"><a href="#dom-command-ro-commandtype">commandType</a></code></dt>
3119:
3120: <dd>
3121:
3122: <p>Exposes the <a href="#command-facet-type" title="command-facet-Type">Type</a> facet of the command.</p>
3123:
3124: </dd>
3125:
3126: <dt><var title="">element</var> . <code title="dom-id"><a href="dom.html#dom-id">id</a></code></dt>
3127:
3128: <dd>
3129:
3130: <p>Exposes the <a href="#command-facet-id" title="command-facet-ID">ID</a> facet of the command.</p>
3131:
3132: </dd>
3133:
3134: <dt><var title="">element</var> . <code title="dom-command-ro-label"><a href="#dom-command-ro-label">label</a></code></dt>
3135:
3136: <dd>
3137:
3138: <p>Exposes the <a href="#command-facet-label" title="command-facet-Label">Label</a> facet of the command.</p>
3139:
3140: </dd>
3141:
3142: <dt><var title="">element</var> . <code title="dom-title"><a href="dom.html#dom-title">title</a></code></dt>
3143:
3144: <dd>
3145:
3146: <p>Exposes the <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> facet of the command.</p>
3147:
3148: </dd>
3149:
3150: <dt><var title="">element</var> . <code title="dom-command-ro-icon"><a href="#dom-command-ro-icon">icon</a></code></dt>
3151:
3152: <dd>
3153:
3154: <p>Exposes the <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> facet of the command.</p>
3155:
3156: </dd>
3157:
3158: <dt><var title="">element</var> . <code title="dom-accessKeyLabel"><a href="editing.html#dom-accesskeylabel">accessKeyLabel</a></code></dt>
3159:
3160: <dd>
3161:
3162: <p>Exposes the <a href="#command-facet-accesskey" title="command-facet-AccessKey">Access Key</a> facet of the command.</p>
3163:
3164: </dd>
3165:
3166: <dt><var title="">element</var> . <code title="dom-hidden"><a href="editing.html#dom-hidden">hidden</a></code></dt>
3167:
3168: <dd>
3169:
3170: <p>Exposes the <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a> facet of the command.</p>
3171:
3172: </dd>
3173:
3174: <dt><var title="">element</var> . <code title="dom-command-ro-disabled"><a href="#dom-command-ro-disabled">disabled</a></code></dt>
3175:
3176: <dd>
3177:
3178: <p>Exposes the <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled State</a> facet of the command.</p>
3179:
3180: </dd>
3181:
3182: <dt><var title="">element</var> . <code title="dom-command-ro-checked"><a href="#dom-command-ro-checked">checked</a></code></dt>
3183:
3184: <dd>
3185:
3186: <p>Exposes the <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a> facet of the command.</p>
3187:
3188: </dd>
3189:
3190: <dt><var title="">element</var> . <code title="dom-click"><a href="editing.html#dom-click">click</a></code>()</dt>
3191:
3192: <dd>
3193:
3194: <p>Triggers the <a href="#command-facet-action" title="command-facet-Action">Action</a> of the command.</p>
3195:
3196: </dd>
3197:
3198: <!--v2COMMAND
3199: <dt><var title="">element</var> . <code title="dom-command-ro-triggers">triggers</code></dt>
3200:
3201: <dd>
3202:
3203: <p>Exposes the <span title="command-facet-Triggers">Triggers</span> facet of the command.</p>
3204:
3205: </dd>
3206: -->
3207:
3208: </dl><div class="impl">
3209:
3210: <p>The <dfn id="dom-command-ro-commandtype" title="dom-command-ro-commandType"><code>commandType</code></dfn>
3211: attribute must return a string whose value is either "<code title="">command</code>", "<code title="">radio</code>", or "<code title="">checked</code>", depending on whether the <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command defined by the
3212: element is "command", "radio", or "checked" respectively. If the
3213: element does not define a command, it must return null.</p>
3214:
3215: <p>The <dfn id="dom-command-ro-label" title="dom-command-ro-label"><code>label</code></dfn>
3216: attribute must return the command's <a href="#command-facet-label" title="command-facet-Label">Label</a>, or null if the element
3217: does not define a command or does not specify a <a href="#command-facet-label" title="command-facet-Label">Label</a>. This attribute will be
3218: shadowed by the <code title="">label</code> DOM attribute on
3219: <code><a href="forms.html#the-option-element">option</a></code> and <code><a href="#the-command">command</a></code> elements.</p>
3220:
3221: <p>The <dfn id="dom-command-ro-icon" title="dom-command-ro-icon"><code>icon</code></dfn>
3222: attribute must return the <a href="infrastructure.html#absolute-url">absolute URL</a> of the command's
3223: <a href="#command-facet-icon" title="command-facet-Icon">Icon</a>. If the element does
3224: not specify an icon, or if the element does not define a command,
3225: then the attribute must return null. This attribute will be shadowed
3226: by the <code title="dom-command-icon"><a href="#dom-command-icon">icon</a></code> DOM attribute on
3227: <code><a href="#the-command">command</a></code> elements.</p>
3228:
3229: <p>The <dfn id="dom-command-ro-disabled" title="dom-command-ro-disabled"><code>disabled</code></dfn>
3230: attribute must return true if the command's <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled State</a> is that
3231: the command is disabled, and false if the command is not
3232: disabled. This attribute is not affected by the command's <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>. If the
3233: element does not define a command, the attribute must return
3234: false. This attribute will be shadowed by the <code title="">disabled</code> attribute on <code><a href="forms.html#the-button-element">button</a></code>,
3235: <code><a href="forms.html#the-input-element">input</a></code>, <code><a href="forms.html#the-option-element">option</a></code>, and <code><a href="#the-command">command</a></code>
3236: elements.</p>
3237:
3238: <p>The <dfn id="dom-command-ro-checked" title="dom-command-ro-checked"><code>checked</code></dfn> attribute
3239: must return true if the command's <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a> is that the
3240: command is checked, and false if it is that the command is not
3241: checked. If the element does not define a command, the attribute
3242: must return false. This attribute will be shadowed by the <code title="">checked</code> attribute on <code><a href="forms.html#the-input-element">input</a></code> and
3243: <code><a href="#the-command">command</a></code> elements.</p>
3244:
3245: <!--v2COMMAND
3246: <p>The <dfn
3247: title="dom-command-ro-triggers"><code>triggers</code></dfn>
3248: attribute must return a list containing the elements that can
3249: trigger the command (the command's <span
3250: title="command-facet-Triggers">Triggers</span>). The list must be
3251: <span>live</span>. While the element does not define a command, the
3252: list must be empty.</p>
3253: -->
3254:
3255: <p class="note">The <a href="#command-facet-id" title="command-facet-ID">ID</a> facet
3256: is exposed by the the <code title="dom-id"><a href="dom.html#dom-id">id</a></code> DOM attribute,
3257: the <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> facet is exposed by
3258: the <code title="dom-title"><a href="dom.html#dom-title">title</a></code> DOM attribute, the <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> facet is exposed by
3259: the <code title="dom-accessKeyLabel"><a href="editing.html#dom-accesskeylabel">accessKeyLabel</a></code> DOM
3260: attribute, and the <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden
3261: State</a> facet is exposed by the <code title="dom-hidden"><a href="editing.html#dom-hidden">hidden</a></code> DOM attribute.</p>
3262:
3263: </div><hr><dl class="domintro"><dt><var title="">document</var> . <code title="dom-document-commands"><a href="#dom-document-commands">commands</a></code></dt>
3264: <dd>
3265: <p>Returns an <code><a href="infrastructure.html#htmlcollection-0">HTMLCollection</a></code> of the elements in the
3266: <code>Document</code> that define commands and have IDs.</p>
3267: </dd>
3268:
3269: </dl><div class="impl">
3270:
3271: <p>The <dfn id="dom-document-commands" title="dom-document-commands"><code>commands</code></dfn> attribute
3272: of the document's <code><a href="dom.html#htmldocument">HTMLDocument</a></code> interface must return an
3273: <code><a href="infrastructure.html#htmlcollection-0">HTMLCollection</a></code> rooted at the <code>Document</code>
3274: node, whose filter matches only elements that <a href="#concept-command" title="concept-command">define commands</a> and have <a href="#command-facet-id" title="command-facet-ID">IDs</a>.</p>
3275:
3276: </div><hr><p>User agents may expose the <a href="#concept-command" title="concept-command">commands</a> whose <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a> facet is false
3277: (visible), e.g. in the user agent's menu bar. User agents are
3278: encouraged to do this especially for commands that have <a href="#command-facet-accesskey" title="command-facet-AccessKey">Access Keys</a>, as a way to
3279: advertise those keys to the user.</p><div class="impl">
3280:
3281: <h5 id="using-the-a-element-to-define-a-command"><span class="secno">4.11.6.1 </span><dfn title="a-command">Using the <code>a</code> element to define a command</dfn></h5>
3282:
3283: <p>An <code><a href="text-level-semantics.html#the-a-element">a</a></code> element with an <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute <a href="#concept-command" title="concept-command">defines a command</a>.</p>
3284:
3285: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command
3286: is "command".</p>
3287:
3288: <p>The <a href="#command-facet-id" title="command-facet-ID">ID</a> of the command is
3289: the value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> attribute of the
3290: element, if the attribute is present and not empty. Otherwise the
3291: command is an <a href="#anonymous-command">anonymous command</a>.</p>
3292:
3293: <p>The <a href="#command-facet-label" title="command-facet-Label">Label</a> of the command
3294: is the string given by the element's <code>textContent</code> DOM
3295: attribute.</p>
3296:
3297: <p>The <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> of the command
3298: is the value of the <code title="attr-title"><a href="dom.html#the-title-attribute">title</a></code> attribute
3299: of the element. If the attribute is not present, the <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> is the empty string.</p>
3300:
3301: <p>The <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> of the command
3302: is the <a href="infrastructure.html#absolute-url">absolute URL</a> obtained from <a href="infrastructure.html#resolve-a-url" title="resolve
3303: a url">resolving</a> the value of the <code title="attr-img-src"><a href="embedded-content-0.html#attr-img-src">src</a></code> attribute of the first
3304: <code><a href="embedded-content-0.html#the-img-element">img</a></code> element descendant of the element, relative to that
3305: element, if there is such an element and resolving its attribute is
3306: successful. Otherwise, there is no <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> for the command.</p>
3307:
3308: <p>The <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> of the
3309: command is the element's <a href="editing.html#assigned-access-key">assigned access key</a>, if
3310: any.</p>
3311:
3312: <p>The <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>
3313: of the command is true (hidden) if the element has a <code title="attr-hidden"><a href="editing.html#the-hidden-attribute">hidden</a></code> attribute, and false
3314: otherwise.</p>
3315:
3316: <p>The <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled
3317: State</a> facet of the command is always false. (The command is
3318: always enabled.)</p>
3319:
3320: <p>The <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>
3321: of the command is always false. (The command is never checked.)</p>
3322:
3323: <p>The <a href="#command-facet-action" title="command-facet-Action">Action</a> of the
3324: command is to <a href="browsers.html#fire-a-click-event" title="fire a click event">fire a <code title="event-click">click</code> event</a> at the element.</p>
3325:
3326:
3327: <h5 id="using-the-button-element-to-define-a-command"><span class="secno">4.11.6.2 </span><dfn title="button-command">Using the <code>button</code> element to define a command</dfn></h5>
3328:
3329: <p>A <code><a href="forms.html#the-button-element">button</a></code> element always <a href="#concept-command" title="concept-command">defines a command</a>.</p>
3330:
3331: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a>, <a href="#command-facet-id" title="command-facet-ID">ID</a>, <a href="#command-facet-label" title="command-facet-Label">Label</a>, <a href="#command-facet-hint" title="command-facet-Hint">Hint</a>, <a href="#command-facet-icon" title="command-facet-Icon">Icon</a>, <a href="#command-facet-accesskey" title="command-facet-AccessKey">Access Key</a>, <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>, <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>, and <a href="#command-facet-action" title="command-facet-Action">Action</a> facets of the command are
3332: determined <a href="#using-the-a-element-to-define-a-command" title="a-command">as for <code>a</code>
3333: elements</a> (see the previous section).</p>
3334:
3335: <p>The <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled
3336: State</a> of the command mirrors the <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a> state of the button.</p>
3337:
3338:
3339: <h5 id="using-the-input-element-to-define-a-command"><span class="secno">4.11.6.3 </span><dfn title="input-command">Using the <code>input</code> element to define a command</dfn></h5>
3340:
3341: <p>An <code><a href="forms.html#the-input-element">input</a></code> element whose <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute is in one of the <a href="forms.html#submit-button-state" title="attr-input-type-submit">Submit Button</a>, <a href="forms.html#reset-button-state" title="attr-input-type-reset">Reset Button</a>, <a href="forms.html#button-state" title="attr-input-type-button">Button</a>, <a href="forms.html#radio-button-state" title="attr-input-type-radio">Radio Button</a>, or <a href="forms.html#checkbox-state" title="attr-input-type-checkbox">Checkbox</a> states <a href="#concept-command" title="concept-command">defines a command</a>.</p>
3342:
3343: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command
3344: is "radio" if the <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code>
3345: attribute is in the <code title="attr-input-type-radio"><a href="forms.html#radio-button-state">Radio
3346: Button</a></code> state, "checkbox" if the <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute is in the <code title="attr-input-type-checkbox"><a href="forms.html#checkbox-state">Checkbox</a></code> state, and
3347: "command" otherwise.</p>
3348:
3349: <p>The <a href="#command-facet-id" title="command-facet-ID">ID</a> of the command is
3350: the value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> attribute of the
3351: element, if the attribute is present and not empty. Otherwise the
3352: command is an <a href="#anonymous-command">anonymous command</a>.</p>
3353:
3354: <p>The <a href="#command-facet-label" title="command-facet-Label">Label</a> of the command
3355: depends on the Type of the command:</p>
3356:
3357: <p>If the <a href="#command-facet-type" title="command-facet-Type">Type</a> is "command",
3358: then it is the string given by the <code title="attr-input-value"><a href="forms.html#attr-input-value">value</a></code> attribute, if any, and a
3359: UA-dependent, locale-dependent value that the UA uses to label the
3360: button itself if the attribute is absent.</p>
3361:
3362: <p>Otherwise, the <a href="#command-facet-type" title="command-facet-Type">Type</a> is
3363: "radio" or "checkbox". If the element is a <a href="forms.html#labeled-control">labeled
3364: control</a>, the <code>textContent</code> of the first
3365: <code><a href="forms.html#the-label-element">label</a></code> element in <a href="infrastructure.html#tree-order">tree order</a> whose
3366: <a href="forms.html#labeled-control">labeled control</a> is the element in question is the <a href="#command-facet-label" title="command-facet-Label">Label</a> (in DOM terms, this is the
3367: string given by <code><var title="">element</var>.labels[0].textContent</code>). Otherwise,
3368: the value of the <code title="attr-input-value"><a href="forms.html#attr-input-value">value</a></code>
3369: attribute, if present, is the <a href="#command-facet-label" title="command-facet-Label">Label</a>. Otherwise, the <a href="#command-facet-label" title="command-facet-Label">Label</a> is the empty string.</p>
3370:
3371: <p>The <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> of the command
3372: is the value of the <code title="attr-title"><a href="dom.html#the-title-attribute">title</a></code> attribute
3373: of the <code><a href="forms.html#the-input-element">input</a></code> element. If the attribute is not present, the
3374: <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> is the empty
3375: string.</p>
3376:
3377: <p>There is no <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> for the
3378: command.</p>
3379:
3380: <p>The <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> of the
3381: command is the element's <a href="editing.html#assigned-access-key">assigned access key</a>, if
3382: any.</p>
3383:
3384: <p>The <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>
3385: of the command is true (hidden) if the element has a <code title="attr-hidden"><a href="editing.html#the-hidden-attribute">hidden</a></code> attribute, and false
3386: otherwise.</p>
3387:
3388: <p>The <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled
3389: State</a> of the command mirrors the <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a> state of the
3390: control.</p>
3391:
3392: <p>The <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>
3393: of the command is true if the command is of <a href="#command-facet-type" title="command-facet-Type">Type</a> "radio" or "checkbox" and the
3394: element is <a href="forms.html#concept-fe-checked" title="concept-fe-checked">checked</a>
3395: attribute, and false otherwise.</p>
3396:
3397: <p>The <a href="#command-facet-action" title="command-facet-Action">Action</a> of the
3398: command, if the element has a defined <a href="dom.html#activation-behavior">activation
3399: behavior</a>, is to <a href="dom.html#run-synthetic-click-activation-steps">run synthetic click activation
3400: steps</a> on the element. Otherwise, it is just to <a href="browsers.html#fire-a-click-event">fire a
3401: <code title="event-click">click</code> event</a> at the
3402: element.</p>
3403:
3404:
3405: <h5 id="using-the-option-element-to-define-a-command"><span class="secno">4.11.6.4 </span><dfn title="option-command">Using the <code>option</code> element to define a command</dfn></h5>
3406:
3407: <p>An <code><a href="forms.html#the-option-element">option</a></code> element with an ancestor
3408: <code><a href="forms.html#the-select-element">select</a></code> element and either no <code title="attr-option-value"><a href="forms.html#attr-option-value">value</a></code> attribute or a <code title="attr-option-value"><a href="forms.html#attr-option-value">value</a></code> attribute that is not the
3409: empty string <a href="#concept-command" title="concept-command">defines a
3410: command</a>.</p>
3411:
3412: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command
3413: is "radio" if the <code><a href="forms.html#the-option-element">option</a></code>'s nearest ancestor
3414: <code><a href="forms.html#the-select-element">select</a></code> element has no <code title="attr-select-multiple"><a href="forms.html#attr-select-multiple">multiple</a></code> attribute, and
3415: "checkbox" if it does.</p>
3416:
3417: <p>The <a href="#command-facet-id" title="command-facet-ID">ID</a> of the command is
3418: the value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> attribute of the
3419: element, if the attribute is present and not empty. Otherwise the
3420: command is an <a href="#anonymous-command">anonymous command</a>.</p>
3421:
3422: <p>The <a href="#command-facet-label" title="command-facet-Label">Label</a> of the command
3423: is the value of the <code><a href="forms.html#the-option-element">option</a></code> element's <code title="attr-option-label"><a href="forms.html#attr-option-label">label</a></code> attribute, if there is one,
3424: or the value of the <code><a href="forms.html#the-option-element">option</a></code> element's
3425: <code>textContent</code> DOM attribute if there isn't.</p>
3426:
3427: <p>The <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> of the command
3428: is the string given by the element's <code title="attr-title"><a href="dom.html#the-title-attribute">title</a></code> attribute, if any, and the empty
3429: string if the attribute is absent.</p>
3430:
3431: <p>There is no <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> for the
3432: command.</p>
3433:
3434: <p>The <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> of the
3435: command is the element's <a href="editing.html#assigned-access-key">assigned access key</a>, if
3436: any.</p>
3437:
3438: <p>The <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>
3439: of the command is true (hidden) if the element has a <code title="attr-hidden"><a href="editing.html#the-hidden-attribute">hidden</a></code> attribute, and false
3440: otherwise.</p>
3441:
3442: <p>The <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled
3443: State</a> of the command is true (disabled) if the element is
3444: <a href="forms.html#concept-option-disabled" title="concept-option-disabled">disabled</a> or if its
3445: nearest ancestor <code><a href="forms.html#the-select-element">select</a></code> element is <a href="forms.html#concept-option-disabled" title="concept-option-disabled">disabled</a>, and false
3446: otherwise.</p>
3447:
3448: <p>The <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>
3449: of the command is true (checked) if the element's <a href="forms.html#concept-option-selectedness" title="concept-option-selectedness">selectedness</a> is true, and
3450: false otherwise.</p>
3451:
3452: <p>The <a href="#command-facet-action" title="command-facet-Action">Action</a> of the
3453: command depends on its <a href="#command-facet-type" title="command-facet-Type">Type</a>. If the command is of <a href="#command-facet-type" title="command-facet-Type">Type</a> "radio" then it must <a href="forms.html#concept-select-pick" title="concept-select-pick">pick</a> the <code><a href="forms.html#the-option-element">option</a></code>
3454: element. Otherwise, it must <a href="forms.html#concept-select-toggle" title="concept-select-toggle">toggle</a> the <code><a href="forms.html#the-option-element">option</a></code>
3455: element.</p>
3456:
3457:
3458: <h5 id="using-the-command-element-to-define-a-command"><span class="secno">4.11.6.5 </span>Using the <dfn title="command-element"><code>command</code></dfn> element to define
3459: a command</h5>
3460:
3461: <p>A <code><a href="#the-command">command</a></code> element <a href="#concept-command" title="concept-command">defines a command</a>.</p>
3462:
3463: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command
3464: is "radio" if the <code><a href="#the-command">command</a></code>'s <code title="attr-command-type"><a href="#attr-command-type">type</a></code> attribute is
3465: "<code>radio</code>", "checkbox" if the attribute's value is
3466: "<code>checkbox</code>", and "command" otherwise.</p>
3467:
3468: <p>The <a href="#command-facet-id" title="command-facet-ID">ID</a> of the command is
3469: the value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> attribute of the
3470: element, if the attribute is present and not empty. Otherwise the
3471: command is an <a href="#anonymous-command">anonymous command</a>.</p>
3472:
3473: <p>The <a href="#command-facet-label" title="command-facet-Label">Label</a> of the command
3474: is the value of the element's <code title="attr-command-label"><a href="#attr-command-label">label</a></code> attribute, if there is one,
3475: or the empty string if it doesn't.</p>
3476:
3477: <p>The <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> of the command
3478: is the string given by the element's <code title="attr-command-title"><a href="#attr-command-title">title</a></code> attribute, if any, and the
3479: empty string if the attribute is absent.</p>
3480:
3481: <p>The <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> for the command
3482: is the <a href="infrastructure.html#absolute-url">absolute URL</a> obtained from <a href="infrastructure.html#resolve-a-url" title="resolve
3483: a url">resolving</a> the value of the element's <code title="attr-command-icon"><a href="#attr-command-icon">icon</a></code> attribute, relative to the
3484: element, if it has such an attribute and resolving it is
3485: successful. Otherwise, there is no <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> for the command.</p>
3486:
3487: <p>The <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> of the
3488: command is the element's <a href="editing.html#assigned-access-key">assigned access key</a>, if
3489: any.</p>
3490:
3491: <p>The <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>
3492: of the command is true (hidden) if the element has a <code title="attr-hidden"><a href="editing.html#the-hidden-attribute">hidden</a></code> attribute, and false
3493: otherwise.</p>
3494:
3495: <p>The <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled
3496: State</a> of the command is true (disabled) if the element has a
3497: <code title="attr-command-disabled"><a href="#attr-command-disabled">disabled</a></code> attribute, and
3498: false otherwise.</p>
3499:
3500: <p>The <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>
3501: of the command is true (checked) if the element has a <code title="attr-command-checked"><a href="#attr-command-checked">checked</a></code> attribute, and false
3502: otherwise.</p>
3503:
3504: <p>The <a href="#command-facet-action" title="command-facet-Action">Action</a> of the
3505: command, if the element has a defined <a href="dom.html#activation-behavior">activation
3506: behavior</a>, is to <a href="dom.html#run-synthetic-click-activation-steps">run synthetic click activation
3507: steps</a> on the element. Otherwise, it is just to <a href="browsers.html#fire-a-click-event">fire a
3508: <code title="event-click">click</code> event</a> at the
3509: element.</p>
3510:
3511:
3512:
3513:
3514: <h5 id="using-the-bb-element-to-define-a-command"><span class="secno">4.11.6.6 </span><dfn title="bb-command">Using the <code>bb</code> element to define a command</dfn></h5>
3515:
3516: <p>A <code><a href="#the-bb-element">bb</a></code> element always <a href="#concept-command" title="concept-command">defines a command</a>.</p>
3517:
3518: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command
3519: is "command".</p>
3520:
3521: <p>The <a href="#command-facet-id" title="command-facet-ID">ID</a> of the command is
3522: the value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> attribute of the
3523: element, if the attribute is present and not empty. Otherwise the
3524: command is an <a href="#anonymous-command">anonymous command</a>.</p>
3525:
3526: <p>The <a href="#command-facet-label" title="command-facet-Label">Label</a> of the command
3527: is the string given by the element's <code>textContent</code> DOM
3528: attribute, if that is not the empty string, or a user-agent-defined
3529: string appropriate for the <code><a href="#the-bb-element">bb</a></code> element's <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's state.</p>
3530:
3531: <p>The <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> of the command
3532: is the value of the <code title="attr-title"><a href="dom.html#the-title-attribute">title</a></code> attribute
3533: of the element. If the attribute is not present, the <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> is a user-agent-defined
3534: string appropriate for the <code><a href="#the-bb-element">bb</a></code> element's <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's state.</p>
3535:
3536: <p>The <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> of the command
3537: is the <a href="infrastructure.html#absolute-url">absolute URL</a> obtained from <a href="infrastructure.html#resolve-a-url" title="resolve
3538: a url">resolving</a> the value of the <code title="attr-img-src"><a href="embedded-content-0.html#attr-img-src">src</a></code> attribute of the first
3539: <code><a href="embedded-content-0.html#the-img-element">img</a></code> element descendant of the element, relative to that
3540: element, if there is such an element and resolving its attribute is
3541: successful. Otherwise, the <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> is a user-agent-defined image
3542: appropriate for the <code><a href="#the-bb-element">bb</a></code> element's <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's state.</p>
3543:
3544: <p>The <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> of the
3545: command is the element's <a href="editing.html#assigned-access-key">assigned access key</a>, if
3546: any.</p>
3547:
3548: <p>The <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>
3549: facet of the command is true (hidden) if the <code><a href="#the-bb-element">bb</a></code>
3550: element's <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's state
3551: is <i title="attr-bb-type-null-state"><a href="#attr-bb-type-null-state">null</a></i> or if the element has
3552: a <code title="attr-hidden"><a href="editing.html#the-hidden-attribute">hidden</a></code> attribute, and false
3553: otherwise.</p>
3554:
3555: <p>The <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled
3556: State</a> facet of the command is true if the <code><a href="#the-bb-element">bb</a></code>
3557: element's <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's state's
3558: <i>relevance</i> is false, and true otherwise.</p>
3559:
3560: <p>The <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>
3561: of the command is always false. (The command is never checked.)</p>
3562:
3563: <p>The <a href="#command-facet-action" title="command-facet-Action">Action</a> of the
3564: command is to perform the <i>action</i> of the <code><a href="#the-bb-element">bb</a></code>
3565: element's <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute's
3566: state.</p>
3567:
3568:
3569:
3570: <h5 id="using-the-accesskey-attribute-on-a-label-element-to-define-a-command"><span class="secno">4.11.6.7 </span><dfn title="label-command">Using the <code title="attr-accesskey">accesskey</code> attribute on a <code>label</code> element to define a command</dfn></h5>
3571:
3572: <p>A <code><a href="forms.html#the-label-element">label</a></code> element that has an <a href="editing.html#assigned-access-key">assigned access
3573: key</a> and a <a href="forms.html#labeled-control">labeled control</a> and whose
3574: <a href="forms.html#labeled-control">labeled control</a> <a href="#concept-command" title="concept-command">defines a
3575: command</a>, itself <a href="#concept-command" title="concept-command">defines a
3576: command</a>.</p>
3577:
3578: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command
3579: is "command".</p>
3580:
3581: <p>The <a href="#command-facet-id" title="command-facet-ID">ID</a> of the command is
3582: the value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> attribute of the
3583: element, if the attribute is present and not empty. Otherwise the
3584: command is an <a href="#anonymous-command">anonymous command</a>.</p>
3585:
3586: <p>The <a href="#command-facet-label" title="command-facet-Label">Label</a> of the command
3587: is the string given by the element's <code>textContent</code> DOM
3588: attribute.</p>
3589:
3590: <p>The <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> of the command
3591: is the value of the <code title="attr-title"><a href="dom.html#the-title-attribute">title</a></code> attribute
3592: of the element.</p>
3593:
3594: <p>There is no <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> for the
3595: command.</p>
3596:
3597: <p>The <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> of the
3598: command is the element's <a href="editing.html#assigned-access-key">assigned access key</a>.</p>
3599:
3600: <p>The <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>,
3601: <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled State</a>, and
3602: <a href="#command-facet-action" title="command-facet-Action">Action</a> facets of the
3603: command are the same as the respective facets of the element's
3604: <a href="forms.html#labeled-control">labeled control</a>.</p>
3605:
3606: <p>The <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>
3607: of the command is always false. (The command is never checked.)</p>
3608:
3609:
3610:
3611: <h5 id="using-the-accesskey-attribute-on-a-legend-element-to-define-a-command"><span class="secno">4.11.6.8 </span><dfn title="legend-command">Using the <code title="attr-accesskey">accesskey</code> attribute on a <code>legend</code> element to define a command</dfn></h5>
3612:
3613: <p>A <code><a href="#the-legend-element">legend</a></code> element that has an <a href="editing.html#assigned-access-key">assigned access
3614: key</a> and is a child of a <code><a href="forms.html#the-fieldset-element">fieldset</a></code> element that
3615: has a descendant that is not a descendant of the <code><a href="#the-legend-element">legend</a></code>
3616: element and is neither a <code><a href="forms.html#the-label-element">label</a></code> element nor a
3617: <code><a href="#the-legend-element">legend</a></code> element but that <a href="#concept-command" title="concept-command">defines a command</a>, itself <a href="#concept-command" title="concept-command">defines a command</a>.</p>
3618:
3619: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command
3620: is "command".</p>
3621:
3622: <p>The <a href="#command-facet-id" title="command-facet-ID">ID</a> of the command is
3623: the value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> attribute of the
3624: element, if the attribute is present and not empty. Otherwise the
3625: command is an <a href="#anonymous-command">anonymous command</a>.</p>
3626:
3627: <p>The <a href="#command-facet-label" title="command-facet-Label">Label</a> of the command
3628: is the string given by the element's <code>textContent</code> DOM
3629: attribute.</p>
3630:
3631: <p>The <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> of the command
3632: is the value of the <code title="attr-title"><a href="dom.html#the-title-attribute">title</a></code> attribute
3633: of the element.</p>
3634:
3635: <p>There is no <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> for the
3636: command.</p>
3637:
3638: <p>The <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> of the
3639: command is the element's <a href="editing.html#assigned-access-key">assigned access key</a>.</p>
3640:
3641: <p>The <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>,
3642: <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled State</a>, and
3643: <a href="#command-facet-action" title="command-facet-Action">Action</a> facets of the
3644: command are the same as the respective facets of the first element
3645: in <a href="infrastructure.html#tree-order">tree order</a> that is a descendant of the parent of the
3646: <code><a href="#the-legend-element">legend</a></code> element that <a href="#concept-command" title="concept-command">defines a command</a> but is not a
3647: descendant of the <code><a href="#the-legend-element">legend</a></code> element and is neither a
3648: <code><a href="forms.html#the-label-element">label</a></code> nor a <code><a href="#the-legend-element">legend</a></code> element.</p>
3649:
3650: <p>The <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>
3651: of the command is always false. (The command is never checked.)</p>
3652:
3653:
3654:
3655: <h5 id="using-the-accesskey-attribute-to-define-a-command-on-a-focusable-element"><span class="secno">4.11.6.9 </span><dfn title="accesskey-command">Using the <code title="attr-accesskey">accesskey</code> attribute to define a command on a focusable element</dfn></h5>
3656:
3657: <p>An element that is <a href="editing.html#focusable">focusable</a>, has an <a href="editing.html#assigned-access-key">assigned
3658: access key</a>, and is neither an <code><a href="text-level-semantics.html#the-a-element">a</a></code> element with an
3659: <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute, a
3660: <code><a href="forms.html#the-button-element">button</a></code> element, an <code><a href="forms.html#the-input-element">input</a></code> element whose
3661: attribute is in one of the <a href="forms.html#submit-button-state" title="attr-input-type-submit">Submit Button</a>, <a href="forms.html#reset-button-state" title="attr-input-type-reset">Reset Button</a>, <a href="forms.html#button-state" title="attr-input-type-button">Button</a>, <a href="forms.html#radio-button-state" title="attr-input-type-radio">Radio Button</a>, or <a href="forms.html#checkbox-state" title="attr-input-type-checkbox">Checkbox</a> states, an
3662: <code><a href="forms.html#the-option-element">option</a></code> element with an ancestor <code><a href="forms.html#the-select-element">select</a></code>
3663: element and either no <code title="attr-option-value"><a href="forms.html#attr-option-value">value</a></code>
3664: attribute or a <code title="attr-option-value"><a href="forms.html#attr-option-value">value</a></code>
3665: attribute that is not the empty string, a <code><a href="#the-command">command</a></code>
3666: element, nor a <code><a href="#the-bb-element">bb</a></code> element, <a href="#concept-command" title="concept-command">defines a command</a>.</p>
3667:
3668: <p>The <a href="#command-facet-type" title="command-facet-Type">Type</a> of the command
3669: is "command".</p>
3670:
3671: <p>The <a href="#command-facet-id" title="command-facet-ID">ID</a> of the command is
3672: the value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> attribute of the
3673: element, if the attribute is present and not empty. Otherwise the
3674: command is an <a href="#anonymous-command">anonymous command</a>.</p>
3675:
3676: <p>The <a href="#command-facet-label" title="command-facet-Label">Label</a> of the command
3677: depends on the element. If the element is a <a href="forms.html#labeled-control">labeled
3678: control</a>, the <code>textContent</code> of the first
3679: <code><a href="forms.html#the-label-element">label</a></code> element in <a href="infrastructure.html#tree-order">tree order</a> whose
3680: <a href="forms.html#labeled-control">labeled control</a> is the element in question is the <a href="#command-facet-label" title="command-facet-Label">Label</a> (in DOM terms, this is the
3681: string given by <code><var title="">element</var>.labels[0].textContent</code>). Otherwise, the
3682: <a href="#command-facet-label" title="command-facet-Label">Label</a> is the
3683: <code>textContent</code> of the element itself.</p>
3684:
3685: <p>The <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> of the command
3686: is the value of the <code title="attr-title"><a href="dom.html#the-title-attribute">title</a></code> attribute
3687: of the element. If the attribute is not present, the <a href="#command-facet-hint" title="command-facet-Hint">Hint</a> is the empty string.</p>
3688:
3689: <p>There is no <a href="#command-facet-icon" title="command-facet-Icon">Icon</a> for the
3690: command.</p>
3691:
3692: <p>The <a href="#command-facet-accesskey" title="command-facet-AccessKey">AccessKey</a> of the
3693: command is the element's <a href="editing.html#assigned-access-key">assigned access key</a>.</p>
3694:
3695: <p>The <a href="#command-facet-hiddenstate" title="command-facet-HiddenState">Hidden State</a>
3696: of the command is true (hidden) if the element has a <code title="attr-hidden"><a href="editing.html#the-hidden-attribute">hidden</a></code> attribute, and false
3697: otherwise.</p>
3698:
3699: <p>The <a href="#command-facet-disabledstate" title="command-facet-DisabledState">Disabled
3700: State</a> facet of the command is always false. (The command is
3701: always enabled.)</p>
3702:
3703: <p>The <a href="#command-facet-checkedstate" title="command-facet-CheckedState">Checked State</a>
3704: of the command is always false. (The command is never checked.)</p>
3705:
3706: <p>The <a href="#command-facet-action" title="command-facet-Action">Action</a> of the
3707: command is to run the <a href="editing.html#focusing-steps">focusing steps</a> for the
3708: element.</p>
3709:
3710: </div><h3 id="miscellaneous-elements"><span class="secno">4.12 </span>Miscellaneous elements</h3><h4 id="the-legend-element"><span class="secno">4.12.1 </span>The <dfn><code>legend</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
3711: <dd>None.</dd>
3712: <dt>Contexts in which this element may be used:</dt>
3713: <dd>As the first child of a <code><a href="forms.html#the-fieldset-element">fieldset</a></code> element.</dd>
3714: <dd>As the first child of a <code><a href="#the-details-element">details</a></code> element.</dd>
3715: <dd>As the first or last child of a <code><a href="embedded-content-0.html#the-figure-element">figure</a></code> element, if there are no other <code><a href="#the-legend-element">legend</a></code> element children of that element.</dd>
3716: <dt>Content model:</dt>
3717: <dd>When the parent node is a <code><a href="embedded-content-0.html#the-figure-element">figure</a></code> element: <a href="dom.html#flow-content-0">flow content</a>, but with no descendant <code><a href="embedded-content-0.html#the-figure-element">figure</a></code> elements.</dd>
3718: <dd>Otherwise: <a href="dom.html#phrasing-content-0">phrasing content</a>.</dd>
3719: <dt>Content attributes:</dt>
3720: <dd><a href="dom.html#global-attributes">Global attributes</a></dd>
3721: <dt>DOM interface:</dt>
3722: <dd>
3723: <pre class="idl">interface <dfn id="htmllegendelement">HTMLLegendElement</dfn> : <a href="dom.html#htmlelement">HTMLElement</a> {
3724: readonly attribute <a href="forms.html#htmlformelement">HTMLFormElement</a> <a href="#dom-legend-form" title="dom-legend-form">form</a>;
3725: };</pre>
3726: </dd>
3727: </dl><p>The <code><a href="#the-legend-element">legend</a></code> element <a href="the-xhtml-syntax.html#represents">represents</a> a title
3728: or explanatory caption for the rest of the contents of the
3729: <code><a href="#the-legend-element">legend</a></code> element's parent element.</p><dl class="domintro"><dt><var title="">legend</var> . <code title="dom-legend-form"><a href="#dom-legend-form">form</a></code></dt>
3730:
3731: <dd>
3732:
3733: <p>Returns the element's <code><a href="forms.html#the-form-element">form</a></code> element, if any, or
3734: null otherwise.</p>
3735:
3736: </dd>
3737:
3738: </dl><div class="impl">
3739:
3740: <p>The <dfn id="dom-legend-form" title="dom-legend-form"><code>form</code></dfn> DOM
3741: attribute's behavior depends on whether the <code><a href="#the-legend-element">legend</a></code>
3742: element is in a <code><a href="forms.html#the-fieldset-element">fieldset</a></code> element or not. If the
3743: <code><a href="#the-legend-element">legend</a></code> has a <code><a href="forms.html#the-fieldset-element">fieldset</a></code> element as its
3744: parent, then the <code title="dom-legend-form"><a href="#dom-legend-form">form</a></code> DOM
3745: attribute must return the same value as the <code title="dom-fae-form"><a href="forms.html#dom-fae-form">form</a></code> DOM attribute on that
3746: <code><a href="forms.html#the-fieldset-element">fieldset</a></code> element. Otherwise, it must return null.</p>
3747:
3748: </div><h4 id="the-div-element"><span class="secno">4.12.2 </span>The <dfn><code>div</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
3749: <dd><a href="dom.html#flow-content-0">Flow content</a>.</dd>
3750: <dd><a href="editing.html#formatblock-candidate"><code title="">formatBlock</code> candidate</a>.</dd>
3751: <dt>Contexts in which this element may be used:</dt>
3752: <dd>Where <a href="dom.html#flow-content-0">flow content</a> is expected.</dd>
3753: <dt>Content model:</dt>
3754: <dd><a href="dom.html#flow-content-0">Flow content</a>.</dd>
3755: <dt>Content attributes:</dt>
3756: <dd><a href="dom.html#global-attributes">Global attributes</a></dd>
3757: <dt>DOM interface:</dt>
3758: <dd>
3759: <pre class="idl">interface <dfn id="htmldivelement">HTMLDivElement</dfn> : <a href="dom.html#htmlelement">HTMLElement</a> {};</pre>
3760: </dd>
3761: </dl><p>The <code><a href="#the-div-element">div</a></code> element has no special meaning at all. It
3762: <a href="the-xhtml-syntax.html#represents">represents</a> its children. It can be used with the <code title="attr-class"><a href="dom.html#classes">class</a></code>, <code title="attr-lang"><a href="dom.html#attr-lang">lang</a></code>, and <code title="attr-title"><a href="dom.html#the-title-attribute">title</a></code> attributes to mark up semantics
3763: common to a group of consecutive elements.</p><p class="note">Authors are strongly encouraged to view the
3764: <code><a href="#the-div-element">div</a></code> element as an element of last resort, for when no
3765: other element is suitable. Use of the <code><a href="#the-div-element">div</a></code> element
3766: instead of more appropriate elements leads to poor accessibility for
3767: readers and poor maintainability for authors.</p><div class="example">
3768:
3769: <p>For example, a blog post would be marked up using
3770: <code><a href="semantics.html#the-article-element">article</a></code>, a chapter using <code><a href="semantics.html#the-section-element">section</a></code>, a
3771: page's navigation aids using <code><a href="semantics.html#the-nav-element">nav</a></code>, and a group of form
3772: controls using <code><a href="forms.html#the-fieldset-element">fieldset</a></code>.</p>
3773:
3774: <p>On the other hand, <code><a href="#the-div-element">div</a></code> elements can be useful for
3775: stylistic purposes or to wrap multiple paragraphs within a section
3776: that are all to be annotated in a similar way. In the following
3777: example, we see <code><a href="#the-div-element">div</a></code> elements used as a way to set the
3778: language of two paragraphs at once, instead of setting the language
3779: on the two paragraph elements separately:</p>
3780:
3781: <pre><article lang="en-US">
3782: <h1>My use of language and my cats</h1>
3783: <p>My cat's behavior hasn't changed much since her absence, except
3784: that she plays her new physique to the neighbors regularly, in an
3785: attempt to get pets.</p>
3786: <div lang="en-GB">
3787: <p>My other cat, coloured black and white, is a sweetie. He followed
3788: us to the pool today, walking down the pavement with us. Yesterday
3789: he apparently visited our neighbours. I wonder if he recognises that
3790: their flat is a mirror image of ours.</p>
3791: <p>Hm, I just noticed that in the last paragraph I used British
3792: English. But I'm supposed to write in American English. So I
3793: shouldn't say "pavement" or "flat" or "colour"...</p>
3794: </div>
3795: <p>I should say "sidewalk" and "apartment" and "color"!</p>
3796: </article></pre>
3797:
3798: </div><div class="impl">
3799:
3800: <h3 id="matching-html-elements-using-selectors"><span class="secno">4.13 </span>Matching HTML elements using selectors</h3>
3801:
3802: <p>There are a number of dynamic selectors that can be used with
3803: HTML. This section defines when these selectors match HTML
3804: elements.</p>
3805:
3806: <dl><dt><dfn id="selector-link" title="selector-link"><code>:link</code></dfn></dt>
3807: <dt><dfn id="selector-visited" title="selector-visited"><code>:visited</code></dfn></dt>
3808:
3809: <dd>
3810:
3811: <p>All <code><a href="text-level-semantics.html#the-a-element">a</a></code> elements that have an <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute, all
3812: <code><a href="the-canvas-element.html#the-area-element">area</a></code> elements that have an <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute, and all
3813: <code><a href="semantics.html#the-link-element">link</a></code> elements that have an <code title="attr-link-href"><a href="semantics.html#attr-link-href">href</a></code> attribute, must match one of
3814: <code title="selector-link"><a href="#selector-link">:link</a></code> and <code title="selector-visited"><a href="#selector-visited">:visited</a></code>.</p>
3815:
3816: </dd>
3817:
3818:
3819: <dt><dfn id="selector-active" title="selector-active"><code>:active</code></dfn></dt>
3820:
3821: <dd>
3822:
3823: <p>The <code title="selector-active"><a href="#selector-active">:active</a></code> pseudo-class
3824: must match the following elements between the time the user begins
3825: to activate the element and the time the users stops activating
3826: the element:</p>
3827:
3828: <ul><li><code><a href="text-level-semantics.html#the-a-element">a</a></code> elements that have an <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute</li>
3829:
3830: <li><code><a href="the-canvas-element.html#the-area-element">area</a></code> elements that have an <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute</li>
3831:
3832: <li><code><a href="semantics.html#the-link-element">link</a></code> elements that have an <code title="attr-link-href"><a href="semantics.html#attr-link-href">href</a></code> attribute</li>
3833:
3834: <li><code><a href="#the-bb-element">bb</a></code> elements whose <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute is in a state whose
3835: <i>relevance</i> is true</li>
3836:
3837: <li><code><a href="forms.html#the-button-element">button</a></code> elements that are not <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3838:
3839: <li><code><a href="forms.html#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute is in the <a href="forms.html#submit-button-state" title="attr-input-type-submit">Submit Button</a>, <a href="forms.html#image-button-state" title="attr-input-type-image">Image Button</a>, <a href="forms.html#reset-button-state" title="attr-input-type-reset">Reset Button</a>, or <a href="forms.html#button-state" title="attr-input-type-button">Button</a> state</li>
3840:
3841: <li><code><a href="#the-command">command</a></code> elements that do not have a <code title="attr-command-disabled"><a href="#attr-command-disabled">disabled</a></code> attribute</li>
3842:
3843: <li>any other element, if it is <a href="editing.html#specially-focusable">specially
3844: focusable</a></li>
3845:
3846: </ul><p class="example">For example, if the user is using a keyboard to
3847: push a <code><a href="forms.html#the-button-element">button</a></code> element by pressing the space bar, the
3848: element would match this pseudo-class in between the time that the
3849: element received the <code title="event-keydown">keydown</code>
3850: event and the time the element received the <code title="event-keyup">keyup</code> event.</p>
3851:
3852: </dd>
3853:
3854:
3855: <dt><dfn id="selector-enabled" title="selector-enabled"><code>:enabled</code></dfn></dt>
3856:
3857: <dd>
3858:
3859: <p>The <code title="selector-enabled"><a href="#selector-enabled">:enabled</a></code> pseudo-class
3860: must match the following elements:</p>
3861:
3862: <ul><li><code><a href="text-level-semantics.html#the-a-element">a</a></code> elements that have an <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute</li>
3863:
3864: <li><code><a href="the-canvas-element.html#the-area-element">area</a></code> elements that have an <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute</li>
3865:
3866: <li><code><a href="semantics.html#the-link-element">link</a></code> elements that have an <code title="attr-link-href"><a href="semantics.html#attr-link-href">href</a></code> attribute</li>
3867:
3868: <li><code><a href="#the-bb-element">bb</a></code> elements whose <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute is in a state whose
3869: <i>relevance</i> is true</li>
3870:
3871: <li><code><a href="forms.html#the-button-element">button</a></code> elements that are not <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3872:
3873: <li><code><a href="forms.html#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute are not in the
3874: <a href="forms.html#hidden-state" title="attr-input-type-hidden">Hidden</a> state and that
3875: are not <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3876:
3877: <li><code><a href="forms.html#the-select-element">select</a></code> elements that are not <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3878:
3879: <li><code><a href="forms.html#the-textarea-element">textarea</a></code> elements that are not <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3880:
3881: <li><code><a href="forms.html#the-option-element">option</a></code> elements that do not have a <code title="attr-option-disabled"><a href="forms.html#attr-option-disabled">disabled</a></code> attribute</li>
3882:
3883: <li><code><a href="#the-command">command</a></code> elements that do not have a <code title="attr-command-disabled"><a href="#attr-command-disabled">disabled</a></code> attribute</li>
3884:
3885: <li><code><a href="semantics.html#the-li-element">li</a></code> elements that are children of
3886: <code><a href="#menus">menu</a></code> elements, and that have a child element that
3887: defines a <a href="#concept-command" title="concept-command">command</a>, if the
3888: first such element's <a href="#command-facet-disabledstate" title="command-facet-disabledstate">Disabled State</a> facet
3889: is false (not disabled)</li>
3890:
3891: </ul></dd>
3892:
3893:
3894: <dt><dfn id="selector-disabled" title="selector-disabled"><code>:disabled</code></dfn></dt>
3895:
3896: <dd>
3897:
3898: <p>The <code title="selector-disabled"><a href="#selector-disabled">:disabled</a></code>
3899: pseudo-class must match the following elements:</p>
3900:
3901: <ul><li><code><a href="#the-bb-element">bb</a></code> elements whose <code title="attr-bb-type"><a href="#attr-bb-type">type</a></code> attribute is in a state whose
3902: <i>relevance</i> is false</li>
3903:
3904: <li><code><a href="forms.html#the-button-element">button</a></code> elements that are <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3905:
3906: <li><code><a href="forms.html#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute are not in the
3907: <a href="forms.html#hidden-state" title="attr-input-type-hidden">Hidden</a> state and that
3908: are <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3909:
3910: <li><code><a href="forms.html#the-select-element">select</a></code> elements that are <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3911:
3912: <li><code><a href="forms.html#the-textarea-element">textarea</a></code> elements that are <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
3913:
3914: <li><code><a href="forms.html#the-option-element">option</a></code> elements that have a <code title="attr-option-disabled"><a href="forms.html#attr-option-disabled">disabled</a></code> attribute</li>
3915:
3916: <li><code><a href="#the-command">command</a></code> elements that have a <code title="attr-command-disabled"><a href="#attr-command-disabled">disabled</a></code> attribute</li>
3917:
3918: <li><code><a href="semantics.html#the-li-element">li</a></code> elements that are children of
3919: <code><a href="#menus">menu</a></code> elements, and that have a child element that
3920: defines a <a href="#concept-command" title="concept-command">command</a>, if the
3921: first such element's <a href="#command-facet-disabledstate" title="command-facet-disabledstate">Disabled State</a> facet
3922: is true (disabled)</li>
3923:
3924: </ul></dd>
3925:
3926:
3927: <dt><dfn id="selector-checked" title="selector-checked"><code>:checked</code></dfn></dt>
3928:
3929: <dd>
3930:
3931: <p>The <code title="selector-checked"><a href="#selector-checked">:checked</a></code> pseudo-class
3932: must match the following elements:</p>
3933:
3934: <ul><li><code><a href="forms.html#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute is in the <a href="forms.html#checkbox-state" title="attr-input-type-checkbox">Checkbox</a> state and whose
3935: <a href="forms.html#concept-fe-checked" title="concept-fe-checked">checkedness</a> state is
3936: true</li>
3937:
3938: <li><code><a href="forms.html#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute is in the <a href="forms.html#radio-button-state" title="attr-input-type-radio">Radio Button</a> state and whose
3939: <a href="forms.html#concept-fe-checked" title="concept-fe-checked">checkedness</a> state is
3940: true</li>
3941:
3942: <li><code><a href="#the-command">command</a></code> elements whose <code title="attr-command-type"><a href="#attr-command-type">type</a></code> attribute is in the <a href="#attr-command-type-state-checkbox" title="attr-command-type-state-checkbox">Checkbox</a> state
3943: and that have a <code title="attr-command-checked"><a href="#attr-command-checked">checked</a></code>
3944: attribute</li>
3945:
3946: <li><code><a href="#the-command">command</a></code> elements whose <code title="attr-command-type"><a href="#attr-command-type">type</a></code> attribute is in the <a href="#attr-command-type-state-radio" title="attr-command-type-state-radio">Radio</a> state and that
3947: have a <code title="attr-command-checked"><a href="#attr-command-checked">checked</a></code>
3948: attribute</li>
3949:
3950: </ul></dd>
3951:
3952:
3953: <dt><dfn id="selector-indeterminate" title="selector-indeterminate"><code>:indeterminate</code></dfn></dt>
3954:
3955: <dd>
3956:
3957: <p>The <code title="selector-indeterminate"><a href="#selector-indeterminate">:indeterminate</a></code>
3958: pseudo-class must match <code><a href="forms.html#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute is in the <a href="forms.html#checkbox-state" title="attr-input-type-checkbox">Checkbox</a> state and whose
3959: <code title="dom-input-indeterminate"><a href="forms.html#dom-input-indeterminate">indeterminate</a></code> DOM
3960: attribute is set to true.</p>
3961:
3962: </dd>
3963:
3964:
3965: <dt><dfn id="selector-default" title="selector-default"><code>:default</code></dfn></dt>
3966:
3967: <dd>
3968:
3969: <p>The <code title="selector-default"><a href="#selector-default">:default</a></code> pseudo-class
3970: must match the following elements:</p>
3971:
3972: <ul><li><code><a href="forms.html#the-button-element">button</a></code> elements that are their form's
3973: <a href="forms.html#default-button">default button</a></li>
3974:
3975: <li><code><a href="forms.html#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="forms.html#attr-input-type">type</a></code> attribute is in the <a href="forms.html#submit-button-state" title="attr-input-type-submit">Submit Button</a> or <a href="forms.html#image-button-state" title="attr-input-type-image">Image Button</a> state, and that
3976: are their form's <a href="forms.html#default-button">default button</a></li>
3977: <!--
3978: <li><code>command</code> elements that have a <code
3979: title="attr-command-default">default</code> attribute</li>
3980: -->
3981: </ul></dd>
3982:
3983:
3984: <dt><dfn id="selector-valid" title="selector-valid"><code>:valid</code></dfn></dt>
3985:
3986: <dd>
3987:
3988: <p>The <code title="selector-valid"><a href="#selector-valid">:valid</a></code> pseudo-class
3989: must match all elements that are <a href="forms.html#candidate-for-constraint-validation" title="candidate for
3990: constraint validation">candidates for constraint validation</a>
3991: and that <a href="forms.html#concept-fv-valid" title="concept-fv-valid">satisfy their
3992: constraints</a>.</p>
3993:
3994: </dd>
3995:
3996:
3997: <dt><dfn id="selector-invalid" title="selector-invalid"><code>:invalid</code></dfn></dt>
3998:
3999: <dd>
4000:
4001: <p>The <code title="selector-invalid"><a href="#selector-invalid">:invalid</a></code> pseudo-class
4002: must match all elements that are <a href="forms.html#candidate-for-constraint-validation" title="candidate for
4003: constraint validation">candidates for constraint validation</a>
4004: but that do not <a href="forms.html#concept-fv-valid" title="concept-fv-valid">satisfy their
4005: constraints</a>.</p>
4006:
4007: </dd>
4008:
4009:
4010: <dt><dfn id="selector-in-range" title="selector-in-range"><code>:in-range</code></dfn></dt>
4011:
4012: <dd>
4013:
4014: <p>The <code title="selector-in-range"><a href="#selector-in-range">:in-range</a></code>
4015: pseudo-class must match all elements that are <a href="forms.html#candidate-for-constraint-validation" title="candidate for constraint validation">candidates for
4016: constraint validation</a> and that are neither <a href="forms.html#suffering-from-an-underflow">suffering
4017: from an underflow</a> nor <a href="forms.html#suffering-from-an-overflow">suffering from an
4018: overflow</a>.</p>
4019:
4020: </dd>
4021:
4022:
4023: <dt><dfn id="selector-out-of-range" title="selector-out-of-range"><code>:out-of-range</code></dfn></dt>
4024:
4025: <dd>
4026:
4027: <p>The <code title="selector-out-of-range"><a href="#selector-out-of-range">:out-of-range</a></code>
4028: pseudo-class must match all elements that are <a href="forms.html#candidate-for-constraint-validation" title="candidate for constraint validation">candidates for
4029: constraint validation</a> and that are <a href="forms.html#suffering-from-an-underflow">suffering from an
4030: underflow</a> or <a href="forms.html#suffering-from-an-overflow">suffering from an overflow</a>.</p>
4031:
4032: </dd>
4033:
4034:
4035: <dt><dfn id="selector-required" title="selector-required"><code>:required</code></dfn></dt>
4036:
4037: <dd>
4038:
4039: <p>The <code title="selector-required"><a href="#selector-required">:required</a></code>
4040: pseudo-class must match the following elements:</p>
4041:
4042: <ul><li><code><a href="forms.html#the-input-element">input</a></code> elements that are <i title="concept-input-required"><a href="forms.html#concept-input-required">required</a></i></li>
4043:
4044: <li><code><a href="forms.html#the-textarea-element">textarea</a></code> elements that have a <code title="attr-textarea-required"><a href="forms.html#attr-textarea-required">required</a></code>
4045: attribute</li>
4046:
4047: </ul></dd>
4048:
4049:
4050: <dt><dfn id="selector-optional" title="selector-optional"><code>:optional</code></dfn></dt>
4051:
4052: <dd>
4053:
4054: <p>The <code title="selector-optional"><a href="#selector-optional">:optional</a></code>
4055: pseudo-class must match the following elements:</p>
4056:
4057: <ul><li><code><a href="forms.html#the-button-element">button</a></code> elements</li>
4058:
4059: <li><code><a href="forms.html#the-input-element">input</a></code> elements that are not <i title="concept-input-required"><a href="forms.html#concept-input-required">required</a></i></li>
4060:
4061: <li><code><a href="forms.html#the-select-element">select</a></code> elements</li>
4062:
4063: <li><code><a href="forms.html#the-textarea-element">textarea</a></code> elements that do not have a <code title="attr-textarea-required"><a href="forms.html#attr-textarea-required">required</a></code>
4064: attribute</li>
4065:
4066: </ul></dd>
4067:
4068:
4069: <dt><dfn id="selector-read-only" title="selector-read-only"><code>:read-only</code></dfn></dt>
4070: <dt><dfn id="selector-read-write" title="selector-read-write"><code>:read-write</code></dfn></dt>
4071:
4072: <dd>
4073:
4074: <p>The <code title="selector-read-write"><a href="#selector-read-write">:read-write</a></code>
4075: pseudo-class must match the following elements:</p>
4076:
4077: <ul><li><code><a href="forms.html#the-input-element">input</a></code> elements to which the <code title="attr-input-readonly"><a href="forms.html#attr-input-readonly">readonly</a></code> attribute applies,
4078: but that are not <i title="concept-input-immutable"><a href="forms.html#concept-input-immutable">immutable</a></i>
4079: (i.e. that do not have the <code title="attr-input-readonly"><a href="forms.html#attr-input-readonly">readonly</a></code> attribute specified
4080: and that are not <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a>)</li>
4081:
4082: <li><code><a href="forms.html#the-textarea-element">textarea</a></code> elements that do not have a <code title="attr-textarea-readonly"><a href="forms.html#attr-textarea-readonly">readonly</a></code> attribute, and
4083: that are not <a href="forms.html#concept-fe-disabled" title="concept-fe-disabled">disabled</a></li>
4084:
4085: <li>any element that is <a href="editing.html#editable">editable</a></li>
4086:
4087: </ul><p>The <code title="selector-read-only"><a href="#selector-read-only">:read-only</a></code>
4088: pseudo-class must match all other <a href="infrastructure.html#html-elements">HTML elements</a>.</p>
4089:
4090: </dd>
4091:
4092: </dl><p class="note">Another section of this specification defines the
4093: <i><a href="history.html#target-element">target element</a></i> used with the <code title="selector-target">:target</code> pseudo-class.</p>
4094:
4095: <p class="note">This specification does not define when an element
4096: matches the <code title="selector-hover">:hover</code>, <code title="selector-focus">:focus</code>, or <code title="selector-lang()">:lang()</code> dynamic pseudo-classes, as
4097: those are all defined in sufficient detail in a language-agnostic
4098: fashion in the Selectors specification. <a href="references.html#references">[SELECTORS]</a></p>
4099:
4100: </div></body></html>
Webmaster
![[BACK]](/https/dev.w3.org/cvsweb/icons/back.gif){kind=icon}
Return to interactive-elements.html CVS log ![[TXT]](/https/dev.w3.org/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/https/dev.w3.org/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / html5 / spec