src/tip/QuickTipManager.js

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