src/widgets/tips/ToolTip.js

   1 /*!
   2  * Ext JS Library 3.3.1
   3  * Copyright(c) 2006-2010 Sencha Inc.
   4  * licensing@sencha.com
   5  * http://www.sencha.com/license
   6  */
   7 /**
   8  * @class Ext.ToolTip
   9  * @extends Ext.Tip
  10  * A standard tooltip implementation for providing additional information when hovering over a target element.
  11  * @xtype tooltip
  12  * @constructor
  13  * Create a new Tooltip
  14  * @param {Object} config The configuration options
  15  */
  16 Ext.ToolTip = Ext.extend(Ext.Tip, {
  17     /**
  18      * When a Tooltip is configured with the <code>{@link #delegate}</code>
  19      * option to cause selected child elements of the <code>{@link #target}</code>
  20      * Element to each trigger a seperate show event, this property is set to
  21      * the DOM element which triggered the show.
  22      * @type DOMElement
  23      * @property triggerElement
  24      */
  25     /**
  26      * @cfg {Mixed} target The target HTMLElement, Ext.Element or id to monitor
  27      * for mouseover events to trigger showing this ToolTip.
  28      */
  29     /**
  30      * @cfg {Boolean} autoHide True to automatically hide the tooltip after the
  31      * mouse exits the target element or after the <code>{@link #dismissDelay}</code>
  32      * has expired if set (defaults to true).  If <code>{@link closable} = true</code>
  33      * a close tool button will be rendered into the tooltip header.
  34      */
  35     /**
  36      * @cfg {Number} showDelay Delay in milliseconds before the tooltip displays
  37      * after the mouse enters the target element (defaults to 500)
  38      */
  39     showDelay : 500,
  40     /**
  41      * @cfg {Number} hideDelay Delay in milliseconds after the mouse exits the
  42      * target element but before the tooltip actually hides (defaults to 200).
  43      * Set to 0 for the tooltip to hide immediately.
  44      */
  45     hideDelay : 200,
  46     /**
  47      * @cfg {Number} dismissDelay Delay in milliseconds before the tooltip
  48      * automatically hides (defaults to 5000). To disable automatic hiding, set
  49      * dismissDelay = 0.
  50      */
  51     dismissDelay : 5000,
  52     /**
  53      * @cfg {Array} mouseOffset An XY offset from the mouse position where the
  54      * tooltip should be shown (defaults to [15,18]).
  55      */
  56     /**
  57      * @cfg {Boolean} trackMouse True to have the tooltip follow the mouse as it
  58      * moves over the target element (defaults to false).
  59      */
  60     trackMouse : false,
  61     /**
  62      * @cfg {Boolean} anchorToTarget True to anchor the tooltip to the target
  63      * element, false to anchor it relative to the mouse coordinates (defaults
  64      * to true).  When <code>anchorToTarget</code> is true, use
  65      * <code>{@link #defaultAlign}</code> to control tooltip alignment to the
  66      * target element.  When <code>anchorToTarget</code> is false, use
  67      * <code>{@link #anchorPosition}</code> instead to control alignment.
  68      */
  69     anchorToTarget : true,
  70     /**
  71      * @cfg {Number} anchorOffset A numeric pixel value used to offset the
  72      * default position of the anchor arrow (defaults to 0).  When the anchor
  73      * position is on the top or bottom of the tooltip, <code>anchorOffset</code>
  74      * will be used as a horizontal offset.  Likewise, when the anchor position
  75      * is on the left or right side, <code>anchorOffset</code> will be used as
  76      * a vertical offset.
  77      */
  78     anchorOffset : 0,
  79     /**
  80      * @cfg {String} delegate <p>Optional. A {@link Ext.DomQuery DomQuery}
  81      * selector which allows selection of individual elements within the
  82      * <code>{@link #target}</code> element to trigger showing and hiding the
  83      * ToolTip as the mouse moves within the target.</p>
  84      * <p>When specified, the child element of the target which caused a show
  85      * event is placed into the <code>{@link #triggerElement}</code> property
  86      * before the ToolTip is shown.</p>
  87      * <p>This may be useful when a Component has regular, repeating elements
  88      * in it, each of which need a Tooltip which contains information specific
  89      * to that element. For example:</p><pre><code>
  90 var myGrid = new Ext.grid.gridPanel(gridConfig);
  91 myGrid.on('render', function(grid) {
  92     var store = grid.getStore();  // Capture the Store.
  93     var view = grid.getView();    // Capture the GridView.
  94     myGrid.tip = new Ext.ToolTip({
  95         target: view.mainBody,    // The overall target element.
  96         delegate: '.x-grid3-row', // Each grid row causes its own seperate show and hide.
  97         trackMouse: true,         // Moving within the row should not hide the tip.
  98         renderTo: document.body,  // Render immediately so that tip.body can be
  99                                   //  referenced prior to the first show.
 100         listeners: {              // Change content dynamically depending on which element
 101                                   //  triggered the show.
 102             beforeshow: function updateTipBody(tip) {
 103                 var rowIndex = view.findRowIndex(tip.triggerElement);
 104                 tip.body.dom.innerHTML = 'Over Record ID ' + store.getAt(rowIndex).id;
 105             }
 106         }
 107     });
 108 });
 109      *</code></pre>
 110      */
 111
 112     // private
 113     targetCounter : 0,
 114
 115     constrainPosition : false,
 116
 117     // private
 118     initComponent : function(){
 119         Ext.ToolTip.superclass.initComponent.call(this);
 120         this.lastActive = new Date();
 121         this.initTarget(this.target);
 122         this.origAnchor = this.anchor;
 123     },
 124
 125     // private
 126     onRender : function(ct, position){
 127         Ext.ToolTip.superclass.onRender.call(this, ct, position);
 128         this.anchorCls = 'x-tip-anchor-' + this.getAnchorPosition();
 129         this.anchorEl = this.el.createChild({
 130             cls: 'x-tip-anchor ' + this.anchorCls
 131         });
 132     },
 133
 134     // private
 135     afterRender : function(){
 136         Ext.ToolTip.superclass.afterRender.call(this);
 137         this.anchorEl.setStyle('z-index', this.el.getZIndex() + 1).setVisibilityMode(Ext.Element.DISPLAY);
 138     },
 139
 140     /**
 141      * Binds this ToolTip to the specified element. The tooltip will be displayed when the mouse moves over the element.
 142      * @param {Mixed} t The Element, HtmlElement, or ID of an element to bind to
 143      */
 144     initTarget : function(target){
 145         var t;
 146         if((t = Ext.get(target))){
 147             if(this.target){
 148                 var tg = Ext.get(this.target);
 149                 this.mun(tg, 'mouseover', this.onTargetOver, this);
 150                 this.mun(tg, 'mouseout', this.onTargetOut, this);
 151                 this.mun(tg, 'mousemove', this.onMouseMove, this);
 152             }
 153             this.mon(t, {
 154                 mouseover: this.onTargetOver,
 155                 mouseout: this.onTargetOut,
 156                 mousemove: this.onMouseMove,
 157                 scope: this
 158             });
 159             this.target = t;
 160         }
 161         if(this.anchor){
 162             this.anchorTarget = this.target;
 163         }
 164     },
 165
 166     // private
 167     onMouseMove : function(e){
 168         var t = this.delegate ? e.getTarget(this.delegate) : this.triggerElement = true;
 169         if (t) {
 170             this.targetXY = e.getXY();
 171             if (t === this.triggerElement) {
 172                 if(!this.hidden && this.trackMouse){
 173                     this.setPagePosition(this.getTargetXY());
 174                 }
 175             } else {
 176                 this.hide();
 177                 this.lastActive = new Date(0);
 178                 this.onTargetOver(e);
 179             }
 180         } else if (!this.closable && this.isVisible()) {
 181             this.hide();
 182         }
 183     },
 184
 185     // private
 186     getTargetXY : function(){
 187         if(this.delegate){
 188             this.anchorTarget = this.triggerElement;
 189         }
 190         if(this.anchor){
 191             this.targetCounter++;
 192             var offsets = this.getOffsets(),
 193                 xy = (this.anchorToTarget && !this.trackMouse) ? this.el.getAlignToXY(this.anchorTarget, this.getAnchorAlign()) : this.targetXY,
 194                 dw = Ext.lib.Dom.getViewWidth() - 5,
 195                 dh = Ext.lib.Dom.getViewHeight() - 5,
 196                 de = document.documentElement,
 197                 bd = document.body,
 198                 scrollX = (de.scrollLeft || bd.scrollLeft || 0) + 5,
 199                 scrollY = (de.scrollTop || bd.scrollTop || 0) + 5,
 200                 axy = [xy[0] + offsets[0], xy[1] + offsets[1]],
 201                 sz = this.getSize();
 202
 203             this.anchorEl.removeClass(this.anchorCls);
 204
 205             if(this.targetCounter < 2){
 206                 if(axy[0] < scrollX){
 207                     if(this.anchorToTarget){
 208                         this.defaultAlign = 'l-r';
 209                         if(this.mouseOffset){this.mouseOffset[0] *= -1;}
 210                     }
 211                     this.anchor = 'left';
 212                     return this.getTargetXY();
 213                 }
 214                 if(axy[0]+sz.width > dw){
 215                     if(this.anchorToTarget){
 216                         this.defaultAlign = 'r-l';
 217                         if(this.mouseOffset){this.mouseOffset[0] *= -1;}
 218                     }
 219                     this.anchor = 'right';
 220                     return this.getTargetXY();
 221                 }
 222                 if(axy[1] < scrollY){
 223                     if(this.anchorToTarget){
 224                         this.defaultAlign = 't-b';
 225                         if(this.mouseOffset){this.mouseOffset[1] *= -1;}
 226                     }
 227                     this.anchor = 'top';
 228                     return this.getTargetXY();
 229                 }
 230                 if(axy[1]+sz.height > dh){
 231                     if(this.anchorToTarget){
 232                         this.defaultAlign = 'b-t';
 233                         if(this.mouseOffset){this.mouseOffset[1] *= -1;}
 234                     }
 235                     this.anchor = 'bottom';
 236                     return this.getTargetXY();
 237                 }
 238             }
 239
 240             this.anchorCls = 'x-tip-anchor-'+this.getAnchorPosition();
 241             this.anchorEl.addClass(this.anchorCls);
 242             this.targetCounter = 0;
 243             return axy;
 244         }else{
 245             var mouseOffset = this.getMouseOffset();
 246             return [this.targetXY[0]+mouseOffset[0], this.targetXY[1]+mouseOffset[1]];
 247         }
 248     },
 249
 250     getMouseOffset : function(){
 251         var offset = this.anchor ? [0,0] : [15,18];
 252         if(this.mouseOffset){
 253             offset[0] += this.mouseOffset[0];
 254             offset[1] += this.mouseOffset[1];
 255         }
 256         return offset;
 257     },
 258
 259     // private
 260     getAnchorPosition : function(){
 261         if(this.anchor){
 262             this.tipAnchor = this.anchor.charAt(0);
 263         }else{
 264             var m = this.defaultAlign.match(/^([a-z]+)-([a-z]+)(\?)?$/);
 265             if(!m){
 266                throw 'AnchorTip.defaultAlign is invalid';
 267             }
 268             this.tipAnchor = m[1].charAt(0);
 269         }
 270
 271         switch(this.tipAnchor){
 272             case 't': return 'top';
 273             case 'b': return 'bottom';
 274             case 'r': return 'right';
 275         }
 276         return 'left';
 277     },
 278
 279     // private
 280     getAnchorAlign : function(){
 281         switch(this.anchor){
 282             case 'top'  : return 'tl-bl';
 283             case 'left' : return 'tl-tr';
 284             case 'right': return 'tr-tl';
 285             default     : return 'bl-tl';
 286         }
 287     },
 288
 289     // private
 290     getOffsets : function(){
 291         var offsets,
 292             ap = this.getAnchorPosition().charAt(0);
 293         if(this.anchorToTarget && !this.trackMouse){
 294             switch(ap){
 295                 case 't':
 296                     offsets = [0, 9];
 297                     break;
 298                 case 'b':
 299                     offsets = [0, -13];
 300                     break;
 301                 case 'r':
 302                     offsets = [-13, 0];
 303                     break;
 304                 default:
 305                     offsets = [9, 0];
 306                     break;
 307             }
 308         }else{
 309             switch(ap){
 310                 case 't':
 311                     offsets = [-15-this.anchorOffset, 30];
 312                     break;
 313                 case 'b':
 314                     offsets = [-19-this.anchorOffset, -13-this.el.dom.offsetHeight];
 315                     break;
 316                 case 'r':
 317                     offsets = [-15-this.el.dom.offsetWidth, -13-this.anchorOffset];
 318                     break;
 319                 default:
 320                     offsets = [25, -13-this.anchorOffset];
 321                     break;
 322             }
 323         }
 324         var mouseOffset = this.getMouseOffset();
 325         offsets[0] += mouseOffset[0];
 326         offsets[1] += mouseOffset[1];
 327
 328         return offsets;
 329     },
 330
 331     // private
 332     onTargetOver : function(e){
 333         if(this.disabled || e.within(this.target.dom, true)){
 334             return;
 335         }
 336         var t = e.getTarget(this.delegate);
 337         if (t) {
 338             this.triggerElement = t;
 339             this.clearTimer('hide');
 340             this.targetXY = e.getXY();
 341             this.delayShow();
 342         }
 343     },
 344
 345     // private
 346     delayShow : function(){
 347         if(this.hidden && !this.showTimer){
 348             if(this.lastActive.getElapsed() < this.quickShowInterval){
 349                 this.show();
 350             }else{
 351                 this.showTimer = this.show.defer(this.showDelay, this);
 352             }
 353         }else if(!this.hidden && this.autoHide !== false){
 354             this.show();
 355         }
 356     },
 357
 358     // private
 359     onTargetOut : function(e){
 360         if(this.disabled || e.within(this.target.dom, true)){
 361             return;
 362         }
 363         this.clearTimer('show');
 364         if(this.autoHide !== false){
 365             this.delayHide();
 366         }
 367     },
 368
 369     // private
 370     delayHide : function(){
 371         if(!this.hidden && !this.hideTimer){
 372             this.hideTimer = this.hide.defer(this.hideDelay, this);
 373         }
 374     },
 375
 376     /**
 377      * Hides this tooltip if visible.
 378      */
 379     hide: function(){
 380         this.clearTimer('dismiss');
 381         this.lastActive = new Date();
 382         if(this.anchorEl){
 383             this.anchorEl.hide();
 384         }
 385         Ext.ToolTip.superclass.hide.call(this);
 386         delete this.triggerElement;
 387     },
 388
 389     /**
 390      * Shows this tooltip at the current event target XY position.
 391      */
 392     show : function(){
 393         if(this.anchor){
 394             // pre-show it off screen so that the el will have dimensions
 395             // for positioning calcs when getting xy next
 396             this.showAt([-1000,-1000]);
 397             this.origConstrainPosition = this.constrainPosition;
 398             this.constrainPosition = false;
 399             this.anchor = this.origAnchor;
 400         }
 401         this.showAt(this.getTargetXY());
 402
 403         if(this.anchor){
 404             this.anchorEl.show();
 405             this.syncAnchor();
 406             this.constrainPosition = this.origConstrainPosition;
 407         }else{
 408             this.anchorEl.hide();
 409         }
 410     },
 411
 412     // inherit docs
 413     showAt : function(xy){
 414         this.lastActive = new Date();
 415         this.clearTimers();
 416         Ext.ToolTip.superclass.showAt.call(this, xy);
 417         if(this.dismissDelay && this.autoHide !== false){
 418             this.dismissTimer = this.hide.defer(this.dismissDelay, this);
 419         }
 420         if(this.anchor && !this.anchorEl.isVisible()){
 421             this.syncAnchor();
 422             this.anchorEl.show();
 423         }else{
 424             this.anchorEl.hide();
 425         }
 426     },
 427
 428     // private
 429     syncAnchor : function(){
 430         var anchorPos, targetPos, offset;
 431         switch(this.tipAnchor.charAt(0)){
 432             case 't':
 433                 anchorPos = 'b';
 434                 targetPos = 'tl';
 435                 offset = [20+this.anchorOffset, 2];
 436                 break;
 437             case 'r':
 438                 anchorPos = 'l';
 439                 targetPos = 'tr';
 440                 offset = [-2, 11+this.anchorOffset];
 441                 break;
 442             case 'b':
 443                 anchorPos = 't';
 444                 targetPos = 'bl';
 445                 offset = [20+this.anchorOffset, -2];
 446                 break;
 447             default:
 448                 anchorPos = 'r';
 449                 targetPos = 'tl';
 450                 offset = [2, 11+this.anchorOffset];
 451                 break;
 452         }
 453         this.anchorEl.alignTo(this.el, anchorPos+'-'+targetPos, offset);
 454     },
 455
 456     // private
 457     setPagePosition : function(x, y){
 458         Ext.ToolTip.superclass.setPagePosition.call(this, x, y);
 459         if(this.anchor){
 460             this.syncAnchor();
 461         }
 462     },
 463
 464     // private
 465     clearTimer : function(name){
 466         name = name + 'Timer';
 467         clearTimeout(this[name]);
 468         delete this[name];
 469     },
 470
 471     // private
 472     clearTimers : function(){
 473         this.clearTimer('show');
 474         this.clearTimer('dismiss');
 475         this.clearTimer('hide');
 476     },
 477
 478     // private
 479     onShow : function(){
 480         Ext.ToolTip.superclass.onShow.call(this);
 481         Ext.getDoc().on('mousedown', this.onDocMouseDown, this);
 482     },
 483
 484     // private
 485     onHide : function(){
 486         Ext.ToolTip.superclass.onHide.call(this);
 487         Ext.getDoc().un('mousedown', this.onDocMouseDown, this);
 488     },
 489
 490     // private
 491     onDocMouseDown : function(e){
 492         if(this.autoHide !== true && !this.closable && !e.within(this.el.dom)){
 493             this.disable();
 494             this.doEnable.defer(100, this);
 495         }
 496     },
 497
 498     // private
 499     doEnable : function(){
 500         if(!this.isDestroyed){
 501             this.enable();
 502         }
 503     },
 504
 505     // private
 506     onDisable : function(){
 507         this.clearTimers();
 508         this.hide();
 509     },
 510
 511     // private
 512     adjustPosition : function(x, y){
 513         if(this.contstrainPosition){
 514             var ay = this.targetXY[1], h = this.getSize().height;
 515             if(y <= ay && (y+h) >= ay){
 516                 y = ay-h-5;
 517             }
 518         }
 519         return {x : x, y: y};
 520     },
 521
 522     beforeDestroy : function(){
 523         this.clearTimers();
 524         Ext.destroy(this.anchorEl);
 525         delete this.anchorEl;
 526         delete this.target;
 527         delete this.anchorTarget;
 528         delete this.triggerElement;
 529         Ext.ToolTip.superclass.beforeDestroy.call(this);
 530     },
 531
 532     // private
 533     onDestroy : function(){
 534         Ext.getDoc().un('mousedown', this.onDocMouseDown, this);
 535         Ext.ToolTip.superclass.onDestroy.call(this);
 536     }
 537 });
 538
 539 Ext.reg('tooltip', Ext.ToolTip);