Events - Appendices - Web Development with jQuery (2015)

Web Development with jQuery (2015)

Part IV. Appendices

Appendix D. Events

The following table contains all the event methods supported by jQuery as listed in jQuery's official documentation at www.jquery.com.

All the event methods return the jQuery object.

Method

Description

Page Load

ready(function)
function(event)

Attaches a function that is executed when the DOM is completely loaded; that is, all markup, CSS, and JavaScript are loaded, but not necessarily images.

Event Handling

bind(events, function)
string events
function(event)

Attaches a function that is executed when the event occurs. Multiple events can be specified in the event argument; if you specify multiple events, each event must be separated with a single space.
The on() method is preferred over bind() in jQuery 1.7 or later.

bind(events[, data][,function])
string events
object data
function(event)

The bind() method accepts an optional data argument. The data argument is an object that allows you to pass custom data to the event, which is available in the event handler, in the event argument as event.data.
The on() method is preferred over bind() in jQuery 1.7 or later.

bind(events[, data][, preventBubble])
string events
object data
boolean preventBubble

When calling the bind() method with the preventBubble argument, an event handler is automatically created, which prevents bubbling, as well as the default action.

bind(eventName, false);

or

bind(eventName);

is equivalent to creating the following:

bind(

eventName,

function(event)

{

event.preventDefault();

event.stopPropagation();

}

);

The on() method is preferred over bind() in jQuery 1.7 or later.

bind(events)
object events

Allows multiple events to be bound by passing an object where the property is the name of the event and the value is the callback function. For example:

bind({

click : function(event)

{

},

mouseover : function(event)

{

},

mouseout : function(event)

{

}

})


The on() method is preferred over bind() in jQuery 1.7 or later.

delegate(selector, events, function)
string selector
string events
function(event)

Provides the same functionality as the on() method in jQuery 1.4.2 and later. The on() method is preferred over delegate() in jQuery 1.7 or later.

delegate(selector, events, data, function)
string selector
string events
object data
function(event)

Provides the same functionality as the on() method in jQuery 1.4.2 and later. The on() method is preferred over delegate() in jQuery 1.7 or later.

delegate(selector, events)
string selector
string events

Provides the same functionality as the on() method in jQuery 1.4.2 and later. The on() method is preferred over delegate() in jQuery 1.7 or later.

off(events[, selector][, function])
string events
string selector
function(event)

Removes an event handler.

off(events[, selector])
string events
string selector

Removes an event handler.

off()

Removes all event handlers.

on(events[, selector][, data], function)
string events
string selector
object data
function(event)

Attaches an event handler for the selected elements; the elements referenced in the selection must exist at the time on() is called.
If a selector is provided in the second argument, descendant element(s) referenced by the selector will be the element(s) receiving the event(s), rather than the original selection. Elements referenced by the selector may or may not exist when on() is called. If new descendant elements matching the selector are created after the attachment of the event(s), those element(s) automatically receive the event(s) when they exist.
Custom data can be passed in the data argument;, if custom data is provided, it will be available in the event handler, in the event argument, as event.data.

on(events[, selector][, data])
string events
string selector
object data

Attaches an event handler for the selected elements; the elements referenced in the selection must exist at the time on() is called.
If a selector is provided in the second argument, descendant element(s) referenced by the selector will be the element(s) receiving the event(s), rather than the original selection. Elements referenced by the selector may or may not exist when on() is called. If new descendant elements matching the selector are created after the attachment of the event(s), those element(s) automatically receive the event(s) when they exist.
Custom data can be passed in the data argument; if custom data is provided it will be available in the event handler, in the event argument, as event.data.

one(events, function)
string events
function(event)

Attaches a function to be fired for the specified event. The function is executed only once. Subsequent events will not execute the specified function.

one(events[, data], function)
string events
object data
function(event)

The one() method accepts an optional data argument. The data argument is an object that is passed to the event object of the attached function as event.data.

one(events[, selector][,data], function)
string events
string selector
object data
function(event)

Attaches an event handler that is always executed just once per element and event.
If a selector is provided in the second argument, descendant element(s) referenced by the selector will be the element(s) receiving the event(s), rather than the original selection. Elements referenced by the selector may or may not exist when one() is called. If new descendant elements matching the selector are created after the attachment of the event(s), those element(s) automatically receive the event(s) when they exist.
Custom data can be passed in the data argument; if custom data is provided, it will be available in the event handler, in the event argument, as event.data.

trigger(events)
string events

Triggers the specified event on matched elements.

trigger(events, parameters)
string events
array parameters

