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