1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-tip.ToolTip-method-constructor'><span id='Ext-tip.ToolTip'>/**
2 </span></span> * @class Ext.tip.ToolTip
5 * ToolTip is a {@link Ext.tip.Tip} implementation that handles the common case of displaying a
6 * tooltip when hovering over a certain element or elements on the page. It allows fine-grained
7 * control over the tooltip's alignment relative to the target element or mouse, and the timing
8 * of when it is automatically shown and hidden.
10 * This implementation does **not** have a built-in method of automatically populating the tooltip's
11 * text based on the target element; you must either configure a fixed {@link #html} value for each
12 * ToolTip instance, or implement custom logic (e.g. in a {@link #beforeshow} event listener) to
13 * generate the appropriate tooltip content on the fly. See {@link Ext.tip.QuickTip} for a more
14 * convenient way of automatically populating and configuring a tooltip based on specific DOM
15 * attributes of each target element.
19 * var tip = Ext.create('Ext.tip.ToolTip', {
20 * target: 'clearButton',
21 * html: 'Press this button to clear the form'
24 * {@img Ext.tip.ToolTip/Ext.tip.ToolTip1.png Basic Ext.tip.ToolTip}
28 * In addition to attaching a ToolTip to a single element, you can also use delegation to attach
29 * one ToolTip to many elements under a common parent. This is more efficient than creating many
30 * ToolTip instances. To do this, point the {@link #target} config to a common ancestor of all the
31 * elements, and then set the {@link #delegate} config to a CSS selector that will select all the
32 * appropriate sub-elements.
34 * When using delegation, it is likely that you will want to programmatically change the content
35 * of the ToolTip based on each delegate element; you can do this by implementing a custom
36 * listener for the {@link #beforeshow} event. Example:
38 * var myGrid = Ext.create('Ext.grid.GridPanel', gridConfig);
39 * myGrid.on('render', function(grid) {
40 * var view = grid.getView(); // Capture the grid's view.
41 * grid.tip = Ext.create('Ext.tip.ToolTip', {
42 * target: view.el, // The overall target element.
43 * delegate: view.itemSelector, // Each grid row causes its own seperate show and hide.
44 * trackMouse: true, // Moving within the row should not hide the tip.
45 * renderTo: Ext.getBody(), // Render immediately so that tip.body can be referenced prior to the first show.
46 * listeners: { // Change content dynamically depending on which element triggered the show.
47 * beforeshow: function updateTipBody(tip) {
48 * tip.update('Over company "' + view.getRecord(tip.triggerElement).get('company') + '"');
54 * {@img Ext.tip.ToolTip/Ext.tip.ToolTip2.png Ext.tip.ToolTip with delegation}
58 * The following configuration properties allow control over how the ToolTip is aligned relative to
59 * the target element and/or mouse pointer:
62 * - {@link #anchorToTarget}
63 * - {@link #anchorOffset}
64 * - {@link #trackMouse}
65 * - {@link #mouseOffset}
69 * The following configuration properties allow control over how and when the ToolTip is automatically
73 * - {@link #showDelay}
74 * - {@link #hideDelay}
75 * - {@link #dismissDelay}
78 * Create a new ToolTip instance
79 * @param {Object} config The configuration options
82 * @docauthor Jason Johnston <jason@sencha.com>
84 Ext.define('Ext.tip.ToolTip', {
85 extend: 'Ext.tip.Tip',
86 alias: 'widget.tooltip',
87 alternateClassName: 'Ext.ToolTip',
88 <span id='Ext-tip.ToolTip-property-triggerElement'> /**
89 </span> * When a ToolTip is configured with the <code>{@link #delegate}</code>
90 * option to cause selected child elements of the <code>{@link #target}</code>
91 * Element to each trigger a seperate show event, this property is set to
92 * the DOM element which triggered the show.
94 * @property triggerElement
96 <span id='Ext-tip.ToolTip-cfg-target'> /**
97 </span> * @cfg {Mixed} target The target HTMLElement, Ext.core.Element or id to monitor
98 * for mouseover events to trigger showing this ToolTip.
100 <span id='Ext-tip.ToolTip-cfg-autoHide'> /**
101 </span> * @cfg {Boolean} autoHide True to automatically hide the tooltip after the
102 * mouse exits the target element or after the <code>{@link #dismissDelay}</code>
103 * has expired if set (defaults to true). If <code>{@link #closable} = true</code>
104 * a close tool button will be rendered into the tooltip header.
106 <span id='Ext-tip.ToolTip-cfg-showDelay'> /**
107 </span> * @cfg {Number} showDelay Delay in milliseconds before the tooltip displays
108 * after the mouse enters the target element (defaults to 500)
111 <span id='Ext-tip.ToolTip-cfg-hideDelay'> /**
112 </span> * @cfg {Number} hideDelay Delay in milliseconds after the mouse exits the
113 * target element but before the tooltip actually hides (defaults to 200).
114 * Set to 0 for the tooltip to hide immediately.
117 <span id='Ext-tip.ToolTip-cfg-dismissDelay'> /**
118 </span> * @cfg {Number} dismissDelay Delay in milliseconds before the tooltip
119 * automatically hides (defaults to 5000). To disable automatic hiding, set
123 <span id='Ext-tip.ToolTip-cfg-mouseOffset'> /**
124 </span> * @cfg {Array} mouseOffset An XY offset from the mouse position where the
125 * tooltip should be shown (defaults to [15,18]).
127 <span id='Ext-tip.ToolTip-cfg-trackMouse'> /**
128 </span> * @cfg {Boolean} trackMouse True to have the tooltip follow the mouse as it
129 * moves over the target element (defaults to false).
132 <span id='Ext-tip.ToolTip-cfg-anchor'> /**
133 </span> * @cfg {String} anchor If specified, indicates that the tip should be anchored to a
134 * particular side of the target element or mouse pointer ("top", "right", "bottom",
135 * or "left"), with an arrow pointing back at the target or mouse pointer. If
136 * {@link #constrainPosition} is enabled, this will be used as a preferred value
137 * only and may be flipped as needed.
139 <span id='Ext-tip.ToolTip-cfg-anchorToTarget'> /**
140 </span> * @cfg {Boolean} anchorToTarget True to anchor the tooltip to the target
141 * element, false to anchor it relative to the mouse coordinates (defaults
142 * to true). When <code>anchorToTarget</code> is true, use
143 * <code>{@link #defaultAlign}</code> to control tooltip alignment to the
144 * target element. When <code>anchorToTarget</code> is false, use
145 * <code>{@link #anchorPosition}</code> instead to control alignment.
147 anchorToTarget: true,
148 <span id='Ext-tip.ToolTip-cfg-anchorOffset'> /**
149 </span> * @cfg {Number} anchorOffset A numeric pixel value used to offset the
150 * default position of the anchor arrow (defaults to 0). When the anchor
151 * position is on the top or bottom of the tooltip, <code>anchorOffset</code>
152 * will be used as a horizontal offset. Likewise, when the anchor position
153 * is on the left or right side, <code>anchorOffset</code> will be used as
157 <span id='Ext-tip.ToolTip-cfg-delegate'> /**
158 </span> * @cfg {String} delegate <p>Optional. A {@link Ext.DomQuery DomQuery}
159 * selector which allows selection of individual elements within the
160 * <code>{@link #target}</code> element to trigger showing and hiding the
161 * ToolTip as the mouse moves within the target.</p>
162 * <p>When specified, the child element of the target which caused a show
163 * event is placed into the <code>{@link #triggerElement}</code> property
164 * before the ToolTip is shown.</p>
165 * <p>This may be useful when a Component has regular, repeating elements
166 * in it, each of which need a ToolTip which contains information specific
167 * to that element. For example:</p><pre><code>
168 var myGrid = Ext.create('Ext.grid.GridPanel', gridConfig);
169 myGrid.on('render', function(grid) {
170 var view = grid.getView(); // Capture the grid's view.
171 grid.tip = Ext.create('Ext.tip.ToolTip', {
172 target: view.el, // The overall target element.
173 delegate: view.itemSelector, // Each grid row causes its own seperate show and hide.
174 trackMouse: true, // Moving within the row should not hide the tip.
175 renderTo: Ext.getBody(), // Render immediately so that tip.body can be referenced prior to the first show.
176 listeners: { // Change content dynamically depending on which element triggered the show.
177 beforeshow: function(tip) {
178 tip.update('Over Record ID ' + view.getRecord(tip.triggerElement).id);
183 *</code></pre>
188 quickShowInterval: 250,
191 initComponent: function() {
193 me.callParent(arguments);
194 me.lastActive = new Date();
195 me.setTarget(me.target);
196 me.origAnchor = me.anchor;
200 onRender: function(ct, position) {
202 me.callParent(arguments);
203 me.anchorCls = Ext.baseCSSPrefix + 'tip-anchor-' + me.getAnchorPosition();
204 me.anchorEl = me.el.createChild({
205 cls: Ext.baseCSSPrefix + 'tip-anchor ' + me.anchorCls
210 afterRender: function() {
214 me.callParent(arguments);
215 zIndex = parseInt(me.el.getZIndex(), 10) || 0;
216 me.anchorEl.setStyle('z-index', zIndex + 1).setVisibilityMode(Ext.core.Element.DISPLAY);
219 <span id='Ext-tip.ToolTip-method-setTarget'> /**
220 </span> * Binds this ToolTip to the specified element. The tooltip will be displayed when the mouse moves over the element.
221 * @param {Mixed} t The Element, HtmlElement, or ID of an element to bind to
223 setTarget: function(target) {
229 tg = Ext.get(me.target);
230 me.mun(tg, 'mouseover', me.onTargetOver, me);
231 me.mun(tg, 'mouseout', me.onTargetOut, me);
232 me.mun(tg, 'mousemove', me.onMouseMove, me);
239 // TODO - investigate why IE6/7 seem to fire recursive resize in e.getXY
240 // breaking QuickTip#onTargetOver (EXTJSIV-1608)
243 mouseover: me.onTargetOver,
244 mouseout: me.onTargetOut,
245 mousemove: me.onMouseMove,
250 me.anchorTarget = me.target;
255 onMouseMove: function(e) {
257 t = me.delegate ? e.getTarget(me.delegate) : me.triggerElement = true,
260 me.targetXY = e.getXY();
261 if (t === me.triggerElement) {
262 if (!me.hidden && me.trackMouse) {
263 xy = me.getTargetXY();
264 if (me.constrainPosition) {
265 xy = me.el.adjustForConstraints(xy, me.el.dom.parentNode);
267 me.setPagePosition(xy);
271 me.lastActive = new Date(0);
274 } else if ((!me.closable && me.isVisible()) && me.autoHide !== false) {
280 getTargetXY: function() {
284 me.anchorTarget = me.triggerElement;
288 var offsets = me.getOffsets(),
289 xy = (me.anchorToTarget && !me.trackMouse) ? me.el.getAlignToXY(me.anchorTarget, me.getAnchorAlign()) : me.targetXY,
290 dw = Ext.core.Element.getViewWidth() - 5,
291 dh = Ext.core.Element.getViewHeight() - 5,
292 de = document.documentElement,
294 scrollX = (de.scrollLeft || bd.scrollLeft || 0) + 5,
295 scrollY = (de.scrollTop || bd.scrollTop || 0) + 5,
296 axy = [xy[0] + offsets[0], xy[1] + offsets[1]],
298 constrainPosition = me.constrainPosition;
300 me.anchorEl.removeCls(me.anchorCls);
302 if (me.targetCounter < 2 && constrainPosition) {
303 if (axy[0] < scrollX) {
304 if (me.anchorToTarget) {
305 me.defaultAlign = 'l-r';
306 if (me.mouseOffset) {
307 me.mouseOffset[0] *= -1;
311 return me.getTargetXY();
313 if (axy[0] + sz.width > dw) {
314 if (me.anchorToTarget) {
315 me.defaultAlign = 'r-l';
316 if (me.mouseOffset) {
317 me.mouseOffset[0] *= -1;
321 return me.getTargetXY();
323 if (axy[1] < scrollY) {
324 if (me.anchorToTarget) {
325 me.defaultAlign = 't-b';
326 if (me.mouseOffset) {
327 me.mouseOffset[1] *= -1;
331 return me.getTargetXY();
333 if (axy[1] + sz.height > dh) {
334 if (me.anchorToTarget) {
335 me.defaultAlign = 'b-t';
336 if (me.mouseOffset) {
337 me.mouseOffset[1] *= -1;
340 me.anchor = 'bottom';
341 return me.getTargetXY();
345 me.anchorCls = Ext.baseCSSPrefix + 'tip-anchor-' + me.getAnchorPosition();
346 me.anchorEl.addCls(me.anchorCls);
347 me.targetCounter = 0;
350 mouseOffset = me.getMouseOffset();
351 return (me.targetXY) ? [me.targetXY[0] + mouseOffset[0], me.targetXY[1] + mouseOffset[1]] : mouseOffset;
355 getMouseOffset: function() {
357 offset = me.anchor ? [0, 0] : [15, 18];
358 if (me.mouseOffset) {
359 offset[0] += me.mouseOffset[0];
360 offset[1] += me.mouseOffset[1];
366 getAnchorPosition: function() {
370 me.tipAnchor = me.anchor.charAt(0);
372 m = me.defaultAlign.match(/^([a-z]+)-([a-z]+)(\?)?$/);
375 Ext.Error.raise('The AnchorTip.defaultAlign value "' + me.defaultAlign + '" is invalid.');
378 me.tipAnchor = m[1].charAt(0);
381 switch (me.tipAnchor) {
393 getAnchorAlign: function() {
394 switch (this.anchor) {
407 getOffsets: function() {
411 ap = me.getAnchorPosition().charAt(0);
412 if (me.anchorToTarget && !me.trackMouse) {
421 offsets = [ - 13, 0];
430 offsets = [ - 15 - me.anchorOffset, 30];
433 offsets = [ - 19 - me.anchorOffset, -13 - me.el.dom.offsetHeight];
436 offsets = [ - 15 - me.el.dom.offsetWidth, -13 - me.anchorOffset];
439 offsets = [25, -13 - me.anchorOffset];
443 mouseOffset = me.getMouseOffset();
444 offsets[0] += mouseOffset[0];
445 offsets[1] += mouseOffset[1];
451 onTargetOver: function(e) {
455 if (me.disabled || e.within(me.target.dom, true)) {
458 t = e.getTarget(me.delegate);
460 me.triggerElement = t;
461 me.clearTimer('hide');
462 me.targetXY = e.getXY();
468 delayShow: function() {
470 if (me.hidden && !me.showTimer) {
471 if (Ext.Date.getElapsed(me.lastActive) < me.quickShowInterval) {
474 me.showTimer = Ext.defer(me.show, me.showDelay, me);
477 else if (!me.hidden && me.autoHide !== false) {
483 onTargetOut: function(e) {
485 if (me.disabled || e.within(me.target.dom, true)) {
488 me.clearTimer('show');
489 if (me.autoHide !== false) {
495 delayHide: function() {
497 if (!me.hidden && !me.hideTimer) {
498 me.hideTimer = Ext.defer(me.hide, me.hideDelay, me);
502 <span id='Ext-tip.ToolTip-method-hide'> /**
503 </span> * Hides this tooltip if visible.
507 me.clearTimer('dismiss');
508 me.lastActive = new Date();
512 me.callParent(arguments);
513 delete me.triggerElement;
516 <span id='Ext-tip.ToolTip-method-show'> /**
517 </span> * Shows this tooltip at the current event target XY position.
522 // Show this Component first, so that sizing can be calculated
523 // pre-show it off screen so that the el will have dimensions
525 if (this.hidden === false) {
526 me.setPagePosition(-10000, -10000);
529 me.anchor = me.origAnchor;
531 me.showAt(me.getTargetXY());
543 showAt: function(xy) {
545 me.lastActive = new Date();
548 // Only call if this is hidden. May have been called from show above.
549 if (!me.isVisible()) {
550 this.callParent(arguments);
553 // Show may have been vetoed.
554 if (me.isVisible()) {
555 me.setPagePosition(xy[0], xy[1]);
556 if (me.constrainPosition || me.constrain) {
562 if (me.dismissDelay && me.autoHide !== false) {
563 me.dismissTimer = Ext.defer(me.hide, me.dismissDelay, me);
567 if (!me.anchorEl.isVisible()) {
576 syncAnchor: function() {
581 switch (me.tipAnchor.charAt(0)) {
585 offset = [20 + me.anchorOffset, 1];
590 offset = [ - 1, 12 + me.anchorOffset];
595 offset = [20 + me.anchorOffset, -1];
600 offset = [1, 12 + me.anchorOffset];
603 me.anchorEl.alignTo(me.el, anchorPos + '-' + targetPos, offset);
607 setPagePosition: function(x, y) {
609 me.callParent(arguments);
616 clearTimer: function(name) {
617 name = name + 'Timer';
618 clearTimeout(this[name]);
623 clearTimers: function() {
625 me.clearTimer('show');
626 me.clearTimer('dismiss');
627 me.clearTimer('hide');
634 me.mon(Ext.getDoc(), 'mousedown', me.onDocMouseDown, me);
641 me.mun(Ext.getDoc(), 'mousedown', me.onDocMouseDown, me);
645 onDocMouseDown: function(e) {
647 if (me.autoHide !== true && !me.closable && !e.within(me.el.dom)) {
649 Ext.defer(me.doEnable, 100, me);
654 doEnable: function() {
655 if (!this.isDestroyed) {
661 onDisable: function() {
667 beforeDestroy: function() {
670 Ext.destroy(me.anchorEl);
673 delete me.anchorTarget;
674 delete me.triggerElement;
679 onDestroy: function() {
680 Ext.getDoc().un('mousedown', this.onDocMouseDown, this);
684 </pre></pre></body></html>