The trigger() method accepts an optional data argument. The data argument is an object that is passed to event object functions being triggered as event.data.

triggerHandler(events)
string events

Triggers the specified event on matched elements while canceling the browser's default action for any given event.

triggerHandler(events, parameters)
string events
array parameters

The triggerHandler() method accepts an optional data argument. The data argument is an object that is passed to event object functions being triggered as event.data.

unbind()

Removes all events from the selected element(s).

unbind(events)
string events

Removes the specified event from the selected element(s).

unbind(events, function)
string events
function(event)

Removes by event and event handler.

unbind(events, false)
string events

Removes the specified events.

undelegate()

Provides the same functionality as the off() method in jQuery 1.4.2 and later. The off() method is preferred over undelegate() in jQuery 1.7 or later.

undelegate(selector, events)
string selector
string events

Provides the same functionality as the off() method in jQuery 1.4.2 and later. The off() method is preferred over undelegate() in jQuery 1.7 or later.

undelegate(selector, events, function)
string selector
string events
function(event)

Provides the same functionality as the off() method in jQuery 1.4.2 and later. The off() method is preferred over undelegate() in jQuery 1.7 or later.

undelegate(namespace)

Provides the same functionality as the off() method in jQuery 1.4.2 and later. The off() method is preferred over undelegate() in jQuery 1.7 or later.

Event Helpers

hover(mouseoverFunction,mouseoutFunction)
mouseoverFunction(event)
mouseoutFunction(event)

Attaches a function for mouseover and a function for mouseout to the same element.

toggle(function1, function2[,function3]. . .)
function1(event)
function2(event)
function3(event)
...

Upon first click, the first function is executed; upon second click, the second function is executed; upon third click, the third function is executed, and so on. A minimum of two functions must be specified; an unlimited number of total functions may be specified.
The toggle() method was deprecated in jQuery 1.8 and removed altogether in version 1.9.

Event Methods

blur()
blur([data, ]function)

Triggers the blur event of each selected element.
Attaches a function to the blur event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

change()
change([data, ]function)

Triggers the change event of each selected element.
Attaches a function to the change event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

click()
click([data, ]function)

Triggers the click event of each selected element.
Attaches a function to the click event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

dblclick()
dblclick([data, ]function)

Triggers the dblclick (double-click) event of each selected element.
Attaches a function to the dblclick event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

error()
error([data, ]function)

Triggers the error event of each selected element.
Attaches a function to the error event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

focus()
focus([data, ]function)

Triggers the focus event of each selected element.
Attaches a function to the focus event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

focusin()
focusin([data, ]function)

Triggers the focusin event of each selected element.
Attaches an event handler to the focusin event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

focusout()
focusout([data, ]function)

Triggers the focusout event of each selected element.
Attaches an event handler to the focusout event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

keydown()
keydown([data, ]function)

With no arguments, the keydown event of each selected element is triggered.
With only a callback function, the callback function is executed upon the keydown event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

keypress()
keypress([data, ]function)

Triggers the keypress event of each selected element.
Attaches a keypress event handler to each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

keyup()
keyup([data, ]function)

Triggers the keyup event of each selected element.
Attaches a function to the keyup event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

load(function)
load([data, ]function)

Attaches a function to the load event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

mousedown()
mousedown([data, ]function)

Triggers the mousedown event of each selected element.
Attaches a function to the mousedown event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

mouseenter()
mouseenter([data, ]function)

Triggers the mouseenter event of each selected element.
Attaches a function to the mouseenter event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

mouseleave()
mouseleave([data, ]function)

Triggers the mouseleave event of each selected element.
Attaches a function to the mouseleave event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

mousemove()
mousemove([data, ]function)

Triggers the mousemove event of each selected element.
Attaches a function to the mousemove event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

mouseout()
mouseout([data, ]function)

Triggers the mouseout event of each selected element.
Attaches a function to the mouseout event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

mouseover()
mouseover([data, ]function)

Triggers the mouseover event of each selected element.
Attaches a function to the mouseover event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

mouseup()
mouseup([data, ]function)

Triggers the mouseup event of each selected element.
Attaches a function to the mouseup event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

resize()
resize([data, ]function)

Triggers the resize event of each selected element.
Attaches a function to the resize event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

scroll()
scroll([data, ]function)

Triggers the scroll event of each selected element.
Attaches a function to the scroll event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

select()
select([data, ]function)

Triggers the select event of each selected element.
Attaches a function to the select event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

submit()
submit([data, ]function)

Triggers the submit event of each selected element.
Attaches a function to the submit event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

