SceneModifications

AMD: require(["esri/layers/support/SceneModifications"], (SceneModifications) => { /* code goes here */ });
ESM: import SceneModifications from "@arcgis/core/layers/support/SceneModifications.js";
Class: esri/layers/support/SceneModifications
Inheritance: SceneModifications Collection Accessor
Since: ArcGIS Maps SDK for JavaScript 4.16

A collection of SceneModification with polygons and types to apply client-side modifications. The SceneModifications could be applied to the IntegratedMeshLayer.modifications property.

The modifications for IntegratedMeshLayer need to be in the same spatial reference as the IntegratedMeshLayer. Reprojection between WGS84 and WebMercator will be done automatically. Reprojection of the geometry to other spatial references can be done with the client-side projection engine.

See also

Constructors

SceneModifications

Constructor
new SceneModifications(properties)
Parameter
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class

The name of the class.

Accessor

The number of items in the Collection.

Collection

Property Details

declaredClass

Inherited
Property
declaredClass Stringreadonly
Inherited from Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

length

Inherited
Property
length Number
Inherited from Collection

The number of items in the Collection.

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class

Adds a single item to the collection.

Collection

Adds one or more handles which are to be tied to the lifecycle of the object.

Accessor

Adds multiple items to the collection.

Collection
*

Returns the item at the specified index, allowing for positive and negative integers.

Collection

Creates a clone of this object.

SceneModifications

Creates a new Collection containing the items in the original Collection joined with the items in the input array or Collection.

Collection

Removes and destroys instances of all the items of the Collection.

Collection
*

Removes each item in the input array and destroys it.

Collection

Emits an event on the instance.

Collection

Determines whether all items in the Collection pass a test defined by callback.

Collection

Filters the Collection's items based on a test defined by the callback function.

Collection
*

Returns an item in the Collection if that item passes a test as defined in the callback function.

Collection

Returns the index of an item in the Collection if that item passes a test as defined in the callback function.

Collection

Flattens a hierarchical Collection containing at least one child collection.

Collection

Executes the input function for each item in the Collection.

Collection
*

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product.

SceneModifications
*

Returns the item at the specified index.

Collection

Indicates whether there is an event listener on the instance that matches the provided event name.

Collection

Returns true if a named group of handles exist.

Accessor

Tests if an item is present in the new Collection.

Collection

Returns the index of an element in the collection.

Collection

Creates a string representation of the items in the Collection.

Collection

Returns the last index of an element in the collection.

Collection

Passes each Collection item into the callback function and returns a new array of the returned values.

Collection

Registers an event handler on the instance.

Collection
*

Removes the last item from the collection and returns it.

Collection

Adds an item(s) to the end of the collection.

Collection
*

Reduces all items in the collection (from left to right) into a single variable using callback.

Collection
*

Reduces all items in the collection (from right to left) into a single variable using callback.

Collection

Removes an item from the collection.

Collection

Removes all items from the collection.

Collection
*

Removes an item from the collection at a specified index.

Collection

Removes a group of handles owned by the object.

Accessor
*

Removes each item in the input array.

Collection
*

Moves an item in the Collection to a specified index.

Collection

Reverses the collection in place.

Collection
*

Removes the first item from the collection (at index 0), and returns it.

Collection

Creates a new Collection comprised of a portion of the original Collection.

Collection

Determines whether an item in the Collection passes a test defined by callback.

Collection

Sorts the Collection in place.

Collection

Removes existing items and/or adds new items to the collection.

Collection

Returns a new array object containing the Collection's items.

Collection

Converts an instance of this class to its ArcGIS portal JSON representation.

SceneModifications

Adds one or more items to the beginning of the collection.

Collection

Method Details

add

Inherited
Method
add(item, index)
Inherited from Collection

Adds a single item to the collection. The change event is fired after an item is added to the Collection.

Parameters
item *

The item to add.

index Number
optional

Zero-based index of where in the collection to add the item. If not specified, the items will be added at the end.

Example
let gpc = new Graphic();  // Creates a new graphic
let layer = new GraphicsLayer(); // Creates a new graphics layer
layer.graphics.add(gpc);  // Adds graphic to layer's graphics collection

addHandles

