[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
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 Metro style app samples.
Syntax
var aPromise = new WinJS.Promise(init, onCancel);
Members
The Promise object has these types of members:
Events
The Promise object has these events.
| Event | Description |
|---|---|
| onerror |
Occurs when there is an error in processing. |
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. |
| 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: |
| 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 Metro style 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: |
| 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. You can use this function if you need to pass a value to a function that requires a promise. |
| 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. |
Requirements
|
Minimum supported client | Windows 8 Release Preview |
|---|---|
|
Minimum supported server | Windows Server 2012 |
|
Namespace |
WinJS |
|
Library |
|
Build date: 5/22/2012
