watchUtils

Method Overview

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, { initial: 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 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

• Accessor.watch()

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 Maps SDK 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 Maps SDK 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.whenOnce(() => obj.propertyName === false, abortSignal).

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