diff --git a/docs/api/events.html b/docs/api/events.html index be0d005bd1f..b9e20046dc6 100644 --- a/docs/api/events.html +++ b/docs/api/events.html @@ -28,12 +28,12 @@
jQuery Mobile offers several custom events that build upon native events to create useful hooks for development. Note that these events employ various touch, mouse, and window events, depending on event existence, so you can bind to them for use in both handheld and desktop environments. You can bind to these events like you would with other jQuery events, using live()
or bind()
.
pageInit()
, not $(document).ready()
$(document).bind('pageinit')
, not $(document).ready()
The first thing you learn in jQuery is to call code inside the $(document).ready()
function so everything will execute as soon as the DOM is loaded. However, in jQuery Mobile, Ajax is used to load the contents of each page into the DOM as you navigate, and the DOM ready handler only executes for the first page. To execute code whenever a new page is loaded and created, you can bind to the pageinit
event. This event is explained in detail at the bottom of this page.
pageCreate()
vs pageInit()
$(document).bind('pagecreate')
vs $(document).bind('pageinit')
Prior to Beta 2 the recommendation to users wishing to manipulate jQuery Mobile enhanced page and child widget markup was to bind to the pagecreate
event. In Beta 2 an internal change was made to decouple each of the widgets by binding to the pagecreate
event in place of direct calls to the widget methods. As a result, users binding to the pagecreate
in mobileinit
would find their binding executing before the markup had been enhanced by each of the plugins. In keeping with the lifecycle of the jQuery UI Widget Factory, the initialization method is invoked after the create method, so the pageinit
event provides the correct timing for post enhancement manipulation of the DOM and/or Javascript objects.
In short, if you were previously using pagecreate
to manipulate the enhanced markup before the page was shown, it's very likely you'll want to migrate to 'pageinit'.
@@ -63,7 +63,7 @@
swiperight
We provide a set of "virtual" mouse events that attempt to abstract away mouse and touch events. This allows the developer to register listeners for the basic mouse events, such as mousedown, mousemove, mouseup, and click, and the plugin will take care of registering the correct listeners behind the scenes to invoke the listener at the fastest possible time for that device. In touch environments, the plugin retains the order of event firing that is seen in traditional mouse environments, so for example, vmouseup is always dispatched before vmousedown, and vmousedown before vclick, etc. The virtual mouse events also normalize how coordinate information is extracted from the event, so in touch based environments, coordinates are available from the pageX, pageY, screenX, screenY, clientX, and clientY properties, directly on the event object.
Applications can call preventDefault()
on a vclick
event to cancel an element's default click behavior. On mouse based devices, calling preventDefault()
on a vclick
event equates to calling preventDefault()
on the real click
event during the bubble event phase. On touch based devices, it's a bit more complicated since the actual click
event is dispatched about 300ms after the vclick
event is dispatched. For touch devices, calling preventDefault()
on a vclick
event triggers some code in the vmouse plugin that attempts to catch the next click
event that gets dispatched by the browser, during the capture event phase, and calls preventDefault()
and stopPropagation()
on it. As mentioned in the warning above, it is sometimes difficult to match up a touch event with its corresponding mouse event because the targets can differ. For this reason, the vmouse plugin also falls back to attempting to identify a corresponding click
event by coordinates. There are still cases where both target and coordinate identification fail, which results in the click
event being dispatched and either triggering the default action of the element, or in the case where content has been shifted or replaced, triggering a click on a different element. If this happens on a regular basis for a given element/control, we suggest you use click
for triggering your action.
orientationchange
jQuery Mobile exposes the animationComplete
plugin, which you can utilize after adding or removing a class that applies a CSS transition.