# Yahoo! UI Library

### Container 2.8.0r4

Yahoo! UI Library > container > YAHOO.widget.Tooltip
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.widget.Tooltip - extends YAHOO.widget.Overlay

Tooltip is an implementation of Overlay that behaves like an OS tooltip, displaying when the user mouses over a particular element, and disappearing on mouse out.

### Constructor

YAHOO.widget.Tooltip `( el , userConfig )`

Parameters:
  `el <String>` The element ID representing the Tooltip OR
  `el <HTMLElement>` The element representing the Tooltip
  `userConfig <Object>` The configuration object literal containing the configuration that should be set for this Overlay. See configuration documentation for more details.

### Properties

#### DEFAULT_CONFIG - `private final Object`

Constant representing the Tooltip's configuration properties

#### EVENT_TYPES - `private final Object`

Constant representing the name of the Tooltip's events

#### showProcId - `int`

The unique process ID associated with the thread responsible for showing the Tooltip.

#### YAHOO.widget.Tooltip.CSS_TOOLTIP - `static final String`

Constant representing the Tooltip CSS class

#### Properties inherited from YAHOO.widget.Module:

`body, browser, cfg, contructor, DEFAULT_CONFIG, element, EVENT_TYPES, footer, header, id, imageRoot, isSecure, platform`

#### Properties inherited from YAHOO.widget.Overlay:

`CONTEXT_TRIGGERS, DEFAULT_CONFIG, EVENT_TYPES, YAHOO.widget.Overlay._initialized`

### Methods

#### _removeEventListeners

`protected void _removeEventListeners ( )`
Removes all of the DOM event handlers from the HTML element(s) that trigger the display of the tooltip.

Returns: `void`

#### configContainer

`void configContainer ( type , args , obj )`
The default event handler fired when the "container" property is changed.

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

Returns: `void`

#### configContext

`void configContext ( type , args , obj )`
The default event handler fired when the "context" property is changed.

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

Returns: `void`

#### configText

`void configText ( type , args , obj )`
The default event handler fired when the "text" property is changed.

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

Returns: `void`

#### destroy

`void destroy ( )`
Removes the Tooltip element from the DOM and sets all child elements to null.

Returns: `void`

#### doHide

`void doHide ( )`
Sets the timeout for the auto-dismiss delay, which by default is 5 seconds, meaning that a tooltip will automatically dismiss itself after 5 seconds of being displayed.

Returns: `void`

#### doShow

`Number doShow ( e , context )`
Processes the showing of the Tooltip by setting the timeout delay and offset of the Tooltip.

Parameters:
  `e <DOMEvent>` The current DOM event
  `context <HTMLElement>` The current context element

Returns: `Number`
  The process ID of the timeout function associated with doShow

#### forceUnderlayRedraw

`void forceUnderlayRedraw ( )`
Forces the underlay element to be repainted, through the application/removal of a yui-force-redraw class to the underlay element.

Returns: `void`

#### init

`void init ( el , userConfig )`
The Tooltip initialization method. This method is automatically called by the constructor. A Tooltip is automatically rendered by the init method, and it also is set to be invisible by default, and constrained to viewport by default as well.

Parameters:
  `el <String>` The element ID representing the Tooltip OR
  `el <HTMLElement>` The element representing the Tooltip
  `userConfig <Object>` The configuration object literal containing the configuration that should be set for this Tooltip. See configuration documentation for more details.

Returns: `void`

#### initDefaultConfig

`void initDefaultConfig ( )`
Initializes the class's configurable properties which can be changed using the Overlay's Config object (cfg).

Returns: `void`

#### initEvents

`void initEvents ( )`
Initializes the custom events for Tooltip

Returns: `void`

#### onContextMouseMove

`void onContextMouseMove ( e , obj )`
The default event handler fired when the user moves the mouse while over the context element.

Parameters:
  `e <DOMEvent>` The current DOM event
  `obj <Object>` The object argument

Returns: `void`

#### onContextMouseOut

`void onContextMouseOut ( e , obj )`
The default event handler fired when the user mouses out of the context element.

Parameters:
  `e <DOMEvent>` The current DOM event
  `obj <Object>` The object argument

Returns: `void`

#### onContextMouseOver

`void onContextMouseOver ( e , obj )`
The default event handler fired when the user mouses over the context element.

Parameters:
  `e <DOMEvent>` The current DOM event
  `obj <Object>` The object argument

Returns: `void`

#### onRender

`void onRender ( p_sType , p_aArgs )`
"render" event handler for the Tooltip.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.

Returns: `void`

#### preventOverlay

`void preventOverlay ( pageX , pageY )`
Fired when the Tooltip is moved, this event handler is used to prevent the Tooltip from overlapping with its context element.

Parameters:
  `pageX <Number>` The x coordinate position of the mouse pointer
  `pageY <Number>` The y coordinate position of the mouse pointer

Returns: `void`

#### toString

`String toString ( )`
Returns a string representation of the object.

Returns: `String`
  The string representation of the Tooltip

#### Methods inherited from YAHOO.widget.Module:

`_addToParent, _initResizeMonitor, _renderBody, _renderFooter, _renderHeader, _supportsCWResize, appendToBody, appendToFooter, appendToHeader, configMonitorResize, configVisible, destroy, hide, init, initDefaultConfig, initEvents, initResizeMonitor, onDomResize, render, setBody, setFooter, setHeader, show, toString`

