Debian Codegraph @

closure-library/closure/goog/ui/tree/treecontrol.js

raw
1 // Copyright 2007 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Definition of the goog.ui.tree.TreeControl class, which
17 * provides a way to view a hierarchical set of data.
18 *
19 * @author [email protected] (Erik Arvidsson)
20 * @author [email protected] (Emil A Eklund)
21 *
22 * This is a based on the webfx tree control. It since been updated to add
23 * typeahead support, as well as accessibility support using ARIA framework.
24 *
25 * @see ../../demos/tree/demo.html
26 */
27
28 goog.provide('goog.ui.tree.TreeControl');
29
30 goog.require('goog.a11y.aria');
31 goog.require('goog.asserts');
32 goog.require('goog.dom.classlist');
33 goog.require('goog.events.EventType');
34 goog.require('goog.events.FocusHandler');
35 goog.require('goog.events.KeyHandler');
36 goog.require('goog.html.SafeHtml');
37 goog.require('goog.log');
38 goog.require('goog.ui.tree.BaseNode');
39 goog.require('goog.ui.tree.TreeNode');
40 goog.require('goog.ui.tree.TypeAhead');
41 goog.require('goog.userAgent');
42
43
44
45 /**
46 * This creates a TreeControl object. A tree control provides a way to
47 * view a hierarchical set of data.
48 * @param {string|!goog.html.SafeHtml} content The content of the node label.
49 * Strings are treated as plain-text and will be HTML escaped.
50 * @param {Object=} opt_config The configuration for the tree. See
51 * goog.ui.tree.TreeControl.defaultConfig. If not specified, a default config
52 * will be used.
53 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper.
54 * @constructor
55 * @extends {goog.ui.tree.BaseNode}
56 */
57 goog.ui.tree.TreeControl = function(content, opt_config, opt_domHelper) {
58 goog.ui.tree.BaseNode.call(this, content, opt_config, opt_domHelper);
59
60 // The root is open and selected by default.
61 this.setExpandedInternal(true);
62 this.setSelectedInternal(true);
63
64 this.selectedItem_ = this;
65
66 /**
67 * Used for typeahead support.
68 * @private {!goog.ui.tree.TypeAhead}
69 */
70 this.typeAhead_ = new goog.ui.tree.TypeAhead();
71
72 /**
73 * The object handling keyboard events.
74 * @private {?goog.events.KeyHandler}
75 */
76 this.keyHandler_ = null;
77
78 /**
79 * The object handling focus events.
80 * @private {?goog.events.FocusHandler}
81 */
82 this.focusHandler_ = null;
83
84 /**
85 * Logger
86 * @private {?goog.log.Logger}
87 */
88 this.logger_ = goog.log.getLogger('this');
89
90 /**
91 * Whether the tree is focused.
92 * @private {boolean}
93 */
94 this.focused_ = false;
95
96 /**
97 * Child node that currently has focus.
98 * @private {?goog.ui.tree.BaseNode}
99 */
100 this.focusedNode_ = null;
101
102 /**
103 * Whether to show lines.
104 * @private {boolean}
105 */
106 this.showLines_ = true;
107
108 /**
109 * Whether to show expanded lines.
110 * @private {boolean}
111 */
112 this.showExpandIcons_ = true;
113
114 /**
115 * Whether to show the root node.
116 * @private {boolean}
117 */
118 this.showRootNode_ = true;
119
120 /**
121 * Whether to show the root lines.
122 * @private {boolean}
123 */
124 this.showRootLines_ = true;
125
126 if (goog.userAgent.IE) {
127
128 try {
129 // works since IE6SP1
130 document.execCommand('BackgroundImageCache', false, true);
131 } catch (e) {
132 goog.log.warning(this.logger_, 'Failed to enable background image cache');
133 }
134 }
135 };
136 goog.inherits(goog.ui.tree.TreeControl, goog.ui.tree.BaseNode);
137
138
139 /** @override */
140 goog.ui.tree.TreeControl.prototype.getTree = function() {
141 return this;
142 };
143
144
145 /** @override */
146 goog.ui.tree.TreeControl.prototype.getDepth = function() {
147 return 0;
148 };
149
150
151 /**
152 * Expands the parent chain of this node so that it is visible.
153 * @override
154 */
155 goog.ui.tree.TreeControl.prototype.reveal = function() {
156 // always expanded by default
157 // needs to be overriden so that we don't try to reveal our parent
158 // which is a generic component
159 };
160
161
162 /**
163 * Handles focus on the tree.
164 * @param {!goog.events.BrowserEvent} e The browser event.
165 * @private
166 */
167 goog.ui.tree.TreeControl.prototype.handleFocus_ = function(e) {
168 this.focused_ = true;
169 goog.dom.classlist.add(
170 goog.asserts.assert(this.getElement()), goog.getCssName('focused'));
171
172 if (this.selectedItem_) {
173 this.selectedItem_.select();
174 }
175 };
176
177
178 /**
179 * Handles blur on the tree.
180 * @param {!goog.events.BrowserEvent} e The browser event.
181 * @private
182 */
183 goog.ui.tree.TreeControl.prototype.handleBlur_ = function(e) {
184 this.focused_ = false;
185 goog.dom.classlist.remove(
186 goog.asserts.assert(this.getElement()), goog.getCssName('focused'));
187 };
188
189
190 /**
191 * @return {boolean} Whether the tree has keyboard focus.
192 */
193 goog.ui.tree.TreeControl.prototype.hasFocus = function() {
194 return this.focused_;
195 };
196
197
198 /** @override */
199 goog.ui.tree.TreeControl.prototype.getExpanded = function() {
200 return !this.showRootNode_ ||
201 goog.ui.tree.TreeControl.superClass_.getExpanded.call(this);
202 };
203
204
205 /** @override */
206 goog.ui.tree.TreeControl.prototype.setExpanded = function(expanded) {
207 if (!this.showRootNode_) {
208 this.setExpandedInternal(expanded);
209 } else {
210 goog.ui.tree.TreeControl.superClass_.setExpanded.call(this, expanded);
211 }
212 };
213
214
215 /** @override */
216 goog.ui.tree.TreeControl.prototype.getExpandIconSafeHtml = function() {
217 // no expand icon for root element
218 return goog.html.SafeHtml.EMPTY;
219 };
220
221
222 /** @override */
223 goog.ui.tree.TreeControl.prototype.getIconElement = function() {
224 var el = this.getRowElement();
225 return el ? /** @type {Element} */ (el.firstChild) : null;
226 };
227
228
229 /** @override */
230 goog.ui.tree.TreeControl.prototype.getExpandIconElement = function() {
231 // no expand icon for root element
232 return null;
233 };
234
235
236 /** @override */
237 goog.ui.tree.TreeControl.prototype.updateExpandIcon = function() {
238 // no expand icon
239 };
240
241
242 /** @override */
243 goog.ui.tree.TreeControl.prototype.getRowClassName = function() {
244 return goog.ui.tree.TreeControl.superClass_.getRowClassName.call(this) +
245 (this.showRootNode_ ? '' : ' ' + this.getConfig().cssHideRoot);
246 };
247
248
249 /**
250 * Returns the source for the icon.
251 * @return {string} Src for the icon.
252 * @override
253 */
254 goog.ui.tree.TreeControl.prototype.getCalculatedIconClass = function() {
255 var expanded = this.getExpanded();
256 var expandedIconClass = this.getExpandedIconClass();
257 if (expanded && expandedIconClass) {
258 return expandedIconClass;
259 }
260 var iconClass = this.getIconClass();
261 if (!expanded && iconClass) {
262 return iconClass;
263 }
264
265 // fall back on default icons
266 var config = this.getConfig();
267 if (expanded && config.cssExpandedRootIcon) {
268 return config.cssTreeIcon + ' ' + config.cssExpandedRootIcon;
269 } else if (!expanded && config.cssCollapsedRootIcon) {
270 return config.cssTreeIcon + ' ' + config.cssCollapsedRootIcon;
271 }
272 return '';
273 };
274
275
276 /**
277 * Sets the selected item.
278 * @param {goog.ui.tree.BaseNode} node The item to select.
279 */
280 goog.ui.tree.TreeControl.prototype.setSelectedItem = function(node) {
281 if (this.selectedItem_ == node) {
282 return;
283 }
284
285 var hadFocus = false;
286 if (this.selectedItem_) {
287 hadFocus = this.selectedItem_ == this.focusedNode_;
288 this.selectedItem_.setSelectedInternal(false);
289 }
290
291 this.selectedItem_ = node;
292
293 if (node) {
294 node.setSelectedInternal(true);
295 if (hadFocus) {
296 node.select();
297 }
298 }
299
300 this.dispatchEvent(goog.events.EventType.CHANGE);
301 };
302
303
304 /**
305 * Returns the selected item.
306 * @return {goog.ui.tree.BaseNode} The currently selected item.
307 */
308 goog.ui.tree.TreeControl.prototype.getSelectedItem = function() {
309 return this.selectedItem_;
310 };
311
312
313 /**
314 * Sets whether to show lines.
315 * @param {boolean} b Whether to show lines.
316 */
317 goog.ui.tree.TreeControl.prototype.setShowLines = function(b) {
318 if (this.showLines_ != b) {
319 this.showLines_ = b;
320 if (this.isInDocument()) {
321 this.updateLinesAndExpandIcons_();
322 }
323 }
324 };
325
326
327 /**
328 * @return {boolean} Whether to show lines.
329 */
330 goog.ui.tree.TreeControl.prototype.getShowLines = function() {
331 return this.showLines_;
332 };
333
334
335 /**
336 * Updates the lines after the tree has been drawn.
337 * @private
338 */
339 goog.ui.tree.TreeControl.prototype.updateLinesAndExpandIcons_ = function() {
340 var tree = this;
341 var showLines = tree.getShowLines();
342 var showRootLines = tree.getShowRootLines();
343
344 /**
345 * Recursively walk through all nodes and update the class names of the
346 * expand icon and the children element.
347 * @param {!goog.ui.tree.BaseNode} node
348 */
349 function updateShowLines(node) {
350 var childrenEl = node.getChildrenElement();
351 if (childrenEl) {
352 var hideLines = !showLines || tree == node.getParent() && !showRootLines;
353 var childClass = hideLines ? node.getConfig().cssChildrenNoLines :
354 node.getConfig().cssChildren;
355 childrenEl.className = childClass;
356
357 var expandIconEl = node.getExpandIconElement();
358 if (expandIconEl) {
359 expandIconEl.className = node.getExpandIconClass();
360 }
361 }
362 node.forEachChild(updateShowLines);
363 }
364 updateShowLines(this);
365 };
366
367
368 /**
369 * Sets whether to show root lines.
370 * @param {boolean} b Whether to show root lines.
371 */
372 goog.ui.tree.TreeControl.prototype.setShowRootLines = function(b) {
373 if (this.showRootLines_ != b) {
374 this.showRootLines_ = b;
375 if (this.isInDocument()) {
376 this.updateLinesAndExpandIcons_();
377 }
378 }
379 };
380
381
382 /**
383 * @return {boolean} Whether to show root lines.
384 */
385 goog.ui.tree.TreeControl.prototype.getShowRootLines = function() {
386 return this.showRootLines_;
387 };
388
389
390 /**
391 * Sets whether to show expand icons.
392 * @param {boolean} b Whether to show expand icons.
393 */
394 goog.ui.tree.TreeControl.prototype.setShowExpandIcons = function(b) {
395 if (this.showExpandIcons_ != b) {
396 this.showExpandIcons_ = b;
397 if (this.isInDocument()) {
398 this.updateLinesAndExpandIcons_();
399 }
400 }
401 };
402
403
404 /**
405 * @return {boolean} Whether to show expand icons.
406 */
407 goog.ui.tree.TreeControl.prototype.getShowExpandIcons = function() {
408 return this.showExpandIcons_;
409 };
410
411
412 /**
413 * Sets whether to show the root node.
414 * @param {boolean} b Whether to show the root node.
415 */
416 goog.ui.tree.TreeControl.prototype.setShowRootNode = function(b) {
417 if (this.showRootNode_ != b) {
418 this.showRootNode_ = b;
419 if (this.isInDocument()) {
420 var el = this.getRowElement();
421 if (el) {
422 el.className = this.getRowClassName();
423 }
424 }
425 // Ensure that we do not hide the selected item.
426 if (!b && this.getSelectedItem() == this && this.getFirstChild()) {
427 this.setSelectedItem(this.getFirstChild());
428 }
429 }
430 };
431
432
433 /**
434 * @return {boolean} Whether to show the root node.
435 */
436 goog.ui.tree.TreeControl.prototype.getShowRootNode = function() {
437 return this.showRootNode_;
438 };
439
440
441 /**
442 * Add roles and states.
443 * @protected
444 * @override
445 */
446 goog.ui.tree.TreeControl.prototype.initAccessibility = function() {
447 goog.ui.tree.TreeControl.superClass_.initAccessibility.call(this);
448
449 var elt = this.getElement();
450 goog.asserts.assert(elt, 'The DOM element for the tree cannot be null.');
451 goog.a11y.aria.setRole(elt, 'tree');
452 goog.a11y.aria.setState(elt, 'labelledby', this.getLabelElement().id);
453 };
454
455
456 /** @override */
457 goog.ui.tree.TreeControl.prototype.enterDocument = function() {
458 goog.ui.tree.TreeControl.superClass_.enterDocument.call(this);
459 var el = this.getElement();
460 el.className = this.getConfig().cssRoot;
461 el.setAttribute('hideFocus', 'true');
462 this.attachEvents_();
463 this.initAccessibility();
464 };
465
466
467 /** @override */
468 goog.ui.tree.TreeControl.prototype.exitDocument = function() {
469 goog.ui.tree.TreeControl.superClass_.exitDocument.call(this);
470 this.detachEvents_();
471 };
472
473
474 /**
475 * Adds the event listeners to the tree.
476 * @private
477 */
478 goog.ui.tree.TreeControl.prototype.attachEvents_ = function() {
479 var el = this.getElement();
480 el.tabIndex = 0;
481
482 var kh = this.keyHandler_ = new goog.events.KeyHandler(el);
483 var fh = this.focusHandler_ = new goog.events.FocusHandler(el);
484
485 this.getHandler()
486 .listen(fh, goog.events.FocusHandler.EventType.FOCUSOUT, this.handleBlur_)
487 .listen(fh, goog.events.FocusHandler.EventType.FOCUSIN, this.handleFocus_)
488 .listen(kh, goog.events.KeyHandler.EventType.KEY, this.handleKeyEvent)
489 .listen(el, goog.events.EventType.MOUSEDOWN, this.handleMouseEvent_)
490 .listen(el, goog.events.EventType.CLICK, this.handleMouseEvent_)
491 .listen(el, goog.events.EventType.DBLCLICK, this.handleMouseEvent_);
492 };
493
494
495 /**
496 * Removes the event listeners from the tree.
497 * @private
498 */
499 goog.ui.tree.TreeControl.prototype.detachEvents_ = function() {
500 this.keyHandler_.dispose();
501 this.keyHandler_ = null;
502 this.focusHandler_.dispose();
503 this.focusHandler_ = null;
504 };
505
506
507 /**
508 * Handles mouse events.
509 * @param {!goog.events.BrowserEvent} e The browser event.
510 * @private
511 */
512 goog.ui.tree.TreeControl.prototype.handleMouseEvent_ = function(e) {
513 goog.log.fine(this.logger_, 'Received event ' + e.type);
514 var node = this.getNodeFromEvent_(e);
515 if (node) {
516 switch (e.type) {
517 case goog.events.EventType.MOUSEDOWN:
518 node.onMouseDown(e);
519 break;
520 case goog.events.EventType.CLICK:
521 node.onClick_(e);
522 break;
523 case goog.events.EventType.DBLCLICK:
524 node.onDoubleClick_(e);
525 break;
526 }
527 }
528 };
529
530
531 /**
532 * Handles key down on the tree.
533 * @param {!goog.events.BrowserEvent} e The browser event.
534 * @return {boolean} The handled value.
535 */
536 goog.ui.tree.TreeControl.prototype.handleKeyEvent = function(e) {
537 var handled = false;
538
539 // Handle typeahead and navigation keystrokes.
540 handled = this.typeAhead_.handleNavigation(e) ||
541 (this.selectedItem_ && this.selectedItem_.onKeyDown(e)) ||
542 this.typeAhead_.handleTypeAheadChar(e);
543
544 if (handled) {
545 e.preventDefault();
546 }
547
548 return handled;
549 };
550
551
552 /**
553 * Finds the containing node given an event.
554 * @param {!goog.events.BrowserEvent} e The browser event.
555 * @return {goog.ui.tree.BaseNode} The containing node or null if no node is
556 * found.
557 * @private
558 */
559 goog.ui.tree.TreeControl.prototype.getNodeFromEvent_ = function(e) {
560 // find the right node
561 var node = null;
562 var target = e.target;
563 while (target != null) {
564 var id = target.id;
565 node = goog.ui.tree.BaseNode.allNodes[id];
566 if (node) {
567 return node;
568 }
569 if (target == this.getElement()) {
570 break;
571 }
572 target = target.parentNode;
573 }
574 return null;
575 };
576
577
578 /**
579 * Creates a new tree node using the same config as the root.
580 * @param {string=} opt_content The content of the node label. Strings are
581 * treated as plain-text and will be HTML escaped. To set SafeHtml content,
582 * omit opt_content and call setSafeHtml on the resulting node.
583 * @return {!goog.ui.tree.TreeNode} The new item.
584 */
585 goog.ui.tree.TreeControl.prototype.createNode = function(opt_content) {
586 return new goog.ui.tree.TreeNode(opt_content || goog.html.SafeHtml.EMPTY,
587 this.getConfig(), this.getDomHelper());
588 };
589
590
591 /**
592 * Allows the caller to notify that the given node has been added or just had
593 * been updated in the tree.
594 * @param {goog.ui.tree.BaseNode} node New node being added or existing node
595 * that just had been updated.
596 */
597 goog.ui.tree.TreeControl.prototype.setNode = function(node) {
598 this.typeAhead_.setNodeInMap(node);
599 };
600
601
602 /**
603 * Allows the caller to notify that the given node is being removed from the
604 * tree.
605 * @param {goog.ui.tree.BaseNode} node Node being removed.
606 */
607 goog.ui.tree.TreeControl.prototype.removeNode = function(node) {
608 this.typeAhead_.removeNodeFromMap(node);
609 };
610
611
612 /**
613 * Clear the typeahead buffer.
614 */
615 goog.ui.tree.TreeControl.prototype.clearTypeAhead = function() {
616 this.typeAhead_.clear();
617 };
618
619
620 /**
621 * A default configuration for the tree.
622 */
623 goog.ui.tree.TreeControl.defaultConfig = goog.ui.tree.BaseNode.defaultConfig;