WinJS.Promise object (Windows)

13 out of 30 rated this helpful - Rate this topic

Provides a mechanism to schedule work to be done on a value that has not yet been computed. It is an abstraction for managing interactions with asynchronous APIs.

For more information about asynchronous programming, see Asynchronous programming. For more information about promises in JavaScript, see Asynchronous programming in JavaScript.

For more information about using promises, see the Promise sample at Windows Store app samples.

Syntax

JavaScript


var aPromise = new WinJS.Promise(init, onCancel);

Members

The Promise object has these types of members:

Events
Methods

Events

The Promise object has these events.

Event	Description
onerror	Occurs when there is an error in processing a promise.

Methods

The Promise object has these methods.

Method	Description
addEventListener	Adds an event listener for the promise.
any	Returns a promise that is fulfilled when one of the input promises has been fulfilled.
as	Returns a promise. If the object is already a Promise it is returned; otherwise the object is wrapped in a Promise. You can use this function when you need to treat a non-Promise object like a Promise, for example when you are calling a function that expects a promise, but already have the value needed rather than needing to get it asynchronously.
cancel	Attempts to cancel the fulfillment of a promised value. If the promise hasn't already been fulfilled and cancellation is supported, the promise enters the error state with a value of Error("Canceled").
dispatchEvent	Raises an event of the specified type and properties.
done	Allows you to specify the work to be done on the fulfillment of the promised value, the error handling to be performed if the promise fails to fulfill a value, and the handling of progress notifications along the way. After the handlers have finished executing, this function throws any error that would have been returned from then as a promise in the error state. For more information about the differences between then and done, see the following topics: Quickstart: using promises in JavaScript How to handle errors when using promises in JavaScript Chaining promises in JavaScript
is	Determines whether a value fulfills the promise contract.
join	Creates a Promise that is fulfilled when all the values are fulfilled.
Promise	A promise provides a mechanism to schedule work to be done on a value that has not yet been computed. It is a convenient abstraction for managing interactions with asynchronous APIs. For more information about asynchronous programming, see Asynchronous programming. For more information about promises in JavaScript, see Asynchronous programming in JavaScript. For more information about using promises, see the Promise sample at Windows Store app samples.
removeEventListener	Removes an event listener from the control.
then	Allows you to specify the work to be done on the fulfillment of the promised value, the error handling to be performed if the promise fails to fulfill a value, and the handling of progress notifications along the way. For more information about the differences between then and done, see the following topics: Quickstart: using promises in JavaScript How to handle errors when using promises in JavaScript Chaining promises in JavaScript
theneach	Performs an operation on all the input promises and returns a promise that has the shape of the input and contains the result of the operation that has been performed on each input.
timeout	This method has two forms: WinJS.Promise.timeout(timeout) and WinJS.Promise.timeout(timeout, promise). WinJS.Promise.timeout(timeout) creates a promise that is completed asynchronously after the specified timeout, essentially wrapping a call to setTimeout within a promise. WinJS.Promise.timeout(timeout, promise) sets a timeout period for completion of the specified promise, automatically canceling the promise if it is not completed within the timeout period.
wrap	Wraps a non-promise value in a promise. This method is like wrapError, which allows you to produce a Promise in error conditions, in that it allows you to return a Promise in success conditions.
wrapError	Wraps a non-promise error value in a promise. You can use this function if you need to pass an error to a function that requires a promise.

Examples

The following code shows how to write a function that returns a WinJS.Promise. The complete function that is the first parameter of the init function defines the actual work of the promise; the error function defines what is to be done if the code in the complete function throws an error, and the progress function defines what should be displayed while the asynchronous operation is still in progress.

JavaScript


<button id="start">StartAsync</button>
<div id="result" style="background-color: blue"></div>
    
<script type="text/javascript">

    WinJS.Application.onready = function (ev) {
        document.getElementById("start").addEventListener("click", onClicked, false);
    };

    function onClicked() {
        addAsync(3, 4).then(
            function complete(res) {
                 document.getElementById("result").textContent = "Complete";
            },
             function error(res) {
                 document.getElementById("result").textContent = "Error";
            },
             function progress(res) {
                 document.getElementById("result").textContent = "Progress";
          })
     }

    function addAsync(l, r) {
         return new WinJS.Promise(function (comp, err, prog) {
            setTimeout(function () {
                try {
                    var sum = l + r;
                     var i;
                     for (i = 1; i < 100; i++) {
                         prog(i);
                    }
                         comp(sum);
                    }
                    catch (e) {
                        err(e);
                    }
                }, 1000);
            });
        }
    </script>

Requirements

Minimum supported client	Windows 8 [Windows Store apps only]
Minimum supported server	Windows Server 2012 [Windows Store apps only]
Namespace	WinJS
Library	Base.js

Build date: 12/5/2012

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)