Skip to content

Commit db29f90

Browse files
mgolmgol
committed
All: Deprecate other event shorthands
1 parent 2537bc7 commit db29f90

10 files changed

+381
-131
lines changed

Diff for: ‎entries/contextmenu-shorthand.xml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="contextmenu" return="jQuery" deprecated="3.3">
3+
<title>.contextmenu()</title>
4+
<desc>Bind an event handler to the "contextmenu" 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>.contextmenu( handler )</code> or <code>.contextmenu( eventData, handler )</code>, use <a href="/contextmenu/#on1"><code>.on( "contextmenu", handler )</code></a> or <a href="/contextmenu/#on1"><code>.on( "contextmenu", eventData, handler )</code></a>, respectively.</p>
29+
<p>Instead of <code>.contextmenu()</code>, use <a href="/contextmenu/#trigger2"><code>.trigger( "contextmenu" )</code></a>.</p>
30+
</div>
31+
</longdesc>
32+
<category slug="events/mouse-events"/>
33+
<category slug="version/1.0"/>
34+
<category slug="version/1.4.3"/>
35+
<category slug="deprecated/deprecated-3.3"/>
36+
</entry>

Diff for: ‎entries/contextmenu.xml

+36-19
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="contextmenu" return="jQuery">
3-
<title>.contextmenu()</title>
4-
<desc>Bind an event handler to the "contextmenu" event, or trigger that event on an element.</desc>
2+
<entries>
3+
<desc>Bind an event handler to the "contextmenu" event, or trigger that event on an element.</desc>
4+
5+
<entry type="method" name="on" return="jQuery">
6+
<title>contextmenu event</title>
7+
<desc>Bind an event handler to the "contextmenu" event.</desc>
58
<signature>
69
<added>1.0</added>
710
<argument name="handler" type="Function">
@@ -19,12 +22,8 @@
1922
<argument name="eventObject" type="Event" />
2023
</argument>
2124
</signature>
22-
<signature>
23-
<added>1.0</added>
24-
</signature>
2525
<longdesc>
26-
<p>This method is a shortcut for <code>.on( "contextmenu", handler )</code> in the first two variations, and <code>.trigger( "contextmenu" )</code> in the third.
27-
The <code>contextmenu</code> event is sent to an element when the right button of the mouse is clicked on it, but before the context menu is displayed. In case the context menu key is pressed, the event is triggered on the <code>html</code> element or the currently focused element. Any HTML element can receive this event.
26+
<p>The <code>contextmenu</code> event is sent to an element when the right button of the mouse is clicked on it, but before the context menu is displayed. In case the context menu key is pressed, the event is triggered on the <code>html</code> element or the currently focused element. Any HTML element can receive this event.
2827
For example, consider the HTML:</p>
2928
<pre><code>
3029
&lt;div id="target"&gt;
@@ -33,34 +32,34 @@
3332
</code></pre>
3433
<p>The event handler can be bound to the <code>&lt;div&gt;</code> as follows:</p>
3534
<pre><code>
36-
$( "#target" ).contextmenu(function() {
37-
alert( "Handler for .contextmenu() called." );
38-
});
35+
$( "#target" ).on( "contextmenu", function() {
36+
alert( "Handler for `contextmenu` called." );
37+
} );
3938
</code></pre>
4039
<p>Now right-clicking on this element displays the alert:</p>
4140
<p>
42-
<samp>Handler for .contextmenu() called.</samp>
41+
<samp>Handler for `contextmenu` called.</samp>
4342
</p>
44-
<p>To trigger the event manually, call <code>.contextmenu()</code> without an argument:</p>
43+
<p>To trigger the event manually, use <code>.trigger( "contextmenu" )</code>:</p>
4544
<pre><code>
46-
$( "#target" ).contextmenu();
45+
$( "#target" ).trigger( "contextmenu" );
4746
</code></pre>
4847
</longdesc>
4948
<example>
5049
<desc>To show a "Hello World!" alert box when the contextmenu event is triggered on a paragraph on the page:</desc>
5150
<code><![CDATA[
52-
$( "p" ).contextmenu(function() {
51+
$( "p" ).on( "contextmenu", function() {
5352
alert( "Hello World!" );
54-
});
53+
} );
5554
]]></code>
5655
</example>
5756
<example>
5857
<desc>Right click to toggle background color.</desc>
5958
<code><![CDATA[
6059
var div = $( "div" ).first();
61-
div.contextmenu(function() {
60+
div.on( "contextmenu", function() {
6261
div.toggleClass( "contextmenu" );
63-
});
62+
} );
6463
]]></code>
6564
<css><![CDATA[
6665
div {
@@ -81,5 +80,23 @@ div.contextmenu(function() {
8180
</example>
8281
<category slug="events/mouse-events"/>
8382
<category slug="version/1.0"/>
84-
<category slug="version/1.4.3"/>
83+
<category slug="version/1.7"/>
84+
</entry>
85+
86+
<entry type="method" name="trigger" return="jQuery">
87+
<title>contextmenu event</title>
88+
<desc>Trigger the "contextmenu" event on an element.</desc>
89+
<signature>
90+
<added>1.0</added>
91+
<argument name="&quot;contextmenu&quot;" type="string">
92+
<desc>The string <code>"contextmenu"</code>.</desc>
93+
</argument>
94+
</signature>
95+
<longdesc>
96+
<p>See the description for <a href="#on1"><code>.on( "contextmenu", ... )</code></a>.</p>
97+
</longdesc>
98+
<category slug="events/mouse-events"/>
99+
<category slug="version/1.0"/>
85100
</entry>
101+
102+
</entries>

Diff for: ‎entries/keydown-shorthand.xml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="keydown" return="jQuery" deprecated="3.3">
3+
<title>.keydown()</title>
4+
<desc>Bind an event handler to the "keydown" 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>.keydown( handler )</code> or <code>.keydown( eventData, handler )</code>, use <a href="/keydown/#on1"><code>.on( "keydown", handler )</code></a> or <a href="/keydown/#on1"><code>.on( "keydown", eventData, handler )</code></a>, respectively.</p>
29+
<p>Instead of <code>.keydown()</code>, use <a href="/keydown/#trigger2"><code>.trigger( "keydown" )</code></a>.</p>
30+
</div>
31+
</longdesc>
32+
<category slug="events/keyboard-events"/>
33+
<category slug="version/1.0"/>
34+
<category slug="version/1.4.3"/>
35+
<category slug="deprecated/deprecated-3.3"/>
36+
</entry>

Diff for: ‎entries/keydown.xml

+42-29
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="keydown" return="jQuery">
3-
<title>.keydown()</title>
2+
<entries>
3+
<desc>Bind an event handler to the "keydown" event, or trigger that event on an element.</desc>
4+
5+
<entry type="method" name="on" return="jQuery">
6+
<title>keydown event</title>
7+
<desc>Bind an event handler to the "keydown" event.</desc>
48
<signature>
5-
<added>1.0</added>
6-
<argument name="handler" type="Function">
7-
<desc>A function to execute each time the event is triggered.</desc>
8-
<argument name="eventObject" type="Event" />
9+
<added>1.7</added>
10+
<argument name="&quot;keydown&quot;" type="string">
11+
<desc>The string <code>"keydown"</code>.</desc>
912
</argument>
10-
</signature>
11-
<signature>
12-
<added>1.4.3</added>
1313
<argument name="eventData" type="Anything" optional="true">
1414
<desc>An object containing data that will be passed to the event handler.</desc>
1515
</argument>
@@ -18,12 +18,7 @@
1818
<argument name="eventObject" type="Event" />
1919
</argument>
2020
</signature>
21-
<signature>
22-
<added>1.0</added>
23-
</signature>
24-
<desc>Bind an event handler to the "keydown" event, or trigger that event on an element.</desc>
2521
<longdesc>
26-
<p>This method is a shortcut for <code>.on( "keydown", handler )</code> in the first and second variations, and <code>.trigger( "keydown" )</code> in the third.</p>
2722
<p>The <code>keydown</code> event is sent to an element when the user presses a key on the keyboard. If the key is kept pressed, the event is sent every time the operating system repeats the key. It can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.</p>
2823
<p>For example, consider the HTML:</p>
2924
<pre><code>
@@ -36,19 +31,19 @@
3631
</code></pre>
3732
<p>The event handler can be bound to the input field:</p>
3833
<pre><code>
39-
$( "#target" ).keydown(function() {
40-
alert( "Handler for .keydown() called." );
41-
});
34+
$( "#target" ).on( "keydown", function() {
35+
alert( "Handler for `keydown` called." );
36+
} );
4237
</code></pre>
4338
<p>Now when the insertion point is inside the field, pressing a key displays the alert:</p>
4439
<p>
45-
<samp>Handler for .keydown() called.</samp>
40+
<samp>Handler for `keydown` called.</samp>
4641
</p>
47-
<p>To trigger the event manually, apply <code>.keydown()</code> without an argument:</p>
42+
<p>To trigger the event manually, use <code>.trigger( "keydown" )</code>:</p>
4843
<pre><code>
49-
$( "#other" ).click(function() {
50-
$( "#target" ).keydown();
51-
});
44+
$( "#other" ).on( "click", function() {
45+
$( "#target" ).trigger( "keydown" );
46+
} );
5247
</code></pre>
5348
<p>After this code executes, clicks on <samp>Trigger the handler</samp> will also alert the message.</p>
5449
<p>If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the <code>document</code> object. Because of event bubbling, all key presses will make their way up the DOM to the <code>document</code> object unless explicitly stopped.</p>
@@ -58,19 +53,19 @@ $( "#other" ).click(function() {
5853
<desc>Show the event object for the keydown handler when a key is pressed in the input.</desc>
5954
<code><![CDATA[
6055
var xTriggered = 0;
61-
$( "#target" ).keydown(function( event ) {
56+
$( "#target" ).on( "keydown", function( event ) {
6257
if ( event.which == 13 ) {
6358
event.preventDefault();
6459
}
6560
xTriggered++;
66-
var msg = "Handler for .keydown() called " + xTriggered + " time(s).";
61+
var msg = "Handler for `keydown` called " + xTriggered + " time(s).";
6762
$.print( msg, "html" );
6863
$.print( event );
69-
});
64+
} );
7065
71-
$( "#other" ).click(function() {
72-
$( "#target" ).keydown();
73-
});
66+
$( "#other" ).on( "click", function() {
67+
$( "#target" ).trigger( "keydown" );
68+
} );
7469
]]></code>
7570
<css><![CDATA[
7671
fieldset {
@@ -106,5 +101,23 @@ $( "#other" ).click(function() {
106101
</example>
107102
<category slug="events/keyboard-events"/>
108103
<category slug="version/1.0"/>
109-
<category slug="version/1.4.3"/>
104+
<category slug="version/1.7"/>
110105
</entry>
106+
107+
<entry type="method" name="trigger" return="jQuery">
108+
<title>keydown event</title>
109+
<desc>Trigger the "keydown" event on an element.</desc>
110+
<signature>
111+
<added>1.0</added>
112+
<argument name="&quot;keydown&quot;" type="string">
113+
<desc>The string <code>"keydown"</code>.</desc>
114+
</argument>
115+
</signature>
116+
<longdesc>
117+
<p>See the description for <a href="#on1"><code>.on( "keydown", ... )</code></a>.</p>
118+
</longdesc>
119+
<category slug="events/keyboard-events"/>
120+
<category slug="version/1.0"/>
121+
</entry>
122+
123+
</entries>

Diff for: ‎entries/keypress-shorthand.xml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="keypress" return="jQuery" deprecated="3.3">
3+
<title>.keypress()</title>
4+
<desc>Bind an event handler to the "keypress" 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>.keypress( handler )</code> or <code>.keypress( eventData, handler )</code>, use <a href="/keypress/#on1"><code>.on( "keypress", handler )</code></a> or <a href="/keypress/#on1"><code>.on( "keypress", eventData, handler )</code></a>, respectively.</p>
29+
<p>Instead of <code>.keypress()</code>, use <a href="/keypress/#trigger2"><code>.trigger( "keypress" )</code></a>.</p>
30+
</div>
31+
</longdesc>
32+
<category slug="events/keyboard-events"/>
33+
<category slug="version/1.0"/>
34+
<category slug="version/1.4.3"/>
35+
<category slug="deprecated/deprecated-3.3"/>
36+
</entry>

0 commit comments

Comments
 (0)