Skip to content

Commit e37b0fd

Browse files
mgolmgol
committed
All: Deprecate change & select
1 parent d80a4f9 commit e37b0fd

File tree

4 files changed

+154
-55
lines changed

4 files changed

+154
-55
lines changed

‎entries/change-shorthand.xml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="change" return="jQuery" deprecated="3.3">
3+
<title>.change()</title>
4+
<desc>Bind an event handler to the "change" event, or trigger that event on an element.</desc>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>A function to execute each time the event is triggered.</desc>
9+
<argument name="eventObject" type="Event" />
10+
</argument>
11+
</signature>
12+
<signature>
13+
<added>1.4.3</added>
14+
<argument name="eventData" type="Anything" optional="true">
15+
<desc>An object containing data that will be passed to the event handler.</desc>
16+
</argument>
17+
<argument name="handler" type="Function">
18+
<desc>A function to execute each time the event is triggered.</desc>
19+
<argument name="eventObject" type="Event" />
20+
</argument>
21+
</signature>
22+
<signature>
23+
<added>1.0</added>
24+
</signature>
25+
<longdesc>
26+
<div class="warning">
27+
<p>This API is deprecated.</p>
28+
<p>Instead of <code>.change( handler )</code> or <code>.change( eventData, handler )</code>, use <a href="/change/#on1"><code>.on( "change", handler )</code></a> or <a href="/change/#on1"><code>.on( "change", eventData, handler )</code></a>, respectively.</p>
29+
<p>Instead of <code>.change()</code>, use <a href="/change/#trigger2"><code>.trigger( "change" )</code></a>.</p>
30+
</div>
31+
</longdesc>
32+
<category slug="events/form-events"/>
33+
<category slug="version/1.0"/>
34+
<category slug="version/1.4.3"/>
35+
<category slug="deprecated/deprecated-3.3"/>
36+
</entry>

‎entries/change.xml

