# Class webdriver.promise.Frame_

code »

    webdriver.promise.Promise.<(T|null)>
      └ webdriver.promise.Deferred
          └ webdriver.promise.Node_
              └ webdriver.promise.Frame_

An execution frame within a `webdriver.promise.ControlFlow`. Each frame represents the execution context for either a `webdriver.promise.Task_` or a callback on a `webdriver.promise.Deferred`.

Each frame may contain sub-frames. If child N is a sub-frame, then the items queued within it are given priority over child N+1.

## Constructor

webdriver.promise.Frame_ ( flow )

Parameters

flow: `!webdriver.promise.ControlFlow`
  The flow this instance belongs to.

Show:PublicProtectedPrivate

## Instance Methods

### Defined in `webdriver.promise.Frame_`

code » addChild ( node )

Adds a new node to this frame.

Parameters

node: `!(webdriver.promise.Frame_|webdriver.promise.Task_)`
  The node to insert.

code » cancelRemainingTasks ( error )

Marks all of the tasks that are descendants of this frame in the execution tree as cancelled. This is necessary for callbacks scheduled asynchronous. For example: var someResult; webdriver.promise.createFlow(function(flow) { someResult = flow.execute(function() {}); throw Error(); }).addErrback(function(err) { console.log('flow failed: ' + err); someResult.then(function() { console.log('task succeeded!'); }, function(err) { console.log('task failed! ' + err); }); }); // flow failed: Error: boom // task failed! CanceledTaskError: Task discarded due to a previous // task failure: Error: boom

Parameters

error: `!webdriver.promise.CanceledTaskError_`
  The cancellation error.

code » getFirstChild ( ) ⇒ `(webdriver.promise.Frame_|webdriver.promise.Task_)`

Returns

This frame's fist child.

code » getPendingTask ( ) ⇒ `webdriver.promise.Task_`

Returns

The task currently executing within this frame, if any.

code » lockFrame ( )

Locks this frame.

code » reject ( )
code » removeChild ( child )

Removes a child from this frame.

Parameters

child: `!(webdriver.promise.Frame_|webdriver.promise.Task_)`
  The child to remove.

code » setPendingTask ( task )

Parameters

task: `webdriver.promise.Task_`
  The task currently executing within this frame, if any.

code » toString ( ) ⇒ `string`

### Defined in `webdriver.promise.Node_`

code » getParent ( ) ⇒ `webdriver.promise.Node_`

Returns

This node's parent.

code » getRoot ( ) ⇒ `!webdriver.promise.Node_`

Returns

The root of this node's tree.

code » setParent ( parent )

Parameters

parent: `webdriver.promise.Node_`
  This node's new parent.

### Defined in `webdriver.promise.Deferred`

code » errback ( opt_error )

Rejects this promise. If the error is itself a promise, this instance will be chained to it and be rejected with the error's resolved value.

Parameters

opt_error: `*=`
  The rejection reason, typically either a `Error` or a `string`.

code » fulfill ( opt_value )

Resolves this promise with the given value. If the value is itself a promise and not a reference to this deferred, this instance will wait for it before resolving.

Parameters

opt_value: `T=`
  The fulfilled value.

code » removeAll ( )

Removes all of the listeners previously registered on this deferred.

Throws

`Error`
  If this deferred has already been resolved.

### Defined in `webdriver.promise.Promise.<(T|null)>`

code » cancel ( reason )

Cancels the computation of this promise's value, rejecting the promise in the process.

Parameters

reason: `*`
  The reason this promise is being cancelled. If not an `Error`, one will be created using the value's string representation.

code » isPending ( ) ⇒ `boolean`

Returns

Whether this promise's value is still being computed.

code » `<R>` then ( opt_callback, opt_errback ) ⇒ `!webdriver.promise.Promise.<R>`

Registers listeners for when this instance is resolved. This function most overridden by subtypes.

Parameters

