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
139
140
141
142
143
|
<!DOCTYPE html>
<html lang='en'><head><meta http-equiv='content-type' content='text/html; charset=UTF-8' /></head><body>
<div class="entry-content">
<div class="entry-title roundTop">
<h1 class="jq-clearfix">.promise()</h1>
<div class="entry-meta jq-clearfix">
Categories:
<span class="category"><a href="http://api.jquery.com/category/deferred-object/" title="View all posts in Deferred Object">Deferred Object</a></span>
</div>
</div>
<div id="promise1" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">.promise( [type] [, target] )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#Promise">Promise</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong> Return a Promise object to observe when all actions of a certain type bound to the collection, queued or not, have finished. </p>
<ul class="signatures"><li class="signature" id="promise-type-target">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.6/">1.6</a></span>.promise( [type] [, target] )</h4>
<p class="arguement"><strong>type</strong> The type of queue that needs to be observed. </p>
<p class="arguement"><strong>target</strong>Object onto which the promise methods have to be attached</p>
</li></ul>
<div class="longdesc">
<p>The <code>.promise()</code> method returns a dynamically generated Promise that is resolved once all actions of a certain type bound to the collection, queued or not, have ended.</p>
<p> By default, <code>type</code> is <code>"fx"</code>, which means the returned Promise is resolved when all animations of the selected elements have completed.</p>
<p> Resolve context and sole argument is the collection onto which <code>.promise()</code> has been called. </p>
<p> If <code>target</code> is provided, <code>.promise()</code> will attach the methods onto it and then return this object rather than create a new one. This can be useful to attach the Promise behavior to an object that already exists.</p>
<blockquote><p><strong>Note: </strong>The returned Promise is linked to a Deferred object stored on the <code>.data()</code> for an element. Since the <code>.remove()</code> method removes the element's data as well as the element itself, it will prevent any of the element's unresolved Promises from resolving. If it is necessary to remove an element from the DOM before its Promise is resolved, use <code>.detach()</code> instead and follow with <code>.removeData()</code> after resolution.</p></blockquote>
</div>
<h3>Examples:</h3>
<div class="entry-examples" id="entry-examples">
<div id="example-0">
<h4>Example: <span class="desc">Using .promise() on a collection with no active animation returns a resolved Promise:</span>
</h4>
<pre class="prettyprint"><code class="example">
var div = $( "<div />" );
div.promise().done(function( arg1 ) {
// will fire right away and alert "true"
alert( this === div && arg1 === div );
});
</code></pre>
</div>
<div id="example-1">
<h4>Example: <span class="desc">Resolve the returned Promise when all animations have ended (including those initiated in the animation callback or added later on):</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<style>
div {
height: 50px; width: 50px;
float: left; margin-right: 10px;
display: none; background-color: #090;
}
</style>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<button>Go</button>
<p>Ready...</p>
<div></div>
<div></div>
<div></div>
<div></div>
<script>
$("button").bind( "click", function() {
$("p").append( "Started...");
$("div").each(function( i ) {
$( this ).fadeIn().fadeOut( 1000 * (i+1) );
});
$( "div" ).promise().done(function() {
$( "p" ).append( " Finished! " );
});
});
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
<div id="example-2">
<h4>Example: <span class="desc">Resolve the returned Promise using a $.when() statement (the .promise() method makes it possible to do this with jQuery collections):</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<style>
div {
height: 50px; width: 50px;
float: left; margin-right: 10px;
display: none; background-color: #090;
}
</style>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<button>Go</button>
<p>Ready...</p>
<div></div>
<div></div>
<div></div>
<div></div>
<script>
var effect = function() {
return $("div").fadeIn(800).delay(1200).fadeOut();
};
$("button").bind( "click", function() {
$("p").append( " Started... ");
$.when( effect() ).done(function() {
$("p").append(" Finished! ");
});
});
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
</div>
</div>
</div>
</div>
</body></html>
|
