1 line
4.1 KiB
JSON
1 line
4.1 KiB
JSON
{"name":"focus","type":"method","title":".focus()","deprecated":null,"removed":null,"desc":"Bind an event handler to the \"focus\" JavaScript event, or trigger that event on an element.","categories":["events/form-events","forms","version/1.0","version/1.4.3"],"entries":[{"return":"jQuery","signatures":[{"added":"1.0","argument":{"desc":"A function to execute each time the event is triggered.","name":"handler(eventObject)","type":"Function"}},{"added":"1.4.3","argument":[{"desc":"An object containing data that will be passed to the event handler.","name":"eventData","type":"Object","optional":"true"},{"desc":"A function to execute each time the event is triggered.","name":"handler(eventObject)","type":"Function"}]},{"added":"1.0"}],"examples":[{"desc":"Fire focus.","css":"\n span {\n display: none;\n }\n","code":"\n$( \"input\" ).focus(function() {\n $( this ).next( \"span\" ).css( \"display\", \"inline\" ).fadeOut( 1000 );\n});\n","html":"\n<p><input type=\"text\"> <span>focus fire</span></p>\n<p><input type=\"password\"> <span>focus fire</span></p>\n"},{"desc":"To stop people from writing in text input boxes, try:","code":"\n$( \"input[type=text]\" ).focus(function() {\n $( this ).blur();\n});\n"},{"desc":"To focus on a login input box with id 'login' on page startup, try:","code":"\n$( document ).ready(function() {\n $( \"#login\" ).focus();\n});\n"}],"longdesc":"\n <ul>\n <li>This method is a shortcut for <code>.on( \"focus\", handler )</code> in the first and second variations, and <code>.trigger( \"focus\" )</code> in the third.</li>\n <li>The <code>focus</code> event is sent to an element when it gains focus. This event is implicitly applicable to a limited set of elements, such as form elements (<code><input></code>, <code><select></code>, etc.) and links (<code><a href></code>). In recent browser versions, the event can be extended to include all element types by explicitly setting the element's <code>tabindex</code> property. An element can gain focus via keyboard commands, such as the Tab key, or by mouse clicks on the element.</li>\n <li>Elements with focus are usually highlighted in some way by the browser, for example with a dotted line surrounding the element. The focus is used to determine which element is the first to receive keyboard-related events.</li>\n </ul>\n <div class=\"warning\">\n <p>Attempting to set focus to a hidden element causes an error in Internet Explorer. Take care to only use <code>.focus()</code> on elements that are visible. To run an element's focus event handlers without setting focus to the element, use <code>.triggerHandler( \"focus\" )</code> instead of <code>.focus()</code>.</p>\n </div>\n <p>For example, consider the HTML:</p>\n <pre><code>\n<form>\n <input id=\"target\" type=\"text\" value=\"Field 1\">\n <input type=\"text\" value=\"Field 2\">\n</form>\n<div id=\"other\">\n Trigger the handler\n</div>\n </code></pre>\n <p>The event handler can be bound to the first input field:</p>\n <pre><code>\n$( \"#target\" ).focus(function() {\n alert( \"Handler for .focus() called.\" );\n});\n </code></pre>\n <p>Now clicking on the first field, or tabbing to it from another field, displays the alert:</p>\n <p>\n <samp>Handler for .focus() called.</samp>\n </p>\n <p>We can trigger the event when another element is clicked:</p>\n <pre><code>\n$( \"#other\" ).click(function() {\n $( \"#target\" ).focus();\n});\n </code></pre>\n <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also alert the message.</p>\n <p>The <code>focus</code> event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the <code>focus</code> event will not work consistently across browsers. As of version 1.4.2, however, jQuery works around this limitation by mapping <code>focus</code> to the <code>focusin</code> event in its event delegation methods, <a href=\"/live/\"><code>.live()</code></a> and <a href=\"/delegate/\"><code>.delegate()</code></a>.</p>\n "}]} |