Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / ToolTip.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-tip-ToolTip'>/**
19 </span> * ToolTip is a {@link Ext.tip.Tip} implementation that handles the common case of displaying a
20  * tooltip when hovering over a certain element or elements on the page. It allows fine-grained
21  * control over the tooltip's alignment relative to the target element or mouse, and the timing
22  * of when it is automatically shown and hidden.
23  *
24  * This implementation does **not** have a built-in method of automatically populating the tooltip's
25  * text based on the target element; you must either configure a fixed {@link #html} value for each
26  * ToolTip instance, or implement custom logic (e.g. in a {@link #beforeshow} event listener) to
27  * generate the appropriate tooltip content on the fly. See {@link Ext.tip.QuickTip} for a more
28  * convenient way of automatically populating and configuring a tooltip based on specific DOM
29  * attributes of each target element.
30  *
31  * # Basic Example
32  *
33  *     var tip = Ext.create('Ext.tip.ToolTip', {
34  *         target: 'clearButton',
35  *         html: 'Press this button to clear the form'
36  *     });
37  *
38  * {@img Ext.tip.ToolTip/Ext.tip.ToolTip1.png Basic Ext.tip.ToolTip}
39  *
40  * # Delegation
41  *
42  * In addition to attaching a ToolTip to a single element, you can also use delegation to attach
43  * one ToolTip to many elements under a common parent. This is more efficient than creating many
44  * ToolTip instances. To do this, point the {@link #target} config to a common ancestor of all the
45  * elements, and then set the {@link #delegate} config to a CSS selector that will select all the
46  * appropriate sub-elements.
47  *
48  * When using delegation, it is likely that you will want to programmatically change the content
49  * of the ToolTip based on each delegate element; you can do this by implementing a custom
50  * listener for the {@link #beforeshow} event. Example:
51  *
52  *     var store = Ext.create('Ext.data.ArrayStore', {
53  *         fields: ['company', 'price', 'change'],
54  *         data: [
55  *             ['3m Co',                               71.72, 0.02],
56  *             ['Alcoa Inc',                           29.01, 0.42],
57  *             ['Altria Group Inc',                    83.81, 0.28],
58  *             ['American Express Company',            52.55, 0.01],
59  *             ['American International Group, Inc.',  64.13, 0.31],
60  *             ['AT&amp;T Inc.',                           31.61, -0.48]
61  *         ]
62  *     });
63  *
64  *     var grid = Ext.create('Ext.grid.Panel', {
65  *         title: 'Array Grid',
66  *         store: store,
67  *         columns: [
68  *             {text: 'Company', flex: 1, dataIndex: 'company'},
69  *             {text: 'Price', width: 75, dataIndex: 'price'},
70  *             {text: 'Change', width: 75, dataIndex: 'change'}
71  *         ],
72  *         height: 200,
73  *         width: 400,
74  *         renderTo: Ext.getBody()
75  *     });
76  *
77  *     grid.getView().on('render', function(view) {
78  *         view.tip = Ext.create('Ext.tip.ToolTip', {
79  *             // The overall target element.
80  *             target: view.el,
81  *             // Each grid row causes its own seperate show and hide.
82  *             delegate: view.itemSelector,
83  *             // Moving within the row should not hide the tip.
84  *             trackMouse: true,
85  *             // Render immediately so that tip.body can be referenced prior to the first show.
86  *             renderTo: Ext.getBody(),
87  *             listeners: {
88  *                 // Change content dynamically depending on which element triggered the show.
89  *                 beforeshow: function updateTipBody(tip) {
90  *                     tip.update('Over company &quot;' + view.getRecord(tip.triggerElement).get('company') + '&quot;');
91  *                 }
92  *             }
93  *         });
94  *     });
95  *
96  * {@img Ext.tip.ToolTip/Ext.tip.ToolTip2.png Ext.tip.ToolTip with delegation}
97  *
98  * # Alignment
99  *
100  * The following configuration properties allow control over how the ToolTip is aligned relative to
101  * the target element and/or mouse pointer:
102  *
103  * - {@link #anchor}
104  * - {@link #anchorToTarget}
105  * - {@link #anchorOffset}
106  * - {@link #trackMouse}
107  * - {@link #mouseOffset}
108  *
109  * # Showing/Hiding
110  *
111  * The following configuration properties allow control over how and when the ToolTip is automatically
112  * shown and hidden:
113  *
114  * - {@link #autoHide}
115  * - {@link #showDelay}
116  * - {@link #hideDelay}
117  * - {@link #dismissDelay}
118  *
119  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
120  */
121 Ext.define('Ext.tip.ToolTip', {
122     extend: 'Ext.tip.Tip',
123     alias: 'widget.tooltip',
124     alternateClassName: 'Ext.ToolTip',
125 <span id='Ext-tip-ToolTip-property-triggerElement'>    /**
126 </span>     * @property {HTMLElement} triggerElement
127      * When a ToolTip is configured with the `{@link #delegate}`
128      * option to cause selected child elements of the `{@link #target}`
129      * Element to each trigger a seperate show event, this property is set to
130      * the DOM element which triggered the show.
131      */
132 <span id='Ext-tip-ToolTip-cfg-target'>    /**
133 </span>     * @cfg {HTMLElement/Ext.Element/String} target
134      * The target element or string id to monitor for mouseover events to trigger
135      * showing this ToolTip.
136      */
137 <span id='Ext-tip-ToolTip-cfg-autoHide'>    /**
138 </span>     * @cfg {Boolean} [autoHide=true]
139      * True to automatically hide the tooltip after the
140      * mouse exits the target element or after the `{@link #dismissDelay}`
141      * has expired if set.  If `{@link #closable} = true`
142      * a close tool button will be rendered into the tooltip header.
143      */
144 <span id='Ext-tip-ToolTip-cfg-showDelay'>    /**
145 </span>     * @cfg {Number} showDelay
146      * Delay in milliseconds before the tooltip displays after the mouse enters the target element.
147      */
148     showDelay: 500,
149 <span id='Ext-tip-ToolTip-cfg-hideDelay'>    /**
150 </span>     * @cfg {Number} hideDelay
151      * Delay in milliseconds after the mouse exits the target element but before the tooltip actually hides.
152      * Set to 0 for the tooltip to hide immediately.
153      */
154     hideDelay: 200,
155 <span id='Ext-tip-ToolTip-cfg-dismissDelay'>    /**
156 </span>     * @cfg {Number} dismissDelay
157      * Delay in milliseconds before the tooltip automatically hides. To disable automatic hiding, set
158      * dismissDelay = 0.
159      */
160     dismissDelay: 5000,
161 <span id='Ext-tip-ToolTip-cfg-mouseOffset'>    /**
162 </span>     * @cfg {Number[]} [mouseOffset=[15,18]]
163      * An XY offset from the mouse position where the tooltip should be shown.
164      */
165 <span id='Ext-tip-ToolTip-cfg-trackMouse'>    /**
166 </span>     * @cfg {Boolean} trackMouse
167      * True to have the tooltip follow the mouse as it moves over the target element.
168      */
169     trackMouse: false,
170 <span id='Ext-tip-ToolTip-cfg-anchor'>    /**
171 </span>     * @cfg {String} anchor
172      * If specified, indicates that the tip should be anchored to a
173      * particular side of the target element or mouse pointer (&quot;top&quot;, &quot;right&quot;, &quot;bottom&quot;,
174      * or &quot;left&quot;), with an arrow pointing back at the target or mouse pointer. If
175      * {@link #constrainPosition} is enabled, this will be used as a preferred value
176      * only and may be flipped as needed.
177      */
178 <span id='Ext-tip-ToolTip-cfg-anchorToTarget'>    /**
179 </span>     * @cfg {Boolean} anchorToTarget
180      * True to anchor the tooltip to the target element, false to anchor it relative to the mouse coordinates.
181      * When `anchorToTarget` is true, use `{@link #defaultAlign}` to control tooltip alignment to the
182      * target element.  When `anchorToTarget` is false, use `{@link #anchor}` instead to control alignment.
183      */
184     anchorToTarget: true,
185 <span id='Ext-tip-ToolTip-cfg-anchorOffset'>    /**
186 </span>     * @cfg {Number} anchorOffset
187      * A numeric pixel value used to offset the default position of the anchor arrow.  When the anchor
188      * position is on the top or bottom of the tooltip, `anchorOffset` will be used as a horizontal offset.
189      * Likewise, when the anchor position is on the left or right side, `anchorOffset` will be used as
190      * a vertical offset.
191      */
192     anchorOffset: 0,
193 <span id='Ext-tip-ToolTip-cfg-delegate'>    /**
194 </span>     * @cfg {String} delegate
195      *
196      * A {@link Ext.DomQuery DomQuery} selector which allows selection of individual elements within the
197      * `{@link #target}` element to trigger showing and hiding the ToolTip as the mouse moves within the
198      * target.
199      *
200      * When specified, the child element of the target which caused a show event is placed into the
201      * `{@link #triggerElement}` property before the ToolTip is shown.
202      *
203      * This may be useful when a Component has regular, repeating elements in it, each of which need a
204      * ToolTip which contains information specific to that element.
205      *
206      * See the delegate example in class documentation of {@link Ext.tip.ToolTip}.
207      */
208
209     // private
210     targetCounter: 0,
211     quickShowInterval: 250,
212
213     // private
214     initComponent: function() {
215         var me = this;
216         me.callParent(arguments);
217         me.lastActive = new Date();
218         me.setTarget(me.target);
219         me.origAnchor = me.anchor;
220     },
221
222     // private
223     onRender: function(ct, position) {
224         var me = this;
225         me.callParent(arguments);
226         me.anchorCls = Ext.baseCSSPrefix + 'tip-anchor-' + me.getAnchorPosition();
227         me.anchorEl = me.el.createChild({
228             cls: Ext.baseCSSPrefix + 'tip-anchor ' + me.anchorCls
229         });
230     },
231
232     // private
233     afterRender: function() {
234         var me = this,
235             zIndex;
236
237         me.callParent(arguments);
238         zIndex = parseInt(me.el.getZIndex(), 10) || 0;
239         me.anchorEl.setStyle('z-index', zIndex + 1).setVisibilityMode(Ext.Element.DISPLAY);
240     },
241
242 <span id='Ext-tip-ToolTip-method-setTarget'>    /**
243 </span>     * Binds this ToolTip to the specified element. The tooltip will be displayed when the mouse moves over the element.
244      * @param {String/HTMLElement/Ext.Element} t The Element, HtmlElement, or ID of an element to bind to
245      */
246     setTarget: function(target) {
247         var me = this,
248             t = Ext.get(target),
249             tg;
250
251         if (me.target) {
252             tg = Ext.get(me.target);
253             me.mun(tg, 'mouseover', me.onTargetOver, me);
254             me.mun(tg, 'mouseout', me.onTargetOut, me);
255             me.mun(tg, 'mousemove', me.onMouseMove, me);
256         }
257
258         me.target = t;
259         if (t) {
260
261             me.mon(t, {
262                 // TODO - investigate why IE6/7 seem to fire recursive resize in e.getXY
263                 // breaking QuickTip#onTargetOver (EXTJSIV-1608)
264                 freezeEvent: true,
265
266                 mouseover: me.onTargetOver,
267                 mouseout: me.onTargetOut,
268                 mousemove: me.onMouseMove,
269                 scope: me
270             });
271         }
272         if (me.anchor) {
273             me.anchorTarget = me.target;
274         }
275     },
276
277     // private
278     onMouseMove: function(e) {
279         var me = this,
280             t = me.delegate ? e.getTarget(me.delegate) : me.triggerElement = true,
281             xy;
282         if (t) {
283             me.targetXY = e.getXY();
284             if (t === me.triggerElement) {
285                 if (!me.hidden &amp;&amp; me.trackMouse) {
286                     xy = me.getTargetXY();
287                     if (me.constrainPosition) {
288                         xy = me.el.adjustForConstraints(xy, me.el.getScopeParent());
289                     }
290                     me.setPagePosition(xy);
291                 }
292             } else {
293                 me.hide();
294                 me.lastActive = new Date(0);
295                 me.onTargetOver(e);
296             }
297         } else if ((!me.closable &amp;&amp; me.isVisible()) &amp;&amp; me.autoHide !== false) {
298             me.hide();
299         }
300     },
301
302     // private
303     getTargetXY: function() {
304         var me = this,
305             mouseOffset;
306         if (me.delegate) {
307             me.anchorTarget = me.triggerElement;
308         }
309         if (me.anchor) {
310             me.targetCounter++;
311                 var offsets = me.getOffsets(),
312                     xy = (me.anchorToTarget &amp;&amp; !me.trackMouse) ? me.el.getAlignToXY(me.anchorTarget, me.getAnchorAlign()) : me.targetXY,
313                     dw = Ext.Element.getViewWidth() - 5,
314                     dh = Ext.Element.getViewHeight() - 5,
315                     de = document.documentElement,
316                     bd = document.body,
317                     scrollX = (de.scrollLeft || bd.scrollLeft || 0) + 5,
318                     scrollY = (de.scrollTop || bd.scrollTop || 0) + 5,
319                     axy = [xy[0] + offsets[0], xy[1] + offsets[1]],
320                     sz = me.getSize(),
321                     constrainPosition = me.constrainPosition;
322
323             me.anchorEl.removeCls(me.anchorCls);
324
325             if (me.targetCounter &lt; 2 &amp;&amp; constrainPosition) {
326                 if (axy[0] &lt; scrollX) {
327                     if (me.anchorToTarget) {
328                         me.defaultAlign = 'l-r';
329                         if (me.mouseOffset) {
330                             me.mouseOffset[0] *= -1;
331                         }
332                     }
333                     me.anchor = 'left';
334                     return me.getTargetXY();
335                 }
336                 if (axy[0] + sz.width &gt; dw) {
337                     if (me.anchorToTarget) {
338                         me.defaultAlign = 'r-l';
339                         if (me.mouseOffset) {
340                             me.mouseOffset[0] *= -1;
341                         }
342                     }
343                     me.anchor = 'right';
344                     return me.getTargetXY();
345                 }
346                 if (axy[1] &lt; scrollY) {
347                     if (me.anchorToTarget) {
348                         me.defaultAlign = 't-b';
349                         if (me.mouseOffset) {
350                             me.mouseOffset[1] *= -1;
351                         }
352                     }
353                     me.anchor = 'top';
354                     return me.getTargetXY();
355                 }
356                 if (axy[1] + sz.height &gt; dh) {
357                     if (me.anchorToTarget) {
358                         me.defaultAlign = 'b-t';
359                         if (me.mouseOffset) {
360                             me.mouseOffset[1] *= -1;
361                         }
362                     }
363                     me.anchor = 'bottom';
364                     return me.getTargetXY();
365                 }
366             }
367
368             me.anchorCls = Ext.baseCSSPrefix + 'tip-anchor-' + me.getAnchorPosition();
369             me.anchorEl.addCls(me.anchorCls);
370             me.targetCounter = 0;
371             return axy;
372         } else {
373             mouseOffset = me.getMouseOffset();
374             return (me.targetXY) ? [me.targetXY[0] + mouseOffset[0], me.targetXY[1] + mouseOffset[1]] : mouseOffset;
375         }
376     },
377
378     getMouseOffset: function() {
379         var me = this,
380         offset = me.anchor ? [0, 0] : [15, 18];
381         if (me.mouseOffset) {
382             offset[0] += me.mouseOffset[0];
383             offset[1] += me.mouseOffset[1];
384         }
385         return offset;
386     },
387
388     // private
389     getAnchorPosition: function() {
390         var me = this,
391             m;
392         if (me.anchor) {
393             me.tipAnchor = me.anchor.charAt(0);
394         } else {
395             m = me.defaultAlign.match(/^([a-z]+)-([a-z]+)(\?)?$/);
396             //&lt;debug&gt;
397             if (!m) {
398                 Ext.Error.raise('The AnchorTip.defaultAlign value &quot;' + me.defaultAlign + '&quot; is invalid.');
399             }
400             //&lt;/debug&gt;
401             me.tipAnchor = m[1].charAt(0);
402         }
403
404         switch (me.tipAnchor) {
405         case 't':
406             return 'top';
407         case 'b':
408             return 'bottom';
409         case 'r':
410             return 'right';
411         }
412         return 'left';
413     },
414
415     // private
416     getAnchorAlign: function() {
417         switch (this.anchor) {
418         case 'top':
419             return 'tl-bl';
420         case 'left':
421             return 'tl-tr';
422         case 'right':
423             return 'tr-tl';
424         default:
425             return 'bl-tl';
426         }
427     },
428
429     // private
430     getOffsets: function() {
431         var me = this,
432             mouseOffset,
433             offsets,
434             ap = me.getAnchorPosition().charAt(0);
435         if (me.anchorToTarget &amp;&amp; !me.trackMouse) {
436             switch (ap) {
437             case 't':
438                 offsets = [0, 9];
439                 break;
440             case 'b':
441                 offsets = [0, -13];
442                 break;
443             case 'r':
444                 offsets = [ - 13, 0];
445                 break;
446             default:
447                 offsets = [9, 0];
448                 break;
449             }
450         } else {
451             switch (ap) {
452             case 't':
453                 offsets = [ - 15 - me.anchorOffset, 30];
454                 break;
455             case 'b':
456                 offsets = [ - 19 - me.anchorOffset, -13 - me.el.dom.offsetHeight];
457                 break;
458             case 'r':
459                 offsets = [ - 15 - me.el.dom.offsetWidth, -13 - me.anchorOffset];
460                 break;
461             default:
462                 offsets = [25, -13 - me.anchorOffset];
463                 break;
464             }
465         }
466         mouseOffset = me.getMouseOffset();
467         offsets[0] += mouseOffset[0];
468         offsets[1] += mouseOffset[1];
469
470         return offsets;
471     },
472
473     // private
474     onTargetOver: function(e) {
475         var me = this,
476             t;
477
478         if (me.disabled || e.within(me.target.dom, true)) {
479             return;
480         }
481         t = e.getTarget(me.delegate);
482         if (t) {
483             me.triggerElement = t;
484             me.clearTimer('hide');
485             me.targetXY = e.getXY();
486             me.delayShow();
487         }
488     },
489
490     // private
491     delayShow: function() {
492         var me = this;
493         if (me.hidden &amp;&amp; !me.showTimer) {
494             if (Ext.Date.getElapsed(me.lastActive) &lt; me.quickShowInterval) {
495                 me.show();
496             } else {
497                 me.showTimer = Ext.defer(me.show, me.showDelay, me);
498             }
499         }
500         else if (!me.hidden &amp;&amp; me.autoHide !== false) {
501             me.show();
502         }
503     },
504
505     // private
506     onTargetOut: function(e) {
507         var me = this;
508         if (me.disabled || e.within(me.target.dom, true)) {
509             return;
510         }
511         me.clearTimer('show');
512         if (me.autoHide !== false) {
513             me.delayHide();
514         }
515     },
516
517     // private
518     delayHide: function() {
519         var me = this;
520         if (!me.hidden &amp;&amp; !me.hideTimer) {
521             me.hideTimer = Ext.defer(me.hide, me.hideDelay, me);
522         }
523     },
524
525 <span id='Ext-tip-ToolTip-method-hide'>    /**
526 </span>     * Hides this tooltip if visible.
527      */
528     hide: function() {
529         var me = this;
530         me.clearTimer('dismiss');
531         me.lastActive = new Date();
532         if (me.anchorEl) {
533             me.anchorEl.hide();
534         }
535         me.callParent(arguments);
536         delete me.triggerElement;
537     },
538
539 <span id='Ext-tip-ToolTip-method-show'>    /**
540 </span>     * Shows this tooltip at the current event target XY position.
541      */
542     show: function() {
543         var me = this;
544
545         // Show this Component first, so that sizing can be calculated
546         // pre-show it off screen so that the el will have dimensions
547         this.callParent();
548         if (this.hidden === false) {
549             me.setPagePosition(-10000, -10000);
550
551             if (me.anchor) {
552                 me.anchor = me.origAnchor;
553             }
554             me.showAt(me.getTargetXY());
555
556             if (me.anchor) {
557                 me.syncAnchor();
558                 me.anchorEl.show();
559             } else {
560                 me.anchorEl.hide();
561             }
562         }
563     },
564
565     // inherit docs
566     showAt: function(xy) {
567         var me = this;
568         me.lastActive = new Date();
569         me.clearTimers();
570
571         // Only call if this is hidden. May have been called from show above.
572         if (!me.isVisible()) {
573             this.callParent(arguments);
574         }
575
576         // Show may have been vetoed.
577         if (me.isVisible()) {
578             me.setPagePosition(xy[0], xy[1]);
579             if (me.constrainPosition || me.constrain) {
580                 me.doConstrain();
581             }
582             me.toFront(true);
583         }
584
585         if (me.dismissDelay &amp;&amp; me.autoHide !== false) {
586             me.dismissTimer = Ext.defer(me.hide, me.dismissDelay, me);
587         }
588         if (me.anchor) {
589             me.syncAnchor();
590             if (!me.anchorEl.isVisible()) {
591                 me.anchorEl.show();
592             }
593         } else {
594             me.anchorEl.hide();
595         }
596     },
597
598     // private
599     syncAnchor: function() {
600         var me = this,
601             anchorPos,
602             targetPos,
603             offset;
604         switch (me.tipAnchor.charAt(0)) {
605         case 't':
606             anchorPos = 'b';
607             targetPos = 'tl';
608             offset = [20 + me.anchorOffset, 1];
609             break;
610         case 'r':
611             anchorPos = 'l';
612             targetPos = 'tr';
613             offset = [ - 1, 12 + me.anchorOffset];
614             break;
615         case 'b':
616             anchorPos = 't';
617             targetPos = 'bl';
618             offset = [20 + me.anchorOffset, -1];
619             break;
620         default:
621             anchorPos = 'r';
622             targetPos = 'tl';
623             offset = [1, 12 + me.anchorOffset];
624             break;
625         }
626         me.anchorEl.alignTo(me.el, anchorPos + '-' + targetPos, offset);
627     },
628
629     // private
630     setPagePosition: function(x, y) {
631         var me = this;
632         me.callParent(arguments);
633         if (me.anchor) {
634             me.syncAnchor();
635         }
636     },
637
638     // private
639     clearTimer: function(name) {
640         name = name + 'Timer';
641         clearTimeout(this[name]);
642         delete this[name];
643     },
644
645     // private
646     clearTimers: function() {
647         var me = this;
648         me.clearTimer('show');
649         me.clearTimer('dismiss');
650         me.clearTimer('hide');
651     },
652
653     // private
654     onShow: function() {
655         var me = this;
656         me.callParent();
657         me.mon(Ext.getDoc(), 'mousedown', me.onDocMouseDown, me);
658     },
659
660     // private
661     onHide: function() {
662         var me = this;
663         me.callParent();
664         me.mun(Ext.getDoc(), 'mousedown', me.onDocMouseDown, me);
665     },
666
667     // private
668     onDocMouseDown: function(e) {
669         var me = this;
670         if (me.autoHide !== true &amp;&amp; !me.closable &amp;&amp; !e.within(me.el.dom)) {
671             me.disable();
672             Ext.defer(me.doEnable, 100, me);
673         }
674     },
675
676     // private
677     doEnable: function() {
678         if (!this.isDestroyed) {
679             this.enable();
680         }
681     },
682
683     // private
684     onDisable: function() {
685         this.callParent();
686         this.clearTimers();
687         this.hide();
688     },
689
690     beforeDestroy: function() {
691         var me = this;
692         me.clearTimers();
693         Ext.destroy(me.anchorEl);
694         delete me.anchorEl;
695         delete me.target;
696         delete me.anchorTarget;
697         delete me.triggerElement;
698         me.callParent();
699     },
700
701     // private
702     onDestroy: function() {
703         Ext.getDoc().un('mousedown', this.onDocMouseDown, this);
704         this.callParent();
705     }
706 });
707 </pre>
708 </body>
709 </html>