api.jquery.com/entries/bind.xml at ad18d2123753e55ad8f238efe1a3cfe0a7c391b8 · esx/api.jquery.com · 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
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
<?xml version="1.0"?>
<entry type="method" name="bind" return="jQuery">
  <title>.bind()</title>
  <signature>
    <added>1.0</added>
    <argument name="eventType" type="String">
      <desc>A string containing one or more DOM event types, such as "click" or "submit," or custom event names.</desc>
    </argument>
    <argument name="eventData" type="Object" optional="true">
      <desc>An object containing data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventType" type="String">
      <desc>A string containing one or more DOM event types, such as "click" or "submit," or custom event names.</desc>
    </argument>
    <argument name="eventData" type="Object" optional="true">
      <desc>An object containing data that will be passed to the event handler.</desc>
    </argument>
    <argument name="preventBubble" type="Boolean">
      <desc>Setting the third argument to false will attach a function that prevents the default action from occurring and stops the event from bubbling. The default is true.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="events" type="Object">
      <desc>An object containing one or more DOM event types and functions to execute for them.</desc>
    </argument>
  </signature>
  <desc>Attach a handler to an event for the elements.</desc>
  <longdesc>
    <p>As of jQuery 1.7, the <a href="http://api.jquery.com/on"><code>.on()</code></a> method is the preferred method for attaching event handlers to a document. For earlier versions, the <code>.bind()</code> method is used for attaching an event handler directly to elements. Handlers are attached to the currently selected elements in the jQuery object, so those elements <em>must exist</em> at the point the call to <code>.bind()</code> occurs. For more flexible event binding, see the discussion of event delegation in <a href="http://api.jquery.com/on"><code>.on()</code></a> or <a href="http://api.jquery.com/delegate"><code>.delegate()</code></a>.</p>
    <p>Any string is legal for <code>eventType</code>; if the string is not the name of a native DOM event, then the handler is bound to a custom event. These events are never called by the browser, but may be triggered manually from other JavaScript code using <code>.trigger()</code> or <code>.triggerHandler()</code>.</p>
    <p>If the <code>eventType</code> string contains a period (<code>.</code>) character, then the event is namespaced. The period character separates the event from its namespace. For example, in the call <code>.bind( "click.name", handler )</code>, the string <code>click</code> is the event type, and the string <code>name</code> is the namespace. Namespacing allows us to unbind or trigger some events of a type without affecting others. See the discussion of <code>.unbind()</code> for more information.</p>
    <p>There are shorthand methods for some standard browser events such as <a href="/click"><code>.click()</code></a> that can be used to attach or trigger event handlers. For a complete list of shorthand methods, see the <a href="http://api.jquery.com/category/events/">events category</a>.</p>
    <p>When an event reaches an element, all handlers bound to that event type for the element are fired. If there are multiple handlers registered, they will always execute in the order in which they were bound. After all handlers have executed, the event continues along the normal event propagation path.</p>
    <p>A basic usage of <code>.bind()</code> is:</p>
    <pre><code>
$( "#foo" ).bind( "click", function() {
  alert( "User clicked on 'foo.'" );
});
    </code></pre>
    <p>This code will cause the element with an ID of <code>foo</code> to respond to the <code>click</code> event. When a user clicks inside this element thereafter, the alert will be shown.</p>
    <h4 id="multiple-events">Multiple Events</h4>
    <p>Multiple event types can be bound at once by including each one separated by a space:</p>
    <pre><code>
$( "#foo" ).bind( "mouseenter mouseleave", function() {
  $( this ).toggleClass( "entered" );
});
    </code></pre>
    <p>The effect of this on <code>&lt;div id="foo"&gt;</code> (when it does not initially have the "entered" class) is to add the "entered" class when the mouse enters the <code>&lt;div&gt;</code> and remove the class when the mouse leaves. </p>
    <p>As of jQuery 1.4 we can bind multiple event handlers simultaneously by passing an object of event type/handler pairs:</p>
    <pre><code>
