control-freak-ide/Control-Freak-Documentation/jQuery/docs/entries/jQuery.Deferred.json

{"name":"jQuery.Deferred","type":"method","title":"jQuery.Deferred()","deprecated":null,"removed":null,"desc":" A constructor function that returns a chainable utility object with methods to register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.","categories":["deferred-object","version/1.5"],"entries":[{"return":"Deferred","signatures":{"added":"1.5","argument":{"desc":"\n        A function that is called just before the constructor returns.\n      ","argument":{"desc":"\n          The constructed Deferred object.\n        ","name":"deferred","type":"Deferred"},"name":"beforeStart","type":"Function","optional":"true"}},"examples":null,"longdesc":"\n    <p>The <code>jQuery.Deferred()</code> constructor creates a new Deferred object. The <code>new</code> operator is optional.</p>\n    <p>The <code>jQuery.Deferred</code> method can be passed an optional function, which is called just before the constructor returns and is passed the constructed <code>deferred</code> object as both the <code>this</code> object and as the first argument to the function. The called function can attach callbacks using <a href=\"/deferred.then/\"><code>deferred.then()</code></a>, for example.</p>\n    <p>A Deferred object starts in the <em>pending</em> state. Any callbacks added to the object with <a href=\"/deferred.then/\"><code>deferred.then()</code></a>, <a href=\"/deferred.always/\"><code>deferred.always()</code></a>, <a href=\"/deferred.done/\"><code>deferred.done()</code></a>, or <a href=\"/deferred.fail/\"><code>deferred.fail()</code></a> are queued to be executed later. Calling <a href=\"/deferred.resolve/\"><code>deferred.resolve()</code></a> or <a href=\"/deferred.resolveWith/\"><code>deferred.resolveWith()</code></a> transitions the Deferred into the <em>resolved</em> state and immediately executes any <code>doneCallbacks</code> that are set. Calling <a href=\"/deferred.reject/\"><code>deferred.reject()</code></a> or <a href=\"/deferred.rejectWith/\"><code>deferred.rejectWith()</code></a> transitions the Deferred into the <em>rejected</em> state and immediately executes any <code>failCallbacks</code> that are set. Once the object has entered the resolved or rejected state, it stays in that state. Callbacks can still be added to the resolved or rejected Deferred — they will execute immediately.</p>\n    <h4>\n      Enhanced Callbacks with jQuery Deferred\n    </h4>\n    <p>In JavaScript it is common to invoke functions that optionally accept callbacks that are called within that function. For example, in versions prior to jQuery 1.5, asynchronous processes such as <code>jQuery.ajax()</code> accept callbacks to be invoked some time in the near-future upon success, error, and completion of the ajax request.</p>\n    <p><code>jQuery.Deferred()</code> introduces several enhancements to the way callbacks are managed and invoked. In particular, <code>jQuery.Deferred()</code> provides flexible ways to provide multiple callbacks, and these callbacks can be invoked regardless of whether the original callback dispatch has already occurred. jQuery Deferred is based on the <a href=\"http://wiki.commonjs.org/wiki/Promises/A\">CommonJS Promises/A</a> design.</p>\n    <p>One model for understanding Deferred is to think of it as a chain-aware function wrapper. The <a href=\"/deferred.then/\"><code>deferred.then()</code></a>, <a href=\"/deferred.always/\"><code>deferred.always()</code></a>, <a href=\"/deferred.done/\"><code>deferred.done()</code></a>, and <a href=\"/deferred.fail/\"><code>deferred.fail()</code></a> methods specify the functions to be called and the <a href=\"/deferred.resolve/\"><code>deferred.resolve(args)</code></a> or <a href=\"/deferred.reject/\"><code>deferred.reject(args)</code></a> methods \"call\" the functions with the arguments you supply. Once the Deferred has been resolved or rejected it stays in that state; a second call to <code>deferred.resolve()</code>, for example, is ignored. If more functions are added by <code>deferred.then()</code>, for example, after the Deferred is resolved, they are called immediately with the arguments previously provided.</p>\n    <p>In most cases where a jQuery API call returns a Deferred or Deferred-compatible object, such as <a href=\"/jQuery.ajax/\"><code>jQuery.ajax()</code></a> or <a href=\"/jQuery.when/\"><code>jQuery.when()</code></a>, you will only want to use the <a href=\"/deferred.then/\"><code>deferred.then()</code></a>, <a href=\"/deferred.done/\"><code>deferred.done()</code></a>, and <a href=\"/deferred.fail/\"><code>deferred.fail()</code></a> methods to add callbacks to the Deferred's queues. The internals of the API call or code that created the Deferred will invoke <a href=\"/deferred.resolve/\"><code>deferred.resolve()</code></a> or <a href=\"/deferred.reject/\"><code>deferred.reject()</code></a> on the deferred at some point, causing the appropriate callbacks to run.</p>\n  "}]}