Hello! My name's , I'm using qTip at http:// and I think it's !

Note: Points will be deducted for bad grammar and spelling... and sentences that make no sense!

Documentation

 

Checkout some tutorials »

API

Introduction

The API (Application Programming Interface) allows you to interface with your qTip's, updating options on-the-fly, and extending its capabilities via built-in methods. In this section we'll cover the use of the API and it's methods, as well as some details how on how it works on a per-qTip basis.

Back to the top

Accessing the API

Gaining access to the API itself is very easy, and its done via the tooltip element itself. Let's take a look at a quick example: 

var api = $('.qtip').qtip('api'); // Access the API of the first tooltip on the page

NB: This is where the id option really shines. If you need access to the API of a specific qTip give it a unique id and reference it via the #ui-tooltip-<id> selector instead! 

var api = $('#ui-tooltip-foo').qtip('api'); // Access the API of the qTip with an id of 'foo'

Now we have a reference to this particular tooltips API, we gain access to several methods and properties we can use to manipulate the tooltip element, listed below:

Back to the top

API storage

The API for a tooltip is held in two places: the $.data object of the original target element and the tooltip element itself, under the name qtip. These for example, are functionally equivalent ways of grabbing the API of a qTip: 

var api = $('.selector').data('qtip'); // Access the API of an element with a qTip applied
var api = $('.qtip').data('qtip'); // Access the API of the first tooltip on the page

NB: The preferred way of gaining access to the API of an element is detailed above. Please do not use this method.

Now we know where the API data is stored for a particular tooltip, its possible to use some hackery and allow multiple tooltips per element, though this isn't recommended and could cause problems. But check-out the tutorial if you're feeling edgey!

Back to the top

API Properties

– #
"String"

id

Description

Stores the id option passed when the qTip was created. If none was passed, an integer will be used.

Getter/setter

$('.selector').qtip('option', 'id'); // Getter
$('.selector').qtip('option', 'id', 'newValue'); // Setter
– #
true, false

rendered:false

Description

A read-only boolean flag which indicates the current state of the qTip i.e. whether or not it's been rendered yet (show event has been triggered at-least once).

– #
true, false

destroyed:false

Description

A read-only boolean flag which indicates the whether or not the destroy method has been called i.e. whether or not the tooltip has been destroyed.

– #
Object

elements:{…}

Description

An object containing references to all currently rendered elements of the qTip, including the target, tooltip, wrapper, title and content elements.

Elements

api.elements = {
	target: $(element), // Element used for the qTip call i.e. $(element).qtip({...})
 
	tooltip: $('<div />'), // Main tooltip element that encapsulates:
		wrapper: $('<div />'), // Wrapper element encapsulates all the below (except the tip)
			content: $('<div />'), // Content element which your content.text is appended to
 
		/* When content.title is set... */
		titlebar: $('<div />'), // Titlebar which encapsulates:
			title: $('<div />'), // Title element which your content.title.text is appended to
			button: $('<div />'), // Button element containing your content.text.button
 
		// Tips plugin - element that contains the canvas/vml/polygon tip
		tip: $('<div />'), 
 
		// Modal plugin - Translucent window overlay element
		overlay: $('<div id="qtip-overlay" />'),
 
		// BGIFrame plugin - IFrame element used for IE6 z-index fix
		bgiframe: $('<div />') 
}
– #
Object

timers:{…}

Description

An object containing all currently running timers related to show and hide delays.

Properties

api.timers = {
	show: timerObject, // Contains the object returned by the show setTimeout()
	hide: timerObject // Contains the object returned by the hide setTimeout()
}

Uses

  • Can use clearTimeout to stop any running show/hide delays, preventing tooltip state change
– #
Object

options:{…}

Description

Object containing all options passed upon initialisation, sanitized and merged with the $.fn.qtip.defaults object.

Properties

api.options = {
	prerender: false,
	id: false,
	overwrite: true,
	metadata: {
		type: 'class'
	},
	content: {
		text: true,
		attr: 'title',
		title: {
			text: false,
			button: false
		}
	},
	position: {
		my: 'top left',
		at: 'bottom right',
		target: false,
		container: false,
		viewport: false,
		adjust: {
			x: 0, y: 0,
			mouse: true,
			method: 'flip',
			resize: true
		},
		effect: true
	},
	show: {
		target: false,
		event: 'mouseenter',
		effect: true,
		delay: 90,
		solo: false,
		ready: false,
		modal: {
			on: false,
			effect: true,
			blur: true,
			keyboard: true
		}
	},
	hide: {
		target: false,
		event: 'mouseleave',
		effect: true,
		delay: 0,
		fixed: false,
		inactive: false,
		leave: 'window',
		distance: false
	},
	style: {
		classes: '',
		widget: false,
		tip: {
			corner: true,
			mimic: false,
			method: true,
			width: 9,
			height: 9,
			border: 0,
			offset: 0
		}
	},
	events: {
		render: null,
		move: null,
		show: null,
		hide: null,
		toggle: null,
		focus: null,
		blur: null
	}
};

Warning

  • See the Overriding defaults tutorial.
  • Do not use this object to update a qTip's options! Use the api.set() method instead!
– #
Object

plugins:{…}

Description

Object containing references to all currently initialised plugin API's. You shouldn't really need to use this, as it's only for internal storage purposes.

API Methods

– #
"String"

.get( option )

Description

Gets the current value of the specified option (represented in dot notation).

Example

$('.selector').qtip('option', 'content.text'); // Preferred
$('.selector').qtip('api').get('content.text'); // Direct API method
– #
"String", "String" or Object

.set( option, value )

Description

Sets the value of the specified option (represented in dot notation) and updates all of the qTip's relevant properties. An object may also be used to set multiple options at once.