#### Methods inherited from YAHOO.widget.Overlay:

`_alignOnTrigger, _autoFillOnHeightChange, _findTriggerCE, _getComputedHeight, _getConstrainedPos, _getPreciseHeight, _preventOverlap, _primeXYFromDOM, _processTriggers, _setDomVisibility, _validateAutoFillHeight, align, bringToTop, center, configAutoFillHeight, configConstrainToViewport, configContext, configFixedCenter, configHeight, configIframe, configVisible, configWidth, configX, configXY, configY, configzIndex, destroy, doCenterOnDOMEvent, enforceConstraints, fillHeight, fitsInViewport, forceContainerRedraw, getConstrainedX, getConstrainedXY, getConstrainedY, hideIframe, hideMacGeckoScrollbars, init, initDefaultConfig, initEvents, moveTo, onDomResize, showIframe, showMacGeckoScrollbars, stackIframe, syncIframe, syncPosition, toString`

### Events

#### contextMouseOutEvent

`contextMouseOutEvent ( context , e )`
CustomEvent fired when the user mouses out of a context element.

Parameters:
  `context <HTMLElement>` The context element which the user just moused out of
  `e <DOMEvent>` The DOM event object, associated with the mouse out

#### contextMouseOverEvent

`contextMouseOverEvent ( context , e )`
CustomEvent fired when user mouses over a context element. Returning false from a subscriber to this event will prevent the tooltip from being displayed for the current context element.

Parameters:
  `context <HTMLElement>` The context element which the user just moused over
  `e <DOMEvent>` The DOM event object, associated with the mouse over

#### contextTriggerEvent

`contextTriggerEvent ( context )`
CustomEvent fired just before the tooltip is displayed for the current context.

You can subscribe to this event if you need to set up the text for the tooltip based on the context element for which it is about to be displayed.

This event differs from the beforeShow event in following respects:

1. When moving from one context element to another, if the tooltip is not hidden (the `hidedelay` is not reached), the beforeShow and Show events will not be fired when the tooltip is displayed for the new context since it is already visible. However the contextTrigger event is always fired before displaying the tooltip for a new context.
2. The trigger event provides access to the context element, allowing you to set the text of the tooltip based on context element for which the tooltip is triggered.

It is not possible to prevent the tooltip from being displayed using this event. You can use the contextMouseOverEvent if you need to prevent the tooltip from being displayed.

Parameters:
  `context <HTMLElement>` The context element for which the tooltip is triggered

#### Events inherited from YAHOO.widget.Module:

`appendEvent, beforeHideEvent, beforeInitEvent, beforeRenderEvent, beforeShowEvent, changeBodyEvent, changeContentEvent, changeFooterEvent, changeHeaderEvent, destroyEvent, hideEvent, initEvent renderEvent showEvent YAHOO.widget.Module.textResizeEvent`

#### Events inherited from YAHOO.widget.Overlay:

`beforeMoveEvent, moveEvent, YAHOO.widget.Overlay.windowResizeEvent, YAHOO.widget.Overlay.windowScrollEvent,`

### Configuration Attributes

#### autodismissdelay `- Number`

The number of milliseconds to wait before automatically dismissing a Tooltip after the mouse has been resting on the context element.
Default Value: 5000

#### container `- HTMLElement/String`

Specifies the container element that the Tooltip's markup should be rendered into.
Default Value: document.body

#### context `- HTMLElement[]/String[]`

Specifies the element or elements that the Tooltip should be anchored to on mouseover.
Default Value: null

#### disabled `- Boolean`

Specifies whether or not the tooltip is disabled. Disabled tooltips will not be displayed. If the tooltip is driven by the title attribute of the context element, the title attribute will still be removed for disabled tooltips, to prevent default tooltip behavior.
Default Value: false

#### hidedelay `- Number`

The number of milliseconds to wait before hiding a Tooltip after mouseout.
Default Value: 250

#### preventoverlap `- Boolean`

Specifies whether the Tooltip should be kept from overlapping its context element.
Default Value: true

#### showdelay `- Number`

The number of milliseconds to wait before showing a Tooltip on mouseover.
Default Value: 200

#### text `- String`

Specifies the Tooltip's text.
Default Value: null

#### width `- String`

String representing the width of the Tooltip. Please note: As of version 2.3 if either no value or a value of "auto" is specified, and the Toolip's "container" configuration property is set to something other than `document.body` or its "context" element resides outside the immediately visible portion of the document, the width of the Tooltip will be calculated based on the offsetWidth of its root HTML and set just before it is made visible. The original value will be restored when the Tooltip is hidden. This ensures the Tooltip is rendered at a usable width. For more information see YUILibrary bug #1685496 and YUILibrary bug #1735423.
Default Value: null

#### xyoffset `- Array`

Specifies the XY offset from the mouse position, where the tooltip should be displayed, specified as a 2 element array (e.g. [10, 20]);
Default Value: [0, 25]

#### Configuration attributes inherited from YAHOO.widget.Module:

`appendtodocumentbody, effect, monitorresize, visible,`

#### Configuration attributes inherited from YAHOO.widget.Overlay:

`autofillheight, constraintoviewport, context, fixedcenter, height, iframe, preventcontextoverlap, width, x, xy, y, zIndex,`

Copyright © 2009 Yahoo! Inc. All rights reserved.