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
144
145
146
147
148
149
150
151
152
153
154
155
156
|
<!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">.unbind()</h1>
<div class="entry-meta jq-clearfix">
Categories:
<span class="category"><a href="http://api.jquery.com/category/events/" title="View all posts in Events">Events</a> > <a href="http://api.jquery.com/category/events/event-handler-attachment/" title="View all posts in Event Handler Attachment">Event Handler Attachment</a></span>
</div>
</div>
<div id="unbind1" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">.unbind( [eventType] [, handler(eventObject)] )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#jQuery">jQuery</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong>Remove a previously-attached event handler from the elements.</p>
<ul class="signatures">
<li class="signature" id="unbind-eventType-handlereventObject">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>.unbind( [eventType] [, handler(eventObject)] )</h4>
<p class="arguement"><strong>eventType</strong>A string containing a JavaScript event type, such as <code>click</code> or <code>submit</code>.</p>
<p class="arguement"><strong>handler(eventObject)</strong>The function that is to be no longer executed.</p>
</li>
<li class="signature" id="unbind-eventType-false">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.4.3/">1.4.3</a></span>.unbind( eventType, false )</h4>
<p class="arguement"><strong>eventType</strong>A string containing a JavaScript event type, such as <code>click</code> or <code>submit</code>.</p>
<p class="arguement"><strong>false</strong>Unbinds the corresponding 'return false' function that was bound using <code>.bind( eventType, false )</code>.</p>
</li>
<li class="signature" id="unbind-event">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>.unbind( event )</h4>
<p class="arguement"><strong>event</strong>A JavaScript event object as passed to an event handler.</p>
</li>
</ul>
<div class="longdesc">
<p>Event handlers attached with <code>.bind()</code> can be removed with <code>.unbind()</code>. (As of jQuery 1.7, the <a href="http://api.jquery.com/on"><code>.on()</code></a> and <a href="http://api.jquery.com/off"><code>.off()</code></a> methods are preferred to attach and remove event handlers on elements.) In the simplest case, with no arguments, <code>.unbind()</code> removes all handlers attached to the elements:</p>
<pre>$('#foo').unbind();</pre>
<p>This version removes the handlers regardless of type. To be more precise, we can pass an event type:</p>
<pre>$('#foo').unbind('click');</pre>
<p>By specifying the <code>click</code> event type, only handlers for that event type will be unbound. This approach can still have negative ramifications if other scripts might be attaching behaviors to the same element, however. Robust and extensible applications typically demand the two-argument version for this reason:</p>
<pre>var handler = function() {
alert('The quick brown fox jumps over the lazy dog.');
};
$('#foo').bind('click', handler);
$('#foo').unbind('click', handler);
</pre>
<p>By naming the handler, we can be assured that no other functions are accidentally removed. Note that the following will <em>not</em> work:</p>
<pre>$('#foo').bind('click', function() {
alert('The quick brown fox jumps over the lazy dog.');
});
// will NOT work
$('#foo').unbind('click', function() {
alert('The quick brown fox jumps over the lazy dog.');
});</pre>
<p>Even though the two functions are identical in content, they are created separately and so JavaScript is free to keep them as distinct function objects. To unbind a particular handler, we need a reference to that function and not a different one that happens to do the same thing.</p>
<blockquote><p><strong>Note:</strong> Using a proxied function to unbind an event on an element will unbind all proxied functions on that element, as the same proxy function is used for all proxied events. To allow unbinding a specific event, use unique class names on the event (e.g. <code>click.proxy1</code>, <code>click.proxy2</code>) when attaching them.</p></blockquote>
<h4>Using Namespaces</h4>
<p>Instead of maintaining references to handlers in order to unbind them, we can namespace the events and use this capability to narrow the scope of our unbinding actions. As shown in the discussion for the <code>.bind()</code> method, namespaces are defined by using a period (<code>.</code>) character when binding a handler:</p>
<pre>$('#foo').bind('click.myEvents', handler);</pre>
<p>When a handler is bound in this fashion, we can still unbind it the normal way:</p>
<pre>$('#foo').unbind('click');</pre>
<p>However, if we want to avoid affecting other handlers, we can be more specific:</p>
<pre>$('#foo').unbind('click.myEvents');</pre>
<p>We can also unbind all of the handlers in a namespace, regardless of event type:</p>
<pre>$('#foo').unbind('.myEvents');</pre>
<p>It is particularly useful to attach namespaces to event bindings when we are developing plug-ins or otherwise writing code that may interact with other event-handling code in the future.</p>
<h4>Using the Event Object</h4>
<p>The third form of the <code>.unbind()</code> method is used when we wish to unbind a handler from within itself. For example, suppose we wish to trigger an event handler only three times:</p>
<pre>var timesClicked = 0;
$('#foo').bind('click', function(event) {
alert('The quick brown fox jumps over the lazy dog.');
timesClicked++;
if (timesClicked >= 3) {
$(this).unbind(event);
}
});
</pre>
<p>The handler in this case must take a parameter, so that we can capture the event object and use it to unbind the handler after the third click. The event object contains the context necessary for <code>.unbind()</code> to know which handler to remove.
This example is also an illustration of a closure. Since the handler refers to the <code>timesClicked</code> variable, which is defined outside the function, incrementing the variable has an effect even between invocations of the handler.</p>
</div>
<h3>Examples:</h3>
<div class="entry-examples" id="entry-examples">
<div id="example-0">
<h4>Example: <span class="desc">Can bind and unbind events to the colored button.</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<style>
button { margin:5px; }
button#theone { color:red; background:yellow; }
</style>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<button id="theone">Does nothing...</button>
<button id="bind">Bind Click</button>
<button id="unbind">Unbind Click</button>
<div style="display:none;">Click!</div>
<script>
function aClick() {
$("div").show().fadeOut("slow");
}
$("#bind").click(function () {
// could use .bind('click', aClick) instead but for variety...
$("#theone").click(aClick)
.text("Can Click!");
});
$("#unbind").click(function () {
$("#theone").unbind('click', aClick)
.text("Does nothing...");
});
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
<div id="example-1">
<h4>Example: <span class="desc">To unbind all events from all paragraphs, write:</span>
</h4>
<pre class="prettyprint"><code class="example">$("p").unbind()</code></pre>
</div>
<div id="example-2">
<h4>Example: <span class="desc">To unbind all click events from all paragraphs, write:</span>
</h4>
<pre class="prettyprint"><code class="example">$("p").unbind( "click" )</code></pre>
</div>
<div id="example-3">
<h4>Example: <span class="desc">To unbind just one previously bound handler, pass the function in as the second argument:</span>
</h4>
<pre class="prettyprint"><code class="example">var foo = function () {
// code to handle some kind of event
};
$("p").bind("click", foo); // ... now foo will be called when paragraphs are clicked ...
$("p").unbind("click", foo); // ... foo will no longer be called.</code></pre>
</div>
</div>
</div>
</div>
</div>
</body></html>
|
