jquery-mobile/docs/api/events.html at transitions · jnlin/jquery-mobile · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8" />
	<title>jQuery Mobile Docs - Events</title>
	<link rel="stylesheet"  href="../../themes/default/" />
	<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
	<script type="text/javascript" src="../../js/jquery.js"></script>
	<script type="text/javascript" src="../../js/"></script>
</head>
<body>

<div data-role="page">

	<div data-role="header">
		<h1>Events</h1>
	</div><!-- /header -->

	<div data-role="content">


		<p>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 <code>live()</code> or <code>bind()</code>.</p>

		<h2>Touch events</h2>
		<dl>
			<dt><code>tap</code></dt>
			<dd>Triggers after a quick, complete touch event.</dd>

			<dt><code>taphold</code></dt>
			<dd>Triggers after a held complete touch event (close to one second).</dd>

			<dt><code>swipe</code></dt>
			<dd>Triggers when a horizontal drag of 30px or more (and less than 20px vertically) occurs within 1 second duration.</dd>

			<dt><code>swipeleft</code></dt>
			<dd>Triggers when a swipe event occurred moving in the left direction.</dd>

			<dt><code>swiperight</code></dt>
			<dd>Triggers when a swipe event occurred moving in the right direction.</dd>
			</dl>
		<h2>Orientation change event</h2>
		<dl>
			<dt><code>orientationchange</code></dt>
			<dd>Triggers when a device orientation changes (by turning it vertically or horizontally). When bound to this event, your callback function can leverage a second argument, which contains an <code>orientation</code> property equal to either "portrait" or "landscape". These values are also added as classes to the HTML element, allowing you to leverage them in your CSS selectors. Note that we currently bind to the resize event when orientationChange is not natively supported.</dd>
		</dl>

		<h2>Scroll events</h2>
		<dl>
			<dt><code>scrollstart</code></dt>
			<dd>Triggers when a scroll begins. Note that iOS devices freeze DOM manipulation during scroll, queuing them to apply when the scroll finishes. We're currently investigating ways to allow DOM manipulations to apply before a scroll starts.</dd>
		</dl>
		<dl>
			<dt><code>scrollstop</code></dt>
			<dd>Triggers when a scroll finishes.</dd>
		</dl>

		<h2>Page show/hide events</h2>
		<p>Whenever a page is shown or hidden in jQuery Mobile, two events are triggered on that page. The events triggered depend on whether that page is being shown or hidden, so when a page transition occurs, there are actually 4 events triggered: 2 for each page. </p>
		<dl>
			<dt><code>pagebeforeshow</code></dt>
			<dd>Triggered on the page being shown, before its transition begins.</dd>

			<dt><code>pagebeforehide</code></dt>
			<dd>Triggered on the page being hidden, before its transition begins.</dd>

			<dt><code>pageshow</code></dt>
			<dd>Triggered on the page being shown, after its transition completes.</dd>

			<dt><code>pagehide</code></dt>
			<dd>Triggered on the page being hidden, after its transition completes.</dd>

		</dl>

		<p>Note that all four of these events expose a reference to either the next page (<code>nextPage</code>) or previous page (<code>prevPage</code>), depending on whether the page is being shown or hidden, and whether that next or previous page exists (the first ever page shown does not have a previous page to reference, but an empty jQuery object is provided just the same). You can access this reference via the second argument of a bound callback function. For example: </p>
		<pre>
		<code>
$('div').live('pageshow',function(event, ui){
  alert('This page was just hidden: '+ ui.prevPage);
});

$('div').live('pagehide',function(event, ui){
  alert('This page was just shown: '+ ui.nextPage);
});
		</code>
		</pre>
		<p>Also, for these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes.  This can be done in the <code>mobileinit</code> handler, as described on the <a href="globalconfig.html">global config</a> page.
		<h2>Page initialization events</h2>

		<p>Internally, jQuery Mobile auto-initializes plugins based on the markup conventions found in a given "page". For example, an <code>input</code> element with a <code>type</code> of <code>range</code> will automatically generate a custom slider control.</p>

		<p>This auto-initialization is controlled by the "page" plugin, which dispatches events before and after it executes, allowing you to manipulate a page either pre-or-post initialization, or even provide your own intialization behavior and prevent the auto-initializations from occuring. Note that these events will only fire once per "page", as opposed to the show/hide events, which fire every time a page is shown and hidden.</p>

		<dl>
			<dt><code>pagebeforecreate</code></dt>
			<dd>Triggered on the page being initialized, before initialization occurs.</dd>
			<dt><code>pagecreate</code></dt>
			<dd>Triggered on the page being initialized, after initialization occurs.</dd>
		</dl>


				<pre>
		<code>
$('#aboutPage').live('pagebeforecreate',function(event){
  alert('This page was just inserted into the dom!');
});

$('#aboutPage').live('pagecreate',function(event){
  alert('This page was just enhanced by jQuery Mobile!');
});
		</code>
		</pre>

		<p>Note that by binding to <code>pagebeforecreate</code> and returning <code>false</code>, you can prevent the page plugin from making its manipulations.</p>

<pre>
		<code>
$('#aboutPage').live('pagebeforecreate',function(event){
  //run your own enhancement scripting here...
  return false;
});

		</code>
		</pre>

		<div class="ui-body ui-body-e">
			<p><strong>Note on Page IDs in Alpha 2 release (<em>no longer an issue</em>): </strong> In jQuery Mobile Alpha 2 and older, page elements utilized the <code>ID</code> attribute for storing the location from which they came. When you place an <code>ID</code> attribute on a page that is brought into jQuery Mobile's single-page environment through Ajax, jQuery Mobile wraps that page with a new "page" <code>div</code> element, preserving any CSS references to your <code>ID</code>. However, this means that your <code>ID</code> attribute is no longer on the "page" element, so you must keep this in mind when binding to page events (<code>pagebeforecreate</code>, <code>pagecreate</code>, etc). To avoid issues, try using a class if possible. </p>
		</div>


		<h2>Animation Events</h2>
		<p>jQuery Mobile exposes the <code>animationComplete</code> plugin, which you can utilize after adding or removing a class that applies a CSS transition.</p>

    </div><!-- /content -->

</div><!-- /page -->

</body>
</html>