Example

Set an individual option of a qTip: 
$('.selector').qtip('option', 'content.text', 'new content'); // Preferred
$('.selector').qtip('api').set('content.text', 'new content'); // Direct API method
We can also use object notation to set multiple options simultaneously: 
// Preferred
$('.selector').qtip('option', {
	'content.title.text': 'New Title',
	'style.widget': true
});
 
// Direct API method
$('.selector').qtip('api').set({
	'content.title.text': 'New Title',
	'style.widget': true
});
– #
Boolean, Event

.toggle( [ state, event ] )

Description

Toggles the current visibility of the qTip. If state is passed as true, it will show the qTip, and vice-versa. If no state argument is passed, the current visibility will determine whether it hides or shows.

The event argument is optional, and if passed will be used for things such as mouse positioning, if enabled.

Example

// Will "toggle" the visiblitiy of the tooltip i.e. hiding it if current visible, or vise-versa.
$('.selector').qtip('toggle');
 
$('.selector').qtip('toggle', true); // Shows the tooltip
$('.selector').qtip('toggle', false); // Hides the tooltip
 
// Shows the tooltip and passes on an event object i.e. from within an event handler.
$('.selector').qtip('toggle', true, event); 
 
// Direct API call
$('.selector').qtip('api').toggle(true);

Fires

tooltipshow tooltiphide
 
– #
Event

.show( [ event ] )

Description

Shows the qTip. Is a shortcut method to the toggle method above. The event argument is optional, and if passed will be used for things such as mouse positioning, if enabled.

Example

// Show the tooltip
$('.selector').qtip('show');
 
// Shows the tooltip and passes on an event object i.e. from within an event handler.
$('.selector').qtip('show', event);
 
// Direct API call
$('.selector').qtip('api').show();

Fires

tooltipshow

Notes

 
– #
Event

.hide( [ event ] )

Description

Hides the qTip. Is a shortcut method to the toggle method above. The event argument is optional, and if passed will be used for things such as mouse positioning, if enabled.

Example

// Hide the tooltip
$('.selector').qtip('hide');
 
// Hides the tooltip and passes on an event object i.e. from within an event handler.
$('.selector').qtip('hide', event);
 
// Direct API call
$('.selector').qtip('api').hide();

Fires

tooltiphide

Notes

 
– #
Boolean

.disable( [ state ] )

Description

Toggles the current interactive state of the qTip (whether it's disabled or not) i.e. if it responds to user events. If no state argument is passed, the current state of the qTip will determine its new state e.g. if currently disabled, it will be enabled and vise-versa.

Example

// These are equivalent to:
$('.selector').qtip('disable');
$('.selector').qtip('enable');
 
// ...these and...
$('.selector').qtip('disable', true);
$('.selector').qtip('disable', false);
 
// ...these. (Direct API calls)
$('.selector').qtip('api').disable(true); // Disables the tooltip
$('.selector').qtip('api').disable(false); // Enables the tooltip
 
// Can also use the direct call to 'toggle'
$('.selector').qtip('api').disable(); // Toggle functionality

Notes

  • When disabled, the qtip will no longer respond to any user events.
– #
Event

.reposition( [ event ] )

Description

Updates the qTip's position relative to the position.target element. The event argument is optional, and if passed will be used for things such as mouse positioning, if enabled.

Example

// Preferred method
$('.selector').qtip('reposition');
 
// Updates the tooltips position and passes on an event object i.e. from within an event handler.
$('.selector').qtip('reposition', event);
 
// Direct API call
$('.selector').qtip('api').reposition();

Fires

tooltipmove

Notes

  • If you are using adjust.mouse functionality and calling this method manually, try to make sure you pass an event object, otherwise the positioning may momentarily glitch.
 
– #
Event

.focus( [ event ] )

Description

Focuses the qTip i.e. moves it above all others in the z-index stack. This is the functional equivalent to focusing a window on your desktop, raising it above all others whilst preserving the stacking order. The event argument is optional, and is passed to the fired events via the event.originalEvent attribute when called.

Example

// Preferred method
$('.selector').qtip('focus');
 
// Focuses the tooltip and passes on an event object to any bound focus handlers.
$('.selector').qtip('focus', event);
 
// Direct API call
$('.selector').qtip('api').focus();

Fires

tooltipfocus tooltipblur

Toggles

  • This function triggers a tooltipblur event on all other tooltips on the page when called.
 
– #
Event

.blur( [ event ] )

Description

Blurs the qTip i.e. removes the focus class and triggers the 'tooltipblur' event. The event argument is optional, and is passed to the fired events via the event.originalEvent attribute when called.

Example

// Preferred method
$('.selector').qtip('blur');
 
// Blurs the tooltip and passes on an event object to any bound blur handlers.
$('.selector').qtip('blur', event);
 
// Direct API call
$('.selector').qtip('api').blur();

Fires

tooltipblur

Toggles

  • This method is triggered on every tooltip on the page when a tooltip is focused (except the one being focused).
 
– #

.destroy( )

Description

Completely removes the qTip from the page, including all related event handlers and rendered DOM elements.

Example

$('.selector').qtip('destroy'); // Preferred method
 
$('.selector').qtip('api').destroy(); // Direct API call

Toggles

  • This method is automatically called when an element with a qTip applied is remove via .remove().
 
– #

.render( )

Description

Immediately renders the tooltip when called. Useful when no hide/show events have been applied to manually cause tooltip rendering.

Example

$('.selector').qtip('render'); // Preferred method
 
$('.selector').qtip('api').render(); // Direct API call

Toggles

  • The use-cases for this function are quite edgy, so you shouldn't really need to use this much.