src/tip/QuickTipManager.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @class Ext.tip.QuickTipManager
  17  *
  18  * Provides attractive and customizable tooltips for any element. The QuickTips
  19  * singleton is used to configure and manage tooltips globally for multiple elements
  20  * in a generic manner.  To create individual tooltips with maximum customizability,
  21  * you should consider either {@link Ext.tip.Tip} or {@link Ext.tip.ToolTip}.
  22  *
  23  * Quicktips can be configured via tag attributes directly in markup, or by
  24  * registering quick tips programmatically via the {@link #register} method.
  25  *
  26  * The singleton's instance of {@link Ext.tip.QuickTip} is available via
  27  * {@link #getQuickTip}, and supports all the methods, and all the all the
  28  * configuration properties of Ext.tip.QuickTip. These settings will apply to all
  29  * tooltips shown by the singleton.
  30  *
  31  * Below is the summary of the configuration properties which can be used.
  32  * For detailed descriptions see the config options for the {@link Ext.tip.QuickTip QuickTip} class
  33  *
  34  * ## QuickTips singleton configs (all are optional)
  35  *
  36  *  - `dismissDelay`
  37  *  - `hideDelay`
  38  *  - `maxWidth`
  39  *  - `minWidth`
  40  *  - `showDelay`
  41  *  - `trackMouse`
  42  *
  43  * ## Target element configs (optional unless otherwise noted)
  44  *
  45  *  - `autoHide`
  46  *  - `cls`
  47  *  - `dismissDelay` (overrides singleton value)
  48  *  - `target` (required)
  49  *  - `text` (required)
  50  *  - `title`
  51  *  - `width`
  52  *
  53  * Here is an example showing how some of these config options could be used:
  54  *
  55  *     @example
  56  *     // Init the singleton.  Any tag-based quick tips will start working.
  57  *     Ext.tip.QuickTipManager.init();
  58  *
  59  *     // Apply a set of config properties to the singleton
  60  *     Ext.apply(Ext.tip.QuickTipManager.getQuickTip(), {
  61  *         maxWidth: 200,
  62  *         minWidth: 100,
  63  *         showDelay: 50      // Show 50ms after entering target
  64  *     });
  65  *
  66  *     // Create a small panel to add a quick tip to
  67  *     Ext.create('Ext.container.Container', {
  68  *         id: 'quickTipContainer',
  69  *         width: 200,
  70  *         height: 150,
  71  *         style: {
  72  *             backgroundColor:'#000000'
  73  *         },
  74  *         renderTo: Ext.getBody()
  75  *     });
  76  *
  77  *
  78  *     // Manually register a quick tip for a specific element
  79  *     Ext.tip.QuickTipManager.register({
  80  *         target: 'quickTipContainer',
  81  *         title: 'My Tooltip',
  82  *         text: 'This tooltip was added in code',
  83  *         width: 100,
  84  *         dismissDelay: 10000 // Hide after 10 seconds hover
  85  *     });
  86  *
  87  * To register a quick tip in markup, you simply add one or more of the valid QuickTip attributes prefixed with
  88  * the **data-** namespace.  The HTML element itself is automatically set as the quick tip target. Here is the summary
  89  * of supported attributes (optional unless otherwise noted):
  90  *
  91  *  - `hide`: Specifying "user" is equivalent to setting autoHide = false.  Any other value will be the same as autoHide = true.
  92  *  - `qclass`: A CSS class to be applied to the quick tip (equivalent to the 'cls' target element config).
  93  *  - `qtip (required)`: The quick tip text (equivalent to the 'text' target element config).
  94  *  - `qtitle`: The quick tip title (equivalent to the 'title' target element config).
  95  *  - `qwidth`: The quick tip width (equivalent to the 'width' target element config).
  96  *
  97  * Here is an example of configuring an HTML element to display a tooltip from markup:
  98  *
  99  *     // Add a quick tip to an HTML button
 100  *     <input type="button" value="OK" data-qtitle="OK Button" data-qwidth="100"
 101  *          data-qtip="This is a quick tip from markup!"></input>
 102  *
 103  * @singleton
 104  */
 105 Ext.define('Ext.tip.QuickTipManager', function() {
 106     var tip,
 107         disabled = false;
 108
 109     return {
 110         requires: ['Ext.tip.QuickTip'],
 111         singleton: true,
 112         alternateClassName: 'Ext.QuickTips',
 113
 114         /**
 115          * Initialize the global QuickTips instance and prepare any quick tips.
 116          * @param {Boolean} autoRender (optional) True to render the QuickTips container immediately to
 117          * preload images. (Defaults to true)
 118          * @param {Object} config (optional) config object for the created QuickTip. By
 119          * default, the {@link Ext.tip.QuickTip QuickTip} class is instantiated, but this can
 120          * be changed by supplying an xtype property or a className property in this object.
 121          * All other properties on this object are configuration for the created component.
 122          */
 123         init : function (autoRender, config) {
 124             if (!tip) {
 125                 if (!Ext.isReady) {
 126                     Ext.onReady(function(){
 127                         Ext.tip.QuickTipManager.init(autoRender);
 128                     });
 129                     return;
 130                 }
 131
 132                 var tipConfig = Ext.apply({ disabled: disabled }, config),
 133                     className = tipConfig.className,
 134                     xtype = tipConfig.xtype;
 135
 136                 if (className) {
 137                     delete tipConfig.className;
 138                 } else if (xtype) {
 139                     className = 'widget.' + xtype;
 140                     delete tipConfig.xtype;
 141                 }
 142
 143                 if (autoRender !== false) {
 144                     tipConfig.renderTo = document.body;
 145
 146                     //<debug>
 147                     if (tipConfig.renderTo.tagName != 'BODY') { // e.g., == 'FRAMESET'
 148                         Ext.Error.raise({
 149                             sourceClass: 'Ext.tip.QuickTipManager',
 150                             sourceMethod: 'init',
 151                             msg: 'Cannot init QuickTipManager: no document body'
 152                         });
 153                     }
 154                     //</debug>
 155                 }
 156
 157                 tip = Ext.create(className || 'Ext.tip.QuickTip', tipConfig);
 158             }
 159         },
 160
 161         /**
 162          * Destroy the QuickTips instance.
 163          */
 164         destroy: function() {
 165             if (tip) {
 166                 var undef;
 167                 tip.destroy();
 168                 tip = undef;
 169             }
 170         },
 171
 172         // Protected method called by the dd classes
 173         ddDisable : function(){
 174             // don't disable it if we don't need to
 175             if(tip && !disabled){
 176                 tip.disable();
 177             }
 178         },
 179
 180         // Protected method called by the dd classes
 181         ddEnable : function(){
 182             // only enable it if it hasn't been disabled
 183             if(tip && !disabled){
 184                 tip.enable();
 185             }
 186         },
 187
 188         /**
 189          * Enable quick tips globally.
 190          */
 191         enable : function(){
 192             if(tip){
 193                 tip.enable();
 194             }
 195             disabled = false;
 196         },
 197
 198         /**
 199          * Disable quick tips globally.
 200          */
 201         disable : function(){
 202             if(tip){
 203                 tip.disable();
 204             }
 205             disabled = true;
 206         },
 207
 208         /**
 209          * Returns true if quick tips are enabled, else false.
 210          * @return {Boolean}
 211          */
 212         isEnabled : function(){
 213             return tip !== undefined && !tip.disabled;
 214         },
 215
 216         /**
 217          * Gets the single {@link Ext.tip.QuickTip QuickTip} instance used to show tips from all registered elements.
 218          * @return {Ext.tip.QuickTip}
 219          */
 220         getQuickTip : function(){
 221             return tip;
 222         },
 223
 224         /**
 225          * Configures a new quick tip instance and assigns it to a target element.  See
 226          * {@link Ext.tip.QuickTip#register} for details.
 227          * @param {Object} config The config object
 228          */
 229         register : function(){
 230             tip.register.apply(tip, arguments);
 231         },
 232
 233         /**
 234          * Removes any registered quick tip from the target element and destroys it.
 235          * @param {String/HTMLElement/Ext.Element} el The element from which the quick tip is to be removed or ID of the element.
 236          */
 237         unregister : function(){
 238             tip.unregister.apply(tip, arguments);
 239         },
 240
 241         /**
 242          * Alias of {@link #register}.
 243          * @param {Object} config The config object
 244          */
 245         tips : function(){
 246             tip.register.apply(tip, arguments);
 247         }
 248     };
 249 }());