/**
* @class Ext.tip.ToolTip
* @extends Ext.tip.Tip
*
* ToolTip is a {@link Ext.tip.Tip} implementation that handles the common case of displaying a
* tooltip when hovering over a certain element or elements on the page. It allows fine-grained
* control over the tooltip's alignment relative to the target element or mouse, and the timing
* of when it is automatically shown and hidden.
*
* This implementation does **not** have a built-in method of automatically populating the tooltip's
* text based on the target element; you must either configure a fixed {@link #html} value for each
* ToolTip instance, or implement custom logic (e.g. in a {@link #beforeshow} event listener) to
* generate the appropriate tooltip content on the fly. See {@link Ext.tip.QuickTip} for a more
* convenient way of automatically populating and configuring a tooltip based on specific DOM
* attributes of each target element.
*
* ## Basic Example
*
* var tip = Ext.create('Ext.tip.ToolTip', {
* target: 'clearButton',
* html: 'Press this button to clear the form'
* });
*
* {@img Ext.tip.ToolTip/Ext.tip.ToolTip1.png Basic Ext.tip.ToolTip}
*
* ## Delegation
*
* In addition to attaching a ToolTip to a single element, you can also use delegation to attach
* one ToolTip to many elements under a common parent. This is more efficient than creating many
* ToolTip instances. To do this, point the {@link #target} config to a common ancestor of all the
* elements, and then set the {@link #delegate} config to a CSS selector that will select all the
* appropriate sub-elements.
*
* When using delegation, it is likely that you will want to programmatically change the content
* of the ToolTip based on each delegate element; you can do this by implementing a custom
* listener for the {@link #beforeshow} event. Example:
*
* var myGrid = Ext.create('Ext.grid.GridPanel', gridConfig);
* myGrid.on('render', function(grid) {
* var view = grid.getView(); // Capture the grid's view.
* grid.tip = Ext.create('Ext.tip.ToolTip', {
* target: view.el, // The overall target element.
* delegate: view.itemSelector, // Each grid row causes its own seperate show and hide.
* trackMouse: true, // Moving within the row should not hide the tip.
* renderTo: Ext.getBody(), // Render immediately so that tip.body can be referenced prior to the first show.
* listeners: { // Change content dynamically depending on which element triggered the show.
* beforeshow: function updateTipBody(tip) {
* tip.update('Over company "' + view.getRecord(tip.triggerElement).get('company') + '"');
* }
* }
* });
* });
*
* {@img Ext.tip.ToolTip/Ext.tip.ToolTip2.png Ext.tip.ToolTip with delegation}
*
* ## Alignment
*
* The following configuration properties allow control over how the ToolTip is aligned relative to
* the target element and/or mouse pointer:
*
* - {@link #anchor}
* - {@link #anchorToTarget}
* - {@link #anchorOffset}
* - {@link #trackMouse}
* - {@link #mouseOffset}
*
* ## Showing/Hiding
*
* The following configuration properties allow control over how and when the ToolTip is automatically
* shown and hidden:
*
* - {@link #autoHide}
* - {@link #showDelay}
* - {@link #hideDelay}
* - {@link #dismissDelay}
*
* @constructor
* Create a new ToolTip instance
* @param {Object} config The configuration options
* @xtype tooltip
* @markdown
* @docauthor Jason Johnston <jason@sencha.com>
*/
Ext.define('Ext.tip.ToolTip', {
extend: 'Ext.tip.Tip',
alias: 'widget.tooltip',
alternateClassName: 'Ext.ToolTip',
/**
* When a ToolTip is configured with the <code>{@link #delegate}</code>
* option to cause selected child elements of the <code>{@link #target}</code>
* Element to each trigger a seperate show event, this property is set to
* the DOM element which triggered the show.
* @type DOMElement
* @property triggerElement
*/
/**
* @cfg {Mixed} target The target HTMLElement, Ext.core.Element or id to monitor
* for mouseover events to trigger showing this ToolTip.
*/
/**
* @cfg {Boolean} autoHide True to automatically hide the tooltip after the
* mouse exits the target element or after the <code>{@link #dismissDelay}</code>
* has expired if set (defaults to true). If <code>{@link #closable} = true</code>
* a close tool button will be rendered into the tooltip header.
*/
/**
* @cfg {Number} showDelay Delay in milliseconds before the tooltip displays
* after the mouse enters the target element (defaults to 500)
*/
showDelay: 500,
/**
* @cfg {Number} hideDelay Delay in milliseconds after the mouse exits the
* target element but before the tooltip actually hides (defaults to 200).
* Set to 0 for the tooltip to hide immediately.
*/
hideDelay: 200,
/**
* @cfg {Number} dismissDelay Delay in milliseconds before the tooltip
* automatically hides (defaults to 5000). To disable automatic hiding, set
* dismissDelay = 0.
*/
dismissDelay: 5000,
/**
* @cfg {Array} mouseOffset An XY offset from the mouse position where the
* tooltip should be shown (defaults to [15,18]).
*/
/**
* @cfg {Boolean} trackMouse True to have the tooltip follow the mouse as it
* moves over the target element (defaults to false).
*/
trackMouse: false,
/**
* @cfg {String} anchor If specified, indicates that the tip should be anchored to a
* particular side of the target element or mouse pointer ("top", "right", "bottom",
* or "left"), with an arrow pointing back at the target or mouse pointer. If
* {@link #constrainPosition} is enabled, this will be used as a preferred value
* only and may be flipped as needed.
*/
/**
* @cfg {Boolean} anchorToTarget True to anchor the tooltip to the target
* element, false to anchor it relative to the mouse coordinates (defaults
* to true). When <code>anchorToTarget</code> is true, use
* <code>{@link #defaultAlign}</code> to control tooltip alignment to the
* target element. When <code>anchorToTarget</code> is false, use
* <code>{@link #anchorPosition}</code> instead to control alignment.
*/
anchorToTarget: true,
/**
* @cfg {Number} anchorOffset A numeric pixel value used to offset the
* default position of the anchor arrow (defaults to 0). When the anchor
* position is on the top or bottom of the tooltip, <code>anchorOffset</code>
* will be used as a horizontal offset. Likewise, when the anchor position
* is on the left or right side, <code>anchorOffset</code> will be used as
* a vertical offset.
*/
anchorOffset: 0,
/**
* @cfg {String} delegate <p>Optional. A {@link Ext.DomQuery DomQuery}
* selector which allows selection of individual elements within the
* <code>{@link #target}</code> element to trigger showing and hiding the
* ToolTip as the mouse moves within the target.</p>
* <p>When specified, the child element of the target which caused a show
* event is placed into the <code>{@link #triggerElement}</code> property
* before the ToolTip is shown.</p>
* <p>This may be useful when a Component has regular, repeating elements
* in it, each of which need a ToolTip which contains information specific
* to that element. For example:</p><pre><code>
var myGrid = Ext.create('Ext.grid.GridPanel', gridConfig);
myGrid.on('render', function(grid) {
var view = grid.getView(); // Capture the grid's view.
grid.tip = Ext.create('Ext.tip.ToolTip', {
target: view.el, // The overall target element.
delegate: view.itemSelector, // Each grid row causes its own seperate show and hide.
trackMouse: true, // Moving within the row should not hide the tip.
renderTo: Ext.getBody(), // Render immediately so that tip.body can be referenced prior to the first show.
listeners: { // Change content dynamically depending on which element triggered the show.
beforeshow: function(tip) {
tip.update('Over Record ID ' + view.getRecord(tip.triggerElement).id);
}
}
});
});
*</code></pre>
*/
// private
targetCounter: 0,
quickShowInterval: 250,
// private
initComponent: function() {
var me = this;
me.callParent(arguments);
me.lastActive = new Date();
me.setTarget(me.target);
me.origAnchor = me.anchor;
},
// private
onRender: function(ct, position) {
var me = this;
me.callParent(arguments);
me.anchorCls = Ext.baseCSSPrefix + 'tip-anchor-' + me.getAnchorPosition();
me.anchorEl = me.el.createChild({
cls: Ext.baseCSSPrefix + 'tip-anchor ' + me.anchorCls
});
},
// private
afterRender: function() {
var me = this,
zIndex;
me.callParent(arguments);
zIndex = parseInt(me.el.getZIndex(), 10) || 0;
me.anchorEl.setStyle('z-index', zIndex + 1).setVisibilityMode(Ext.core.Element.DISPLAY);
},
/**
* Binds this ToolTip to the specified element. The tooltip will be displayed when the mouse moves over the element.
* @param {Mixed} t The Element, HtmlElement, or ID of an element to bind to
*/
setTarget: function(target) {
var me = this,
t = Ext.get(target),
tg;
if (me.target) {
tg = Ext.get(me.target);
me.mun(tg, 'mouseover', me.onTargetOver, me);
me.mun(tg, 'mouseout', me.onTargetOut, me);
me.mun(tg, 'mousemove', me.onMouseMove, me);
}
me.target = t;
if (t) {
me.mon(t, {
// TODO - investigate why IE6/7 seem to fire recursive resize in e.getXY
// breaking QuickTip#onTargetOver (EXTJSIV-1608)
freezeEvent: true,
mouseover: me.onTargetOver,
mouseout: me.onTargetOut,
mousemove: me.onMouseMove,
scope: me
});
}
if (me.anchor) {
me.anchorTarget = me.target;
}
},
// private
onMouseMove: function(e) {
var me = this,
t = me.delegate ? e.getTarget(me.delegate) : me.triggerElement = true,
xy;
if (t) {
me.targetXY = e.getXY();
if (t === me.triggerElement) {
if (!me.hidden && me.trackMouse) {
xy = me.getTargetXY();
if (me.constrainPosition) {
xy = me.el.adjustForConstraints(xy, me.el.dom.parentNode);
}
me.setPagePosition(xy);
}
} else {
me.hide();
me.lastActive = new Date(0);
me.onTargetOver(e);
}
} else if ((!me.closable && me.isVisible()) && me.autoHide !== false) {
me.hide();
}
},
// private
getTargetXY: function() {
var me = this,
mouseOffset;
if (me.delegate) {
me.anchorTarget = me.triggerElement;
}
if (me.anchor) {
me.targetCounter++;
var offsets = me.getOffsets(),
xy = (me.anchorToTarget && !me.trackMouse) ? me.el.getAlignToXY(me.anchorTarget, me.getAnchorAlign()) : me.targetXY,
dw = Ext.core.Element.getViewWidth() - 5,
dh = Ext.core.Element.getViewHeight() - 5,
de = document.documentElement,
bd = document.body,
scrollX = (de.scrollLeft || bd.scrollLeft || 0) + 5,
scrollY = (de.scrollTop || bd.scrollTop || 0) + 5,
axy = [xy[0] + offsets[0], xy[1] + offsets[1]],
sz = me.getSize(),
constrainPosition = me.constrainPosition;
me.anchorEl.removeCls(me.anchorCls);
if (me.targetCounter < 2 && constrainPosition) {
if (axy[0] < scrollX) {
if (me.anchorToTarget) {
me.defaultAlign = 'l-r';
if (me.mouseOffset) {
me.mouseOffset[0] *= -1;
}
}
me.anchor = 'left';
return me.getTargetXY();
}
if (axy[0] + sz.width > dw) {
if (me.anchorToTarget) {
me.defaultAlign = 'r-l';
if (me.mouseOffset) {
me.mouseOffset[0] *= -1;
}
}
me.anchor = 'right';
return me.getTargetXY();
}
if (axy[1] < scrollY) {
if (me.anchorToTarget) {
me.defaultAlign = 't-b';
if (me.mouseOffset) {
me.mouseOffset[1] *= -1;
}
}
me.anchor = 'top';
return me.getTargetXY();
}
if (axy[1] + sz.height > dh) {
if (me.anchorToTarget) {
me.defaultAlign = 'b-t';
if (me.mouseOffset) {
me.mouseOffset[1] *= -1;
}
}
me.anchor = 'bottom';
return me.getTargetXY();
}
}
me.anchorCls = Ext.baseCSSPrefix + 'tip-anchor-' + me.getAnchorPosition();
me.anchorEl.addCls(me.anchorCls);
me.targetCounter = 0;
return axy;
} else {
mouseOffset = me.getMouseOffset();
return (me.targetXY) ? [me.targetXY[0] + mouseOffset[0], me.targetXY[1] + mouseOffset[1]] : mouseOffset;
}
},
getMouseOffset: function() {
var me = this,
offset = me.anchor ? [0, 0] : [15, 18];
if (me.mouseOffset) {
offset[0] += me.mouseOffset[0];
offset[1] += me.mouseOffset[1];
}
return offset;
},
// private
getAnchorPosition: function() {
var me = this,
m;
if (me.anchor) {
me.tipAnchor = me.anchor.charAt(0);
} else {
m = me.defaultAlign.match(/^([a-z]+)-([a-z]+)(\?)?$/);
//<debug>
if (!m) {
Ext.Error.raise('The AnchorTip.defaultAlign value "' + me.defaultAlign + '" is invalid.');
}
//</debug>
me.tipAnchor = m[1].charAt(0);
}
switch (me.tipAnchor) {
case 't':
return 'top';
case 'b':
return 'bottom';
case 'r':
return 'right';
}
return 'left';
},
// private
getAnchorAlign: function() {
switch (this.anchor) {
case 'top':
return 'tl-bl';
case 'left':
return 'tl-tr';
case 'right':
return 'tr-tl';
default:
return 'bl-tl';
}
},
// private
getOffsets: function() {
var me = this,
mouseOffset,
offsets,
ap = me.getAnchorPosition().charAt(0);
if (me.anchorToTarget && !me.trackMouse) {
switch (ap) {
case 't':
offsets = [0, 9];
break;
case 'b':
offsets = [0, -13];
break;
case 'r':
offsets = [ - 13, 0];
break;
default:
offsets = [9, 0];
break;
}
} else {
switch (ap) {
case 't':
offsets = [ - 15 - me.anchorOffset, 30];
break;
case 'b':
offsets = [ - 19 - me.anchorOffset, -13 - me.el.dom.offsetHeight];
break;
case 'r':
offsets = [ - 15 - me.el.dom.offsetWidth, -13 - me.anchorOffset];
break;
default:
offsets = [25, -13 - me.anchorOffset];
break;
}
}
mouseOffset = me.getMouseOffset();
offsets[0] += mouseOffset[0];
offsets[1] += mouseOffset[1];
return offsets;
},
// private
onTargetOver: function(e) {
var me = this,
t;
if (me.disabled || e.within(me.target.dom, true)) {
return;
}
t = e.getTarget(me.delegate);
if (t) {
me.triggerElement = t;
me.clearTimer('hide');
me.targetXY = e.getXY();
me.delayShow();
}
},
// private
delayShow: function() {
var me = this;
if (me.hidden && !me.showTimer) {
if (Ext.Date.getElapsed(me.lastActive) < me.quickShowInterval) {
me.show();
} else {
me.showTimer = Ext.defer(me.show, me.showDelay, me);
}
}
else if (!me.hidden && me.autoHide !== false) {
me.show();
}
},
// private
onTargetOut: function(e) {
var me = this;
if (me.disabled || e.within(me.target.dom, true)) {
return;
}
me.clearTimer('show');
if (me.autoHide !== false) {
me.delayHide();
}
},
// private
delayHide: function() {
var me = this;
if (!me.hidden && !me.hideTimer) {
me.hideTimer = Ext.defer(me.hide, me.hideDelay, me);
}
},
/**
* Hides this tooltip if visible.
*/
hide: function() {
var me = this;
me.clearTimer('dismiss');
me.lastActive = new Date();
if (me.anchorEl) {
me.anchorEl.hide();
}
me.callParent(arguments);
delete me.triggerElement;
},
/**
* Shows this tooltip at the current event target XY position.
*/
show: function() {
var me = this;
// Show this Component first, so that sizing can be calculated
// pre-show it off screen so that the el will have dimensions
this.callParent();
if (this.hidden === false) {
me.setPagePosition(-10000, -10000);
if (me.anchor) {
me.anchor = me.origAnchor;
}
me.showAt(me.getTargetXY());
if (me.anchor) {
me.syncAnchor();
me.anchorEl.show();
} else {
me.anchorEl.hide();
}
}
},
// inherit docs
showAt: function(xy) {
var me = this;
me.lastActive = new Date();
me.clearTimers();
// Only call if this is hidden. May have been called from show above.
if (!me.isVisible()) {
this.callParent(arguments);
}
// Show may have been vetoed.
if (me.isVisible()) {
me.setPagePosition(xy[0], xy[1]);
if (me.constrainPosition || me.constrain) {
me.doConstrain();
}
me.toFront(true);
}
if (me.dismissDelay && me.autoHide !== false) {
me.dismissTimer = Ext.defer(me.hide, me.dismissDelay, me);
}
if (me.anchor) {
me.syncAnchor();
if (!me.anchorEl.isVisible()) {
me.anchorEl.show();
}
} else {
me.anchorEl.hide();
}
},
// private
syncAnchor: function() {
var me = this,
anchorPos,
targetPos,
offset;
switch (me.tipAnchor.charAt(0)) {
case 't':
anchorPos = 'b';
targetPos = 'tl';
offset = [20 + me.anchorOffset, 1];
break;
case 'r':
anchorPos = 'l';
targetPos = 'tr';
offset = [ - 1, 12 + me.anchorOffset];
break;
case 'b':
anchorPos = 't';
targetPos = 'bl';
offset = [20 + me.anchorOffset, -1];
break;
default:
anchorPos = 'r';
targetPos = 'tl';
offset = [1, 12 + me.anchorOffset];
break;
}
me.anchorEl.alignTo(me.el, anchorPos + '-' + targetPos, offset);
},
// private
setPagePosition: function(x, y) {
var me = this;
me.callParent(arguments);
if (me.anchor) {
me.syncAnchor();
}
},
// private
clearTimer: function(name) {
name = name + 'Timer';
clearTimeout(this[name]);
delete this[name];
},
// private
clearTimers: function() {
var me = this;
me.clearTimer('show');
me.clearTimer('dismiss');
me.clearTimer('hide');
},
// private
onShow: function() {
var me = this;
me.callParent();
me.mon(Ext.getDoc(), 'mousedown', me.onDocMouseDown, me);
},
// private
onHide: function() {
var me = this;
me.callParent();
me.mun(Ext.getDoc(), 'mousedown', me.onDocMouseDown, me);
},
// private
onDocMouseDown: function(e) {
var me = this;
if (me.autoHide !== true && !me.closable && !e.within(me.el.dom)) {
me.disable();
Ext.defer(me.doEnable, 100, me);
}
},
// private
doEnable: function() {
if (!this.isDestroyed) {
this.enable();
}
},
// private
onDisable: function() {
this.callParent();
this.clearTimers();
this.hide();
},
beforeDestroy: function() {
var me = this;
me.clearTimers();
Ext.destroy(me.anchorEl);
delete me.anchorEl;
delete me.target;
delete me.anchorTarget;
delete me.triggerElement;
me.callParent();
},
// private
onDestroy: function() {
Ext.getDoc().un('mousedown', this.onDocMouseDown, this);
this.callParent();
}
});