/** * 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 * * @example * Ext.getBody().appendChild({ * id: 'clearButton', * html: 'Clear Button', * style: 'display:inline-block;background:#A2C841;padding:7px;cursor:pointer;' * }); * * var tip = Ext.create('Ext.tip.ToolTip', { * target: 'clearButton', * html: 'Press this button to clear the form' * }); * * # 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: * * @example * var store = Ext.create('Ext.data.ArrayStore', { * fields: ['company', 'price', 'change'], * data: [ * ['3m Co', 71.72, 0.02], * ['Alcoa Inc', 29.01, 0.42], * ['Altria Group Inc', 83.81, 0.28], * ['American Express Company', 52.55, 0.01], * ['American International Group, Inc.', 64.13, 0.31], * ['AT&T Inc.', 31.61, -0.48] * ] * }); * * var grid = Ext.create('Ext.grid.Panel', { * title: 'Array Grid', * store: store, * columns: [ * {text: 'Company', flex: 1, dataIndex: 'company'}, * {text: 'Price', width: 75, dataIndex: 'price'}, * {text: 'Change', width: 75, dataIndex: 'change'} * ], * height: 200, * width: 400, * renderTo: Ext.getBody() * }); * * var view = grid.getView(); * var tip = Ext.create('Ext.tip.ToolTip', { * // The overall target element. * target: view.el, * // Each grid row causes its own separate show and hide. * delegate: view.itemSelector, * // Moving within the row should not hide the tip. * trackMouse: true, * // Render immediately so that tip.body can be referenced prior to the first show. * renderTo: Ext.getBody(), * 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') + '"'); * } * } * }); * * # 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 #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} */Ext.define('Ext.tip.ToolTip', { extend: 'Ext.tip.Tip', alias: 'widget.tooltip', alternateClassName: 'Ext.ToolTip', requires: ['Ext.util.Offset'], /** * @property {HTMLElement} triggerElement * When a ToolTip is configured with the `{@link #delegate}` * option to cause selected child elements of the `{@link #target}` * Element to each trigger a separate show event, this property is set to * the DOM element which triggered the show. */ /** * @cfg {HTMLElement/Ext.dom.Element/String} target * The target element or string id to monitor for mouseover events to trigger * showing this ToolTip. */ /** * @cfg {Boolean} [autoHide=true] * True to automatically hide the tooltip after the * mouse exits the target element or after the `{@link #dismissDelay}` * has expired if set. If `{@link #closable} = true` * a close tool button will be rendered into the tooltip header. */ autoHide: true, /** * @cfg {Number} showDelay * Delay in milliseconds before the tooltip displays after the mouse enters the target element. */ showDelay: 500, /** * @cfg {Number} hideDelay * Delay in milliseconds after the mouse exits the target element but before the tooltip actually hides. * Set to 0 for the tooltip to hide immediately. */ hideDelay: 200, /** * @cfg {Number} dismissDelay * Delay in milliseconds before the tooltip automatically hides. To disable automatic hiding, set * dismissDelay = 0. */ dismissDelay: 5000, /** * @cfg {Number[]} [targetOffset=[0, 0]] * When {@link #anchorToTarget} is being used to position this tip relative to its target element, * this may be used as an extra XY offset from the target element. */ /** * @cfg {Number[]} [mouseOffset=[15, 18]] * An XY offset from the mouse position where the tooltip should be shown. */ mouseOffset: [15, 18], /** * @cfg {Boolean} trackMouse * True to have the tooltip follow the mouse as it moves over the target element. */ 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. * When `anchorToTarget` is true, use `{@link #defaultAlign}` to control tooltip alignment to the * target element. When `anchorToTarget` is false, use `{@link #anchor}` instead to control alignment. */ anchorToTarget: true, /** * @cfg {String} delegate * * A {@link Ext.DomQuery DomQuery} simple selector which allows selection of individual elements within the * `{@link #target}` element to trigger showing and hiding the ToolTip as the mouse moves within the * target. See {@link Ext.dom.Query} for information about simple selectors. * * When specified, the child element of the target which caused a show event is placed into the * `{@link #triggerElement}` property before the ToolTip is shown. * * 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. * * See the delegate example in class documentation of {@link Ext.tip.ToolTip}. */ /** * @cfg {Boolean} [showOnTap=false] * On touch platforms, if {@link #showOnTap} is `true`, a tap on the target shows the tip. * In this case any {@link #showDelay} is ignored. * * This is useful for adding tips on elements which do not have tap listeners. It would * not be appropriate for a ToolTip on a {@link Ext.Button Button}. */ /** * @private */ targetCounter: 0, quickShowInterval: 250, /** * @cfg {String} [hideAction="hide"] * The method to use to hide the tooltip. Another useful method for this is `fadeOut`. */ hideAction: 'hide', /** * @cfg {Number} [fadeOutDuration=1000] * The number of milliseconds for the `fadeOut` animation. Only valid if `hideAction` * is set to `fadeOut`. */ fadeOutDuration: 1000, /** * @cfg {String} defaultAlign * A string which specifies how this ToolTip is to align with regard to its * {@link #currentTarget} by means of identifying the point of the tooltip to * join to the point of the target. * * By default, the tooltip shows at {@link #mouseOffset} pixels from the * triggering pointer event. Using this config anchors the ToolTip to its target * instead. * * This may take the following forms: * * - **Blank**: Defaults to aligning the element's top-left corner to the target's * bottom-left corner ("tl-bl"). * - **Two anchors**: If two values from the table below are passed separated by a dash, * the first value is used as the element's anchor point, and the second value is * used as the target's anchor point. * - **Two edge/offset descriptors:** An edge/offset descriptor is an edge initial * (`t`/`r`/`b`/`l`) followed by a percentage along that side. This describes a * point to align with a similar point in the target. So `'t0-b0'` would be * the same as `'tl-bl'`, `'l0-r50'` would place the top left corner of this item * halfway down the right edge of the target item. This allows more flexibility * and also describes which two edges are considered adjacent when positioning a tip pointer. * * Following are all of the supported predefined anchor positions: * * Value Description * ----- ----------------------------- * tl The top left corner * t The center of the top edge * tr The top right corner * l The center of the left edge * c The center * r The center of the right edge * bl The bottom left corner * b The center of the bottom edge * br The bottom right corner * * You can put a '?' at the end of the alignment string to constrain the positioned element to the * {@link Ext.Viewport Viewport}. The element will attempt to align as specified, but the position * will be adjusted to constrain to the viewport if necessary. Note that the element being aligned * might be swapped to align to a different position than that specified in order to enforce the viewport * constraints. * * Example Usage: * * // align the top left corner of the tooltip with the top right corner of its target. * defaultAlign: 'tl-tr' * * // align the bottom right corner of the tooltip with the center left edge of its target. * defaultAlign: 'br-l' * * // align the top center of the tooltip with the bottom left corner of its target. * defaultAlign: 't-bl' * * // align the 25% point on the bottom edge of this tooltip * // with the 75% point on the top edge of its target. * defaultAlign: 'b25-t75' */ defaultAlign: 'bl-tl', ariaRole: 'tooltip', alwaysOnTop: true, initComponent: function() { var me = this; me.callParent(); me.setTarget(me.target); // currentTarget is a flyweight which points to the activeTarget. me.currentTarget = new Ext.dom.Fly(); }, onRender: function(ct, position) { var me = this; me.callParent(arguments); //<debug> if (me.sticky) { // tell the spec runner to ignore this element when checking if the dom is clean me.el.dom.setAttribute('data-sticky', true); } //</debug> me.anchorEl = me.el.createChild({ role: 'presentation', cls: Ext.baseCSSPrefix + 'tip-anchor' }); }, show: function() { // A programmatic show should align to the target if (!this.currentTarget.dom && this.target) { return this.showBy(this.target); } this.callParent(); }, /** * Binds this ToolTip to the specified element. The tooltip will be displayed when the mouse moves over the element. * @param {String/HTMLElement/Ext.dom.Element} target The Element, HTMLElement, or * ID of an element to bind to */ setTarget: function(target) { var me = this, listeners; if (me.targetListeners) { me.targetListeners.destroy(); } if (target) { me.target = target = Ext.get(target.el || target); listeners = { mouseover: 'onTargetOver', mouseout: 'onTargetOut', mousemove: 'onMouseMove', tap: 'onTargetTap', scope: me, destroyable: true }; me.targetListeners = target.on(listeners); } else { me.target = null; } }, /** * @private */ onMouseMove: function(e) { var me = this, dismissDelay = me.dismissDelay; // Always update pointerEvent, so that if there's a delayed show // scheduled, it gets the latest pointer to align to. me.pointerEvent = e; if (me.isVisible() && me.currentTarget.contains(e.target)) { // If they move the mouse, restart the dismiss delay if (dismissDelay && me.autoHide !== false) { me.clearTimer('dismiss'); me.dismissTimer = Ext.defer(me.hide, dismissDelay, me); } if (me.trackMouse) { me.doAlignment(me.getAlignRegion()); } } }, /** * @private */ getAlignRegion: function() { var me = this, anchorEl = me.anchorEl, align = me.getAnchorAlign(), overlap, alignSpec, target, mouseOffset = me.mouseOffset; if (!me.anchorSize) { anchorEl.addCls(Ext.baseCSSPrefix + 'tip-anchor-top'); anchorEl.show(); me.anchorSize = new Ext.util.Offset(anchorEl.getWidth(false, true), anchorEl.getHeight(false, true)); anchorEl.removeCls(Ext.baseCSSPrefix + 'tip-anchor-top'); anchorEl.hide(); } // Target region from the anchorTarget element unless trackMouse set if ((me.anchor || me.align) && me.anchorToTarget && !me.trackMouse) { target = me.currentTarget.getRegion(); } // Here, we're either trackMouse: true, or we're not anchored to the target // element, so we should show offset from the mouse. // If we are being shown programatically, use 0, 0 else { target = me.pointerEvent ? me.pointerEvent.getPoint().adjust(-Math.abs(mouseOffset[1]), Math.abs(mouseOffset[0]), Math.abs(mouseOffset[1]), -Math.abs(mouseOffset[0])) : new Ext.util.Point(); if (!me.anchor) { overlap = true; if (mouseOffset[0] > 0) { if (mouseOffset[1] > 0) { align = 'tl-br'; } else { align = 'bl-tr'; } } else { if (mouseOffset[1] > 0) { align = 'tr-bl'; } else { align = 'br-tl'; } } } } alignSpec = { align: me.convertPositionSpec(align), axisLock: me.axisLock, target: target, overlap: overlap, offset: me.targetOffset, inside: me.constrainPosition ? (me.constrainTo || Ext.getBody().getRegion().adjust(5, -5, -5, 5)) : null }; if (me.anchor) { alignSpec.anchorSize = me.anchorSize; } return me.getRegion().alignTo(alignSpec); }, fadeOut: function () { var me = this; me.el.fadeOut({ duration: me.fadeOutDuration, callback: function () { me.hide(); me.el.setOpacity(''); } }); }, /** * @private */ getAnchorAlign: function() { switch (this.anchor) { case 'top': return 'tl-bl'; case 'left': return 'tl-tr'; case 'right': return 'tr-tl'; default: return this.defaultAlign; } }, onTargetTap: function(e) { // On hybrid mouse/touch systems, we want to show the tip on touch, but // we don't want to show it if this is coming from a click event, because // the mouse is already hovered. Tap occasionally hides - eg: pickers, menus. if (this.showOnTap && e.pointerType !== 'mouse' && Ext.fly(e.target).isVisible(true)) { this.onTargetOver(e); } }, /** * @private */ onTargetOver: function(e) { var me = this, delegate = me.delegate, currentTarget = me.currentTarget, fromElement = e.relatedTarget || e.fromElement, newTarget, myListeners = me.hasListeners; if (me.disabled) { return; } if (delegate) { // Moving inside a delegate if (currentTarget.contains(e.target)) { return; } newTarget = e.getTarget(delegate); // Mouseovers while within a target do nothing if (newTarget && e.getRelatedTarget(delegate) === newTarget) { return; } } // Moved from outside the target else if (!me.target.contains(fromElement)) { newTarget = me.target.dom; } // Moving inside the target else { return; } // If pointer entered the target or a delegate child, then show. if (newTarget) { // If users need to see show events on target change, we must hide. if ((myListeners.beforeshow || myListeners.show) && me.isVisible()) { me.hide(); } me.triggerElement = newTarget; me.pointerEvent = e; currentTarget.attach(newTarget); me.handleTargetOver(newTarget, e); } // If over a non-delegate child, behave as in target out else if (currentTarget.dom) { me.handleTargetOut(); } }, handleTargetOver: function(target, event) { // Separated from onTargetOver so that subclasses can handle target over in any way. // If we are showing on tap, show immediately if (event.pointerType !== 'mouse') { this.showFromDelay(); } else { this.delayShow(); } }, /** * @private */ delayShow: function() { var me = this; me.clearTimer('hide'); if (me.hidden && !me.showTimer) { if (me.delegate && Ext.Date.getElapsed(me.lastHidden) < me.quickShowInterval) { me.showFromDelay(); } else { me.showTimer = Ext.defer(me.showFromDelay, me.pointerEvent.pointerType !== 'mouse' ? 0 : me.showDelay, me); } } else if (!me.hidden && me.autoHide !== false) { me.showFromDelay(); } }, showFromDelay: function () { var me = this; // Need to check this here since onDisable only gets called after render, which // the show call below may trigger if (!me.disabled) { me.fireEvent('hovertarget', me, me.currentTarget, me.currentTarget.dom); if (me.isVisible()) { me.realignToTarget(); } else { me.triggerElement = me.currentTarget.dom; me.fromDelayShow = true; me.show(); me.fromDelayShow = false; } } }, /** * @private */ onTargetOut: function(e) { // We have exited the current target if (this.currentTarget.dom && !this.currentTarget.contains(e.relatedTarget)) { this.handleTargetOut(); } }, handleTargetOut: function() { var me = this; if (me.showTimer) { me.clearTimer('show'); } if (me.isVisible() && me.autoHide) { me.delayHide(); } }, /** * @private */ delayHide: function() { var me = this; if (!me.hidden && !me.hideTimer) { me.clearTimer('dismiss'); me.hideTimer = Ext.defer(me[me.hideAction], me.hideDelay, me); } }, /** * Hides this tooltip if visible. */ hide: function() { var me = this; // Must also do this on hide in case it was dismissed while over me.currentTarget.detach(); me.clearTimer('dismiss'); me.lastHidden = new Date(); if (me.anchorEl) { me.anchorEl.hide(); } me.callParent(arguments); me.triggerElement = null; }, /** * Ensures this tooltip at the current event target XY position. */ afterShow: function () { this.callParent(); this.realignToTarget(); }, /** * Realign this tooltip to the {@link #cfg-target}. * * @since 6.2.1 */ realignToTarget: function() { var me = this; me.clearTimers(); if (!me.calledFromShowAt) { me.doAlignment(me.getAlignRegion()); } if (me.dismissDelay && me.autoHide !== false) { me.dismissTimer = Ext.defer(me.hide, me.dismissDelay, me); } }, /** * Shows this ToolTip aligned to the passed Component or element or event according to the {@link #anchor} config. * @param {Ext.Component/Ext.event.Event/Ext.dom.Element} target The {@link Ext.Component} or {@link Ext.dom.Element}, or (Ext.event.Event} * to show this ToolTip by. */ showBy: function(target) { var me = this; me.align = me.defaultAlign; if (target.isEvent) { me.currentTarget.attach(target.target); me.pointerEvent = target; } else { me.currentTarget.attach(Ext.getDom(target.el || target)); me.triggerElement = me.currentTarget.dom; } if (me.isVisible()) { me.realignToTarget(); } else { me.show(); } return me; }, _timerNames: {}, /** * @private */ clearTimer: function (name) { var me = this, names = me._timerNames, propName = names[name] || (names[name] = name + 'Timer'), timer = me[propName]; if (timer) { Ext.undefer(timer); me[propName] = null; // We were going to show against the target, but now not. if (name === 'show' && me.isHidden()) { me.currentTarget.detach(); } } }, /** * @private */ clearTimers: function() { var me = this; me.clearTimer('show'); me.clearTimer('dismiss'); me.clearTimer('hide'); me.clearTimer('enable'); }, onShow: function() { var me = this; me.callParent(); me.mousedownListener = Ext.on({ mousedown: 'onDocMouseDown', scope: me, destroyable: true }); }, onHide: function() { var me = this; me.callParent(); Ext.destroy(me.mousedownListener); }, /** * @private */ onDocMouseDown: function(e) { var me = this, delegate = me.delegate; if (e.within(me.el.dom)) { // A real touch event inside the tip is the equivalent of // mousing over the tip to keep it visible, so cancel the // dismiss timer. if (e.pointerType !== 'mouse' && me.allowOver) { me.clearTimer('dismiss'); } } // Only respond to the mousedown if it's not on this tip, and it's not on a target. // If it's on a target, onTargetTap will handle it. else if (!me.closable) { if (e.within(me.target) && (!delegate || e.getTarget(delegate))) { me.delayHide(); } else { me.disable(); me.enableTimer = Ext.defer(me.enable, 100, me); } } }, /** * @private */ doEnable: function() { if (!this.destroyed) { this.enable(); } }, onDisable: function() { this.callParent(); this.clearTimers(); this.hide(); }, doDestroy: function() { var me = this; me.clearTimers(); me.destroyMembers('mousedownListener', 'anchorEl'); me.callParent(); }, privates: { /** * Implementation for universal apps so that the Tooltip interface they are using works * when common code uses the ToolTip API. */ getTrackMouse: function() { return this.trackMouse; }, clipTo: function(clippingEl, sides) { // Override because we also need to clip the anchor var clippingRegion; // Allow a Region to be passed if (clippingEl.isRegion) { clippingRegion = clippingEl; } else { clippingRegion = (clippingEl.isComponent ? clippingEl.el : Ext.fly(clippingEl)).getConstrainRegion(); } this.callParent([clippingRegion, sides]); // Clip the anchor to the same bounds this.anchorEl.clipTo(clippingRegion, sides); } }});