closure 1.1.692

data/closure-library/closure/goog/ui/control.js

@@ -0,0 +1,1348 @@
+// Copyright 2007 The Closure Library Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @fileoverview Base class for UI controls such as buttons, menus, menu items,
+ * toolbar buttons, etc.  The implementation is based on a generalized version
+ * of {@link goog.ui.MenuItem}.
+ * TODO(user):  If the renderer framework works well, pull it into Component.
+ *
+ * @see ../demos/control.html
+ * @see http://code.google.com/p/closure-library/wiki/IntroToControls
+ */
+
+goog.provide('goog.ui.Control');
+
+goog.require('goog.array');
+goog.require('goog.dom');
+goog.require('goog.events.BrowserEvent.MouseButton');
+goog.require('goog.events.Event');
+goog.require('goog.events.EventType');
+goog.require('goog.events.KeyCodes');
+goog.require('goog.events.KeyHandler');
+goog.require('goog.events.KeyHandler.EventType');
+goog.require('goog.string');
+goog.require('goog.ui.Component');
+goog.require('goog.ui.Component.Error');
+goog.require('goog.ui.Component.EventType');
+goog.require('goog.ui.Component.State');
+goog.require('goog.ui.ControlContent');
+goog.require('goog.ui.ControlRenderer');
+goog.require('goog.ui.decorate');
+goog.require('goog.ui.registry');
+goog.require('goog.userAgent');
+
+
+
+/**
+ * Base class for UI controls.  Extends {@link goog.ui.Component} by adding
+ * the following:
+ *  <ul>
+ *    <li>a {@link goog.events.KeyHandler}, to simplify keyboard handling,
+ *    <li>a pluggable <em>renderer</em> framework, to simplify the creation of
+ *        simple controls without the need to subclass this class,
+ *    <li>the notion of component <em>content</em>, like a text caption or DOM
+ *        structure displayed in the component (e.g. a button label),
+ *    <li>getter and setter for component content, as well as a getter and
+ *        setter specifically for caption text (for convenience),
+ *    <li>support for hiding/showing the component,
+      <li>fine-grained control over supported states and state transition
+          events, and
+ *    <li>default mouse and keyboard event handling.
+ *  </ul>
+ * This class has sufficient built-in functionality for most simple UI controls.
+ * All controls dispatch SHOW, HIDE, ENTER, LEAVE, and ACTION events on show,
+ * hide, mouseover, mouseout, and user action, respectively.  Additional states
+ * are also supported.  See closure/demos/control.html
+ * for example usage.
+ * @param {goog.ui.ControlContent} content Text caption or DOM structure
+ *     to display as the content of the component (if any).
+ * @param {goog.ui.ControlRenderer=} opt_renderer Renderer used to render or
+ *     decorate the component; defaults to {@link goog.ui.ControlRenderer}.
+ * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper, used for
+ *     document interaction.
+ * @constructor
+ * @extends {goog.ui.Component}
+ */
+goog.ui.Control = function(content, opt_renderer, opt_domHelper) {
+  goog.ui.Component.call(this, opt_domHelper);
+  this.renderer_ = opt_renderer ||
+      goog.ui.registry.getDefaultRenderer(this.constructor);
+  this.setContentInternal(content);
+};
+goog.inherits(goog.ui.Control, goog.ui.Component);
+
+
+// Renderer registry.
+// TODO(user): Refactor existing usages inside Google in a follow-up CL.
+
+
+/**
+ * Maps a CSS class name to a function that returns a new instance of
+ * {@link goog.ui.Control} or a subclass thereof, suitable to decorate
+ * an element that has the specified CSS class.  UI components that extend
+ * {@link goog.ui.Control} and want {@link goog.ui.Container}s to be able
+ * to discover and decorate elements using them should register a factory
+ * function via this API.
+ * @param {string} className CSS class name.
+ * @param {Function} decoratorFunction Function that takes no arguments and
+ *     returns a new instance of a control to decorate an element with the
+ *     given class.
+ * @deprecated Use {@link goog.ui.registry.setDecoratorByClassName} instead.
+ */
+goog.ui.Control.registerDecorator = goog.ui.registry.setDecoratorByClassName;
+
+
+/**
+ * Takes an element and returns a new instance of {@link goog.ui.Control}
+ * or a subclass, suitable to decorate it (based on the element's CSS class).
+ * @param {Element} element Element to decorate.
+ * @return {goog.ui.Control?} New control instance to decorate the element
+ *     (null if none).
+ * @deprecated Use {@link goog.ui.registry.getDecorator} instead.
+ */
+goog.ui.Control.getDecorator =
+    /** @type {function(Element): goog.ui.Control} */ (
+        goog.ui.registry.getDecorator);
+
+
+/**
+ * Takes an element, and decorates it with a {@link goog.ui.Control} instance
+ * if a suitable decorator is found.
+ * @param {Element} element Element to decorate.
+ * @return {goog.ui.Control?} New control instance that decorates the element
+ *     (null if none).
+ * @deprecated Use {@link goog.ui.decorate} instead.
+ */
+goog.ui.Control.decorate = /** @type {function(Element): goog.ui.Control} */ (
+    goog.ui.decorate);
+
+
+/**
+ * Renderer associated with the component.
+ * @type {goog.ui.ControlRenderer|undefined}
+ * @private
+ */
+goog.ui.Control.prototype.renderer_;
+
+
+/**
+ * Text caption or DOM structure displayed in the component.
+ * @type {goog.ui.ControlContent}
+ * @private
+ */
+goog.ui.Control.prototype.content_ = null;
+
+
+/**
+ * Current component state; a bit mask of {@link goog.ui.Component.State}s.
+ * @type {number}
+ * @private
+ */
+goog.ui.Control.prototype.state_ = 0x00;
+
+
+/**
+ * A bit mask of {@link goog.ui.Component.State}s this component supports.
+ * @type {number}
+ * @private
+ */
+goog.ui.Control.prototype.supportedStates_ =
+    goog.ui.Component.State.DISABLED |
+    goog.ui.Component.State.HOVER |
+    goog.ui.Component.State.ACTIVE |
+    goog.ui.Component.State.FOCUSED;
+
+
+/**
+ * A bit mask of {@link goog.ui.Component.State}s for which this component
+ * provides default event handling.  For example, a component that handles
+ * the HOVER state automatically will highlight itself on mouseover, whereas
+ * a component that doesn't handle HOVER automatically will only dispatch
+ * ENTER and LEAVE events but not call {@link setHighlighted} on itself.
+ * By default, components provide default event handling for all states.
+ * Controls hosted in containers (e.g. menu items in a menu, or buttons in a
+ * toolbar) will typically want to have their container manage their highlight
+ * state.  Selectable controls managed by a selection model will also typically
+ * want their selection state to be managed by the model.
+ * @type {number}
+ * @private
+ */
+goog.ui.Control.prototype.autoStates_ = goog.ui.Component.State.ALL;
+
+
+/**
+ * A bit mask of {@link goog.ui.Component.State}s for which this component
+ * dispatches state transition events.  Because events are expensive, the
+ * default behavior is to not dispatch any state transition events at all.
+ * Use the {@link #setDispatchTransitionEvents} API to request transition
+ * events  as needed.  Subclasses may enable transition events by default.
+ * Controls hosted in containers or managed by a selection model will typically
+ * want to dispatch transition events.
+ * @type {number}
+ * @private
+ */
+goog.ui.Control.prototype.statesWithTransitionEvents_ = 0x00;
+
+
+/**
+ * Component visibility.
+ * @type {boolean}
+ * @private
+ */
+goog.ui.Control.prototype.visible_ = true;
+
+
+/**
+ * Keyboard event handler.
+ * @type {goog.events.KeyHandler}
+ * @private
+ */
+goog.ui.Control.prototype.keyHandler_;
+
+
+/**
+ * Additional class name(s) to apply to the control's root element, if any.
+ * @type {Array.<string>?}
+ * @private
+ */
+goog.ui.Control.prototype.extraClassNames_ = null;
+
+
+/**
+ * Whether the control should listen for and handle mouse events; defaults to
+ * true.
+ * @type {boolean}
+ * @private
+ */
+goog.ui.Control.prototype.handleMouseEvents_ = true;
+
+
+/**
+ * Whether the control allows text selection within its DOM.  Defaults to false.
+ * @type {boolean}
+ * @private
+ */
+goog.ui.Control.prototype.allowTextSelection_ = false;
+
+
+// Event handler and renderer management.
+
+
+/**
+ * Returns true if the control is configured to handle its own mouse events,
+ * false otherwise.  Controls not hosted in {@link goog.ui.Container}s have
+ * to handle their own mouse events, but controls hosted in containers may
+ * allow their parent to handle mouse events on their behalf.  Considered
+ * protected; should only be used within this package and by subclasses.
+ * @return {boolean} Whether the control handles its own mouse events.
+ */
+goog.ui.Control.prototype.isHandleMouseEvents = function() {
+  return this.handleMouseEvents_;
+};
+
+
+/**
+ * Enables or disables mouse event handling for the control.  Containers may
+ * use this method to disable mouse event handling in their child controls.
+ * Considered protected; should only be used within this package and by
+ * subclasses.
+ * @param {boolean} enable Whether to enable or disable mouse event handling.
+ */
+goog.ui.Control.prototype.setHandleMouseEvents = function(enable) {
+  if (this.isInDocument() && enable != this.handleMouseEvents_) {
+    // Already in the document; need to update event handler.
+    this.enableMouseEventHandling_(enable);
+  }
+  this.handleMouseEvents_ = enable;
+};
+
+
+/**
+ * Returns the DOM element on which the control is listening for keyboard
+ * events (null if none).
+ * @return {Element} Element on which the control is listening for key
+ *     events.
+ */
+goog.ui.Control.prototype.getKeyEventTarget = function() {
+  // Delegate to renderer.
+  return this.renderer_.getKeyEventTarget(this);
+};
+
+
+/**
+ * Returns the keyboard event handler for this component, lazily created the
+ * first time this method is called.  Considered protected; should only be
+ * used within this package and by subclasses.
+ * @return {goog.events.KeyHandler} Keyboard event handler for this component.
+ * @protected
+ */
+goog.ui.Control.prototype.getKeyHandler = function() {
+  return this.keyHandler_ || (this.keyHandler_ = new goog.events.KeyHandler());
+};
+
+
+/**
+ * Returns the renderer used by this component to render itself or to decorate
+ * an existing element.
+ * @return {goog.ui.ControlRenderer|undefined} Renderer used by the component
+ *     (undefined if none).
+ */
+goog.ui.Control.prototype.getRenderer = function() {
+  return this.renderer_;
+};
+
+
+/**
+ * Registers the given renderer with the component.  Changing renderers after
+ * the component has entered the document is an error.
+ * @param {goog.ui.ControlRenderer} renderer Renderer used by the component.
+ * @throws {Error} If the control is already in the document.
+ */
+goog.ui.Control.prototype.setRenderer = function(renderer) {
+  if (this.isInDocument()) {
+    // Too late.
+    throw Error(goog.ui.Component.Error.ALREADY_RENDERED);
+  }
+
+  if (this.getElement()) {
+    // The component has already been rendered, but isn't yet in the document.
+    // Replace the renderer and delete the current DOM, so it can be re-rendered
+    // using the new renderer the next time someone calls render().
+    this.setElementInternal(null);
+  }
+
+  this.renderer_ = renderer;
+};
+
+
+// Support for additional styling.
+
+
+/**
+ * Returns any additional class name(s) to be applied to the component's
+ * root element, or null if no extra class names are needed.
+ * @return {Array.<string>?} Additional class names to be applied to
+ *     the component's root element (null if none).
+ */
+goog.ui.Control.prototype.getExtraClassNames = function() {
+  return this.extraClassNames_;
+};
+
+
+/**
+ * Adds the given class name to the list of classes to be applied to the
+ * component's root element.
+ * @param {string} className Additional class name to be applied to the
+ *     component's root element.
+ */
+goog.ui.Control.prototype.addClassName = function(className) {
+  if (className) {
+    if (this.extraClassNames_) {
+      if (!goog.array.contains(this.extraClassNames_, className)) {
+        this.extraClassNames_.push(className);
+      }
+    } else {
+      this.extraClassNames_ = [className];
+    }
+    this.renderer_.enableExtraClassName(this, className, true);
+  }
+};
+
+
+/**
+ * Removes the given class name from the list of classes to be applied to
+ * the component's root element.
+ * @param {string} className Class name to be removed from the component's root
+ *     element.
+ */
+goog.ui.Control.prototype.removeClassName = function(className) {
+  if (className && this.extraClassNames_) {
+    goog.array.remove(this.extraClassNames_, className);
+    if (this.extraClassNames_.length == 0) {
+      this.extraClassNames_ = null;
+    }
+    this.renderer_.enableExtraClassName(this, className, false);
+  }
+};
+
+
+/**
+ * Adds or removes the given class name to/from the list of classes to be
+ * applied to the component's root element.
+ * @param {string} className CSS class name to add or remove.
+ * @param {boolean} enable Whether to add or remove the class name.
+ */
+goog.ui.Control.prototype.enableClassName = function(className, enable) {
+  if (enable) {
+    this.addClassName(className);
+  } else {
+    this.removeClassName(className);
+  }
+};
+
+
+// Standard goog.ui.Component implementation.
+
+
+/**
+ * Creates the control's DOM.  Overrides {@link goog.ui.Component#createDom} by
+ * delegating DOM manipulation to the control's renderer.
+ * @override
+ */
+goog.ui.Control.prototype.createDom = function() {
+  var element = this.renderer_.createDom(this);
+  this.setElementInternal(element);
+
+  // Initialize ARIA role.
+  this.renderer_.setAriaRole(element);
+
+  // Initialize text selection.
+  if (!this.isAllowTextSelection()) {
+    // The renderer is assumed to create selectable elements.  Since making
+    // elements unselectable is expensive, only do it if needed (bug 1037090).
+    this.renderer_.setAllowTextSelection(element, false);
+  }
+
+  // Initialize visibility.
+  if (!this.isVisible()) {
+    // The renderer is assumed to create visible elements. Since hiding
+    // elements can be expensive, only do it if needed (bug 1037105).
+    this.renderer_.setVisible(element, false);
+  }
+};
+
+
+/**
+ * Returns the DOM element into which child components are to be rendered,
+ * or null if the control itself hasn't been rendered yet.  Overrides
+ * {@link goog.ui.Component#getContentElement} by delegating to the renderer.
+ * @return {Element} Element to contain child elements (null if none).
+ */
+goog.ui.Control.prototype.getContentElement = function() {
+  // Delegate to renderer.
+  return this.renderer_.getContentElement(this.getElement());
+};
+
+
+/**
+ * Returns true if the given element can be decorated by this component.
+ * Overrides {@link goog.ui.Component#canDecorate}.
+ * @param {Element} element Element to decorate.
+ * @return {boolean} Whether the element can be decorated by this component.
+ */
+goog.ui.Control.prototype.canDecorate = function(element) {
+  // Controls support pluggable renderers; delegate to the renderer.
+  return this.renderer_.canDecorate(element);
+};
+
+
+/**
+ * Decorates the given element with this component. Overrides {@link
+ * goog.ui.Component#decorateInternal} by delegating DOM manipulation
+ * to the control's renderer.
+ * @param {Element} element Element to decorate.
+ * @protected
+ * @override
+ */
+goog.ui.Control.prototype.decorateInternal = function(element) {
+  element = this.renderer_.decorate(this, element);
+  this.setElementInternal(element);
+
+  // Initialize ARIA role.
+  this.renderer_.setAriaRole(element);
+
+  // Initialize text selection.
+  if (!this.isAllowTextSelection()) {
+    // Decorated elements are assumed to be selectable.  Since making elements
+    // unselectable is expensive, only do it if needed (bug 1037090).
+    this.renderer_.setAllowTextSelection(element, false);
+  }
+
+  // Initialize visibility based on the decorated element's styling.
+  this.visible_ = element.style.display != 'none';
+};
+
+
+/**
+ * Configures the component after its DOM has been rendered, and sets up event
+ * handling.  Overrides {@link goog.ui.Component#enterDocument}.
+ * @override
+ */
+goog.ui.Control.prototype.enterDocument = function() {
+  goog.ui.Control.superClass_.enterDocument.call(this);
+
+  // Call the renderer's initializeDom method to configure properties of the
+  // control's DOM that can only be done once it's in the document.
+  this.renderer_.initializeDom(this);
+
+  // Initialize event handling if at least one state other than DISABLED is
+  // supported.
+  if (this.supportedStates_ & ~goog.ui.Component.State.DISABLED) {
+    // Initialize mouse event handling if the control is configured to handle
+    // its own mouse events.  (Controls hosted in containers don't need to
+    // handle their own mouse events.)
+    if (this.isHandleMouseEvents()) {
+      this.enableMouseEventHandling_(true);
+    }
+
+    // Initialize keyboard event handling if the control is focusable and has
+    // a key event target.  (Controls hosted in containers typically aren't
+    // focusable, allowing their container to handle keyboard events for them.)
+    if (this.isSupportedState(goog.ui.Component.State.FOCUSED)) {
+      var keyTarget = this.getKeyEventTarget();
+      if (keyTarget) {
+        var keyHandler = this.getKeyHandler();
+        keyHandler.attach(keyTarget);
+        this.getHandler().
+            listen(keyHandler, goog.events.KeyHandler.EventType.KEY,
+                this.handleKeyEvent).
+            listen(keyTarget, goog.events.EventType.FOCUS,
+                this.handleFocus).
+            listen(keyTarget, goog.events.EventType.BLUR,
+                this.handleBlur);
+      }
+    }
+  }
+};
+
+
+/**
+ * Enables or disables mouse event handling on the control.
+ * @param {boolean} enable Whether to enable mouse event handling.
+ * @private
+ */
+goog.ui.Control.prototype.enableMouseEventHandling_ = function(enable) {
+  var handler = this.getHandler();
+  var element = this.getElement();
+  if (enable) {
+    handler.
+        listen(element, goog.events.EventType.MOUSEOVER, this.handleMouseOver).
+        listen(element, goog.events.EventType.MOUSEDOWN, this.handleMouseDown).
+        listen(element, goog.events.EventType.MOUSEUP, this.handleMouseUp).
+        listen(element, goog.events.EventType.MOUSEOUT, this.handleMouseOut);
+    if (goog.userAgent.IE) {
+      handler.listen(element, goog.events.EventType.DBLCLICK,
+          this.handleDblClick);
+    }
+  } else {
+    handler.
+        unlisten(element, goog.events.EventType.MOUSEOVER,
+            this.handleMouseOver).
+        unlisten(element, goog.events.EventType.MOUSEDOWN,
+            this.handleMouseDown).
+        unlisten(element, goog.events.EventType.MOUSEUP, this.handleMouseUp).
+        unlisten(element, goog.events.EventType.MOUSEOUT, this.handleMouseOut);
+    if (goog.userAgent.IE) {
+      handler.unlisten(element, goog.events.EventType.DBLCLICK,
+          this.handleDblClick);
+    }
+  }
+};
+
+
+/**
+ * Cleans up the component before its DOM is removed from the document, and
+ * removes event handlers.  Overrides {@link goog.ui.Component#exitDocument}
+ * by making sure that components that are removed from the document aren't
+ * focusable (i.e. have no tab index).
+ * @override
+ */
+goog.ui.Control.prototype.exitDocument = function() {
+  goog.ui.Control.superClass_.exitDocument.call(this);
+  if (this.keyHandler_) {
+    this.keyHandler_.detach();
+  }
+  if (this.isVisible() && this.isEnabled()) {
+    this.renderer_.setFocusable(this, false);
+  }
+};
+
+
+/** @inheritDoc */
+goog.ui.Control.prototype.disposeInternal = function() {
+  goog.ui.Control.superClass_.disposeInternal.call(this);
+  if (this.keyHandler_) {
+    this.keyHandler_.dispose();
+    delete this.keyHandler_;
+  }
+  delete this.renderer_;
+  this.content_ = null;
+  this.extraClassNames_ = null;
+};
+
+
+// Component content management.
+
+
+/**
+ * Returns the text caption or DOM structure displayed in the component.
+ * @return {goog.ui.ControlContent} Text caption or DOM structure
+ *     comprising the component's contents.
+ */
+goog.ui.Control.prototype.getContent = function() {
+  return this.content_;
+};
+
+
+/**
+ * Sets the component's content to the given text caption, element, or array of
+ * nodes.  (If the argument is an array of nodes, it must be an actual array,
+ * not an array-like object.)
+ * @param {goog.ui.ControlContent} content Text caption or DOM
+ *     structure to set as the component's contents.
+ */
+goog.ui.Control.prototype.setContent = function(content) {
+  // Controls support pluggable renderers; delegate to the renderer.
+  this.renderer_.setContent(this.getElement(), content);
+
+  // setContentInternal needs to be after the renderer, since the implementation
+  // may depend on the content being in the DOM.
+  this.setContentInternal(content);
+};
+
+
+/**
+ * Sets the component's content to the given text caption, element, or array
+ * of nodes.  Unlike {@link #setContent}, doesn't modify the component's DOM.
+ * Called by renderers during element decoration.  Considered protected; should
+ * only be used within this package and by subclasses.
+ * @param {goog.ui.ControlContent} content Text caption or DOM structure
+ *     to set as the component's contents.
+ * @protected
+ */
+goog.ui.Control.prototype.setContentInternal = function(content) {
+  this.content_ = content;
+};
+
+
+/**
+ * Returns the text caption of the component.
+ * @param {function(Node): string} getChildElementContent Function that takes an
+ *     element and returns a string.
+ * @return {?string} Text caption of the component (null if none).
+ */
+goog.ui.Control.prototype.getCaptionInternal =
+    function(getChildElementContent) {
+  var content = this.getContent();
+  if (!content || goog.isString(content)) {
+    return content;
+  }
+
+  var caption = goog.isArray(content) ?
+      goog.array.map(content, getChildElementContent).join('') :
+      goog.dom.getTextContent(/** @type {!Node} */ (content));
+  return caption && goog.string.trim(caption);
+};
+
+
+/**
+ * Returns the text caption of the component.
+ * @return {?string} Text caption of the component (null if none).
+ */
+goog.ui.Control.prototype.getCaption = function() {
+  return this.getCaptionInternal(goog.dom.getTextContent);
+};
+
+
+/**
+ * Sets the text caption of the component.
+ * @param {string} caption Text caption of the component (null to clear).
+ */
+goog.ui.Control.prototype.setCaption = function(caption) {
+  this.setContent(caption);
+};
+
+
+// Component state management.
+
+
+/** @inheritDoc */
+goog.ui.Control.prototype.setRightToLeft = function(rightToLeft) {
+  // The superclass implementation ensures the control isn't in the document.
+  goog.ui.Control.superClass_.setRightToLeft.call(this, rightToLeft);
+
+  var element = this.getElement();
+  if (element) {
+    this.renderer_.setRightToLeft(element, rightToLeft);
+  }
+};
+
+
+/**
+ * Returns true if the control allows text selection within its DOM, false
+ * otherwise.  Controls that disallow text selection have the appropriate
+ * unselectable styling applied to their elements.  Note that controls hosted
+ * in containers will report that they allow text selection even if their
+ * container disallows text selection.
+ * @return {boolean} Whether the control allows text selection.
+ */
+goog.ui.Control.prototype.isAllowTextSelection = function() {
+  return this.allowTextSelection_;
+};
+
+
+/**
+ * Allows or disallows text selection within the control's DOM.
+ * @param {boolean} allow Whether the control should allow text selection.
+ */
+goog.ui.Control.prototype.setAllowTextSelection = function(allow) {
+  this.allowTextSelection_ = allow;
+
+  var element = this.getElement();
+  if (element) {
+    this.renderer_.setAllowTextSelection(element, allow);
+  }
+};
+
+
+/**
+ * Returns true if the component's visibility is set to visible, false if
+ * it is set to hidden.  A component that is set to hidden is guaranteed
+ * to be hidden from the user, but the reverse isn't necessarily true.
+ * A component may be set to visible but can otherwise be obscured by another
+ * element, rendered off-screen, or hidden using direct CSS manipulation.
+ * @return {boolean} Whether the component is visible.
+ */
+goog.ui.Control.prototype.isVisible = function() {
+  return this.visible_;
+};
+
+
+/**
+ * Shows or hides the component.  Does nothing if the component already has
+ * the requested visibility.  Otherwise, dispatches a SHOW or HIDE event as
+ * appropriate, giving listeners a chance to prevent the visibility change.
+ * When showing a component that is both enabled and focusable, ensures that
+ * its key target has a tab index.  When hiding a component that is enabled
+ * and focusable, blurs its key target and removes its tab index.
+ * @param {boolean} visible Whether to show or hide the component.
+ * @param {boolean=} opt_force If true, doesn't check whether the component
+ *     already has the requested visibility, and doesn't dispatch any events.
+ * @return {boolean} Whether the visibility was changed.
+ */
+goog.ui.Control.prototype.setVisible = function(visible, opt_force) {
+  if (opt_force || (this.visible_ != visible && this.dispatchEvent(visible ?
+      goog.ui.Component.EventType.SHOW : goog.ui.Component.EventType.HIDE))) {
+    var element = this.getElement();
+    if (element) {
+      this.renderer_.setVisible(element, visible);
+    }
+    if (this.isEnabled()) {
+      this.renderer_.setFocusable(this, visible);
+    }
+    this.visible_ = visible;
+    return true;
+  }
+  return false;
+};
+
+
+/**
+ * Returns true if the component is enabled, false otherwise.
+ * @return {boolean} Whether the component is enabled.
+ */
+goog.ui.Control.prototype.isEnabled = function() {
+  return !this.hasState(goog.ui.Component.State.DISABLED);
+};
+
+
+/**
+ * Returns true if the control has a parent that is itself disabled, false
+ * otherwise.
+ * @return {boolean} Whether the component is hosted in a disabled container.
+ * @private
+ */
+goog.ui.Control.prototype.isParentDisabled_ = function() {
+  var parent = this.getParent();
+  return !!parent && typeof parent.isEnabled == 'function' &&
+      !parent.isEnabled();
+};
+
+
+/**
+ * Enables or disables the component.  Does nothing if this state transition
+ * is disallowed.  If the component is both visible and focusable, updates its
+ * focused state and tab index as needed.  If the component is being disabled,
+ * ensures that it is also deactivated and un-highlighted first.  Note that the
+ * component's enabled/disabled state is "locked" as long as it is hosted in a
+ * {@link goog.ui.Container} that is itself disabled; this is to prevent clients
+ * from accidentally re-enabling a control that is in a disabled container.
+ * @param {boolean} enable Whether to enable or disable the component.
+ * @see #isTransitionAllowed
+ */
+goog.ui.Control.prototype.setEnabled = function(enable) {
+  if (!this.isParentDisabled_() &&
+      this.isTransitionAllowed(goog.ui.Component.State.DISABLED, !enable)) {
+    if (!enable) {
+      this.setActive(false);
+      this.setHighlighted(false);
+    }
+    if (this.isVisible()) {
+      this.renderer_.setFocusable(this, enable);
+    }
+    this.setState(goog.ui.Component.State.DISABLED, !enable);
+  }
+};
+
+
+/**
+ * Returns true if the component is currently highlighted, false otherwise.
+ * @return {boolean} Whether the component is highlighted.
+ */
+goog.ui.Control.prototype.isHighlighted = function() {
+  return this.hasState(goog.ui.Component.State.HOVER);
+};
+
+
+/**
+ * Highlights or unhighlights the component.  Does nothing if this state
+ * transition is disallowed.
+ * @param {boolean} highlight Whether to highlight or unhighlight the component.
+ * @see #isTransitionAllowed
+ */
+goog.ui.Control.prototype.setHighlighted = function(highlight) {
+  if (this.isTransitionAllowed(goog.ui.Component.State.HOVER, highlight)) {
+    this.setState(goog.ui.Component.State.HOVER, highlight);
+  }
+};
+
+
+/**
+ * Returns true if the component is active (pressed), false otherwise.
+ * @return {boolean} Whether the component is active.
+ */
+goog.ui.Control.prototype.isActive = function() {
+  return this.hasState(goog.ui.Component.State.ACTIVE);
+};
+
+
+/**
+ * Activates or deactivates the component.  Does nothing if this state
+ * transition is disallowed.
+ * @param {boolean} active Whether to activate or deactivate the component.
+ * @see #isTransitionAllowed
+ */
+goog.ui.Control.prototype.setActive = function(active) {
+  if (this.isTransitionAllowed(goog.ui.Component.State.ACTIVE, active)) {
+    this.setState(goog.ui.Component.State.ACTIVE, active);
+  }
+};
+
+
+/**
+ * Returns true if the component is selected, false otherwise.
+ * @return {boolean} Whether the component is selected.
+ */
+goog.ui.Control.prototype.isSelected = function() {
+  return this.hasState(goog.ui.Component.State.SELECTED);
+};
+
+
+/**
+ * Selects or unselects the component.  Does nothing if this state transition
+ * is disallowed.
+ * @param {boolean} select Whether to select or unselect the component.
+ * @see #isTransitionAllowed
+ */
+goog.ui.Control.prototype.setSelected = function(select) {
+  if (this.isTransitionAllowed(goog.ui.Component.State.SELECTED, select)) {
+    this.setState(goog.ui.Component.State.SELECTED, select);
+  }
+};
+
+
+/**
+ * Returns true if the component is checked, false otherwise.
+ * @return {boolean} Whether the component is checked.
+ */
+goog.ui.Control.prototype.isChecked = function() {
+  return this.hasState(goog.ui.Component.State.CHECKED);
+};
+
+
+/**
+ * Checks or unchecks the component.  Does nothing if this state transition
+ * is disallowed.
+ * @param {boolean} check Whether to check or uncheck the component.
+ * @see #isTransitionAllowed
+ */
+goog.ui.Control.prototype.setChecked = function(check) {
+  if (this.isTransitionAllowed(goog.ui.Component.State.CHECKED, check)) {
+    this.setState(goog.ui.Component.State.CHECKED, check);
+  }
+};
+
+
+/**
+ * Returns true if the component is styled to indicate that it has keyboard
+ * focus, false otherwise.  Note that {@code isFocused()} returning true
+ * doesn't guarantee that the component's key event target has keyborad focus,
+ * only that it is styled as such.
+ * @return {boolean} Whether the component is styled to indicate as having
+ *     keyboard focus.
+ */
+goog.ui.Control.prototype.isFocused = function() {
+  return this.hasState(goog.ui.Component.State.FOCUSED);
+};
+
+
+/**
+ * Applies or removes styling indicating that the component has keyboard focus.
+ * Note that unlike the other "set" methods, this method is called as a result
+ * of the component's element having received or lost keyboard focus, not the
+ * other way around, so calling {@code setFocused(true)} doesn't guarantee that
+ * the component's key event target has keyboard focus, only that it is styled
+ * as such.
+ * @param {boolean} focused Whether to apply or remove styling to indicate that
+ *     the component's element has keyboard focus.
+ */
+goog.ui.Control.prototype.setFocused = function(focused) {
+  if (this.isTransitionAllowed(goog.ui.Component.State.FOCUSED, focused)) {
+    this.setState(goog.ui.Component.State.FOCUSED, focused);
+  }
+};
+
+
+/**
+ * Returns true if the component is open (expanded), false otherwise.
+ * @return {boolean} Whether the component is open.
+ */
+goog.ui.Control.prototype.isOpen = function() {
+  return this.hasState(goog.ui.Component.State.OPENED);
+};
+
+
+/**
+ * Opens (expands) or closes (collapses) the component.  Does nothing if this
+ * state transition is disallowed.
+ * @param {boolean} open Whether to open or close the component.
+ * @see #isTransitionAllowed
+ */
+goog.ui.Control.prototype.setOpen = function(open) {
+  if (this.isTransitionAllowed(goog.ui.Component.State.OPENED, open)) {
+    this.setState(goog.ui.Component.State.OPENED, open);
+  }
+};
+
+
+/**
+ * Returns the component's state as a bit mask of {@link
+ * goog.ui.Component.State}s.
+ * @return {number} Bit mask representing component state.
+ */
+goog.ui.Control.prototype.getState = function() {
+  return this.state_;
+};
+
+
+/**
+ * Returns true if the component is in the specified state, false otherwise.
+ * @param {goog.ui.Component.State} state State to check.
+ * @return {boolean} Whether the component is in the given state.
+ */
+goog.ui.Control.prototype.hasState = function(state) {
+  return !!(this.state_ & state);
+};
+
+
+/**
+ * Sets or clears the given state on the component, and updates its styling
+ * accordingly.  Does nothing if the component is already in the correct state
+ * or if it doesn't support the specified state.  Doesn't dispatch any state
+ * transition events; use advisedly.
+ * @param {goog.ui.Component.State} state State to set or clear.
+ * @param {boolean} enable Whether to set or clear the state (if supported).
+ */
+goog.ui.Control.prototype.setState = function(state, enable) {
+  if (this.isSupportedState(state) && enable != this.hasState(state)) {
+    // Delegate actual styling to the renderer, since it is DOM-specific.
+    this.renderer_.setState(this, state, enable);
+    this.state_ = enable ? this.state_ | state : this.state_ & ~state;
+  }
+};
+
+
+/**
+ * Sets the component's state to the state represented by a bit mask of
+ * {@link goog.ui.Component.State}s.  Unlike {@link #setState}, doesn't
+ * update the component's styling, and doesn't reject unsupported states.
+ * Called by renderers during element decoration.  Considered protected;
+ * should only be used within this package and by subclasses.
+ * @param {number} state Bit mask representing component state.
+ * @protected
+ */
+goog.ui.Control.prototype.setStateInternal = function(state) {
+  this.state_ = state;
+};
+
+
+/**
+ * Returns true if the component supports the specified state, false otherwise.
+ * @param {goog.ui.Component.State} state State to check.
+ * @return {boolean} Whether the component supports the given state.
+ */
+goog.ui.Control.prototype.isSupportedState = function(state) {
+  return !!(this.supportedStates_ & state);
+};
+
+
+/**
+ * Enables or disables support for the given state. Disabling support
+ * for a state while the component is in that state is an error.
+ * @param {goog.ui.Component.State} state State to support or de-support.
+ * @param {boolean} support Whether the component should support the state.
+ * @throws {Error} If disabling support for a state the control is currently in.
+ */
+goog.ui.Control.prototype.setSupportedState = function(state, support) {
+  if (this.isInDocument() && this.hasState(state) && !support) {
+    // Since we hook up event handlers in enterDocument(), this is an error.
+    throw Error(goog.ui.Component.Error.ALREADY_RENDERED);
+  }
+
+  if (!support && this.hasState(state)) {
+    // We are removing support for a state that the component is currently in.
+    this.setState(state, false);
+  }
+
+  this.supportedStates_ = support ?
+      this.supportedStates_ | state : this.supportedStates_ & ~state;
+};
+
+
+/**
+ * Returns true if the component provides default event handling for the state,
+ * false otherwise.
+ * @param {goog.ui.Component.State} state State to check.
+ * @return {boolean} Whether the component provides default event handling for
+ *     the state.
+ */
+goog.ui.Control.prototype.isAutoState = function(state) {
+  return !!(this.autoStates_ & state) && this.isSupportedState(state);
+};
+
+
+/**
+ * Enables or disables automatic event handling for the given state(s).
+ * @param {number} states Bit mask of {@link goog.ui.Component.State}s for which
+ *     default event handling is to be enabled or disabled.
+ * @param {boolean} enable Whether the component should provide default event
+ *     handling for the state(s).
+ */
+goog.ui.Control.prototype.setAutoStates = function(states, enable) {
+  this.autoStates_ = enable ?
+      this.autoStates_ | states : this.autoStates_ & ~states;
+};
+
+
+/**
+ * Returns true if the component is set to dispatch transition events for the
+ * given state, false otherwise.
+ * @param {goog.ui.Component.State} state State to check.
+ * @return {boolean} Whether the component dispatches transition events for
+ *     the state.
+ */
+goog.ui.Control.prototype.isDispatchTransitionEvents = function(state) {
+  return !!(this.statesWithTransitionEvents_ & state) &&
+      this.isSupportedState(state);
+};
+
+
+/**
+ * Enables or disables transition events for the given state(s).  Controls
+ * handle state transitions internally by default, and only dispatch state
+ * transition events if explicitly requested to do so by calling this method.
+ * @param {number} states Bit mask of {@link goog.ui.Component.State}s for
+ *     which transition events should be enabled or disabled.
+ * @param {boolean} enable Whether transition events should be enabled.
+ */
+goog.ui.Control.prototype.setDispatchTransitionEvents = function(states,
+    enable) {
+  this.statesWithTransitionEvents_ = enable ?
+      this.statesWithTransitionEvents_ | states :
+      this.statesWithTransitionEvents_ & ~states;
+};
+
+
+/**
+ * Returns true if the transition into or out of the given state is allowed to
+ * proceed, false otherwise.  A state transition is allowed under the following
+ * conditions:
+ * <ul>
+ *   <li>the component supports the state,
+ *   <li>the component isn't already in the target state,
+ *   <li>either the component is configured not to dispatch events for this
+ *       state transition, or a transition event was dispatched and wasn't
+ *       canceled by any event listener, and
+ *   <li>the component hasn't been disposed of
+ * </ul>
+ * Considered protected; should only be used within this package and by
+ * subclasses.
+ * @param {goog.ui.Component.State} state State to/from which the control is
+ *     transitioning.
+ * @param {boolean} enable Whether the control is entering or leaving the state.
+ * @return {boolean} Whether the state transition is allowed to proceed.
+ * @protected
+ */
+goog.ui.Control.prototype.isTransitionAllowed = function(state, enable) {
+  return this.isSupportedState(state) &&
+      this.hasState(state) != enable &&
+      (!(this.statesWithTransitionEvents_ & state) || this.dispatchEvent(
+          goog.ui.Component.getStateTransitionEvent(state, enable))) &&
+      !this.isDisposed();
+};
+
+
+// Default event handlers, to be overridden in subclasses.
+
+
+/**
+ * Handles mouseover events.  Dispatches an ENTER event; if the event isn't
+ * canceled, the component is enabled, and it supports auto-highlighting,
+ * highlights the component.  Considered protected; should only be used
+ * within this package and by subclasses.
+ * @param {goog.events.BrowserEvent} e Mouse event to handle.
+ */
+goog.ui.Control.prototype.handleMouseOver = function(e) {
+  // Ignore mouse moves between descendants.
+  if (!goog.ui.Control.isMouseEventWithinElement_(e, this.getElement()) &&
+      this.dispatchEvent(goog.ui.Component.EventType.ENTER) &&
+      this.isEnabled() &&
+      this.isAutoState(goog.ui.Component.State.HOVER)) {
+    this.setHighlighted(true);
+  }
+};
+
+
+/**
+ * Handles mouseout events.  Dispatches a LEAVE event; if the event isn't
+ * canceled, and the component supports auto-highlighting, deactivates and
+ * un-highlights the component.  Considered protected; should only be used
+ * within this package and by subclasses.
+ * @param {goog.events.BrowserEvent} e Mouse event to handle.
+ */
+goog.ui.Control.prototype.handleMouseOut = function(e) {
+  if (!goog.ui.Control.isMouseEventWithinElement_(e, this.getElement()) &&
+      this.dispatchEvent(goog.ui.Component.EventType.LEAVE)) {
+    if (this.isAutoState(goog.ui.Component.State.ACTIVE)) {
+      // Deactivate on mouseout; otherwise we lose track of the mouse button.
+      this.setActive(false);
+    }
+    if (this.isAutoState(goog.ui.Component.State.HOVER)) {
+      this.setHighlighted(false);
+    }
+  }
+};
+
+
+/**
+ * Checks if a mouse event (mouseover or mouseout) occured below an element.
+ * @param {goog.events.BrowserEvent} e Mouse event (should be mouseover or
+ *     mouseout).
+ * @param {Element} elem The ancestor element.
+ * @return {boolean} Whether the event has a relatedTarget (the element the
+ *     mouse is coming from) and it's a descendent of elem.
+ * @private
+ */
+goog.ui.Control.isMouseEventWithinElement_ = function(e, elem) {
+  // If relatedTarget is null, it means there was no previous element (e.g.
+  // the mouse moved out of the window).  Assume this means that the mouse
+  // event was not within the element.
+  return !!e.relatedTarget && goog.dom.contains(elem, e.relatedTarget);
+};
+
+
+/**
+ * Handles mousedown events.  If the component is enabled, highlights and
+ * activates it.  If the component isn't configured for keyboard access,
+ * prevents it from receiving keyboard focus.  Considered protected; should
+ * only be used within this package andy by subclasses.
+ * @param {goog.events.Event} e Mouse event to handle.
+ */
+goog.ui.Control.prototype.handleMouseDown = function(e) {
+  if (this.isEnabled()) {
+    // Highlight enabled control on mousedown, regardless of the mouse button.
+    if (this.isAutoState(goog.ui.Component.State.HOVER)) {
+      this.setHighlighted(true);
+    }
+
+    // For the left button only, activate the control, and focus its key event
+    // target (if supported).
+    if (e.isMouseActionButton()) {
+      if (this.isAutoState(goog.ui.Component.State.ACTIVE)) {
+        this.setActive(true);
+      }
+      if (this.renderer_.isFocusable(this)) {
+        this.getKeyEventTarget().focus();
+      }
+    }
+  }
+
+  // Cancel the default action unless the control allows text selection.
+  if (!this.isAllowTextSelection() && e.isMouseActionButton()) {
+    e.preventDefault();
+  }
+};
+
+
+/**
+ * Handles mouseup events.  If the component is enabled, highlights it.  If
+ * the component has previously been activated, performs its associated action
+ * by calling {@link performActionInternal}, then deactivates it.  Considered
+ * protected; should only be used within this package and by subclasses.
+ * @param {goog.events.Event} e Mouse event to handle.
+ */
+goog.ui.Control.prototype.handleMouseUp = function(e) {
+  if (this.isEnabled()) {
+    if (this.isAutoState(goog.ui.Component.State.HOVER)) {
+      this.setHighlighted(true);
+    }
+    if (this.isActive() &&
+        this.performActionInternal(e) &&
+        this.isAutoState(goog.ui.Component.State.ACTIVE)) {
+      this.setActive(false);
+    }
+  }
+};
+
+
+/**
+ * Handles dblclick events.  Should only be registered if the user agent is
+ * IE.  If the component is enabled, performs its associated action by calling
+ * {@link performActionInternal}.  This is used to allow more performant
+ * buttons in IE.  In IE, no mousedown event is fired when that mousedown will
+ * trigger a dblclick event.  Because of this, a user clicking quickly will
+ * only cause ACTION events to fire on every other click.  This is a workaround
+ * to generate ACTION events for every click.  Unfortunately, this workaround
+ * won't ever trigger the ACTIVE state.  This is roughly the same behaviour as
+ * if this were a 'button' element with a listener on mouseup.  Considered
+ * protected; should only be used within this package and by subclasses.
+ * @param {goog.events.Event} e Mouse event to handle.
+ */
+goog.ui.Control.prototype.handleDblClick = function(e) {
+  if (this.isEnabled()) {
+    this.performActionInternal(e);
+  }
+};
+
+
+/**
+ * Performs the appropriate action when the control is activated by the user.
+ * The default implementation first updates the checked and selected state of
+ * controls that support them, then dispatches an ACTION event.  Considered
+ * protected; should only be used within this package and by subclasses.
+ * @param {goog.events.Event} e Event that triggered the action.
+ * @return {boolean} Whether the action is allowed to proceed.
+ * @protected
+ */
+goog.ui.Control.prototype.performActionInternal = function(e) {
+  if (this.isAutoState(goog.ui.Component.State.CHECKED)) {
+    this.setChecked(!this.isChecked());
+  }
+  if (this.isAutoState(goog.ui.Component.State.SELECTED)) {
+    this.setSelected(true);
+  }
+  if (this.isAutoState(goog.ui.Component.State.OPENED)) {
+    this.setOpen(!this.isOpen());
+  }
+
+  var actionEvent = new goog.events.Event(goog.ui.Component.EventType.ACTION,
+      this);
+  if (e) {
+    var properties = [
+      'altKey', 'ctrlKey', 'metaKey', 'shiftKey', 'platformModifierKey'
+    ];
+    for (var property, i = 0; property = properties[i]; i++) {
+      actionEvent[property] = e[property];
+    }
+  }
+  return this.dispatchEvent(actionEvent);
+};
+
+
+/**
+ * Handles focus events on the component's key event target element.  If the
+ * component is focusable, updates its state and styling to indicate that it
+ * now has keyboard focus.  Considered protected; should only be used within
+ * this package and by subclasses.  <b>Warning:</b> IE dispatches focus and
+ * blur events asynchronously!
+ * @param {goog.events.Event} e Focus event to handle.
+ */
+goog.ui.Control.prototype.handleFocus = function(e) {
+  if (this.isAutoState(goog.ui.Component.State.FOCUSED)) {
+    this.setFocused(true);
+  }
+};
+
+
+/**
+ * Handles blur events on the component's key event target element.  Always
+ * deactivates the component.  In addition, if the component is focusable,
+ * updates its state and styling to indicate that it no longer has keyboard
+ * focus.  Considered protected; should only be used within this package and
+ * by subclasses.  <b>Warning:</b> IE dispatches focus and blur events
+ * asynchronously!
+ * @param {goog.events.Event} e Blur event to handle.
+ */
+goog.ui.Control.prototype.handleBlur = function(e) {
+  if (this.isAutoState(goog.ui.Component.State.ACTIVE)) {
+    this.setActive(false);
+  }
+  if (this.isAutoState(goog.ui.Component.State.FOCUSED)) {
+    this.setFocused(false);
+  }
+};
+
+
+/**
+ * Attempts to handle a keyboard event, if the component is enabled and visible,
+ * by calling {@link handleKeyEventInternal}.  Considered protected; should only
+ * be used within this package and by subclasses.
+ * @param {goog.events.KeyEvent} e Key event to handle.
+ * @return {boolean} Whether the key event was handled.
+ */
+goog.ui.Control.prototype.handleKeyEvent = function(e) {
+  if (this.isVisible() && this.isEnabled() &&
+      this.handleKeyEventInternal(e)) {
+    e.preventDefault();
+    e.stopPropagation();
+    return true;
+  }
+  return false;
+};
+
+
+/**
+ * Attempts to handle a keyboard event; returns true if the event was handled,
+ * false otherwise.  Considered protected; should only be used within this
+ * package and by subclasses.
+ * @param {goog.events.KeyEvent} e Key event to handle.
+ * @return {boolean} Whether the key event was handled.
+ * @protected
+ */
+goog.ui.Control.prototype.handleKeyEventInternal = function(e) {
+  return e.keyCode == goog.events.KeyCodes.ENTER &&
+      this.performActionInternal(e);
+};
+
+
+// Register the default renderer for goog.ui.Controls.
+goog.ui.registry.setDefaultRenderer(goog.ui.Control, goog.ui.ControlRenderer);
+
+
+// Register a decorator factory function for goog.ui.Controls.
+goog.ui.registry.setDecoratorByClassName(goog.ui.ControlRenderer.CSS_CLASS,
+    function() {
+      return new goog.ui.Control(null);
+    });