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