Method Overview

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:

obj Accessor 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:

Type	Description
WatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|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:

Type	Description
WatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|String[] The name of the property to watch.

callback watchCallback optional The function to call when the property changes.

Returns:

Type	Description
PromisedWatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|String[] The name of the property to watch.

callback watchCallback optional The function to call when the property changes.

Returns:

Type	Description
PausableWatchHandle	A 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:

obj Accessor 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:

Type	Description
WatchHandle	A watch handle.

See also:

• Accessor.watch()

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:

obj Accessor 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:

Type	Description
WatchHandle	A 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:

obj Accessor 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:

Type	Description
WatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|String[] The name of the property to watch.

callback watchCallback optional The function to call when the property changes.

Returns:

Type	Description
PromisedWatchHandle	A watch handle which implements the Promise interface.

whenEqual(obj, propertyName, value, callback){WatchHandle}static

Since: ArcGIS API for JavaScript 4.13

Watches a property for becoming equal with a given value. The callback will fire after the given property has a value equal to the provided value.

Parameters:

obj Accessor The object containing the property to watch.

propertyName String The name of the property to watch.

value * The value to test with the value of the given property.

callback watchCallback The function to call when the property is equal to the given value.

Returns:

Type	Description
WatchHandle	A watch handle.

Example:

watchUtils.whenEqual(slider, "values.0", 50, function(){
  // do something when the slider's first thumb value is equal to 50
});

watchUtils.whenEqual(slider, "state", "dragging", function(){
  // do something while the user drags the slider thumb(s)
});

whenEqualOnce(obj, propertyName, value, callback){PromisedWatchHandle}static

Since: ArcGIS API for JavaScript 4.13

Watches a property for becoming equal with a given value. The callback will fire after the given property is equal to the provided value for the first time. 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:

obj Accessor The object containing the property to watch.

propertyName String The name of the property to watch.

value * The value to test with the value of the given property.

callback watchCallback optional The function to call when the property is equal to the given value.

Returns:

Type	Description
PromisedWatchHandle	A watch handle which implements the Promise interface.

Example:

watchUtils.whenEqualOnce(slider, "state", "disabled", function(){
  // do something when the slider becomes disabled for the first time
});

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:

obj Accessor 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:

Type	Description
WatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|String[] The name of the property to watch.

callback watchCallback optional The function to call when the property changes.

Returns:

Type	Description
PromisedWatchHandle	A 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:

obj Accessor 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:

Type	Description
WatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|String[] The name of the property to watch.

callback watchCallback optional The function to call when the property changes.

Returns:

Type	Description
PromisedWatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|String[] The name of the property to watch.

callback watchCallback optional The function to call when the property changes.

Returns:

Type	Description
PromisedWatchHandle	A 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:

obj Accessor 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:

Type	Description
WatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|String[] The name of the property to watch.

callback watchCallback optional The function to call when the property changes.

Returns:

Type	Description
PromisedWatchHandle	A 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:

obj Accessor 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:

Type	Description
WatchHandle	A 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:

obj Accessor The object containing the property to watch.

propertyName String|String[] The name of the property to watch.

callback watchCallback optional The function to call when the property changes.

Returns:

Type	Description
PromisedWatchHandle	A 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.

obj Accessor optional The watched object.

eventName String optional The event name.

PausableWatchHandle Object

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();

PromisedWatchHandle Object

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

Properties:

remove Function Removes the watch handle.

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

then Function 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");
  });