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  * {@img Ext.tip.QuickTipManager/Ext.tip.QuickTipManager.png Ext.tip.QuickTipManager component}
  56  *
  57  * ## Code
  58  *
  59  *     // Init the singleton.  Any tag-based quick tips will start working.
  60  *     Ext.tip.QuickTipManager.init();
  61  *
  62  *     // Apply a set of config properties to the singleton
  63  *     Ext.apply(Ext.tip.QuickTipManager.getQuickTip(), {
  64  *         maxWidth: 200,
  65  *         minWidth: 100,
  66  *         showDelay: 50      // Show 50ms after entering target
  67  *     });
  68  *
  69  *     // Create a small panel to add a quick tip to
  70  *     Ext.create('Ext.container.Container', {
  71  *         id: 'quickTipContainer',
  72  *         width: 200,
  73  *         height: 150,
  74  *         style: {
  75  *             backgroundColor:'#000000'
  76  *         },
  77  *         renderTo: Ext.getBody()
  78  *     });
  79  *
  80  *
  81  *     // Manually register a quick tip for a specific element
  82  *     Ext.tip.QuickTipManager.register({
  83  *         target: 'quickTipContainer',
  84  *         title: 'My Tooltip',
  85  *         text: 'This tooltip was added in code',
  86  *         width: 100,
  87  *         dismissDelay: 10000 // Hide after 10 seconds hover
  88  *     });
  89  *
  90  * To register a quick tip in markup, you simply add one or more of the valid QuickTip attributes prefixed with
  91  * the **data-** namespace.  The HTML element itself is automatically set as the quick tip target. Here is the summary
  92  * of supported attributes (optional unless otherwise noted):
  93  *
  94  *  - `hide`: Specifying "user" is equivalent to setting autoHide = false.  Any other value will be the same as autoHide = true.
  95  *  - `qclass`: A CSS class to be applied to the quick tip (equivalent to the 'cls' target element config).
  96  *  - `qtip (required)`: The quick tip text (equivalent to the 'text' target element config).
  97  *  - `qtitle`: The quick tip title (equivalent to the 'title' target element config).
  98  *  - `qwidth`: The quick tip width (equivalent to the 'width' target element config).
  99  *
 100  * Here is an example of configuring an HTML element to display a tooltip from markup:
 101  *
 102  *     // Add a quick tip to an HTML button
 103  *     <input type="button" value="OK" data-qtitle="OK Button" data-qwidth="100"
 104  *          data-qtip="This is a quick tip from markup!"></input>
 105  *
 106  * @singleton
 107  */
 108 Ext.define('Ext.tip.QuickTipManager', function() {
 109     var tip,
 110         disabled = false;
 111
 112     return {
 113         requires: ['Ext.tip.QuickTip'],
 114         singleton: true,
 115         alternateClassName: 'Ext.QuickTips',
 116
 117         /**
 118          * Initialize the global QuickTips instance and prepare any quick tips.
 119          * @param {Boolean} autoRender True to render the QuickTips container immediately to
 120          * preload images. (Defaults to true)
 121          * @param {Object} config An optional config object for the created QuickTip. By
 122          * default, the {@link Ext.tip.QuickTip QuickTip} class is instantiated, but this can
 123          * be changed by supplying an xtype property or a className property in this object.
 124          * All other properties on this object are configuration for the created component.
 125          */
 126         init : function (autoRender, config) {
 127             if (!tip) {
 128                 if (!Ext.isReady) {
 129                     Ext.onReady(function(){
 130                         Ext.tip.QuickTipManager.init(autoRender);
 131                     });
 132                     return;
 133                 }
 134
 135                 var tipConfig = Ext.apply({ disabled: disabled }, config),
 136                     className = tipConfig.className,
 137                     xtype = tipConfig.xtype;
 138
 139                 if (className) {
 140                     delete tipConfig.className;
 141                 } else if (xtype) {
 142                     className = 'widget.' + xtype;
 143                     delete tipConfig.xtype;
 144                 }
 145
 146                 if (autoRender !== false) {
 147                     tipConfig.renderTo = document.body;
 148
 149                     //<debug>
 150                     if (tipConfig.renderTo.tagName != 'BODY') { // e.g., == 'FRAMESET'
 151                         Ext.Error.raise({
 152                             sourceClass: 'Ext.tip.QuickTipManager',
 153                             sourceMethod: 'init',
 154                             msg: 'Cannot init QuickTipManager: no document body'
 155                         });
 156                     }
 157                     //</debug>
 158                 }
 159
 160                 tip = Ext.create(className || 'Ext.tip.QuickTip', tipConfig);
 161             }
 162         },
 163
 164         /**
 165          * Destroy the QuickTips instance.
 166          */
 167         destroy: function() {
 168             if (tip) {
 169                 var undef;
 170                 tip.destroy();
 171                 tip = undef;
 172             }
 173         },
 174
 175         // Protected method called by the dd classes
 176         ddDisable : function(){
 177             // don't disable it if we don't need to
 178             if(tip && !disabled){
 179                 tip.disable();
 180             }
 181         },
 182
 183         // Protected method called by the dd classes
 184         ddEnable : function(){
 185             // only enable it if it hasn't been disabled
 186             if(tip && !disabled){
 187                 tip.enable();
 188             }
 189         },
 190
 191         /**
 192          * Enable quick tips globally.
 193          */
 194         enable : function(){
 195             if(tip){
 196                 tip.enable();
 197             }
 198             disabled = false;
 199         },
 200
 201         /**
 202          * Disable quick tips globally.
 203          */
 204         disable : function(){
 205             if(tip){
 206                 tip.disable();
 207             }
 208             disabled = true;
 209         },
 210
 211         /**
 212          * Returns true if quick tips are enabled, else false.
 213          * @return {Boolean}
 214          */
 215         isEnabled : function(){
 216             return tip !== undefined && !tip.disabled;
 217         },
 218
 219         /**
 220          * Gets the single {@link Ext.tip.QuickTip QuickTip} instance used to show tips from all registered elements.
 221          * @return {Ext.tip.QuickTip}
 222          */
 223         getQuickTip : function(){
 224             return tip;
 225         },
 226
 227         /**
 228          * Configures a new quick tip instance and assigns it to a target element.  See
 229          * {@link Ext.tip.QuickTip#register} for details.
 230          * @param {Object} config The config object
 231          */
 232         register : function(){
 233             tip.register.apply(tip, arguments);
 234         },
 235
 236         /**
 237          * Removes any registered quick tip from the target element and destroys it.
 238          * @param {String/HTMLElement/Element} el The element from which the quick tip is to be removed.
 239          */
 240         unregister : function(){
 241             tip.unregister.apply(tip, arguments);
 242         },
 243
 244         /**
 245          * Alias of {@link #register}.
 246          * @param {Object} config The config object
 247          */
 248         tips : function(){
 249             tip.register.apply(tip, arguments);
 250         }
 251     };
 252 }());