watchUtils

AMD: require(["esri/core/watchUtils"], (watchUtils) => { /* code goes here */ });
ESM: import * as watchUtils from "@arcgis/core/core/watchUtils";
Object: esri/core/watchUtils
Since: ArcGIS API for JavaScript 4.0

Various utilities and convenience functions for watching Accessor properties.

Method Overview

Name Return Type Summary Object
WatchHandlemore details

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

more detailswatchUtils
WatchHandlemore details

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

more detailswatchUtils
PromisedWatchHandlemore details

Watches a property for changes once.

more detailswatchUtils
PausableWatchHandlemore details

Watches a property for changes.

more detailswatchUtils
WatchHandlemore details

Watches a property for changes.

more detailswatchUtils
WatchHandlemore details

Watches a property for becoming truthy.

more detailswatchUtils
WatchHandlemore details

Watches a property for becoming defined.

more detailswatchUtils
PromisedWatchHandlemore details

Watches a property for becoming defined once.

more detailswatchUtils
WatchHandlemore details

Watches a property for becoming equal with a given value.

more detailswatchUtils
PromisedWatchHandlemore details

Watches a property for becoming equal with a given value.

more detailswatchUtils
WatchHandlemore details

Watches a property for becoming false.

more detailswatchUtils
PromisedWatchHandlemore details

Watches a property for becoming false once.

more detailswatchUtils
WatchHandlemore details

Watches a property for becoming falsy.

more detailswatchUtils
PromisedWatchHandlemore details

Watches a property for becoming falsy once.

more detailswatchUtils
PromisedWatchHandlemore details

Watches a property for becoming truthy once.

more detailswatchUtils
WatchHandlemore details

Watches a property for becoming true.

more detailswatchUtils
PromisedWatchHandlemore details

Watches a property for becoming true once.

more detailswatchUtils
WatchHandlemore details

Watches a property for becoming undefined.

more detailswatchUtils
PromisedWatchHandlemore details

Watches a property for becoming undefined once.

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:
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 esri/core/watchUtils~EventAttachedCallback
optional

Callback called each time the event handler is attached.

detachedHandler esri/core/watchUtils~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:
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 equal to a value. 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

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:
let 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");
  });

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.