Debian Codegraph @

closure-library/closure/goog/ui/control.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 Base class for UI controls such as buttons, menus, menu items,
17 * toolbar buttons, etc. The implementation is based on a generalized version
18 * of {@link goog.ui.MenuItem}.
19 * TODO(attila): If the renderer framework works well, pull it into Component.
20 *
21 * @author [email protected] (Attila Bodis)
22 * @see ../demos/control.html
23 * @see http://code.google.com/p/closure-library/wiki/IntroToControls
24 */
25
26 goog.provide('goog.ui.Control');
27
28 goog.require('goog.Disposable');
29 goog.require('goog.array');
30 goog.require('goog.dom');
31 goog.require('goog.events.BrowserEvent');
32 goog.require('goog.events.Event');
33 goog.require('goog.events.EventHandler');
34 goog.require('goog.events.EventType');
35 goog.require('goog.events.KeyCodes');
36 goog.require('goog.events.KeyHandler');
37 goog.require('goog.string');
38 goog.require('goog.ui.Component');
39 /** @suppress {extraRequire} */
40 goog.require('goog.ui.ControlContent');
41 goog.require('goog.ui.ControlRenderer');
42 goog.require('goog.ui.registry');
43 goog.require('goog.userAgent');
44
45
46
47 /**
48 * Base class for UI controls. Extends {@link goog.ui.Component} by adding
49 * the following:
50 * <ul>
51 * <li>a {@link goog.events.KeyHandler}, to simplify keyboard handling,
52 * <li>a pluggable <em>renderer</em> framework, to simplify the creation of
53 * simple controls without the need to subclass this class,
54 * <li>the notion of component <em>content</em>, like a text caption or DOM
55 * structure displayed in the component (e.g. a button label),
56 * <li>getter and setter for component content, as well as a getter and
57 * setter specifically for caption text (for convenience),
58 * <li>support for hiding/showing the component,
59 <li>fine-grained control over supported states and state transition
60 events, and
61 * <li>default mouse and keyboard event handling.
62 * </ul>
63 * This class has sufficient built-in functionality for most simple UI controls.
64 * All controls dispatch SHOW, HIDE, ENTER, LEAVE, and ACTION events on show,
65 * hide, mouseover, mouseout, and user action, respectively. Additional states
66 * are also supported. See closure/demos/control.html
67 * for example usage.
68 * @param {goog.ui.ControlContent=} opt_content Text caption or DOM structure
69 * to display as the content of the control (if any).
70 * @param {goog.ui.ControlRenderer=} opt_renderer Renderer used to render or
71 * decorate the component; defaults to {@link goog.ui.ControlRenderer}.
72 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper, used for
73 * document interaction.
74 * @constructor
75 * @extends {goog.ui.Component}
76 */
77 goog.ui.Control = function(opt_content, opt_renderer, opt_domHelper) {
78 goog.ui.Component.call(this, opt_domHelper);
79 this.renderer_ =
80 opt_renderer || goog.ui.registry.getDefaultRenderer(this.constructor);
81 this.setContentInternal(goog.isDef(opt_content) ? opt_content : null);
82
83 /** @private {?string} The control's aria-label. */
84 this.ariaLabel_ = null;
85
86 /** @private {goog.ui.Control.IeMouseEventSequenceSimulator_} */
87 this.ieMouseEventSequenceSimulator_;
88 };
89 goog.inherits(goog.ui.Control, goog.ui.Component);
90 goog.tagUnsealableClass(goog.ui.Control);
91
92
93 // Renderer registry.
94 // TODO(attila): Refactor existing usages inside Google in a follow-up CL.
95
96
97 /**
98 * Maps a CSS class name to a function that returns a new instance of
99 * {@link goog.ui.Control} or a subclass thereof, suitable to decorate
100 * an element that has the specified CSS class. UI components that extend
101 * {@link goog.ui.Control} and want {@link goog.ui.Container}s to be able
102 * to discover and decorate elements using them should register a factory
103 * function via this API.
104 * @param {string} className CSS class name.
105 * @param {Function} decoratorFunction Function that takes no arguments and
106 * returns a new instance of a control to decorate an element with the
107 * given class.
108 * @deprecated Use {@link goog.ui.registry.setDecoratorByClassName} instead.
109 */
110 goog.ui.Control.registerDecorator = goog.ui.registry.setDecoratorByClassName;
111
112
113 /**
114 * Takes an element and returns a new instance of {@link goog.ui.Control}
115 * or a subclass, suitable to decorate it (based on the element's CSS class).
116 * @param {Element} element Element to decorate.
117 * @return {goog.ui.Control?} New control instance to decorate the element
118 * (null if none).
119 * @deprecated Use {@link goog.ui.registry.getDecorator} instead.
120 */
121 goog.ui.Control.getDecorator =
122 /** @type {function(Element): goog.ui.Control} */ (
123 goog.ui.registry.getDecorator);
124
125
126 /**
127 * Renderer associated with the component.
128 * @type {goog.ui.ControlRenderer|undefined}
129 * @private
130 */
131 goog.ui.Control.prototype.renderer_;
132
133
134 /**
135 * Text caption or DOM structure displayed in the component.
136 * @type {goog.ui.ControlContent}
137 * @private
138 */
139 goog.ui.Control.prototype.content_ = null;
140
141
142 /**
143 * Current component state; a bit mask of {@link goog.ui.Component.State}s.
144 * @type {number}
145 * @private
146 */
147 goog.ui.Control.prototype.state_ = 0x00;
148
149
150 /**
151 * A bit mask of {@link goog.ui.Component.State}s this component supports.
152 * @type {number}
153 * @private
154 */
155 goog.ui.Control.prototype.supportedStates_ = goog.ui.Component.State.DISABLED |
156 goog.ui.Component.State.HOVER | goog.ui.Component.State.ACTIVE |
157 goog.ui.Component.State.FOCUSED;
158
159
160 /**
161 * A bit mask of {@link goog.ui.Component.State}s for which this component
162 * provides default event handling. For example, a component that handles
163 * the HOVER state automatically will highlight itself on mouseover, whereas
164 * a component that doesn't handle HOVER automatically will only dispatch
165 * ENTER and LEAVE events but not call {@link setHighlighted} on itself.
166 * By default, components provide default event handling for all states.
167 * Controls hosted in containers (e.g. menu items in a menu, or buttons in a
168 * toolbar) will typically want to have their container manage their highlight
169 * state. Selectable controls managed by a selection model will also typically
170 * want their selection state to be managed by the model.
171 * @type {number}
172 * @private
173 */
174 goog.ui.Control.prototype.autoStates_ = goog.ui.Component.State.ALL;
175
176
177 /**
178 * A bit mask of {@link goog.ui.Component.State}s for which this component
179 * dispatches state transition events. Because events are expensive, the
180 * default behavior is to not dispatch any state transition events at all.
181 * Use the {@link #setDispatchTransitionEvents} API to request transition
182 * events as needed. Subclasses may enable transition events by default.
183 * Controls hosted in containers or managed by a selection model will typically
184 * want to dispatch transition events.
185 * @type {number}
186 * @private
187 */
188 goog.ui.Control.prototype.statesWithTransitionEvents_ = 0x00;
189
190
191 /**
192 * Component visibility.
193 * @type {boolean}
194 * @private
195 */
196 goog.ui.Control.prototype.visible_ = true;
197
198
199 /**
200 * Keyboard event handler.
201 * @type {goog.events.KeyHandler}
202 * @private
203 */
204 goog.ui.Control.prototype.keyHandler_;
205
206
207 /**
208 * Additional class name(s) to apply to the control's root element, if any.
209 * @type {Array<string>?}
210 * @private
211 */
212 goog.ui.Control.prototype.extraClassNames_ = null;
213
214
215 /**
216 * Whether the control should listen for and handle mouse events; defaults to
217 * true.
218 * @type {boolean}
219 * @private
220 */
221 goog.ui.Control.prototype.handleMouseEvents_ = true;
222
223
224 /**
225 * Whether the control allows text selection within its DOM. Defaults to false.
226 * @type {boolean}
227 * @private
228 */
229 goog.ui.Control.prototype.allowTextSelection_ = false;
230
231
232 /**
233 * The control's preferred ARIA role.
234 * @type {?goog.a11y.aria.Role}
235 * @private
236 */
237 goog.ui.Control.prototype.preferredAriaRole_ = null;
238
239
240 // Event handler and renderer management.
241
242
243 /**
244 * Returns true if the control is configured to handle its own mouse events,
245 * false otherwise. Controls not hosted in {@link goog.ui.Container}s have
246 * to handle their own mouse events, but controls hosted in containers may
247 * allow their parent to handle mouse events on their behalf. Considered
248 * protected; should only be used within this package and by subclasses.
249 * @return {boolean} Whether the control handles its own mouse events.
250 */
251 goog.ui.Control.prototype.isHandleMouseEvents = function() {
252 return this.handleMouseEvents_;
253 };
254
255
256 /**
257 * Enables or disables mouse event handling for the control. Containers may
258 * use this method to disable mouse event handling in their child controls.
259 * Considered protected; should only be used within this package and by
260 * subclasses.
261 * @param {boolean} enable Whether to enable or disable mouse event handling.
262 */
263 goog.ui.Control.prototype.setHandleMouseEvents = function(enable) {
264 if (this.isInDocument() && enable != this.handleMouseEvents_) {
265 // Already in the document; need to update event handler.
266 this.enableMouseEventHandling_(enable);
267 }
268 this.handleMouseEvents_ = enable;
269 };
270
271
272 /**
273 * Returns the DOM element on which the control is listening for keyboard
274 * events (null if none).
275 * @return {Element} Element on which the control is listening for key
276 * events.
277 */
278 goog.ui.Control.prototype.getKeyEventTarget = function() {
279 // Delegate to renderer.
280 return this.renderer_.getKeyEventTarget(this);
281 };
282
283
284 /**
285 * Returns the keyboard event handler for this component, lazily created the
286 * first time this method is called. Considered protected; should only be
287 * used within this package and by subclasses.
288 * @return {!goog.events.KeyHandler} Keyboard event handler for this component.
289 * @protected
290 */
291 goog.ui.Control.prototype.getKeyHandler = function() {
292 return this.keyHandler_ || (this.keyHandler_ = new goog.events.KeyHandler());
293 };
294
295
296 /**
297 * Returns the renderer used by this component to render itself or to decorate
298 * an existing element.
299 * @return {goog.ui.ControlRenderer|undefined} Renderer used by the component
300 * (undefined if none).
301 */
302 goog.ui.Control.prototype.getRenderer = function() {
303 return this.renderer_;
304 };
305
306
307 /**
308 * Registers the given renderer with the component. Changing renderers after
309 * the component has entered the document is an error.
310 * @param {goog.ui.ControlRenderer} renderer Renderer used by the component.
311 * @throws {Error} If the control is already in the document.
312 */
313 goog.ui.Control.prototype.setRenderer = function(renderer) {
314 if (this.isInDocument()) {
315 // Too late.
316 throw new Error(goog.ui.Component.Error.ALREADY_RENDERED);
317 }
318
319 if (this.getElement()) {
320 // The component has already been rendered, but isn't yet in the document.
321 // Replace the renderer and delete the current DOM, so it can be re-rendered
322 // using the new renderer the next time someone calls render().
323 this.setElementInternal(null);
324 }
325
326 this.renderer_ = renderer;
327 };
328
329
330 // Support for additional styling.
331
332
333 /**
334 * Returns any additional class name(s) to be applied to the component's
335 * root element, or null if no extra class names are needed.
336 * @return {Array<string>?} Additional class names to be applied to
337 * the component's root element (null if none).
338 */
339 goog.ui.Control.prototype.getExtraClassNames = function() {
340 return this.extraClassNames_;
341 };
342
343
344 /**
345 * Adds the given class name to the list of classes to be applied to the
346 * component's root element.
347 * @param {string} className Additional class name to be applied to the
348 * component's root element.
349 */
350 goog.ui.Control.prototype.addClassName = function(className) {
351 if (className) {
352 if (this.extraClassNames_) {
353 if (!goog.array.contains(this.extraClassNames_, className)) {
354 this.extraClassNames_.push(className);
355 }
356 } else {
357 this.extraClassNames_ = [className];
358 }
359 this.renderer_.enableExtraClassName(this, className, true);
360 }
361 };
362
363
364 /**
365 * Removes the given class name from the list of classes to be applied to
366 * the component's root element.
367 * @param {string} className Class name to be removed from the component's root
368 * element.
369 */
370 goog.ui.Control.prototype.removeClassName = function(className) {
371 if (className && this.extraClassNames_ &&
372 goog.array.remove(this.extraClassNames_, className)) {
373 if (this.extraClassNames_.length == 0) {
374 this.extraClassNames_ = null;
375 }
376 this.renderer_.enableExtraClassName(this, className, false);
377 }
378 };
379
380
381 /**
382 * Adds or removes the given class name to/from the list of classes to be
383 * applied to the component's root element.
384 * @param {string} className CSS class name to add or remove.
385 * @param {boolean} enable Whether to add or remove the class name.
386 */
387 goog.ui.Control.prototype.enableClassName = function(className, enable) {
388 if (enable) {
389 this.addClassName(className);
390 } else {
391 this.removeClassName(className);
392 }
393 };
394
395
396 // Standard goog.ui.Component implementation.
397
398
399 /**
400 * Creates the control's DOM. Overrides {@link goog.ui.Component#createDom} by
401 * delegating DOM manipulation to the control's renderer.
402 * @override
403 */
404 goog.ui.Control.prototype.createDom = function() {
405 var element = this.renderer_.createDom(this);
406 this.setElementInternal(element);
407
408 // Initialize ARIA role.
409 this.renderer_.setAriaRole(element, this.getPreferredAriaRole());
410
411 // Initialize text selection.
412 if (!this.isAllowTextSelection()) {
413 // The renderer is assumed to create selectable elements. Since making
414 // elements unselectable is expensive, only do it if needed (bug 1037090).
415 this.renderer_.setAllowTextSelection(element, false);
416 }
417
418 // Initialize visibility.
419 if (!this.isVisible()) {
420 // The renderer is assumed to create visible elements. Since hiding
421 // elements can be expensive, only do it if needed (bug 1037105).
422 this.renderer_.setVisible(element, false);
423 }
424 };
425
426
427 /**
428 * Returns the control's preferred ARIA role. This can be used by a control to
429 * override the role that would be assigned by the renderer. This is useful in
430 * cases where a different ARIA role is appropriate for a control because of the
431 * context in which it's used. E.g., a {@link goog.ui.MenuButton} added to a
432 * {@link goog.ui.Select} should have an ARIA role of LISTBOX and not MENUITEM.
433 * @return {?goog.a11y.aria.Role} This control's preferred ARIA role or null if
434 * no preferred ARIA role is set.
435 */
436 goog.ui.Control.prototype.getPreferredAriaRole = function() {
437 return this.preferredAriaRole_;
438 };
439
440
441 /**
442 * Sets the control's preferred ARIA role. This can be used to override the role
443 * that would be assigned by the renderer. This is useful in cases where a
444 * different ARIA role is appropriate for a control because of the
445 * context in which it's used. E.g., a {@link goog.ui.MenuButton} added to a
446 * {@link goog.ui.Select} should have an ARIA role of LISTBOX and not MENUITEM.
447 * @param {goog.a11y.aria.Role} role This control's preferred ARIA role.
448 */
449 goog.ui.Control.prototype.setPreferredAriaRole = function(role) {
450 this.preferredAriaRole_ = role;
451 };
452
453
454 /**
455 * Gets the control's aria label.
456 * @return {?string} This control's aria label.
457 */
458 goog.ui.Control.prototype.getAriaLabel = function() {
459 return this.ariaLabel_;
460 };
461
462
463 /**
464 * Sets the control's aria label. This can be used to assign aria label to the
465 * element after it is rendered.
466 * @param {string} label The string to set as the aria label for this control.
467 * No escaping is done on this value.
468 */
469 goog.ui.Control.prototype.setAriaLabel = function(label) {
470 this.ariaLabel_ = label;
471 var element = this.getElement();
472 if (element) {
473 this.renderer_.setAriaLabel(element, label);
474 }
475 };
476
477
478 /**
479 * Returns the DOM element into which child components are to be rendered,
480 * or null if the control itself hasn't been rendered yet. Overrides
481 * {@link goog.ui.Component#getContentElement} by delegating to the renderer.
482 * @return {Element} Element to contain child elements (null if none).
483 * @override
484 */
485 goog.ui.Control.prototype.getContentElement = function() {
486 // Delegate to renderer.
487 return this.renderer_.getContentElement(this.getElement());
488 };
489
490
491 /**
492 * Returns true if the given element can be decorated by this component.
493 * Overrides {@link goog.ui.Component#canDecorate}.
494 * @param {Element} element Element to decorate.
495 * @return {boolean} Whether the element can be decorated by this component.
496 * @override
497 */
498 goog.ui.Control.prototype.canDecorate = function(element) {
499 // Controls support pluggable renderers; delegate to the renderer.
500 return this.renderer_.canDecorate(element);
501 };
502
503
504 /**
505 * Decorates the given element with this component. Overrides {@link
506 * goog.ui.Component#decorateInternal} by delegating DOM manipulation
507 * to the control's renderer.
508 * @param {Element} element Element to decorate.
509 * @protected
510 * @override
511 */
512 goog.ui.Control.prototype.decorateInternal = function(element) {
513 element = this.renderer_.decorate(this, element);
514 this.setElementInternal(element);
515
516 // Initialize ARIA role.
517 this.renderer_.setAriaRole(element, this.getPreferredAriaRole());
518
519 // Initialize text selection.
520 if (!this.isAllowTextSelection()) {
521 // Decorated elements are assumed to be selectable. Since making elements
522 // unselectable is expensive, only do it if needed (bug 1037090).
523 this.renderer_.setAllowTextSelection(element, false);
524 }
525
526 // Initialize visibility based on the decorated element's styling.
527 this.visible_ = element.style.display != 'none';
528 };
529
530
531 /**
532 * Configures the component after its DOM has been rendered, and sets up event
533 * handling. Overrides {@link goog.ui.Component#enterDocument}.
534 * @override
535 */
536 goog.ui.Control.prototype.enterDocument = function() {
537 goog.ui.Control.superClass_.enterDocument.call(this);
538
539 // Call the renderer's setAriaStates method to set element's aria attributes.
540 this.renderer_.setAriaStates(this, this.getElementStrict());
541
542 // Call the renderer's initializeDom method to configure properties of the
543 // control's DOM that can only be done once it's in the document.
544 this.renderer_.initializeDom(this);
545
546 // Initialize event handling if at least one state other than DISABLED is
547 // supported.
548 if (this.supportedStates_ & ~goog.ui.Component.State.DISABLED) {
549 // Initialize mouse event handling if the control is configured to handle
550 // its own mouse events. (Controls hosted in containers don't need to
551 // handle their own mouse events.)
552 if (this.isHandleMouseEvents()) {
553 this.enableMouseEventHandling_(true);
554 }
555
556 // Initialize keyboard event handling if the control is focusable and has
557 // a key event target. (Controls hosted in containers typically aren't
558 // focusable, allowing their container to handle keyboard events for them.)
559 if (this.isSupportedState(goog.ui.Component.State.FOCUSED)) {
560 var keyTarget = this.getKeyEventTarget();
561 if (keyTarget) {
562 var keyHandler = this.getKeyHandler();
563 keyHandler.attach(keyTarget);
564 this.getHandler()
565 .listen(
566 keyHandler, goog.events.KeyHandler.EventType.KEY,
567 this.handleKeyEvent)
568 .listen(keyTarget, goog.events.EventType.FOCUS, this.handleFocus)
569 .listen(keyTarget, goog.events.EventType.BLUR, this.handleBlur);
570 }
571 }
572 }
573 };
574
575
576 /**
577 * Enables or disables mouse event handling on the control.
578 * @param {boolean} enable Whether to enable mouse event handling.
579 * @private
580 */
581 goog.ui.Control.prototype.enableMouseEventHandling_ = function(enable) {
582 var handler = this.getHandler();
583 var element = this.getElement();
584 if (enable) {
585 handler
586 .listen(element, goog.events.EventType.MOUSEOVER, this.handleMouseOver)
587 .listen(element, goog.events.EventType.MOUSEDOWN, this.handleMouseDown)
588 .listen(element, goog.events.EventType.MOUSEUP, this.handleMouseUp)
589 .listen(element, goog.events.EventType.MOUSEOUT, this.handleMouseOut);
590 if (this.handleContextMenu != goog.nullFunction) {
591 handler.listen(
592 element, goog.events.EventType.CONTEXTMENU, this.handleContextMenu);
593 }
594 if (goog.userAgent.IE) {
595 // Versions of IE before 9 send only one click event followed by a
596 // dblclick, so we must explicitly listen for these. In later versions,
597 // two click events are fired and so a dblclick listener is unnecessary.
598 if (!goog.userAgent.isVersionOrHigher(9)) {
599 handler.listen(
600 element, goog.events.EventType.DBLCLICK, this.handleDblClick);
601 }
602 if (!this.ieMouseEventSequenceSimulator_) {
603 this.ieMouseEventSequenceSimulator_ =
604 new goog.ui.Control.IeMouseEventSequenceSimulator_(this);
605 this.registerDisposable(this.ieMouseEventSequenceSimulator_);
606 }
607 }
608 } else {
609 handler
610 .unlisten(
611 element, goog.events.EventType.MOUSEOVER, this.handleMouseOver)
612 .unlisten(
613 element, goog.events.EventType.MOUSEDOWN, this.handleMouseDown)
614 .unlisten(element, goog.events.EventType.MOUSEUP, this.handleMouseUp)
615 .unlisten(element, goog.events.EventType.MOUSEOUT, this.handleMouseOut);
616 if (this.handleContextMenu != goog.nullFunction) {
617 handler.unlisten(
618 element, goog.events.EventType.CONTEXTMENU, this.handleContextMenu);
619 }
620 if (goog.userAgent.IE) {
621 if (!goog.userAgent.isVersionOrHigher(9)) {
622 handler.unlisten(
623 element, goog.events.EventType.DBLCLICK, this.handleDblClick);
624 }
625 goog.dispose(this.ieMouseEventSequenceSimulator_);
626 this.ieMouseEventSequenceSimulator_ = null;
627 }
628 }
629 };
630
631
632 /**
633 * Cleans up the component before its DOM is removed from the document, and
634 * removes event handlers. Overrides {@link goog.ui.Component#exitDocument}
635 * by making sure that components that are removed from the document aren't
636 * focusable (i.e. have no tab index).
637 * @override
638 */
639 goog.ui.Control.prototype.exitDocument = function() {
640 goog.ui.Control.superClass_.exitDocument.call(this);
641 if (this.keyHandler_) {
642 this.keyHandler_.detach();
643 }
644 if (this.isVisible() && this.isEnabled()) {
645 this.renderer_.setFocusable(this, false);
646 }
647 };
648
649
650 /** @override */
651 goog.ui.Control.prototype.disposeInternal = function() {
652 goog.ui.Control.superClass_.disposeInternal.call(this);
653 if (this.keyHandler_) {
654 this.keyHandler_.dispose();
655 delete this.keyHandler_;
656 }
657 delete this.renderer_;
658 this.content_ = null;
659 this.extraClassNames_ = null;
660 this.ieMouseEventSequenceSimulator_ = null;
661 };
662
663
664 // Component content management.
665
666
667 /**
668 * Returns the text caption or DOM structure displayed in the component.
669 * @return {goog.ui.ControlContent} Text caption or DOM structure
670 * comprising the component's contents.
671 */
672 goog.ui.Control.prototype.getContent = function() {
673 return this.content_;
674 };
675
676
677 /**
678 * Sets the component's content to the given text caption, element, or array of
679 * nodes. (If the argument is an array of nodes, it must be an actual array,
680 * not an array-like object.)
681 * @param {goog.ui.ControlContent} content Text caption or DOM
682 * structure to set as the component's contents.
683 */
684 goog.ui.Control.prototype.setContent = function(content) {
685 // Controls support pluggable renderers; delegate to the renderer.
686 this.renderer_.setContent(this.getElement(), content);
687
688 // setContentInternal needs to be after the renderer, since the implementation
689 // may depend on the content being in the DOM.
690 this.setContentInternal(content);
691 };
692
693
694 /**
695 * Sets the component's content to the given text caption, element, or array
696 * of nodes. Unlike {@link #setContent}, doesn't modify the component's DOM.
697 * Called by renderers during element decoration.
698 *
699 * This should only be used by subclasses and its associated renderers.
700 *
701 * @param {goog.ui.ControlContent} content Text caption or DOM structure
702 * to set as the component's contents.
703 */
704 goog.ui.Control.prototype.setContentInternal = function(content) {
705 this.content_ = content;
706 };
707
708
709 /**
710 * @return {string} Text caption of the control or empty string if none.
711 */
712 goog.ui.Control.prototype.getCaption = function() {
713 var content = this.getContent();
714 if (!content) {
715 return '';
716 }
717 var caption = goog.isString(content) ?
718 content :
719 goog.isArray(content) ?
720 goog.array.map(content, goog.dom.getRawTextContent).join('') :
721 goog.dom.getTextContent(/** @type {!Node} */ (content));
722 return goog.string.collapseBreakingSpaces(caption);
723 };
724
725
726 /**
727 * Sets the text caption of the component.
728 * @param {string} caption Text caption of the component.
729 */
730 goog.ui.Control.prototype.setCaption = function(caption) {
731 this.setContent(caption);
732 };
733
734
735 // Component state management.
736
737
738 /** @override */
739 goog.ui.Control.prototype.setRightToLeft = function(rightToLeft) {
740 // The superclass implementation ensures the control isn't in the document.
741 goog.ui.Control.superClass_.setRightToLeft.call(this, rightToLeft);
742
743 var element = this.getElement();
744 if (element) {
745 this.renderer_.setRightToLeft(element, rightToLeft);
746 }
747 };
748
749
750 /**
751 * Returns true if the control allows text selection within its DOM, false
752 * otherwise. Controls that disallow text selection have the appropriate
753 * unselectable styling applied to their elements. Note that controls hosted
754 * in containers will report that they allow text selection even if their
755 * container disallows text selection.
756 * @return {boolean} Whether the control allows text selection.
757 */
758 goog.ui.Control.prototype.isAllowTextSelection = function() {
759 return this.allowTextSelection_;
760 };
761
762
763 /**
764 * Allows or disallows text selection within the control's DOM.
765 * @param {boolean} allow Whether the control should allow text selection.
766 */
767 goog.ui.Control.prototype.setAllowTextSelection = function(allow) {
768 this.allowTextSelection_ = allow;
769
770 var element = this.getElement();
771 if (element) {
772 this.renderer_.setAllowTextSelection(element, allow);
773 }
774 };
775
776
777 /**
778 * Returns true if the component's visibility is set to visible, false if
779 * it is set to hidden. A component that is set to hidden is guaranteed
780 * to be hidden from the user, but the reverse isn't necessarily true.
781 * A component may be set to visible but can otherwise be obscured by another
782 * element, rendered off-screen, or hidden using direct CSS manipulation.
783 * @return {boolean} Whether the component is visible.
784 */
785 goog.ui.Control.prototype.isVisible = function() {
786 return this.visible_;
787 };
788
789
790 /**
791 * Shows or hides the component. Does nothing if the component already has
792 * the requested visibility. Otherwise, dispatches a SHOW or HIDE event as
793 * appropriate, giving listeners a chance to prevent the visibility change.
794 * When showing a component that is both enabled and focusable, ensures that
795 * its key target has a tab index. When hiding a component that is enabled
796 * and focusable, blurs its key target and removes its tab index.
797 * @param {boolean} visible Whether to show or hide the component.
798 * @param {boolean=} opt_force If true, doesn't check whether the component
799 * already has the requested visibility, and doesn't dispatch any events.
800 * @return {boolean} Whether the visibility was changed.
801 */
802 goog.ui.Control.prototype.setVisible = function(visible, opt_force) {
803 if (opt_force || (this.visible_ != visible &&
804 this.dispatchEvent(
805 visible ? goog.ui.Component.EventType.SHOW :
806 goog.ui.Component.EventType.HIDE))) {
807 var element = this.getElement();
808 if (element) {
809 this.renderer_.setVisible(element, visible);
810 }
811 if (this.isEnabled()) {
812 this.renderer_.setFocusable(this, visible);
813 }
814 this.visible_ = visible;
815 return true;
816 }
817 return false;
818 };
819
820
821 /**
822 * Returns true if the component is enabled, false otherwise.
823 * @return {boolean} Whether the component is enabled.
824 */
825 goog.ui.Control.prototype.isEnabled = function() {
826 return !this.hasState(goog.ui.Component.State.DISABLED);
827 };
828
829
830 /**
831 * Returns true if the control has a parent that is itself disabled, false
832 * otherwise.
833 * @return {boolean} Whether the component is hosted in a disabled container.
834 * @private
835 */
836 goog.ui.Control.prototype.isParentDisabled_ = function() {
837 var parent = this.getParent();
838 return !!parent && typeof parent.isEnabled == 'function' &&
839 !parent.isEnabled();
840 };
841
842
843 /**
844 * Enables or disables the component. Does nothing if this state transition
845 * is disallowed. If the component is both visible and focusable, updates its
846 * focused state and tab index as needed. If the component is being disabled,
847 * ensures that it is also deactivated and un-highlighted first. Note that the
848 * component's enabled/disabled state is "locked" as long as it is hosted in a
849 * {@link goog.ui.Container} that is itself disabled; this is to prevent clients
850 * from accidentally re-enabling a control that is in a disabled container.
851 * @param {boolean} enable Whether to enable or disable the component.
852 * @see #isTransitionAllowed
853 */
854 goog.ui.Control.prototype.setEnabled = function(enable) {
855 if (!this.isParentDisabled_() &&
856 this.isTransitionAllowed(goog.ui.Component.State.DISABLED, !enable)) {
857 if (!enable) {
858 this.setActive(false);
859 this.setHighlighted(false);
860 }
861 if (this.isVisible()) {
862 this.renderer_.setFocusable(this, enable);
863 }
864 this.setState(goog.ui.Component.State.DISABLED, !enable, true);
865 }
866 };
867
868
869 /**
870 * Returns true if the component is currently highlighted, false otherwise.
871 * @return {boolean} Whether the component is highlighted.
872 */
873 goog.ui.Control.prototype.isHighlighted = function() {
874 return this.hasState(goog.ui.Component.State.HOVER);
875 };
876
877
878 /**
879 * Highlights or unhighlights the component. Does nothing if this state
880 * transition is disallowed.
881 * @param {boolean} highlight Whether to highlight or unhighlight the component.
882 * @see #isTransitionAllowed
883 */
884 goog.ui.Control.prototype.setHighlighted = function(highlight) {
885 if (this.isTransitionAllowed(goog.ui.Component.State.HOVER, highlight)) {
886 this.setState(goog.ui.Component.State.HOVER, highlight);
887 }
888 };
889
890
891 /**
892 * Returns true if the component is active (pressed), false otherwise.
893 * @return {boolean} Whether the component is active.
894 */
895 goog.ui.Control.prototype.isActive = function() {
896 return this.hasState(goog.ui.Component.State.ACTIVE);
897 };
898
899
900 /**
901 * Activates or deactivates the component. Does nothing if this state
902 * transition is disallowed.
903 * @param {boolean} active Whether to activate or deactivate the component.
904 * @see #isTransitionAllowed
905 */
906 goog.ui.Control.prototype.setActive = function(active) {
907 if (this.isTransitionAllowed(goog.ui.Component.State.ACTIVE, active)) {
908 this.setState(goog.ui.Component.State.ACTIVE, active);
909 }
910 };
911
912
913 /**
914 * Returns true if the component is selected, false otherwise.
915 * @return {boolean} Whether the component is selected.
916 */
917 goog.ui.Control.prototype.isSelected = function() {
918 return this.hasState(goog.ui.Component.State.SELECTED);
919 };
920
921
922 /**
923 * Selects or unselects the component. Does nothing if this state transition
924 * is disallowed.
925 * @param {boolean} select Whether to select or unselect the component.
926 * @see #isTransitionAllowed
927 */
928 goog.ui.Control.prototype.setSelected = function(select) {
929 if (this.isTransitionAllowed(goog.ui.Component.State.SELECTED, select)) {
930 this.setState(goog.ui.Component.State.SELECTED, select);
931 }
932 };
933
934
935 /**
936 * Returns true if the component is checked, false otherwise.
937 * @return {boolean} Whether the component is checked.
938 */
939 goog.ui.Control.prototype.isChecked = function() {
940 return this.hasState(goog.ui.Component.State.CHECKED);
941 };
942
943
944 /**
945 * Checks or unchecks the component. Does nothing if this state transition
946 * is disallowed.
947 * @param {boolean} check Whether to check or uncheck the component.
948 * @see #isTransitionAllowed
949 */
950 goog.ui.Control.prototype.setChecked = function(check) {
951 if (this.isTransitionAllowed(goog.ui.Component.State.CHECKED, check)) {
952 this.setState(goog.ui.Component.State.CHECKED, check);
953 }
954 };
955
956
957 /**
958 * Returns true if the component is styled to indicate that it has keyboard
959 * focus, false otherwise. Note that {@code isFocused()} returning true
960 * doesn't guarantee that the component's key event target has keyborad focus,
961 * only that it is styled as such.
962 * @return {boolean} Whether the component is styled to indicate as having
963 * keyboard focus.
964 */
965 goog.ui.Control.prototype.isFocused = function() {
966 return this.hasState(goog.ui.Component.State.FOCUSED);
967 };
968
969
970 /**
971 * Applies or removes styling indicating that the component has keyboard focus.
972 * Note that unlike the other "set" methods, this method is called as a result
973 * of the component's element having received or lost keyboard focus, not the
974 * other way around, so calling {@code setFocused(true)} doesn't guarantee that
975 * the component's key event target has keyboard focus, only that it is styled
976 * as such.
977 * @param {boolean} focused Whether to apply or remove styling to indicate that
978 * the component's element has keyboard focus.
979 */
980 goog.ui.Control.prototype.setFocused = function(focused) {
981 if (this.isTransitionAllowed(goog.ui.Component.State.FOCUSED, focused)) {
982 this.setState(goog.ui.Component.State.FOCUSED, focused);
983 }
984 };
985
986
987 /**
988 * Returns true if the component is open (expanded), false otherwise.
989 * @return {boolean} Whether the component is open.
990 */
991 goog.ui.Control.prototype.isOpen = function() {
992 return this.hasState(goog.ui.Component.State.OPENED);
993 };
994
995
996 /**
997 * Opens (expands) or closes (collapses) the component. Does nothing if this
998 * state transition is disallowed.
999 * @param {boolean} open Whether to open or close the component.
1000 * @see #isTransitionAllowed
1001 */
1002 goog.ui.Control.prototype.setOpen = function(open) {
1003 if (this.isTransitionAllowed(goog.ui.Component.State.OPENED, open)) {
1004 this.setState(goog.ui.Component.State.OPENED, open);
1005 }
1006 };
1007
1008
1009 /**
1010 * Returns the component's state as a bit mask of {@link
1011 * goog.ui.Component.State}s.
1012 * @return {number} Bit mask representing component state.
1013 */
1014 goog.ui.Control.prototype.getState = function() {
1015 return this.state_;
1016 };
1017
1018
1019 /**
1020 * Returns true if the component is in the specified state, false otherwise.
1021 * @param {goog.ui.Component.State} state State to check.
1022 * @return {boolean} Whether the component is in the given state.
1023 */
1024 goog.ui.Control.prototype.hasState = function(state) {
1025 return !!(this.state_ & state);
1026 };
1027
1028
1029 /**
1030 * Sets or clears the given state on the component, and updates its styling
1031 * accordingly. Does nothing if the component is already in the correct state
1032 * or if it doesn't support the specified state. Doesn't dispatch any state
1033 * transition events; use advisedly.
1034 * @param {goog.ui.Component.State} state State to set or clear.
1035 * @param {boolean} enable Whether to set or clear the state (if supported).
1036 * @param {boolean=} opt_calledFrom Prevents looping with setEnabled.
1037 */
1038 goog.ui.Control.prototype.setState = function(state, enable, opt_calledFrom) {
1039 if (!opt_calledFrom && state == goog.ui.Component.State.DISABLED) {
1040 this.setEnabled(!enable);
1041 return;
1042 }
1043 if (this.isSupportedState(state) && enable != this.hasState(state)) {
1044 // Delegate actual styling to the renderer, since it is DOM-specific.
1045 this.renderer_.setState(this, state, enable);
1046 this.state_ = enable ? this.state_ | state : this.state_ & ~state;
1047 }
1048 };
1049
1050
1051 /**
1052 * Sets the component's state to the state represented by a bit mask of
1053 * {@link goog.ui.Component.State}s. Unlike {@link #setState}, doesn't
1054 * update the component's styling, and doesn't reject unsupported states.
1055 * Called by renderers during element decoration. Considered protected;
1056 * should only be used within this package and by subclasses.
1057 *
1058 * This should only be used by subclasses and its associated renderers.
1059 *
1060 * @param {number} state Bit mask representing component state.
1061 */
1062 goog.ui.Control.prototype.setStateInternal = function(state) {
1063 this.state_ = state;
1064 };
1065
1066
1067 /**
1068 * Returns true if the component supports the specified state, false otherwise.
1069 * @param {goog.ui.Component.State} state State to check.
1070 * @return {boolean} Whether the component supports the given state.
1071 */
1072 goog.ui.Control.prototype.isSupportedState = function(state) {
1073 return !!(this.supportedStates_ & state);
1074 };
1075
1076
1077 /**
1078 * Enables or disables support for the given state. Disabling support
1079 * for a state while the component is in that state is an error.
1080 * @param {goog.ui.Component.State} state State to support or de-support.
1081 * @param {boolean} support Whether the component should support the state.
1082 * @throws {Error} If disabling support for a state the control is currently in.
1083 */
1084 goog.ui.Control.prototype.setSupportedState = function(state, support) {
1085 if (this.isInDocument() && this.hasState(state) && !support) {
1086 // Since we hook up event handlers in enterDocument(), this is an error.
1087 throw new Error(goog.ui.Component.Error.ALREADY_RENDERED);
1088 }
1089
1090 if (!support && this.hasState(state)) {
1091 // We are removing support for a state that the component is currently in.
1092 this.setState(state, false);
1093 }
1094
1095 this.supportedStates_ =
1096 support ? this.supportedStates_ | state : this.supportedStates_ & ~state;
1097 };
1098
1099
1100 /**
1101 * Returns true if the component provides default event handling for the state,
1102 * false otherwise.
1103 * @param {goog.ui.Component.State} state State to check.
1104 * @return {boolean} Whether the component provides default event handling for
1105 * the state.
1106 */
1107 goog.ui.Control.prototype.isAutoState = function(state) {
1108 return !!(this.autoStates_ & state) && this.isSupportedState(state);
1109 };
1110
1111
1112 /**
1113 * Enables or disables automatic event handling for the given state(s).
1114 * @param {number} states Bit mask of {@link goog.ui.Component.State}s for which
1115 * default event handling is to be enabled or disabled.
1116 * @param {boolean} enable Whether the component should provide default event
1117 * handling for the state(s).
1118 */
1119 goog.ui.Control.prototype.setAutoStates = function(states, enable) {
1120 this.autoStates_ =
1121 enable ? this.autoStates_ | states : this.autoStates_ & ~states;
1122 };
1123
1124
1125 /**
1126 * Returns true if the component is set to dispatch transition events for the
1127 * given state, false otherwise.
1128 * @param {goog.ui.Component.State} state State to check.
1129 * @return {boolean} Whether the component dispatches transition events for
1130 * the state.
1131 */
1132 goog.ui.Control.prototype.isDispatchTransitionEvents = function(state) {
1133 return !!(this.statesWithTransitionEvents_ & state) &&
1134 this.isSupportedState(state);
1135 };
1136
1137
1138 /**
1139 * Enables or disables transition events for the given state(s). Controls
1140 * handle state transitions internally by default, and only dispatch state
1141 * transition events if explicitly requested to do so by calling this method.
1142 * @param {number} states Bit mask of {@link goog.ui.Component.State}s for
1143 * which transition events should be enabled or disabled.
1144 * @param {boolean} enable Whether transition events should be enabled.
1145 */
1146 goog.ui.Control.prototype.setDispatchTransitionEvents = function(
1147 states, enable) {
1148 this.statesWithTransitionEvents_ = enable ?
1149 this.statesWithTransitionEvents_ | states :
1150 this.statesWithTransitionEvents_ & ~states;
1151 };
1152
1153
1154 /**
1155 * Returns true if the transition into or out of the given state is allowed to
1156 * proceed, false otherwise. A state transition is allowed under the following
1157 * conditions:
1158 * <ul>
1159 * <li>the component supports the state,
1160 * <li>the component isn't already in the target state,
1161 * <li>either the component is configured not to dispatch events for this
1162 * state transition, or a transition event was dispatched and wasn't
1163 * canceled by any event listener, and
1164 * <li>the component hasn't been disposed of
1165 * </ul>
1166 * Considered protected; should only be used within this package and by
1167 * subclasses.
1168 * @param {goog.ui.Component.State} state State to/from which the control is
1169 * transitioning.
1170 * @param {boolean} enable Whether the control is entering or leaving the state.
1171 * @return {boolean} Whether the state transition is allowed to proceed.
1172 * @protected
1173 */
1174 goog.ui.Control.prototype.isTransitionAllowed = function(state, enable) {
1175 return this.isSupportedState(state) && this.hasState(state) != enable &&
1176 (!(this.statesWithTransitionEvents_ & state) ||
1177 this.dispatchEvent(
1178 goog.ui.Component.getStateTransitionEvent(state, enable))) &&
1179 !this.isDisposed();
1180 };
1181
1182
1183 // Default event handlers, to be overridden in subclasses.
1184
1185
1186 /**
1187 * Handles mouseover events. Dispatches an ENTER event; if the event isn't
1188 * canceled, the component is enabled, and it supports auto-highlighting,
1189 * highlights the component. Considered protected; should only be used
1190 * within this package and by subclasses.
1191 * @param {goog.events.BrowserEvent} e Mouse event to handle.
1192 */
1193 goog.ui.Control.prototype.handleMouseOver = function(e) {
1194 // Ignore mouse moves between descendants.
1195 if (!goog.ui.Control.isMouseEventWithinElement_(e, this.getElement()) &&
1196 this.dispatchEvent(goog.ui.Component.EventType.ENTER) &&
1197 this.isEnabled() && this.isAutoState(goog.ui.Component.State.HOVER)) {
1198 this.setHighlighted(true);
1199 }
1200 };
1201
1202
1203 /**
1204 * Handles mouseout events. Dispatches a LEAVE event; if the event isn't
1205 * canceled, and the component supports auto-highlighting, deactivates and
1206 * un-highlights the component. Considered protected; should only be used
1207 * within this package and by subclasses.
1208 * @param {goog.events.BrowserEvent} e Mouse event to handle.
1209 */
1210 goog.ui.Control.prototype.handleMouseOut = function(e) {
1211 if (!goog.ui.Control.isMouseEventWithinElement_(e, this.getElement()) &&
1212 this.dispatchEvent(goog.ui.Component.EventType.LEAVE)) {
1213 if (this.isAutoState(goog.ui.Component.State.ACTIVE)) {
1214 // Deactivate on mouseout; otherwise we lose track of the mouse button.
1215 this.setActive(false);
1216 }
1217 if (this.isAutoState(goog.ui.Component.State.HOVER)) {
1218 this.setHighlighted(false);
1219 }
1220 }
1221 };
1222
1223
1224 /**
1225 * Handles contextmenu events.
1226 * @param {goog.events.BrowserEvent} e Event to handle.
1227 */
1228 goog.ui.Control.prototype.handleContextMenu = goog.nullFunction;
1229
1230
1231 /**
1232 * Checks if a mouse event (mouseover or mouseout) occurred below an element.
1233 * @param {goog.events.BrowserEvent} e Mouse event (should be mouseover or
1234 * mouseout).
1235 * @param {Element} elem The ancestor element.
1236 * @return {boolean} Whether the event has a relatedTarget (the element the
1237 * mouse is coming from) and it's a descendent of elem.
1238 * @private
1239 */
1240 goog.ui.Control.isMouseEventWithinElement_ = function(e, elem) {
1241 // If relatedTarget is null, it means there was no previous element (e.g.
1242 // the mouse moved out of the window). Assume this means that the mouse
1243 // event was not within the element.
1244 return !!e.relatedTarget && goog.dom.contains(elem, e.relatedTarget);
1245 };
1246
1247
1248 /**
1249 * Handles mousedown events. If the component is enabled, highlights and
1250 * activates it. If the component isn't configured for keyboard access,
1251 * prevents it from receiving keyboard focus. Considered protected; should
1252 * only be used within this package and by subclasses.
1253 * @param {goog.events.Event} e Mouse event to handle.
1254 */
1255 goog.ui.Control.prototype.handleMouseDown = function(e) {
1256 if (this.isEnabled()) {
1257 // Highlight enabled control on mousedown, regardless of the mouse button.
1258 if (this.isAutoState(goog.ui.Component.State.HOVER)) {
1259 this.setHighlighted(true);
1260 }
1261
1262 // For the left button only, activate the control, and focus its key event
1263 // target (if supported).
1264 if (e.isMouseActionButton()) {
1265 if (this.isAutoState(goog.ui.Component.State.ACTIVE)) {
1266 this.setActive(true);
1267 }
1268 if (this.renderer_ && this.renderer_.isFocusable(this)) {
1269 this.getKeyEventTarget().focus();
1270 }
1271 }
1272 }
1273
1274 // Cancel the default action unless the control allows text selection.
1275 if (!this.isAllowTextSelection() && e.isMouseActionButton()) {
1276 e.preventDefault();
1277 }
1278 };
1279
1280
1281 /**
1282 * Handles mouseup events. If the component is enabled, highlights it. If
1283 * the component has previously been activated, performs its associated action
1284 * by calling {@link performActionInternal}, then deactivates it. Considered
1285 * protected; should only be used within this package and by subclasses.
1286 * @param {goog.events.Event} e Mouse event to handle.
1287 */
1288 goog.ui.Control.prototype.handleMouseUp = function(e) {
1289 if (this.isEnabled()) {
1290 if (this.isAutoState(goog.ui.Component.State.HOVER)) {
1291 this.setHighlighted(true);
1292 }
1293 if (this.isActive() && this.performActionInternal(e) &&
1294 this.isAutoState(goog.ui.Component.State.ACTIVE)) {
1295 this.setActive(false);
1296 }
1297 }
1298 };
1299
1300
1301 /**
1302 * Handles dblclick events. Should only be registered if the user agent is
1303 * IE. If the component is enabled, performs its associated action by calling
1304 * {@link performActionInternal}. This is used to allow more performant
1305 * buttons in IE. In IE, no mousedown event is fired when that mousedown will
1306 * trigger a dblclick event. Because of this, a user clicking quickly will
1307 * only cause ACTION events to fire on every other click. This is a workaround
1308 * to generate ACTION events for every click. Unfortunately, this workaround
1309 * won't ever trigger the ACTIVE state. This is roughly the same behaviour as
1310 * if this were a 'button' element with a listener on mouseup. Considered
1311 * protected; should only be used within this package and by subclasses.
1312 * @param {goog.events.Event} e Mouse event to handle.
1313 */
1314 goog.ui.Control.prototype.handleDblClick = function(e) {
1315 if (this.isEnabled()) {
1316 this.performActionInternal(e);
1317 }
1318 };
1319
1320
1321 /**
1322 * Performs the appropriate action when the control is activated by the user.
1323 * The default implementation first updates the checked and selected state of
1324 * controls that support them, then dispatches an ACTION event. Considered
1325 * protected; should only be used within this package and by subclasses.
1326 * @param {goog.events.Event} e Event that triggered the action.
1327 * @return {boolean} Whether the action is allowed to proceed.
1328 * @protected
1329 */
1330 goog.ui.Control.prototype.performActionInternal = function(e) {
1331 if (this.isAutoState(goog.ui.Component.State.CHECKED)) {
1332 this.setChecked(!this.isChecked());
1333 }
1334 if (this.isAutoState(goog.ui.Component.State.SELECTED)) {
1335 this.setSelected(true);
1336 }
1337 if (this.isAutoState(goog.ui.Component.State.OPENED)) {
1338 this.setOpen(!this.isOpen());
1339 }
1340
1341 var actionEvent =
1342 new goog.events.Event(goog.ui.Component.EventType.ACTION, this);
1343 if (e) {
1344 actionEvent.altKey = e.altKey;
1345 actionEvent.ctrlKey = e.ctrlKey;
1346 actionEvent.metaKey = e.metaKey;
1347 actionEvent.shiftKey = e.shiftKey;
1348 actionEvent.platformModifierKey = e.platformModifierKey;
1349 }
1350 return this.dispatchEvent(actionEvent);
1351 };
1352
1353
1354 /**
1355 * Handles focus events on the component's key event target element. If the
1356 * component is focusable, updates its state and styling to indicate that it
1357 * now has keyboard focus. Considered protected; should only be used within
1358 * this package and by subclasses. <b>Warning:</b> IE dispatches focus and
1359 * blur events asynchronously!
1360 * @param {goog.events.Event} e Focus event to handle.
1361 */
1362 goog.ui.Control.prototype.handleFocus = function(e) {
1363 if (this.isAutoState(goog.ui.Component.State.FOCUSED)) {
1364 this.setFocused(true);
1365 }
1366 };
1367
1368
1369 /**
1370 * Handles blur events on the component's key event target element. Always
1371 * deactivates the component. In addition, if the component is focusable,
1372 * updates its state and styling to indicate that it no longer has keyboard
1373 * focus. Considered protected; should only be used within this package and
1374 * by subclasses. <b>Warning:</b> IE dispatches focus and blur events
1375 * asynchronously!
1376 * @param {goog.events.Event} e Blur event to handle.
1377 */
1378 goog.ui.Control.prototype.handleBlur = function(e) {
1379 if (this.isAutoState(goog.ui.Component.State.ACTIVE)) {
1380 this.setActive(false);
1381 }
1382 if (this.isAutoState(goog.ui.Component.State.FOCUSED)) {
1383 this.setFocused(false);
1384 }
1385 };
1386
1387
1388 /**
1389 * Attempts to handle a keyboard event, if the component is enabled and visible,
1390 * by calling {@link handleKeyEventInternal}. Considered protected; should only
1391 * be used within this package and by subclasses.
1392 * @param {goog.events.KeyEvent} e Key event to handle.
1393 * @return {boolean} Whether the key event was handled.
1394 */
1395 goog.ui.Control.prototype.handleKeyEvent = function(e) {
1396 if (this.isVisible() && this.isEnabled() && this.handleKeyEventInternal(e)) {
1397 e.preventDefault();
1398 e.stopPropagation();
1399 return true;
1400 }
1401 return false;
1402 };
1403
1404
1405 /**
1406 * Attempts to handle a keyboard event; returns true if the event was handled,
1407 * false otherwise. Considered protected; should only be used within this
1408 * package and by subclasses.
1409 * @param {goog.events.KeyEvent} e Key event to handle.
1410 * @return {boolean} Whether the key event was handled.
1411 * @protected
1412 */
1413 goog.ui.Control.prototype.handleKeyEventInternal = function(e) {
1414 return e.keyCode == goog.events.KeyCodes.ENTER &&
1415 this.performActionInternal(e);
1416 };
1417
1418
1419 // Register the default renderer for goog.ui.Controls.
1420 goog.ui.registry.setDefaultRenderer(goog.ui.Control, goog.ui.ControlRenderer);
1421
1422
1423 // Register a decorator factory function for goog.ui.Controls.
1424 goog.ui.registry.setDecoratorByClassName(
1425 goog.ui.ControlRenderer.CSS_CLASS,
1426 function() { return new goog.ui.Control(null); });
1427
1428
1429
1430 /**
1431 * A singleton that helps goog.ui.Control instances play well with screen
1432 * readers. It necessitated by shortcomings in IE, and need not be
1433 * instantiated in any other browser.
1434 *
1435 * In most cases, a click on a goog.ui.Control results in a sequence of events:
1436 * MOUSEDOWN, MOUSEUP and CLICK. UI controls rely on this sequence since most
1437 * behavior is trigged by MOUSEDOWN and MOUSEUP. But when IE is used with some
1438 * traditional screen readers (JAWS, NVDA and perhaps others), IE only sends
1439 * the CLICK event, resulting in the control being unresponsive. This class
1440 * monitors the sequence of these events, and if it detects a CLICK event not
1441 * not preceded by a MOUSEUP event, directly calls the control's event handlers
1442 * for MOUSEDOWN, then MOUSEUP. While the resulting sequence is different from
1443 * the norm (the CLICK comes first instead of last), testing thus far shows
1444 * the resulting behavior to be correct.
1445 *
1446 * See http://goo.gl/qvQR4C for more details.
1447 *
1448 * @param {!goog.ui.Control} control
1449 * @constructor
1450 * @extends {goog.Disposable}
1451 * @private
1452 */
1453 goog.ui.Control.IeMouseEventSequenceSimulator_ = function(control) {
1454 goog.ui.Control.IeMouseEventSequenceSimulator_.base(this, 'constructor');
1455
1456 /** @private {goog.ui.Control}*/
1457 this.control_ = control;
1458
1459 /** @private {boolean} */
1460 this.clickExpected_ = false;
1461
1462 /** @private @const {!goog.events.EventHandler<
1463 * !goog.ui.Control.IeMouseEventSequenceSimulator_>}
1464 */
1465 this.handler_ = new goog.events.EventHandler(this);
1466 this.registerDisposable(this.handler_);
1467
1468 var element = this.control_.getElementStrict();
1469 this.handler_
1470 .listen(element, goog.events.EventType.MOUSEDOWN, this.handleMouseDown_)
1471 .listen(element, goog.events.EventType.MOUSEUP, this.handleMouseUp_)
1472 .listen(element, goog.events.EventType.CLICK, this.handleClick_);
1473 };
1474 goog.inherits(goog.ui.Control.IeMouseEventSequenceSimulator_, goog.Disposable);
1475
1476
1477 /**
1478 * Whether this browser supports synthetic MouseEvents.
1479 *
1480 * See https://msdn.microsoft.com/library/dn905219(v=vs.85).aspx for details.
1481 *
1482 * @private {boolean}
1483 * @const
1484 */
1485 goog.ui.Control.IeMouseEventSequenceSimulator_.SYNTHETIC_EVENTS_ =
1486 !goog.userAgent.IE || goog.userAgent.isDocumentModeOrHigher(9);
1487
1488
1489 /** @private */
1490 goog.ui.Control.IeMouseEventSequenceSimulator_.prototype.handleMouseDown_ =
1491 function() {
1492 this.clickExpected_ = false;
1493 };
1494
1495
1496 /** @private */
1497 goog.ui.Control.IeMouseEventSequenceSimulator_.prototype.handleMouseUp_ =
1498 function() {
1499 this.clickExpected_ = true;
1500 };
1501
1502
1503 /**
1504 * @param {!MouseEvent} e
1505 * @param {goog.events.EventType} typeArg
1506 * @return {!MouseEvent}
1507 * @private
1508 */
1509 goog.ui.Control.IeMouseEventSequenceSimulator_.makeLeftMouseEvent_ = function(
1510 e, typeArg) {
1511 'use strict';
1512
1513 if (!goog.ui.Control.IeMouseEventSequenceSimulator_.SYNTHETIC_EVENTS_) {
1514 // IE < 9 does not support synthetic mouse events. Therefore, reuse the
1515 // existing MouseEvent by overwriting the read only button and type
1516 // properties. As IE < 9 does not support ES5 strict mode this will not
1517 // generate an exception even when the script specifies "use strict".
1518 e.button = goog.events.BrowserEvent.MouseButton.LEFT;
1519 e.type = typeArg;
1520 return e;
1521 }
1522
1523 var event = /** @type {!MouseEvent} */ (document.createEvent('MouseEvents'));
1524 event.initMouseEvent(
1525 typeArg, e.bubbles, e.cancelable,
1526 e.view || null, // IE9 errors if view is undefined
1527 e.detail, e.screenX, e.screenY, e.clientX, e.clientY, e.ctrlKey, e.altKey,
1528 e.shiftKey, e.metaKey, goog.events.BrowserEvent.MouseButton.LEFT,
1529 e.relatedTarget || null); // IE9 errors if relatedTarget is undefined
1530 return event;
1531 };
1532
1533
1534 /**
1535 * @param {!goog.events.Event} e
1536 * @private
1537 */
1538 goog.ui.Control.IeMouseEventSequenceSimulator_.prototype.handleClick_ =
1539 function(e) {
1540 if (this.clickExpected_) {
1541 // This is the end of a normal click sequence: mouse-down, mouse-up, click.
1542 // Assume appropriate actions have already been performed.
1543 this.clickExpected_ = false;
1544 return;
1545 }
1546
1547 // For click events not part of a normal sequence, similate the mouse-down and
1548 // mouse-up events by creating synthetic events for each and directly invoke
1549 // the corresponding event listeners in order.
1550
1551 var browserEvent = /** @type {goog.events.BrowserEvent} */ (e);
1552
1553 var event = /** @type {!MouseEvent} */ (browserEvent.getBrowserEvent());
1554 var origEventButton = event.button;
1555 var origEventType = event.type;
1556
1557 var down = goog.ui.Control.IeMouseEventSequenceSimulator_.makeLeftMouseEvent_(
1558 event, goog.events.EventType.MOUSEDOWN);
1559 this.control_.handleMouseDown(
1560 new goog.events.BrowserEvent(down, browserEvent.currentTarget));
1561
1562 var up = goog.ui.Control.IeMouseEventSequenceSimulator_.makeLeftMouseEvent_(
1563 event, goog.events.EventType.MOUSEUP);
1564 this.control_.handleMouseUp(
1565 new goog.events.BrowserEvent(up, browserEvent.currentTarget));
1566
1567 if (goog.ui.Control.IeMouseEventSequenceSimulator_.SYNTHETIC_EVENTS_) {
1568 // This browser supports synthetic events. Avoid resetting the read only
1569 // properties (type, button) as they were not overwritten and writing them
1570 // results in an exception when running in ES5 strict mode.
1571 return;
1572 }
1573
1574 // Restore original values for click handlers that have not yet been invoked.
1575 event.button = origEventButton;
1576 event.type = origEventType;
1577 };
1578
1579
1580 /** @override */
1581 goog.ui.Control.IeMouseEventSequenceSimulator_.prototype.disposeInternal =
1582 function() {
1583 this.control_ = null;
1584 goog.ui.Control.IeMouseEventSequenceSimulator_.base(this, 'disposeInternal');
1585 };