Upgrade to ExtJS 3.2.0 - Released 03/30/2010
[extjs.git] / 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.0
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>