Skip to content
This repository
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 95 lines (93 sloc) 4.242 kb
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
<?xml version="1.0"?>
<entry type="method" name="keydown" return="jQuery">
  <title>.keydown()</title>
  <signature>
    <added>1.0</added>
    <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="eventData" type="PlainObject" optional="true">
      <desc>A map of 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.0</added>
  </signature>
  <desc>Bind an event handler to the "keydown" JavaScript event, or trigger that event on an element.</desc>
  <longdesc>
    <p>This method is a shortcut for <code>.bind('keydown', handler)</code> in the first and second variations, and <code>.trigger('keydown')</code> in the third.</p>
    <p>The <code>keydown</code> event is sent to an element when the user first presses a key on the keyboard. 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>
    <p>For example, consider the HTML:</p>
    <pre><code>&lt;form&gt;
  &lt;input id="target" type="text" value="Hello there" /&gt;
&lt;/form&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;</code></pre>
    <p>The event handler can be bound to the input field:</p>
    <pre><code>$('#target').keydown(function() {
  alert('Handler for .keydown() called.');
});</code></pre>
    <p>Now when the insertion point is inside the field, pressing a key displays the alert:</p>
    <p>
      <span class="output">Handler for .keydown() called.</span>
    </p>
    <p>To trigger the event manually, apply <code>.keydown()</code> without an argument:</p>
    <pre><code>$('#other').click(function() {
  $('#target').keydown();
});</code></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 key was pressed, examine the <a href="http://api.jquery.com/category/events/event-object/">event object</a> 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 key code. This code corresponds to a key on the keyboard, including codes for special keys such as arrows. For catching actual text entry, <code>.keypress()</code> may be a better choice.</p>
  </longdesc>
  <example>
    <desc>Show the event object for the keydown handler when a key is pressed in the input.</desc>
    <code><![CDATA[
var xTriggered = 0;
$('#target').keydown(function(event) {
if (event.which == 13) {
event.preventDefault();
}
xTriggered++;
var msg = 'Handler for .keydown() called ' + xTriggered + ' time(s).';
$.print(msg, 'html');
$.print(event);
});

$('#other').click(function() {
$('#target').keydown();
});]]></code>
    <css><![CDATA[
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;
}

]]></css>
    <height>460</height>
    <html><![CDATA[<form>
<fieldset>
<label for="target">Type Something:</label>
<input id="target" type="text" />
</fieldset>
</form>
<button id="other">
Trigger the handler
</button>
<script type="text/javascript" src="/scripts/events.js"></script>]]></html>
  </example>
  <category slug="events/keyboard-events"/>
  <category slug="version/1.0"/>
  <category slug="version/1.4.3"/>
</entry>
Something went wrong with that request. Please try again.