-
Notifications
You must be signed in to change notification settings - Fork 469
Events
The events object determines the initial event handlers which are bound to the tooltip.
The API triggers several special events (detailed below) that allow you to bind multiple event handlers to a single qTip and react to certain events. For example, we can bind an event handler that will detect when the tooltip is moved, and update a div element with the tooltip coordinates:
$('.selector').qtip({
content: 'When I move I update coordinates on the page!',
events: {
move: function(event, api) {
$('#coords').text( event.pageX + '/' + event.pageY );
}
}
});That's great! Simple and easy to integrate. However, what if we need want to not only to update the coordinates, but integrate say, another plugin with the qTip? One that might be in a different file and hard to call within our existing move callback?
$('.selector').qtip({
content: 'When I move I update coordinates on the page!',
events: {
/*
* Since your qTip will likely have prerender set to false, we'll bind within the render event
* so we're certain the tooltip is actually rendered before binding our handlers.
*/
render: function(event, api) {
// Grab the tooltip element from the API elements object
var tooltip = api.elements.tooltip;
// Notice the 'tooltip' prefix of the event name!
tooltip.bind('tooltipmove', function(event, api) {
// Update our other plugin and pass our event object
anotherPlugin.update(event);
});
},
// Regular old move option still applies
move: function(event, api) {
$('#coords').text( event.pageX + '/' + event.pageY );
}
}
});Awesome! Binding multiple events is just as simple, and can be used on all the events listed below. Just make sure to prepend your event name with tooltip when binding events manually.
As is the case with regular events in JavaScript, you can use the event.preventDefault(); to prevent the default event from occurring. For example, within a show event it will stop the tooltip from showing:
$('.selector').qtip({
content: 'I wont show because one of my show event handlers returns false!',
show: 'mousedown',
events: {
show: function(event, api) {
event.preventDefault(); // Stop it!
}
}
});This can be handy if you need some conditional logic that determines if the tooltip should show or not. Also be aware that any of the event handlers can stop the default action, not just the first one bound.
All of the events below are passed an event object as their first argument. Within this event object is another object called originalEvent. This contains the event that triggered the callback, and can be used for special event detection, such as right-clicks:
$('.selector').qtip({
content: 'Right-click to open me!',
show: 'mousedown',
events: {
show: function(event, api) {
// Only show the tooltip if it was a right-click
if(event.originalEvent.button !== 2) {
event.preventDefault();
}
}
}
});Fired when the tooltip is rendered
$('.selector').qtip({
content: {
text: 'My tooltip content'
},
events: {
render: function(event, api) {
$('.cartTotal').triggerHandler('update');
}
}
});Update another element e.g. a cart total, when this tooltip is rendered
- The rendering process cannot be interrupted using the event.preventDefault() described above.
- This event is triggered only once during the lifetime of a single qTip.
Fired when the tooltip is shown either by the library itself, or by the user calling the appropriate toggle or show API methods.
Lets hide another element whenever this tooltip is shown
$('.selector').qtip({
content: {
text: 'I hide another element when shown...'
},
events: {
show: function(event, api) {
$('.hideMe').hide();
}
}
});- Using event.preventDefault() described above, will prevent the tooltip from showing.
Fired when the tooltip is hidden either by the library itself, or by the user calling the appropriate toggle or hide API methods.
Lets show another element whenever this tooltip is hidden
$('.selector').qtip({
content: {
text: 'I cause another element to show when Im hidden...'
},
events: {
hide: function(event, api) {
$('.showMe').show();
}
}
});- Using event.preventDefault() described above, will prevent the tooltip from hiding.
Fired when the tooltip is toggled i.e. shown or hidden, by the user calling the appropriate toggle or hide API methods. This is a shortcut method for binding to both tooltipshow and tooltiphide events above.
We can utilise this hide & show shortcut to implement addition/removal of particular properties like classes without duplicating code:
$('.selector').qtip({
content: {
text: 'I toggle a class on my target element when shown or hidden!'
},
events: {
toggle: function(event, api) {
api.elements.target.toggleClass(event.type === 'tooltipshow');
}
}
});- There is no tooltiptoggle event! This is a shortcut for binding to both tooltipshow and tooltiphide.
- Using event.preventDefault() described above, will prevent the tooltip from showing/hiding, depending on the event type being triggered.
Fired when the tooltip becomes visible i.e. immediately after the show.effect has finished and the qTip is visible and has dimensions. This is most useful for plugins and code which requires the tooltip to have layout, that is to be visible and have dimensions, if it is to function correctly.
Because this event is fired after the tooltip is already shown, the event.preventDefault() call will do nothing within this event, since it is already shown when this event is triggered.
Let's output the dimensions of tooltip once it becomes visible:
$('.selector').qtip({
content: {
text: 'I hide another element when shown...'
},
events: {
visible: function(event, api) {
$('.selector').hide();
}
}
});- This is distinct from the show event since it is fired after the show animation is complete, not before.
- Because of the above, the event.preventDefault() call will do nothing within this event, since it is already shown when this event is triggered
Fired when the tooltip becomes hidden i.e. immediately after the hide.effect has finished, the qTip is hidden (display:none). This is most useful for plugins and code which requires the tooltip to be completely hidden, if it is to function correctly.
Because this event is fired after the tooltip is already hidden, the event.preventDefault() call will do nothing within this event, since it is already hidden when this event is triggered.
Let's output the dimensions of tooltip once it becomes hidden:
$('.selector').qtip({
content: {
text: 'I show another element when hidden...'
},
events: {
hidden: function(event, api) {
$('.selector').show();
}
}
});- This is distinct from the hide event since it is fired after the hide animation is complete, not before.
- Because of the above, the event.preventDefault() call will do nothing within this event, since it is already shown when this event is triggered.
Fired when the tooltip is repositioned, either by the library itself, or when the user calls the reposition API method.
Let's update another qTips position, whose position target is actually inside this tooltip.
$('.selector').qtip({
content: {
text: 'When I move, I update all qTips who are positioned in relation to me!'
},
events: {
move: function(event, api) {
// For more information on the API object, check-out the API documentation
api.elements.content.find('.hasTooltip').qtip('update');
}
}
});- Using event.preventDefault() described above, will prevent the tooltips position from being updated.
Fired when the tooltip is focused i.e. most recently displayed or moused over, either by the library itself or the focus API method.
Lets create a qTip whose colour is changed when focused.
$('.selector').qtip({
content: {
text: 'When I gain focus over the other qTips, my colour changes!'
},
events: {
focus: function(event, api) {
// For more information on the API object, check-out the API documentation
api.elements.tooltip.toggleClass('qtip-blue qtip-cream');
}
}
});- Using event.preventDefault() described above, will prevent the tooltip from becoming focused.
Fired when the tooltip loses focus i.e. another tooltip becomes focused (see above) by the library itself or the focus API method.
Lets create another qTip whose colour is changed when it loses focus, similar to the example above.
$('.selector').qtip({
content: {
text: 'When I lose focus to another qTip, my colour changes!'
},
events: {
blur: function(event, api) {
// For more information on the API object, check-out the API documentation
api.elements.tooltip.toggleClass('qtip-blue qtip-cream');
}
}
});- The blurring process cannot be prevented using the event.preventDefault() described above.