require(["esri/core/watchUtils"], function(watchUtils) { /* code goes here */ });
Object: esri/core/watchUtils
Since: ArcGIS API for JavaScript 4.0

Various utilities and convenience functions for watching Accessor properties.

Method Overview

NameReturn TypeSummaryObject
WatchHandle

Watches a property for changes and calls the callback with the initial value of the property.

more details
more detailswatchUtils
WatchHandle

Watches a property for changes and automatically attaches and detaches an event handler for a given event to the property value as needed.

more details
more detailswatchUtils
PromisedWatchHandle

Watches a property for changes once.

more details
more detailswatchUtils
PausableWatchHandle

Watches a property for changes.

more details
more detailswatchUtils
WatchHandle

Watches a property for changes.

more details
more detailswatchUtils
WatchHandle

Watches a property for becoming truthy.

more details
more detailswatchUtils
WatchHandle

Watches a property for becoming defined.

more details
more detailswatchUtils
PromisedWatchHandle

Watches a property for becoming defined once.

more details
more detailswatchUtils
WatchHandle

Watches a property for becoming false.

more details
more detailswatchUtils
PromisedWatchHandle

Watches a property for becoming false once.

more details
more detailswatchUtils
WatchHandle

Watches a property for becoming falsy.

more details
more detailswatchUtils
PromisedWatchHandle

Watches a property for becoming falsy once.

more details
more detailswatchUtils
PromisedWatchHandle

Watches a property for becoming truthy once.

more details
more detailswatchUtils
WatchHandle

Watches a property for becoming true.

more details
more detailswatchUtils
PromisedWatchHandle

Watches a property for becoming true once.

more details
more detailswatchUtils
WatchHandle

Watches a property for becoming undefined.

more details
more detailswatchUtils
PromisedWatchHandle

Watches a property for becoming undefined once.

more details
more detailswatchUtils

Method Details

init(obj, propertyName, callback){WatchHandle}static

Watches a property for changes and calls the callback with the initial value of the property.

Parameters:

The object containing the property to watch.

propertyName String|String[]

The name of the property to watch.

callback watchCallback

The function to call with the initial value of the property when the property changes.

Returns:
TypeDescription
WatchHandleA watch handle.

on(obj, propertyName, eventName, eventHandler, attachedHandler, detachedHandler){WatchHandle}static

Watches a property for changes and automatically attaches and detaches an event handler for a given event to the property value as needed.

The attachedHandler and detachedHandler are optional and if provided will be called whenever the event handler is attached and detached respectively.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

eventName String

The name of the event to attach the event handler for.

eventHandler Function

The event handler callback function.

attachedHandler EventAttachedCallback
optional

Callback called each time the event handler is attached.

detachedHandler EventAttachedCallback
optional

Callback called each time the event handler is detached.

Returns:
TypeDescription
WatchHandleA watch handle.

once(obj, propertyName, callback){PromisedWatchHandle}static

Watches a property for changes once. The returned watch handle is removed after the first time the callback has been invoked.

The returned handle additionally implements the Promise interface and can be used to create a promise chain to asynchronously handle a property value becoming truthy. The promise result is an object containing a value, oldValue, propertyName and target.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback
optional

The function to call when the property changes.

Returns:
TypeDescription
PromisedWatchHandleA watch handle which implements the Promise interface.

pausable(obj, propertyName, callback){PausableWatchHandle}static

Watches a property for changes. The returned handle can be paused (and resumed) to temporarily prevent the callback from being called on property changes.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback
optional

The function to call when the property changes.

Returns:
TypeDescription
PausableWatchHandleA pausable watch handle.

watch(obj, propertyName, callback){WatchHandle}static

Watches a property for changes. This is an alias for Accessor.watch(), provided for completeness.

Parameters:

The object containing the property to watch.

propertyName String|String[]

The name of the property to watch.

callback watchCallback

The function to call when the property changes.

Returns:
TypeDescription
WatchHandleA watch handle.
See also:

when(obj, propertyName, callback){WatchHandle}static

Watches a property for becoming truthy. As with watchUtils, the callback is called initially if the property is initially truthy.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback

The function to call when the property changes.

Returns:
TypeDescription
WatchHandleA watch handle.

whenDefined(obj, propertyName, callback){WatchHandle}static

Watches a property for becoming defined. As with init(), the callback is called if the property is initially defined.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback

The function to call when the property changes.

Returns:
TypeDescription
WatchHandleA watch handle.

whenDefinedOnce(obj, propertyName, callback){PromisedWatchHandle}static

Watches a property for becoming defined once. As with init(), the callback is called if the property is initially defined. The returned watch handle is removed after the first time the callback has been invoked.

The returned handle additionally implements the Promise interface and can be used to create a promise chain to asynchronously handle a property value becoming defined. The promise result is an object containing a value, oldValue, propertyName and target.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback
optional

The function to call when the property changes.

Returns:
TypeDescription
PromisedWatchHandleA watch handle which implements the Promise interface.

whenFalse(obj, propertyName, callback){WatchHandle}static

Watches a property for becoming false. As with init(), the callback is called if the property is initially false.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback

The function to call when the property changes.

Returns:
TypeDescription
WatchHandleA watch handle.

whenFalseOnce(obj, propertyName, callback){PromisedWatchHandle}static

Watches a property for becoming false once. As with init(), the callback is called if the property is initially false. The returned watch handle is removed after the first time the callback has been invoked.