Lines changed: 43 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,15 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="change" return="jQuery">
3-
<title>.change()</title>
4-
<desc>Bind an event handler to the "change" event, or trigger that event on an element.</desc>
2+
<entries>
3+
<desc>Bind an event handler to the "change" event, or trigger that event on an element.</desc>
4+
5+
<entry type="method" name="on" return="jQuery">
6+
<title>change event</title>
7+
<desc>Bind an event handler to the "change" event.</desc>
58
<signature>
6-
<added>1.0</added>
7-
<argument name="handler" type="Function">
8-
<desc>A function to execute each time the event is triggered.</desc>
9-
<argument name="eventObject" type="Event" />
9+
<added>1.7</added>
10+
<argument name="&quot;change&quot;" type="string">
11+
<desc>The string <code>"change"</code>.</desc>
1012
</argument>
11-
</signature>
12-
<signature>
13-
<added>1.4.3</added>
1413
<argument name="eventData" type="Anything" optional="true">
1514
<desc>An object containing data that will be passed to the event handler.</desc>
1615
</argument>
@@ -19,11 +18,7 @@
1918
<argument name="eventObject" type="Event" />
2019
</argument>
2120
</signature>
22-
<signature>
23-
<added>1.0</added>
24-
</signature>
2521
<longdesc>
26-
<p>This method is a shortcut for <code>.on( "change", handler )</code> in the first two variations, and <code>.trigger( "change" )</code> in the third.</p>
2722
<p>The <code>change</code> event is sent to an element when its value changes. This event is limited to <code>&lt;input&gt;</code> elements, <code>&lt;textarea&gt;</code> boxes and <code>&lt;select&gt;</code> elements. For select boxes, checkboxes, and radio buttons, the event is fired immediately when the user makes a selection with the mouse, but for the other element types the event is deferred until the element loses focus.</p>
2823
<p>For example, consider the HTML:</p>
2924
<pre><code>
@@ -40,34 +35,34 @@
4035
</code></pre>
4136
<p>The event handler can be bound to the text input and the select box:</p>
4237
<pre><code>
43-
$( ".target" ).change(function() {
44-
alert( "Handler for .change() called." );
45-
});
38+
$( ".target" ).on( "change", function() {
39+
alert( "Handler for `change` called." );
40+
} );
4641
</code></pre>
47-
<p>Now when the second option is selected from the dropdown, the alert is displayed. It is also displayed if you change the text in the field and then click away. If the field loses focus without the contents having changed, though, the event is not triggered. To trigger the event manually, apply <code>.change()</code> without arguments:</p>
42+
<p>Now when the second option is selected from the dropdown, the alert is displayed. It is also displayed if you change the text in the field and then click away. If the field loses focus without the contents having changed, though, the event is not triggered. To trigger the event manually, use <code>.trigger( "change" )</code>:</p>
4843
<pre><code>
49-
$( "#other" ).click(function() {
50-
$( ".target" ).change();
51-
});
44+
$( "#other" ).on( "click", function() {
45+
$( ".target" ).trigger( "change" );
46+
} );
5247
</code></pre>
5348
<p>After this code executes, clicks on <samp>Trigger the handler</samp> will also alert the message. The message will display twice, because the handler has been bound to the <code>change</code> event on both of the form elements.</p>
5449
<p>As of jQuery 1.4, the <code>change</code> event bubbles in Internet Explorer, behaving consistently with the event in other modern browsers.</p>
5550
<div class="warning">
56-
<p><strong>Note: </strong>Changing the value of an input element using JavaScript, using <a href="/val"><code>.val()</code></a> for example, won't fire the event.</p>
51+
<p><strong>Note: </strong>Changing the value of an input element using JavaScript, using <a href="/val"><code>.val()</code></a> for example, won't fire the event.</p>
5752
</div>
5853
</longdesc>
5954
<example>
6055
<desc>Attaches a change event to the select that gets the text for each selected option and writes them in the div. It then triggers the event for the initial text draw.</desc>
6156
<code><![CDATA[
6257
$( "select" )
63-
.change(function () {
58+
.on( "change", function() {
6459
var str = "";
65-
$( "select option:selected" ).each(function() {
60+
$( "select option:selected" ).each( function() {
6661
str += $( this ).text() + " ";
67-
});
62+
} );
6863
$( "div" ).text( str );
69-
})
70-
.change();
64+
} )
65+
.trigger( "change" );
7166
]]></code>
7267
<css><![CDATA[
7368
div {
@@ -89,13 +84,31 @@ $( "select" )
8984
<example>
9085
<desc>To add a validity test to all text input elements:</desc>
9186
<code><![CDATA[
92-
$( "input[type='text']" ).change(function() {
87+
$( "input[type='text']" ).on( "change", function() {
9388
// Check input( $( this ).val() ) for validity here
94-
});
89+
} );
9590
]]></code>
9691
</example>
9792
<category slug="events/form-events"/>
9893
<category slug="forms"/>
9994
<category slug="version/1.0"/>
100-
<category slug="version/1.4.3"/>
95+
<category slug="version/1.7"/>
96+
</entry>
97+
98+
<entry type="method" name="trigger" return="jQuery">
99+
<title>change event</title>
100+
<desc>Trigger the "change" event on an element.</desc>
101+
<signature>
102+
<added>1.0</added>
103+
<argument name="&quot;change&quot;" type="string">
104+
<desc>The string <code>"change"</code>.</desc>
105+
</argument>
106+
</signature>
107+
<longdesc>
108+
<p>See the description for <a href="#on1"><code>.on( "change", ... )</code></a>.</p>
109+
</longdesc>
110+
<category slug="events/form-events"/>
111+
<category slug="version/1.0"/>
101112
</entry>
113+
114+
</entries>

‎entries/select-shorthand.xml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="select" return="jQuery" deprecated="3.3">
3+
<title>.select()</title>
4+
<desc>Bind an event handler to the "select" event, or trigger that event on an element.</desc>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>A function to execute each time the event is triggered.</desc>
9+
<argument name="eventObject" type="Event" />
10+
</argument>
11+
</signature>
12+
<signature>
13+
<added>1.4.3</added>
14+
<argument name="eventData" type="Anything" optional="true">
15+
<desc>An object containing data that will be passed to the event handler.</desc>
16+
</argument>
17+
<argument name="handler" type="Function">
18+
<desc>A function to execute each time the event is triggered.</desc>
19+
<argument name="eventObject" type="Event" />
20+
</argument>
21+
</signature>
22+
<signature>
23+
<added>1.0</added>
24+
</signature>
25+
<longdesc>
26+
<div class="warning">
27+
<p>This API is deprecated.</p>
28+
<p>Instead of <code>.select( handler )</code> or <code>.select( eventData, handler )</code>, use <a href="/select/#on1"><code>.on( "select", handler )</code></a> or <a href="/select/#on1"><code>.on( "select", eventData, handler )</code></a>, respectively.</p>
29+
<p>Instead of <code>.select()</code>, use <a href="/select/#trigger2"><code>.trigger( "select" )</code></a>.</p>
30+
</div>
31+
</longdesc>
32+
<category slug="events/form-events"/>
33+
<category slug="version/1.0"/>
34+
<category slug="version/1.4.3"/>
35+
<category slug="deprecated/deprecated-3.3"/>
36+
</entry>

‎entries/select.xml

Lines changed: 39 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,15 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="select" return="jQuery">
3-
<title>.select()</title>
4-
<desc>Bind an event handler to the "select" event, or trigger that event on an element.</desc>
2+
<entries>
3+
<desc>Bind an event handler to the "select" event, or trigger that event on an element.</desc>
4+
5+
<entry type="method" name="on" return="jQuery">
6+
<title>select event</title>
7+
<desc>Bind an event handler to the "select" event.</desc>
58
<signature>
6-
<added>1.0</added>
7-
<argument name="handler" type="Function">
8-
<desc>A function to execute each time the event is triggered.</desc>
9-
<argument name="eventObject" type="Event" />
9+
<added>1.7</added>
10+
<argument name="&quot;select&quot;" type="string">
11+
<desc>The string <code>"select"</code>.</desc>
1012
</argument>
11-
</signature>
12-
<signature>
13-
<added>1.4.3</added>
1413
<argument name="eventData" type="Anything" optional="true">
1514
<desc>An object containing data that will be passed to the event handler.</desc>
1615
</argument>
@@ -19,9 +18,6 @@
1918
<argument name="eventObject" type="Event" />
2019
</argument>
2120
</signature>
22-
<signature>
23-
<added>1.0</added>
24-
</signature>
2521
<longdesc>
2622
<p>This method is a shortcut for <code>.on( "select", handler )</code> in the first two variations, and <code>.trigger( "select" )</code> in the third.</p>
2723
<p>The <code>select</code> event is sent to an element when the user makes a text selection inside it. This event is limited to <code>&lt;input type="text"&gt;</code> fields and <code>&lt;textarea&gt;</code> boxes.</p>
@@ -35,19 +31,19 @@
3531
&lt;/div&gt;</code></pre>
3632
<p>The event handler can be bound to the text input:</p>
3733
<pre><code>
38-
$( "#target" ).select(function() {
39-
alert( "Handler for .select() called." );
40-
});
34+
$( "#target" ).on( "select", function() {
35+
alert( "Handler for `select` called." );
36+
} );
4137
</code></pre>
42-
<p>Now when any portion of the text is selected, the alert is displayed. Merely setting the location of the insertion point will not trigger the event. To trigger the event manually, apply <code>.select()</code> without an argument:</p>
38+
<p>Now when any portion of the text is selected, the alert is displayed. Merely setting the location of the insertion point will not trigger the event. To trigger the event manually, use <code>.trigger( "select" )</code>:</p>
4339
<pre><code>
44-
$( "#other").click(function() {
45-
$( "#target" ).select();
46-
});
40+
$( "#other").on( "click", function() {
41+
$( "#target" ).trigger( "select" );
42+
} );
4743
</code></pre>
4844
<p>After this code executes, clicks on the Trigger button will also alert the message:</p>
4945
<p>
50-
<samp>Handler for .select() called.</samp>
46+
<samp>Handler for `select` called.</samp>
5147
</p>
5248
<p>In addition, the default <code>select</code> action on the field will be fired, so the entire text field will be selected.</p>
5349
<div class="warning">
@@ -57,9 +53,9 @@ $( "#other").click(function() {
5753
<example>
5854
<desc>To do something when text in input boxes is selected:</desc>
5955
<code><![CDATA[
60-
$( ":input" ).select(function() {
56+
$( ":input" ).on( "select", function() {
6157
$( "div" ).text( "Something was selected" ).show().fadeOut( 1000 );
62-
});
58+
} );
6359
]]></code>
6460
<css><![CDATA[
6561
p {
@@ -79,11 +75,29 @@ $( ":input" ).select(function() {
7975
<example>
8076
<desc>To trigger the select event on all input elements, try:</desc>
8177
<code><![CDATA[
82-
$( "input" ).select();
78+
$( "input" ).trigger( "select" );
8379
]]></code>
8480
</example>
8581
<category slug="events/form-events"/>
8682
<category slug="forms"/>
8783
<category slug="version/1.0"/>
88-
<category slug="version/1.4.3"/>
84+
<category slug="version/1.7"/>
85+
</entry>
86+
87+
<entry type="method" name="trigger" return="jQuery">
88+
<title>select event</title>
89+
<desc>Trigger the "select" event on an element.</desc>
90+
<signature>
91+
<added>1.0</added>
92+
<argument name="&quot;select&quot;" type="string">
93+
<desc>The string <code>"select"</code>.</desc>
94+
</argument>
95+
</signature>
96+
<longdesc>
97+
<p>See the description for <a href="#on1"><code>.on( "select", ... )</code></a>.</p>
98+
</longdesc>
99+
<category slug="events/form-events"/>
100+
<category slug="version/1.0"/>
89101
</entry>
102+
103+
</entries>

0 commit comments

Comments
 (0)