diff options
Diffstat (limited to 'contexts/data/lib/closure-library/closure/goog/ui/control.js')
| -rw-r--r-- | contexts/data/lib/closure-library/closure/goog/ui/control.js | 1388 |
1 files changed, 0 insertions, 1388 deletions
diff --git a/contexts/data/lib/closure-library/closure/goog/ui/control.js b/contexts/data/lib/closure-library/closure/goog/ui/control.js deleted file mode 100644 index bfab71f..0000000 --- a/contexts/data/lib/closure-library/closure/goog/ui/control.js +++ /dev/null @@ -1,1388 +0,0 @@ -// 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(attila): If the renderer framework works well, pull it into Component. - * - * @author attila@google.com (Attila Bodis) - * @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(attila): 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; - - -/** - * The control's preferred ARIA role. - * @type {?goog.dom.a11y.Role} - * @private - */ -goog.ui.Control.prototype.preferredAriaRole_ = null; - - -// 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, this.getPreferredAriaRole()); - - // 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 control's preferred ARIA role. This can be used by a control to - * override the role that would be assigned by the renderer. This is useful in - * cases where a different ARIA role is appropriate for a control because of the - * context in which it's used. E.g., a {@link goog.ui.MenuButton} added to a - * {@link goog.ui.Select} should have an ARIA role of LISTBOX and not MENUITEM. - * @return {?goog.dom.a11y.Role} This control's preferred ARIA role or null if - * no preferred ARIA role is set. - */ -goog.ui.Control.prototype.getPreferredAriaRole = function() { - return this.preferredAriaRole_; -}; - - -/** - * Sets the control's preferred ARIA role. This can be used to override the role - * that would be assigned by the renderer. This is useful in cases where a - * different ARIA role is appropriate for a control because of the - * context in which it's used. E.g., a {@link goog.ui.MenuButton} added to a - * {@link goog.ui.Select} should have an ARIA role of LISTBOX and not MENUITEM. - * @param {goog.dom.a11y.Role} role This control's preferred ARIA role. - */ -goog.ui.Control.prototype.setPreferredAriaRole = function(role) { - this.preferredAriaRole_ = role; -}; - - -/** - * 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). - * @override - */ -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. - * @override - */ -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, this.getPreferredAriaRole()); - - // 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 (this.handleContextMenu != goog.nullFunction) { - handler.listen(element, goog.events.EventType.CONTEXTMENU, - this.handleContextMenu); - } - 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 (this.handleContextMenu != goog.nullFunction) { - handler.unlisten(element, goog.events.EventType.CONTEXTMENU, - this.handleContextMenu); - } - 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); - } -}; - - -/** @override */ -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; -}; - - -/** - * @return {string} Text caption of the control or empty string if none. - */ -goog.ui.Control.prototype.getCaption = function() { - var content = this.getContent(); - if (!content) { - return ''; - } - var caption = - goog.isString(content) ? content : - goog.isArray(content) ? goog.array.map(content, - goog.dom.getRawTextContent).join('') : - goog.dom.getTextContent(/** @type {!Node} */ (content)); - return goog.string.collapseBreakingSpaces(caption); -}; - - -/** - * Sets the text caption of the component. - * @param {string} caption Text caption of the component. - */ -goog.ui.Control.prototype.setCaption = function(caption) { - this.setContent(caption); -}; - - -// Component state management. - - -/** @override */ -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); - } - } -}; - - -/** - * Handles contextmenu events. - * @param {goog.events.BrowserEvent} e Event to handle. - */ -goog.ui.Control.prototype.handleContextMenu = goog.nullFunction; - - -/** - * 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) { - actionEvent.altKey = e.altKey; - actionEvent.ctrlKey = e.ctrlKey; - actionEvent.metaKey = e.metaKey; - actionEvent.shiftKey = e.shiftKey; - actionEvent.platformModifierKey = e.platformModifierKey; - } - 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); - }); |