docs/source/ToolTip.html

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