Upgrade to ExtJS 3.2.0 - Released 03/30/2010
[extjs.git] / src / widgets / tips / ToolTip.js
1 /*!
2  * Ext JS Library 3.2.0
3  * Copyright(c) 2006-2010 Ext JS, Inc.
4  * licensing@extjs.com
5  * http://www.extjs.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);
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.syncAnchor();
405             this.anchorEl.show();
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         }
424     },
425
426     // private
427     syncAnchor : function(){
428         var anchorPos, targetPos, offset;
429         switch(this.tipAnchor.charAt(0)){
430             case 't':
431                 anchorPos = 'b';
432                 targetPos = 'tl';
433                 offset = [20+this.anchorOffset, 2];
434                 break;
435             case 'r':
436                 anchorPos = 'l';
437                 targetPos = 'tr';
438                 offset = [-2, 11+this.anchorOffset];
439                 break;
440             case 'b':
441                 anchorPos = 't';
442                 targetPos = 'bl';
443                 offset = [20+this.anchorOffset, -2];
444                 break;
445             default:
446                 anchorPos = 'r';
447                 targetPos = 'tl';
448                 offset = [2, 11+this.anchorOffset];
449                 break;
450         }
451         this.anchorEl.alignTo(this.el, anchorPos+'-'+targetPos, offset);
452     },
453
454     // private
455     setPagePosition : function(x, y){
456         Ext.ToolTip.superclass.setPagePosition.call(this, x, y);
457         if(this.anchor){
458             this.syncAnchor();
459         }
460     },
461
462     // private
463     clearTimer : function(name){
464         name = name + 'Timer';
465         clearTimeout(this[name]);
466         delete this[name];
467     },
468
469     // private
470     clearTimers : function(){
471         this.clearTimer('show');
472         this.clearTimer('dismiss');
473         this.clearTimer('hide');
474     },
475
476     // private
477     onShow : function(){
478         Ext.ToolTip.superclass.onShow.call(this);
479         Ext.getDoc().on('mousedown', this.onDocMouseDown, this);
480     },
481
482     // private
483     onHide : function(){
484         Ext.ToolTip.superclass.onHide.call(this);
485         Ext.getDoc().un('mousedown', this.onDocMouseDown, this);
486     },
487
488     // private
489     onDocMouseDown : function(e){
490         if(this.autoHide !== true && !this.closable && !e.within(this.el.dom)){
491             this.disable();
492             this.doEnable.defer(100, this);
493         }
494     },
495     
496     // private
497     doEnable : function(){
498         if(!this.isDestroyed){
499             this.enable();
500         }
501     },
502
503     // private
504     onDisable : function(){
505         this.clearTimers();
506         this.hide();
507     },
508
509     // private
510     adjustPosition : function(x, y){
511         if(this.contstrainPosition){
512             var ay = this.targetXY[1], h = this.getSize().height;
513             if(y <= ay && (y+h) >= ay){
514                 y = ay-h-5;
515             }
516         }
517         return {x : x, y: y};
518     },
519     
520     beforeDestroy : function(){
521         this.clearTimers();
522         Ext.destroy(this.anchorEl);
523         delete this.anchorEl;
524         delete this.target;
525         delete this.anchorTarget;
526         delete this.triggerElement;
527         Ext.ToolTip.superclass.beforeDestroy.call(this);    
528     },
529
530     // private
531     onDestroy : function(){
532         Ext.getDoc().un('mousedown', this.onDocMouseDown, this);
533         Ext.ToolTip.superclass.onDestroy.call(this);
534     }
535 });
536
537 Ext.reg('tooltip', Ext.ToolTip);