The returned handle additionally implements the Promise interface and can be used to create a promise chain to asynchronously handle a property value becoming false. The promise result is an object containing a value, oldValue, propertyName and target.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback
optional

The function to call when the property changes.

Returns:
TypeDescription
PromisedWatchHandleA watch handle which implements the Promise interface.

whenNot(obj, propertyName, callback){WatchHandle}static

Watches a property for becoming falsy. As with watchUtils, the callback is called initially if the property is initially falsy.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback

The function to call when the property changes.

Returns:
TypeDescription
WatchHandleA watch handle.

whenNotOnce(obj, propertyName, callback){PromisedWatchHandle}static

Watches a property for becoming falsy once. As with init(), the callback is called if the property is initially falsy. The returned watch handle is removed after the first time the callback has been invoked.

The returned handle additionally implements the Promise interface and can be used to create a promise chain to asynchronously handle a property value becoming falsy. The promise result is an object containing a value, oldValue, propertyName and target.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback
optional

The function to call when the property changes.

Returns:
TypeDescription
PromisedWatchHandleA watch handle which implements the Promise interface.

whenOnce(obj, propertyName, callback){PromisedWatchHandle}static

Watches a property for becoming truthy once. As with init(), the callback is called if the property is initially truthy. The returned watch handle is removed after the first time the callback has been invoked.

The returned handle additionally implements the Promise interface and can be used to create a promise chain to asynchronously handle a property value becoming truthy. The promise result is an object containing a value, oldValue, propertyName and target.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback
optional

The function to call when the property changes.

Returns:
TypeDescription
PromisedWatchHandleA watch handle which implements the Promise interface.

whenTrue(obj, propertyName, callback){WatchHandle}static

Watches a property for becoming true. As with init(), the callback is called if the property is initially true.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback

The function to call when the property changes.

Returns:
TypeDescription
WatchHandleA watch handle.

whenTrueOnce(obj, propertyName, callback){PromisedWatchHandle}static

Watches a property for becoming true once. As with init(), the callback is called if the property is initially true. The returned watch handle is removed after the first time the callback has been invoked.

The returned handle additionally implements the Promise interface and can be used to create a promise chain to asynchronously handle a property value becoming true. The promise result is an object containing a value, oldValue, propertyName and target.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback
optional

The function to call when the property changes.

Returns:
TypeDescription
PromisedWatchHandleA watch handle which implements the Promise interface.

whenUndefined(obj, propertyName, callback){WatchHandle}static

Watches a property for becoming undefined. As with init(), the callback is called if the property is initially undefined.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback

The function to call when the property changes.

Returns:
TypeDescription
WatchHandleA watch handle.

whenUndefinedOnce(obj, propertyName, callback){PromisedWatchHandle}static

Watches a property for becoming undefined once. As with init(), the callback is called if the property is initially undefined. The returned watch handle is removed after the first time the callback has been invoked.

The returned handle additionally implements the Promise interface and can be used to create a promise chain to asynchronously handle a property value becoming undefined. The promise result is an object containing a value, oldValue, propertyName and target.

Parameters:

The object containing the property to watch.

propertyName String

The name of the property to watch.

callback watchCallback
optional

The function to call when the property changes.

Returns:
TypeDescription
PromisedWatchHandleA watch handle which implements the Promise interface.

Type Definitions

EventAttachedCallback(target, propName, obj, eventName)

Callback to be called when a event handler is either attached or detached.

Parameters:
target *
optional

The target object where the event handle is attached to.

propName String
optional

The watched property.

optional

The watched object.

eventName String
optional

The event name.

PausableWatchHandleObject

Represents a watch created when an object invokes watch().

Properties:
remove Function

Removes the watch handle.

pause Function

Pauses the handle preventing changes to invoke the associated callback.

resume Function

Resumes a paused the handle.

Example:
var handle = watchUtils.pausable(map, 'basemap', function(newVal){
  // Each time the value of map.basemap changes, it is logged in the console
  console.log("new basemap: ", newVal);
});

// When pause() is called on the watch handle, the callback represented by the
// watch is no longer invoked, but is still available for later use
handle.pause();

// When resume() is called on the watch handle, the callback resumes
// firing each time the watched property changes.
handle.resume();

// When remove() is called on the watch handle, the map no longer watches for changes to basemap
handle.remove();

PromisedWatchHandleObject

Represents a watch implementing the Promise interface, created when using any of the watchOnce utility functions.

Properties:
remove Function

Removes the watch handle.

always Function

Adds a callback to be invoked when the promise is resolved or rejected.

cancel Function

Removes the watch handle and informs the deferred it may cancel its asynchronous operation.

isCanceled Function

Checks whether the promise has been canceled.

isFulfilled Function

Checks whether the promise is resolved or rejected.

isRejected Function

Checks whether the promise is rejected.

isResolved Function

Checks whether the promise is resolved.

otherwise Function

Adds a callback to be invoked when the promise is rejected.

Adds a callback to be invoked when the promise is resolved.

Example:
// Animate to the fullExtent of the first layer as soon as the view is
// ready.
watchUtils.whenOnce(view, "ready")
 .then(function(result) {
    // Ensure the layer is loaded before accessing its fullExtent
    return view.map.layers.getItemAt(0).load();
  })
  .then(function(layer) {
    // Animate to the full extent of the layer
    return view.goTo(layer.fullExtent);
  })
  .then(function() {
    // Animation is finished here
    console.log("Animation to first layer extent is finished");
  });

API Reference search results

NameTypeModule

There were no match results from your search criteria.