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