$( "#foo" ).bind({
  click: function() {
    // Do something on click
  },
  mouseenter: function() {
    // Do something on mouseenter
  }
});
    </code></pre>
    <h4 id="event-handlers">Event Handlers</h4>
    <p>The <code>handler</code> parameter takes a callback function, as shown above. Within the handler, the keyword <code>this</code> refers to the DOM element to which the handler is bound. To make use of the element in jQuery, it can be passed to the normal <code>$()</code> function. For example:</p>
    <pre><code>
$( "#foo" ).bind( "click", function() {
  alert( $( this ).text() );
});
    </code></pre>
    <p>After this code is executed, when the user clicks inside the element with an ID of <code>foo</code>, its text contents will be shown as an alert.
    </p>
    <p>As of jQuery 1.4.2 duplicate event handlers can be bound to an element instead of being discarded. This is useful when the event data feature is being used, or when other unique data resides in a closure around the event handler function.</p>
    <p>In jQuery 1.4.3 you can now pass in <code>false</code> in place of an event handler. This will bind an event handler equivalent to: <code>function(){ return false; }</code>. This function can be removed at a later time by calling: <code>.unbind( eventName, false )</code>.</p>
    <h4 id="event-object">
      <a href="http://api.jquery.com/category/events/event-object/">The Event object</a>
    </h4>
    <p>The <code>handler</code> callback function can also take parameters. When the function is called, the event object will be passed to the first parameter.</p>
    <p>The event object is often unnecessary and the parameter omitted, as sufficient context is usually available when the handler is bound to know exactly what needs to be done when the handler is triggered. However, at times it becomes necessary to gather more information about the user's environment at the time the event was initiated. <a href="http://api.jquery.com/category/events/event-object/">View the full Event Object</a>.</p>
    <p>Returning <code>false</code> from a handler is equivalent to calling both <code>.preventDefault()</code> and <code>.stopPropagation()</code> on the event object.</p>
    <p>Using the event object in a handler looks like this:</p>
    <pre><code>
$( document ).ready(function() {
  $( "#foo" ).bind( "click", function( event ) {
    alert( "The mouse cursor is at (" +
      event.pageX + ", " + event.pageY +
      ")" );
  });
});
    </code></pre>
    <p>Note the parameter added to the anonymous function. This code will cause a click on the element with ID <code>foo</code> to report the page coordinates of the mouse cursor at the time of the click.</p>
    <h4 id="passing-event-data">Passing Event Data</h4>
    <p>The optional <code>eventData</code> parameter is not commonly used. When provided, this argument allows us to pass additional information to the handler. One handy use of this parameter is to work around issues caused by closures. For example, suppose we have two event handlers that both refer to the same external variable:</p>
    <pre><code>
var message = "Spoon!";
$( "#foo" ).bind( "click", function() {
  alert( message );
});
message = "Not in the face!";
$( "#bar" ).bind( "click", function() {
  alert( message );
});
    </code></pre>
    <p>Because the handlers are closures that both have <code>message</code> in their environment, both will display the message <samp>Not in the face!</samp> when triggered. The variable's value has changed. To sidestep this, we can pass the message in using <code>eventData</code>:
    </p>
    <pre><code>
var message = "Spoon!";
$( "#foo" ).bind( "click", {
  msg: message
}, function( event ) {
  alert( event.data.msg );
});
message = "Not in the face!";
$( "#bar" ).bind( "click", {
  msg: message
}, function( event ) {
  alert( event.data.msg );
});
    </code></pre>
    <p>This time the variable is not referred to directly within the handlers; instead, the variable is passed in <em>by value</em> through <code>eventData</code>, which fixes the value at the time the event is bound. The first handler will now display <samp>Spoon!</samp> while the second will alert <samp>Not in the face!</samp>
    </p>
    <div class="warning">
      <p>Note that objects are passed to functions <em>by reference</em>, which further complicates this scenario.</p>
    </div>
    <p>If <code>eventData</code> is present, it is the second argument to the <code>.bind()</code> method; if no additional data needs to be sent to the handler, then the callback is passed as the second and final argument.</p>
    <div class="warning">
      <p>See the <code>.trigger()</code> method reference for a way to pass data to a handler at the time the event happens rather than when the handler is bound.</p>
    </div>
    <p>As of jQuery 1.4 we can no longer attach data (and thus, events) to object, embed, or applet elements because critical errors occur when attaching data to Java applets.</p>
    <p><strong>Note: </strong>Although demonstrated in the next example, it is inadvisable to bind handlers to both the <code>click</code> and <code>dblclick</code> events for the same element. The sequence of events triggered varies from browser to browser, with some receiving two click events