opt_callback: `?(function(T): (R|webdriver.promise.Promise.<R>))=`
  The function to call if this promise is successfully resolved. The function should expect a single argument: the promise's resolved value.
opt_errback: `?(function(*): (R|webdriver.promise.Promise.<R>))=`
  The function to call if this promise is rejected. The function should expect a single argument: the rejection reason.

Returns

A new promise which will be resolved with the result of the invoked callback.

code » `<R>` thenCatch ( errback ) ⇒ `!webdriver.promise.Promise.<R>`

Registers a listener for when this promise is rejected. This is synonymous with the `catch` clause in a synchronous API:

       // Synchronous API:
       try {
         doSynchronousWork();
       } catch (ex) {
         console.error(ex);
       }

       // Asynchronous promise API:
       doAsynchronousWork().thenCatch(function(ex) {
         console.error(ex);
       });

Parameters

errback: `function(*): (R|webdriver.promise.Promise.<R>)`
  The function to call if this promise is rejected. The function should expect a single argument: the rejection reason.

Returns

A new promise which will be resolved with the result of the invoked callback.

code » `<R>` thenFinally ( callback ) ⇒ `!webdriver.promise.Promise.<R>`

Registers a listener to invoke when this promise is resolved, regardless of whether the promise's value was successfully computed. This function is synonymous with the `finally` clause in a synchronous API:

       // Synchronous API:
       try {
         doSynchronousWork();
       } finally {
         cleanUp();
       }

       // Asynchronous promise API:
       doAsynchronousWork().thenFinally(cleanUp);

Note: similar to the `finally` clause, if the registered callback returns a rejected promise or throws an error, it will silently replace the rejection error (if any) from this promise:

       try {
         throw Error('one');
       } finally {
         throw Error('two');  // Hides Error: one
       }

       webdriver.promise.rejected(Error('one'))
           .thenFinally(function() {
             throw Error('two');  // Hides Error: one
           });

Parameters

callback: `function(): (R|webdriver.promise.Promise.<R>)`
  The function to call when this promise is resolved.

Returns

A promise that will be fulfilled with the callback result.

## Instance Properties

### Defined in `webdriver.promise.Frame_`

code » children_ : `!Array`
code » isActive_ : `boolean`

Whether this frame is active. A frame is considered active once one of its descendants has been removed for execution. Adding a sub-frame as a child to an active frame is an indication that a callback to a `webdriver.promise.Deferred` is being invoked and any tasks scheduled within it should have priority over previously scheduled tasks: ``

       var flow = webdriver.promise.controlFlow();
       flow.execute('start here', goog.nullFunction).then(function() {
         flow.execute('this should execute 2nd', goog.nullFunction);
       });
       flow.execute('this should execute last', goog.nullFunction);

code » isLocked_ : `boolean`

Whether this frame is currently locked. A locked frame represents a callback or task function which has run to completion and scheduled all of its tasks.

Once a frame becomes `active`, any new frames which are added represent callbacks on a `webdriver.promise.Deferred`, whose tasks must be given priority over previously scheduled tasks.

code » lastInsertedChild_ : `webdriver.promise.Node_`

A reference to the last node inserted in this frame.

code » pendingTask_ : `webdriver.promise.Task_`

The task currently being executed within this frame.

### Defined in `webdriver.promise.Node_`

code » parent_ : `webdriver.promise.Node_`

This node's parent.

### Defined in `webdriver.promise.Deferred`

code » webdriver.promise.Deferred.prototype.promise : `webdriver.promise.Promise.<T>`

Represents the eventual value of a completed operation. Each promise may be in one of three states: pending, resolved, or rejected. Each promise starts in the pending state and may make a single transition to either a fulfilled or failed state.

This class is based on the Promise/A proposal from CommonJS. Additional functions are provided for API compatibility with Dojo Deferred objects.

## Static Properties

code » webdriver.promise.Frame_.superClass_ : `webdriver.promise.Node_.prototype`