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
Deprecated since version 4.24. Use reactiveUtils instead.

Various utilities and convenience functions for watching Accessor properties.

See also:

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}
Deprecated since 4.24. Use reactiveUtils.watch() instead.

Watches a property for changes and calls the callback with the initial value of the property. It is recommend to migrate to reactiveUtils.watch(() => obj.propertyName, callback).

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}
Deprecated since 4.24. Use reactiveUtils.on() instead.

Watches a property for changes and automatically attaches and detaches an event handler for a given event to the property value as needed. It is recommended to migrate to reactiveUtils.on(() => obj.propertyName, eventName, eventHandler, options).

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}
Deprecated since 4.24. Use reactiveUtils.once() instead.

Watches a property for changes once. The returned watch handle is removed after the first time the callback has been invoked. It is recommend to migrate to reactiveUtils.once(() => obj.propertyName, abortSignal).

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}
Deprecated Since 4.24.

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}
Deprecated since 4.24. Use reactiveUtils.watch() instead.

Watches a property for changes. This is an alias for Accessor.watch(). It is recommended to migrate to reactiveUtils.watch(() => obj.propertyName, callback).

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}
Deprecated since 4.24. Use reactiveUtils.when() instead.

Watches a property for becoming truthy. It is recommended to migrate to reactiveUtils.when(() => obj.propertyName, callback).

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}
Deprecated since 4.24. Use reactiveUtils.when() instead.

Watches a property for becoming defined. It is recommended to migrate to reactiveUtils.when(() => obj.propertyName !== undefined, callback).

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}
Deprecated since 4.24. Use reactiveUtils.whenOnce() instead.

Watches a property for becoming defined once. It is recommended to migrate to reactiveUtils.whenOnce(() => obj.propertyName !== undefined, abortSignal).

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}
Since: ArcGIS API for JavaScript 4.13
Deprecated since 4.24. Use reactiveUtils.when() instead

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. It is recommended to migrate to reactiveUtils.when(() => obj.propertyName === value, callback). .

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}
Since: ArcGIS API for JavaScript 4.13
Deprecated since 4.24. Use reactiveUtils.whenOnce() instead.

Watches a property for becoming equal with a given value. It is recommended to migrate to reactiveUtils.whenOnce(() => obj.propertyName === value, abortSignal).

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}
Deprecated since 4.24. Use reactiveUtils.when() instead.

Watches a property for becoming false. It is recommended to migrate to reactiveUtils.when(() => obj.propertyName === false, callback).

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}
Deprecated since 4.24. Use reactiveUtils.whenOnce() instead.

Watches a property for becoming false once. It is recommended to migrate to reactiveUtils.when(() => obj.propertyName === false, callback, { once: true }).

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}
Deprecated since 4.24. Use reactiveUtils.when() instead.

Watches a property for becoming falsy. It is recommended to migrate to reactiveUtils.when(() => !obj.propertyName, callback).

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}
Deprecated since 4.24. Use reactiveUtils.whenOnce() instead.

Watches a property for becoming falsy once. It is recommended to migrate to reactiveUtils.whenOnce(() => obj.propertyName === false, abortSignal).

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}
Deprecated since 4.24. Use reactiveUtils.whenOnce() instead.

Watches a property for becoming truthy once. It is recommended to migrate to reactiveUtils.whenOnce(() => obj.propertyName, abortSignal).

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}
Deprecated since 4.24. Use reactiveUtils.when() instead.

Watches a property for becoming true. It is recommended to migrate to reactiveUtils.when(() => obj.propertyName === true, callback).

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}
Deprecated since 4.24. Use reactiveUtils.whenOnce() instead.

Watches a property for becoming true once. It is recommended to migrate to reactiveUtils.when(() => obj.propertyName === true, callback, { once: true }).

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}
Deprecated since 4.24. Use reactiveUtils.when() instead.

Watches a property for becoming undefined. It is recommended to migrate to reactiveUtils.when(() => obj.propertyName === undefined, callback).

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}
Deprecated since 4.24. Use reactiveUtils.whenOnce() instead.

Watches a property for becoming undefined once. It is recommended to migrate to reactiveUtils.whenOnce(() => obj.propertyName === undefined, abortSignal).

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)
Deprecated since version 4.24. Use reactiveUtils.ReactiveListenerChangeCallback() instead.

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
Deprecated since version 4.24.

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', (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
Deprecated since version 4.24. Use Promise instead.

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((result) => {
    // Ensure the layer is loaded before accessing its fullExtent
    return view.map.layers.getItemAt(0).load();
  })
  .then((layer) => {
    // Animate to the full extent of the layer
    return view.goTo(layer.fullExtent);
  })
  .then(() => {
    // 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.