8000
 before the <code>dblclick</code> and others only one. Double-click sensitivity (maximum time between clicks that is detected as a double click) can vary by operating system and browser, and is often user-configurable.</p>
  </longdesc>
  <example>
    <desc>Handle click and double-click for the paragraph.  Note: the coordinates are window relative, so in this case relative to the demo iframe.</desc>
    <code><![CDATA[
$( "p" ).bind( "click", function( event ) {
  var str = "( " + event.pageX + ", " + event.pageY + " )";
  $( "span" ).text( "Click happened! " + str );
});
$( "p" ).bind( "dblclick", function() {
  $( "span" ).text( "Double-click happened in " + this.nodeName );
});
$( "p" ).bind( "mouseenter mouseleave", function( event ) {
  $( this ).toggleClass( "over" );
});
]]></code>
    <css><![CDATA[
  p {
    background: yellow;
    font-weight: bold;
    cursor: pointer;
    padding: 5px;
  }
  p.over {
     background: #ccc;
  }
  span {
    color: red;
  }
]]></css>
    <html><![CDATA[
<p>Click or double click here.</p>
<span></span>
]]></html>
  </example>
  <example>
    <desc>To display each paragraph's text in an alert box whenever it is clicked:</desc>
    <code><![CDATA[
$( "p" ).bind( "click", function() {
  alert( $( this ).text() );
});
]]></code>
  </example>
  <example>
    <desc>You can pass some extra data before the event handler:</desc>
    <code><![CDATA[
function handler( event ) {
  alert( event.data.foo );
}
$( "p" ).bind( "click", {
  foo: "bar"
}, handler );
]]></code>
  </example>
  <example>
    <desc>Cancel a default action and prevent it from bubbling up by returning <code>false</code>:</desc>
    <code><![CDATA[
$( "form" ).bind( "submit", function() {
  return false;
})
]]></code>
  </example>
  <example>
    <desc>Cancel only the default action by using the .preventDefault() method.</desc>
    <code><![CDATA[
$( "form" ).bind( "submit", function( event ) {
  event.preventDefault();
});
]]></code>
  </example>
  <example>
    <desc>Stop an event from bubbling without preventing the default action by using the .stopPropagation() method.</desc>
    <code><![CDATA[
$( "form" ).bind( "submit", function( event ) {
  event.stopPropagation();
});
]]></code>
  </example>
  <example>
    <desc>Bind custom events.</desc>
    <code><![CDATA[
$( "p" ).bind( "myCustomEvent", function( e, myName, myValue ) {
  $( this ).text( myName + ", hi there!" );
  $( "span" )
    .stop()
    .css( "opacity", 1 )
    .text( "myName = " + myName )
    .fadeIn( 30 )
    .fadeOut( 1000 );
  });
$( "button" ).click(function() {
  $( "p" ).trigger( "myCustomEvent", [ "John" ] );
});
]]></code>
    <css><![CDATA[
  p {
    color: red;
  }
  span {
    color: blue;
  }
  ]]></css>
    <html><![CDATA[
<p>Has an attached custom event.</p>
<button>Trigger custom event</button>
<span style="display: none;"></span>
]]></html>
  </example>
  <example>
    <desc>Bind multiple events simultaneously.</desc>
    <code><![CDATA[
$( "div.test" ).bind({
  click: function() {
    $( this ).addClass( "active" );
  },
  mouseenter: function() {
    $( this ).addClass( "inside" );
  },
  mouseleave: function() {
    $( this ).removeClass( "inside" );
  }
});
]]></code>
  </example>
  <category slug="events/event-handler-attachment"/>
  <category slug="version/1.0"/>
  <category slug="version/1.4"/>
  <category slug="version/1.4.3"/>
</entry>