Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: 8480e4c5f9
Fetching contributors…

Cannot retrieve contributors at this time

124 lines (115 sloc) 6.86 kB
<!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">.keypress()</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> &gt; <a href="http://api.jquery.com/category/events/keyboard-events/" title="View all posts in Keyboard Events">Keyboard Events</a></span>
</div>
</div>
<div id="keypress1" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">.keypress( 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>Bind an event handler to the "keypress" JavaScript event, or trigger that event on an element.</p>
<ul class="signatures">
<li class="signature" id="keypress-handlereventObject">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>.keypress( handler(eventObject) )</h4>
<p class="arguement"><strong>handler(eventObject)</strong>A function to execute each time the event is triggered.</p>
</li>
<li class="signature" id="keypress-eventData-handlereventObject">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.4.3/">1.4.3</a></span>.keypress( [eventData], handler(eventObject) )</h4>
<p class="arguement"><strong>eventData</strong>A map of data that will be passed to the event handler.</p>
<p class="arguement"><strong>handler(eventObject)</strong>A function to execute each time the event is triggered.</p>
</li>
<li class="signature" id="keypress"><h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>.keypress()</h4></li>
</ul>
<div class="longdesc">
<p><strong>Note:</strong> as the <code>keypress</code> event isn't covered by any official specification, the actual behavior encountered when using it may differ across browsers, browser versions, and platforms.</p>
<p>This method is a shortcut for <code>.bind("keypress", handler)</code> in the first two variations, and <code>.trigger("keypress")</code> in the third.</p>
<p>The <code>keypress</code> event is sent to an element when the browser registers keyboard input. This is similar to the <code>keydown</code> event, except in the case of key repeats. If the user presses and holds a key, a <code>keydown </code>event is triggered once, but separate <code>keypress</code> events are triggered for each inserted character. In addition, modifier keys (such as Shift) trigger <code>keydown</code> events but not <code>keypress</code> events.</p>
<p>A <code>keypress</code> event handler 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>
<p>For example, consider the HTML:</p>
<pre>&lt;form&gt;
&lt;fieldset&gt;
&lt;input id="target" type="text" value="Hello there" /&gt;
&lt;/fieldset&gt;
&lt;/form&gt;
&lt;div id="other"&gt;
Trigger the handler
&lt;/div&gt;</pre>
<p>The event handler can be bound to the input field:</p>
<pre>$("#target").keypress(function() {
alert("Handler for .keypress() called.");
});</pre>
<p>Now when the insertion point is inside the field, pressing a key displays the alert:</p>
<p><span class="output">Handler for .keypress() called.</span></p>
<p>The message repeats if the key is held down. To trigger the event manually, apply <code>.keypress()</code> without an argument::</p>
<pre>$('#other').click(function() {
$("#target").keypress();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also alert the message.</p>
<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>
<p>To determine which character was entered, examine the <code>event</code> object that is passed to the handler function. While browsers use differing properties to store this information, jQuery normalizes the <code>.which</code> property so you can reliably use it to retrieve the character code.</p>
<p>Note that <code>keydown</code> and <code>keyup</code> provide a code indicating which key is pressed, while <code>keypress</code> indicates which character was entered. For example, a lowercase "a" will be reported as 65 by <code>keydown</code> and <code>keyup</code>, but as 97 by <code>keypress</code>. An uppercase "A" is reported as 65 by all events. Because of this distinction, when catching special keystrokes such as arrow keys, <code>.keydown()</code> or <code>.keyup()</code> is a better choice.</p>
</div>
<h3>Example:</h3>
<div class="entry-examples" id="entry-examples"><div id="example-0">
<h4><span class="desc">Show the event object when a key is pressed in the input. Note: This demo relies on a simple $.print() plugin (http://api.jquery.com/scripts/events.js) for the event object's output.</span></h4>
<pre class="prettyprint"><code class="example demo-code">&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
&lt;style&gt;
fieldset { margin-bottom: 1em; }
input { display: block; margin-bottom: .25em; }
#print-output {
width: 100%;
}
.print-output-line {
white-space: pre;
padding: 5px;
font-family: monaco, monospace;
font-size: .7em;
}
&lt;/style&gt;
&lt;script src="http://code.jquery.com/jquery-1.7rc2.js"&gt;&lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;form&gt;
&lt;fieldset&gt;
&lt;label for="target"&gt;Type Something:&lt;/label&gt;
&lt;input id="target" type="text" /&gt;
&lt;/fieldset&gt;
&lt;/form&gt;
&lt;button id="other"&gt;
Trigger the handler
&lt;/button&gt;
&lt;script src="http://api.jquery.com/scripts/events.js"&gt;&lt;/script&gt;
&lt;script&gt;
var xTriggered = 0;
$("#target").keypress(function(event) {
if ( event.which == 13 ) {
event.preventDefault();
}
xTriggered++;
var msg = "Handler for .keypress() called " + xTriggered + " time(s).";
$.print( msg, "html" );
$.print( event );
});
$("#other").click(function() {
$("#target").keypress();
});&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;</code></pre>
<h4>Demo:</h4>
<div class="demo code-demo" rel="460"></div>
</div></div>
</div>
</div>
</div>
</body></html>
Jump to Line
Something went wrong with that request. Please try again.