unload()
unload([data, ]function)

Triggers the unload event of each selected element.
Attaches a function to the unload event of each selected element. Optionally, custom data can be passed if the data argument is specified, which is available in turn as event.data.

Event Object

The following table documents event methods and properties supported both by jQuery's event object provided to jQuery events and by regular JavaScript events without jQuery. You can access the regular JavaScript event object from any jQuery event object by using the event.originalEvent object. If you find a method or property listed below missing from the jQuery event object, it is likely to be found within the event.originalEvent object.

Method/Property

Description

event.altKey
boolean

Indicates whether the Option key (Mac) or Alt key (Windows) is being pressed.

event.bubbles
boolean

Indicates whether the event bubbles up through the DOM.

event.cancelable
boolean

Indicates whether the event can be canceled.

event.clientX, event.clientY
integer

Provides x, y coordinates, indicating where the mouse cursor is located relative to the window.

event.createEvent()

Creates a new event, which must be initialized by calling its init() method.

event.ctrlKey
boolean

Indicates whether the Control key is being pressed (Mac and Windows).

event.currentTarget
object

The DOM element that is presently the target of the event. Usually this refers to the same element as the this keyword.

event.data

An object passed to the function acting as an event handler. See the data argument specified for various methods under “Event Handling” in the previous table.

event.defaultPrevented
boolean

Indicates whether the event.preventDefault() method has been called.

event.detail
integer

A numeric property that indicates how many times a mouse has been clicked in the same location. Applies to the click, dblclick, mousedown, and mouseup events.

event.delegateTarget

A reference to the element the event handler is ultimately attached to.

event.eventPhase
integer

A numeric property that indicates the phase of the event execution process.

event.NONE = 0

event.CAPTURING_PHASE = 1

event.AT_TARGET = 2

event.BUBBLING_PHASE = 3

event.initKeyEvent()
type
bubbles
cancelable
view
ctrlKey
altKey
shiftKey
metaKey
keyCode
charCode

The initKeyEvent() method is used to initialize the value of an event created using document.createEvent.

event.initMouseEvent()
type
canBubble
cancelable
view
detail
screenX
screenY
clientX
clientY
ctrlKey
altKey
shiftKey
metaKey
button
relatedTarget

The initMouseEvent() method initializes the value of a mouse event when it's been created using document.createEvent.

event.initUIEvent()
type
canBubble
cancelable
view
detail

The initUIEvent() method initializes a UI event when it has been created, for example, through document.createEvent.

event.isChar
boolean

Indicates whether the event produced a keyCode.

event.isDefaultPrevented()
returns boolean

Determines whether preventDefault() was ever called on the event object.

event.isImmediatePropagationStopped()
returns boolean

Determines whether stopImmediatePropagation() was ever called on the event object.

event.isPropagationStopped()
returns boolean

Determines whether stopPropagation() was ever called on the event object.

event.keyCode
integer

The numeric offset representing which key on the keyboard is currently being pressed.

event.layerX, event.layerY
integer

Coordinates of the event relative to the current layer.

event.metaKey
boolean

Whether the Command key (Mac) or Windows key (Windows) is pressed.

event.namespace

The namespace specified when the event was triggered.

event.originalEvent

A copy of the browser's original event object, before jQuery's modifications were made to it.

event.originalTarget

The original target of the event before any retargeting.

event.pageX, event.pageY
integer

The mouse coordinates relative to the document.

event.preventDefault()

Prevents the browser's default action for a given event, for example, submitting a form or navigating to the href attribute of an <a> element.

event.relatedTarget

Finds another element involved in the event, if applicable.

event.result

The last value returned by an event handler that was triggered by this event, unless the value was undefined.

event.screenX, event.screenY
integer

Returns the horizontal coordinates of the event within the context of the entire screen.

event.shiftKey
boolean

Whether the Shift key (Mac and Windows) is pressed.

event.stopImmediatePropagation()

Prevents other attached listeners for the same event from being called.

event.stopPropagation()

Stops the propagation of an event from a child or descendent element to its parent or ancestor elements, which prevents the same event from running on the later ancestor elements.

event.target

The DOM element that triggered the event.

event.timeStamp

The difference in milliseconds between the time the browser created the event and the UNIX epoch (January 1st, 1970, 12:00:00 AM).

event.type

Provides the type of event, for example, click, mouseover, keyup, and so on.

event.view

Returns the Window object the event happened in. In nonbrowsers, this may be referred to as the AbstractView.

event.which

Returns the numeric keyCode of the key pressed, or the character code, or charCode, for an alphanumeric key that was pressed.