Inherited
Method
addHandles(handleOrHandles, groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, addHandles added at 4.25.

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();
Parameters
handleOrHandles WatchHandle|WatchHandle[]

Handles marked for removal once the object is destroyed.

groupKey *
optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

addMany

Inherited
Method
addMany(items, index)
Inherited from Collection

Adds multiple items to the collection. The change event is fired after items are added to the Collection.

Parameters

An array or collection of items to add.

index Number
optional

Zero-based index of where in the collection to add the items. If not specified, the items will be added at the end.

Example
// Creates two new graphics
let gpc1 = new Graphic();
let gpc2 = new Graphic();

let layer = new GraphicsLayer(); // Creates a new graphics layer

// Adds both graphics to layer's graphics collection
layer.graphics.addMany([gpc1, gpc2]);

at

Inherited
Method
at(index){*}
Inherited from Collection
Since: ArcGIS Maps SDK for JavaScript 4.23 Collection since 4.0, at added at 4.23.

Returns the item at the specified index, allowing for positive and negative integers. Negative integers count back from the last item in the array.

Parameter
index Number

Index of the item in the Collection to retrieve. It can be a relative index from the end of the Collection.

Returns
Type Description
* The item in the Collection stored at the specified index.
Example
// get the layer at the first position
let firstLayer = map.layers.at(0);
// get the layer at the last position
let lastLayer = map.layers.at(-1);

clone

Method
clone(){SceneModifications}

Creates a clone of this object.

Returns
Type Description
SceneModifications A clone of the SceneModifications instance that invoked this method.

concat

Inherited
Method
concat(value){Collection}
Inherited from Collection

Creates a new Collection containing the items in the original Collection joined with the items in the input array or Collection.

Parameter

The array or Collection to append to the existing Collection.

Returns
Type Description
Collection A new Collection comprised of the items in the Collection that invoked this method combined with the input items.
Example
// creating a collection of all the basemap's layers.
let basemap = map.basemap;
let basemapLayers = basemap.baseLayers.concat(basemap.referenceLayers);

destroyAll

Inherited
Method
destroyAll()
Inherited from Collection
Since: ArcGIS Maps SDK for JavaScript 4.30 Collection since 4.0, destroyAll added at 4.30.

Removes and destroys instances of all the items of the Collection.

destroyMany

Inherited
Method
destroyMany(items){*}
Inherited from Collection
Since: ArcGIS Maps SDK for JavaScript 4.30 Collection since 4.0, destroyMany added at 4.30.

Removes each item in the input array and destroys it. If an item is present multiple times in the collection, only the first occurrence is removed and destroyed. The change event is fired after an item is removed from the Collection.

Parameter

The items to remove and destroy.

Returns
Type Description
* The removed and destroyed items present in the collection.

emit

Inherited
Method
emit(type, event){Boolean}
Inherited from Collection

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters
type String

The name of the event.

event Object
optional

The event payload.

Returns
Type Description
Boolean true if a listener was notified

every

Inherited
Method
every(callback){Boolean}
Inherited from Collection

Determines whether all items in the Collection pass a test defined by callback. Each item in the Collection is passed into the callback until one returns a value of false.

Parameter
callback ItemTestCallback

The function to call for each item in the Collection.

Returns
Type Description
Boolean Returns true if every call to the callback function returned true. Returns false if at least one call to the callback returned false.
Example
let meetsStandardSize = graphicsLayer.graphics.every(function(item, i){
  // Tests each geometry's area to see if it is greater than 1,000 acres
  return calculateArea(item.geometry) > 1000;
});

filter

Inherited
Method
filter(callback){Collection}
Inherited from Collection

Filters the Collection's items based on a test defined by the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

Parameter
callback ItemTestCallback

The function that defines a test for determining whether to return the item in a new Collection.

Returns
Type Description
Collection Returns a new Collection containing the items that passed the filter test.
Example
// filteredLayers is a Collection of all the non-visible layers in the map
let filteredLayers = map.layers.filter(function(layer){
  return !layer.visible;
});

find

Inherited
Method
find(callback){*}
Inherited from Collection

Returns an item in the Collection if that item passes a test as defined in the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

Parameter
callback ItemTestCallback

The testing function that will assess each item in the Collection. Returns true if an item passes the test and false if it fails.

Returns
Type Description
* The first item in the Collection that satisfies the test function.
Example
// If the id of a map layer is already known, get the layer that matches the id
let myLayer = map.layers.find(function(layer){
  return layer.id === "speciesLyr01";
});
// myLayer references the layer in map with ID "speciesLyr01"

findIndex

Inherited
Method
findIndex(callback){Number}
Inherited from Collection

Returns the index of an item in the Collection if that item passes a test as defined in the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

Parameter
callback ItemTestCallback

The testing function that will assess each item in the Collection. Returns true if an item passes the test and false if it fails.

Returns
Type Description
Number Returns the index of the Collection item that satisfies the test function. If an item fails the test, -1 is returned.
Example
// gpcIndex is assigned the index of the first graphic whose name
// property is 'Redlands'. This result can be used in getItemAt()
let gpcIndex = graphicsLyr.graphics.findIndex(function(item){
  return item.attributes.name === "Redlands";
});

flatten

Inherited
Method
flatten(callback){Collection}
Inherited from Collection

Flattens a hierarchical Collection containing at least one child collection. Each item in the collection is passed into the callback function, which should check for child collections specified by the developer. A flat collection of all items (parent and children) is returned.

This is useful for scenarios where the user would like to search all the layers in a map, including a GroupLayer's layers and a MapImageLayer's sublayers. The callback should return the sub-collection of the item. If multiple levels of collections exist in the hierarchy, then this method recursively executes for all sub-collections.

Parameter
callback ItemCallback

A function that will assess each item in the Collection.

Returns
Type Description
Collection Returns a flat collection of all items in the original collection and their children.
Example
// create a MapImageLayer with several sublayers and add to a map
// containing another GraphicsLayer
let layer = new MapImageLayer({ sublayers: [ ... ] });
let map = new Map({
  layers: [ layer, new GraphicsLayer() ]
});

// A flat collection of all layers and sublayers
// (if layer is a MapImageLayer) in the map.
// This collection may be searched or used for other purposes
let allLayersAndSublayers = map.layers.flatten(function(item){
  return item.layers || item.sublayers;
});

forEach

Inherited
Method
forEach(callback)
Inherited from Collection

Executes the input function for each item in the Collection.

Parameter
callback ItemCallback

The function to call for each item in the Collection.

Example
graphicsLayer.graphics.forEach(function(item, i){
  // Do something here to each graphic like calculate area of its geometry
  calculateArea(item.geometry);
});

fromJSON

Method
fromJSON(json){*}static

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameter
json Object

A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns
Type Description
* Returns a new instance of this class.

getItemAt

Inherited
Method
getItemAt(index){*}
Inherited from Collection

Returns the item at the specified index.

Parameter
index Number

Zero-based index of the item in the Collection to retrieve.

Returns
Type Description
* The item in the Collection stored at the specified index.
Example
// Assigns the base layer at index 0 to baseLayer
let baseLayer = map.basemap.baseLayers.getItemAt(0);

hasEventListener

Inherited
Method
hasEventListener(type){Boolean}
Inherited from Collection

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameter
type String

The name of the event.

Returns
Type Description
Boolean Returns true if the class supports the input event.

hasHandles

Inherited
Method
hasHandles(groupKey){Boolean}
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, hasHandles added at 4.25.

Returns true if a named group of handles exist.

Parameter
groupKey *
optional

A group key.

Returns
Type Description
Boolean Returns true if a named group of handles exist.
Example
// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

includes

Inherited
Method
includes(searchElement){Boolean}
Inherited from Collection

Tests if an item is present in the new Collection.

Parameter
searchElement *

The item to search for in the collection.

Returns
Type Description
Boolean true if the item is in the collection.
Example
// check if a layer is in the map's operational layers.
if (view.map.layers.includes(myLayer)) {
  // ...
}

indexOf

Inherited
Method
indexOf(searchElement, fromIndex){Number}
Inherited from Collection

Returns the index of an element in the collection.

Parameters
searchElement *

Item to search for in the collection.

fromIndex Number
optional

Use if you don't want to search the whole collection or you don't want to search from the start.

Returns
Type Description
Number The location of the first match found in the collection, or -1 if there is no match.
Example
// index is the index of the first graphic in the
// graphics layer that matches the input graphic
let index = graphicsLayer.graphics.indexOf(graphic);

join

Inherited
Method
join(separator){String}
Inherited from Collection

Creates a string representation of the items in the Collection.

Parameter
separator String
optional
Default Value: ,

The separator used between each item in the final string.

Returns
Type Description
String The string representation of the items.
Example
let stringCollection = new Collection(["how", "are", "you", "doing?"]);
let phrase = stringCollection.join(" ");

// Prints "how are you doing?"
console.log(phrase);

lastIndexOf

Inherited
Method
lastIndexOf(searchElement, fromIndex){Number}
Inherited from Collection

Returns the last index of an element in the collection.

Parameters
searchElement *

Item to search for in the collection.

fromIndex Number
optional

Use if you don't want to search the whole collection, or you don't want to search from the end.

Returns
Type Description
Number The location of the last match found in the collection, or -1 if there is no match.
Example
// index is the index of the first graphic in the
// graphics layer that matches the input graphic
let index = graphicsLayer.graphics.lastIndexOf(graphic);

map

Inherited
Method
map(callback){Collection}
Inherited from Collection

Passes each Collection item into the callback function and returns a new array of the returned values. For example, if you have a Collection of numbers and would like to add each number by 10, you can use map() to create a new Collection with the same numbers incremented by 10.

Parameter
callback ItemMapCallback

The function that processes each item in the Collection and returns a new value at the same index of the original item.

Returns
Type Description
Collection Returns a new collection containing the new items generated from the callback.
Example
// Gets the geometries of the graphics and assigns them to a new Collection
let geometries = graphicsLayer.graphics.map(function(item, i){
  return item.geometry;
});

on

Inherited
Method
on(type, listener){Object}
Inherited from Collection

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters

An event or an array of events to listen for.

listener Function

The function to call when the event fires.

Returns
Type Description
Object Returns an event handler with a remove() method that should be called to stop listening for the event(s).
Property Type Description
remove Function When called, removes the listener from the event.
Example
view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

pop

Inherited
Method
pop(){*}
Inherited from Collection

Removes the last item from the collection and returns it.

Returns
Type Description
* The last item in the collection.
Example
// Removes the last layer in the map and stores it in lastLayer
let lastLayer = map.layers.pop();

push

Inherited
Method
push(item){Number}
Inherited from Collection

Adds an item(s) to the end of the collection.

Parameter
item *

An item or comma-separated list of items to add to the end of the collection.

Returns
Type Description
Number The new length of the collection.
Examples
// Adds a new graphic to the end of the graphics collection on a GraphicsLayer
graphicsLyr.graphics.push(newGraphic);
// Adds three new graphics to the end of the GraphicsLayer's graphics collection
graphicsLyr.graphics.push(g1, g2, g3);

reduce

Inherited
Method
reduce(callback){*}
Inherited from Collection

Reduces all items in the collection (from left to right) into a single variable using callback.

Parameter

The function that processes each item in the Collection and appends it to the previous item.

Returns
Type Description
* Returns the value representing the reduction of the Collection's items.

reduceRight

Inherited
Method
reduceRight(callback, initialValue){*}
Inherited from Collection

Reduces all items in the collection (from right to left) into a single variable using callback.

Parameters

The function that processes each item in the Collection and appends it to the previous item.

initialValue *
optional

Item to use as the first element to process in callback.

Returns
Type Description
* Returns the value representing the reduction of the Collection's items.

remove

Inherited
Method
remove(item)
Inherited from Collection

Removes an item from the collection. The change event is fired after an item is removed from the Collection.

Parameter
item *

The item to remove.

Example
let layer = map.layers.at(4);
// Removes the fifth layer from the map
map.layers.remove(layer);

removeAll

Inherited
Method
removeAll()
Inherited from Collection

Removes all items from the collection.

Example
// Removes all layers from the map
map.layers.removeAll();

removeAt

Inherited
Method
removeAt(index){*}
Inherited from Collection

Removes an item from the collection at a specified index. The change event is fired after an item is removed from the Collection.

Parameter
index Number

The index of the item to remove.

Returns
Type Description
* The removed item if present in the collection, undefined otherwise.
Example
// Removes the layer at index 4 of the map
map.layers.removeAt(4);

removeHandles

Inherited
Method
removeHandles(groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, removeHandles added at 4.25.

Removes a group of handles owned by the object.

Parameter
groupKey *
optional

A group key or an array or collection of group keys to remove.

Example
obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

removeMany

Inherited
Method
removeMany(items){*}
Inherited from Collection

Removes each item in the input array. If an item is present multiple times in the collection, only the first occurrence is removed. The change event is fired after an item is removed from the Collection.

Parameter

The items to remove.

Returns
Type Description
* The removed items present in the collection.
Example
let refLayers = [refLyr1, refLyr2, refLyr3];
// Removes three reference layers in the refLayers
// collection from the basemap's referenceLayers
map.basemap.referenceLayers.removeMany(refLayers);

reorder

Inherited
Method
reorder(item, index){*}
Inherited from Collection

Moves an item in the Collection to a specified index. The change event is fired after an item is moved in the Collection.

Parameters
item *

The item to move.

index Number

The index to move the item to.

Returns
Type Description
* The item that was moved. undefined if item is not in the collection
Example
// Get the first two layers in a map
let layer1 = map.layers.at(0);
let layer2 = map.layers.at(1);

// Moves the second layer to the first position in the map.layers Collection
// effectively swapping the positions of layer1 and layer2
map.layers.reorder(layer2, 0);

reverse

Inherited
Method
reverse(){Collection}
Inherited from Collection

Reverses the collection in place.

Returns
Type Description
Collection The reversed collection.
Example
// Reverse layers from the map
map.layers.reverse();

shift

Inherited
Method
shift(){*}
Inherited from Collection

Removes the first item from the collection (at index 0), and returns it. The remaining items of the collection are then shifted down one index from their previous location.

Returns
Type Description
* The first item in the collection.
Example
// Removes the first layer in the map and stores it in firstLyr
let firstLyr = map.layers.shift();

slice

Inherited
Method
slice(begin, end){Collection}
Inherited from Collection

Creates a new Collection comprised of a portion of the original Collection.

Parameters
begin Number
optional

The index of the first item to extract.

end Number
optional

The index of the last item to extract.

Returns
Type Description
Collection Returns a new Collection containing the items in the specified range.
Example
// get the graphics from index 50 to 100;
let selection = graphicsLayer.graphics.slice(50, 100);

some

Inherited
Method
some(callback){Boolean}
Inherited from Collection

Determines whether an item in the Collection passes a test defined by callback. Each item in the Collection is passed into the callback until one returns a value of true.

Parameter
callback ItemCallback

The function that defines the test for each Collection item.

Returns
Type Description
Boolean Returns true if any of the items in the Collection pass the test defined in callback. Returns false if all items fail the test.
Example
// If at least one of the point graphics has a geometry whose
// elevation is above 1000m, then passes will have a value of true.
// Otherwise, it will be false.
let passes = graphicsLayer.graphics.some(function(item, i){
  return item.geometry.z > 1000;
});

sort

Inherited
Method
sort(compareFunction)
Inherited from Collection

Sorts the Collection in place.

Parameter
compareFunction ItemCompareCallback
optional

The function that defines a comparison of two items in the collection.

Example
// Sort graphics based on their elevation or z-value
let sortedGraphics = graphicsLayer.graphics.sort(function(a, b){
  if(a.geometry.z > b.geometry.z){
    return 1;
  }
  else if (a.geometry.z < b.geometry.z){
    return -1;
  }
  else {
    return 0;
  }
});

splice

Inherited
Method
splice(start, deleteCount, items){Array}
Inherited from Collection

Removes existing items and/or adds new items to the collection.

Parameters
start Number

Index at which to start changing the collection.

deleteCount Number

Indicates the number of collection items to remove. If 0 is used then no elements are removed and at least one new item should be added in the items parameter.

items *

The item or comma-separated list of items to add to the collection.

Returns
Type Description
Array An array of the deleted items formerly part of the collection.
Examples
// map.layers is a collection of 6 layers
// Adds a seventh layer to the map at index 3
map.layers.splice(3, 0, layer7);
// Removes two layers starting from index 2 and adds the
// specified layers in the positions of the former layers
let oldLayers = map.layers.splice(2, 2, layer8, layer9, layer10);

// oldLayers = [layer2, layer3]

toArray

Inherited
Method
toArray(){Array}
Inherited from Collection

Returns a new array object containing the Collection's items.

Returns
Type Description
Array An array containing the Collection's items.
Example
// Creates an array populated with the map's layers
let mapLayersArray = map.layers.toArray();

toJSON

Method
toJSON(){Object}

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.

Returns
Type Description
Object The ArcGIS portal JSON representation of an instance of this class.

unshift

Inherited
Method
unshift(items){Number}
Inherited from Collection

Adds one or more items to the beginning of the collection.

Parameter
items *

The item(s) to add to the beginning of the collection.

Returns
Type Description
Number The new length of the collection.
Example
// If a map's basemap has 3 baseLayers: baseLyr0, baseLyr1, baseLyr2
map.basemap.baseLayers.unshift(baseLyr3);

// Now the baseLayers collection is: baseLyr3, baseLyr0, baseLyr1, baseLyr2

Event Overview

Show inherited events Hide inherited events
Name Type Summary Class
{item: *}

Fires after an item has been added to the collection.

Collection

Fires after an item has been added, reordered or removed from the collection.

Collection
{item: *}

Fires after an item has been removed from the collection.

Collection
{cancellable: Boolean,defaultPrevented: Boolean,item: *,preventDefault: Function}

Fires before an item is added to the collection.

Collection
{cancellable: Boolean,defaultPrevented: Boolean,item: *,preventDefault: Function}

Fires before any modifications are performed on the collection.

Collection
{cancellable: Boolean,defaultPrevented: Boolean,item: *,preventDefault: Function}

Fires before an item has been removed from the collection.

Collection
{added: Array,moved: Array,removed: Array}

Fires after an item has been added, reordered, or removed from the Collection.

Collection

Event Details

after-add

Inherited
Event
after-add
Inherited from Collection

Fires after an item has been added to the collection.

Property
item *

The item added to the collection.

Example
// indicates a layer has been added to the map
map.layers.on("after-add", function(event){
  console.log(event.item, " has been added to the map.");
});

after-changes

Inherited
Event
after-changes
Inherited from Collection

Fires after an item has been added, reordered or removed from the collection.

Example
map.layers.on("after-changes", function(event){
  console.log(event, " layer was added/removed from the map.");
});

after-remove

Inherited
Event
after-remove
Inherited from Collection

Fires after an item has been removed from the collection.

Property
item *

The item to remove from the collection.

Example
// indicates a layer has been removed from the map
map.layers.on("after-remove", function(event){
  console.log(event.item, " has been removed from the map.");
});

before-add

Inherited
Event
before-add
Inherited from Collection

Fires before an item is added to the collection. This event can be used to prevent an item from being added to the collection by cancelling it with the event.preventDefault() method.

Properties
cancellable Boolean

Indicates if the change event can be cancelled.

defaultPrevented Boolean

Indicates if this event has previously been cancelled by another event handler.

item *

The item to add to the collection.

preventDefault Function

A method that prevents the item from being added to the collection.

Example
// prevents a layer from being added to the map more than once.
map.layers.on("before-add", function(event){
   if(map.layers.includes(event.item)){
     event.preventDefault();
     console.log("layer already exists in map.");
   }
});

before-changes

Inherited
Event
before-changes
Inherited from Collection

Fires before any modifications are performed on the collection. This event can be used to prevent an item from being added or removed from the collection by cancelling it with the event.preventDefault() method.

Properties
cancellable Boolean

Indicates if the change event can be cancelled.

defaultPrevented Boolean

Indicates if this event has previously been cancelled by another event handler.

item *

The item to add or remove from the collection.

preventDefault Function

A method that prevents the item from being added or removed from the collection.

Example
map.layers.on("before-changes", function(event){
  // prevents layers from being added/removed from the map
  event.preventDefault();
});

before-remove

Inherited
Event
before-remove
Inherited from Collection

Fires before an item has been removed from the collection. This event can be used to prevent an item from being removed from the collection by cancelling it with the event.preventDefault() method.

Properties
cancellable Boolean

Indicates if the change event can be cancelled.

defaultPrevented Boolean

Indicates if this event has previously been cancelled by another event handler.

item *

The item to remove from the collection.

preventDefault Function

A method that prevents the item from being removed from the collection.

Example
// prevents a layer from being removed from the basemap
map.basemap.baseLayers.on("before-remove", function(event){
   if(map.basemap.baseLayers.includes(event.item)){
     event.preventDefault();
     console.log("layer cannot be removed from basemap.");
   }
});

change

Inherited
Event
change
Inherited from Collection

Fires after an item has been added, reordered, or removed from the Collection. Using methods of other classes that affect properties of type Collection will also cause this event to fire, such as Map.add(), Map.remove(), Map.reorder().

For example, map.layers.add(newLyr) and map.add(newLyr) which uses Map.add() to add a new layer to the map.layers collection will cause this event to fire.

The change event can be used to notify the developer/user of changes to the collection. The arrays in the collection event objects are reused. Make a copy of the collection event object if these objects need to be processed in your application.

Properties
added Array

An array of items added to the collection using either add() or addMany().

moved Array

An array of items that moved in the collection using reorder().

removed Array

An array of items removed from the collection using either remove(), removeMany(), removeAt(), or removeAll().

Example
// This function will fire each time a layer is either added,
// moved, or removed from the map.layers Collection
// make a copy of the collection event object for processing
map.layers.on("change", function(event){
  const copiedEvent = JSON.parse(JSON.stringify(event));
  let newLayers = copiedEvent.added; // An array of layers added to the map.layers Collection
  let reorderedLayers = copiedEvent.moved;  // An array of layers moved in the Collection
  let removedLayers = copiedEvent.removed;  // An array of layers removed from map
});

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