Layer Class
Note
Bing Maps Web Control SDK retirement
Bing Maps Web Control SDK is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Web Control SDK until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Web Control SDK until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Web Control SDK will need to be updated to use Azure Maps Web SDK by the retirement date that applies to your Bing Maps for Enterprise account type. For detailed migration guidance, see Migrate from Bing Maps Web Control SDK and Migrate Bing Maps Enterprise applications to Azure Maps with GitHub Copilot.
Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.
The Layer class makes it easy to organize groups of data by storing them in separate layers on the map. Grouping your data into layers provides a number of benefits such as the ability to hide or attach events to all IPrimitive shapes in a layer with a single line of code, while also providing providing a performance benefit over manually looping through each shape and performing these tasks.
Constructor
Layer(id?: string)
Properties
| Name | Type | Description |
|---|---|---|
metadata |
object | Optional property to store any additional metadata for this layer. |
Methods
| Name | Return Type | Description |
|---|---|---|
add(data: IPrimitive or IPrimitive[], index?: number) |
Adds a shapes to the layer, at the specified index if specified. • data: The shape(s) to be added to the layer. • index: The index at which to insert the shape into the layer. |
|
clear() |
Removes all the data in the layer. | |
dispose() |
Cleans up any resources this object is consuming. | |
getId() |
string | Gets the id of the layer. |
getPrimitives() |
IPrimitive[] | Gets an array of shapes that are in the layer. This can be used to iterate over the individual shapes. |
getVisible() |
boolean | Gets a value indicating whether the layer is visible or not. |
getZIndex() |
number | Gets the zIndex of the layer. |
remove(primitive: IPrimitive) |
IPrimitive | Removes a shape from the layer and returns it. |
removeAt(index: number) |
IPrimitive | Removes a shape from the layer at the specified index. |
setPrimitives(primitives: IPrimitive[]) |
Replaces all shapes in the layer with the new array of shapes that have been provided. | |
setVisible(value: boolean) |
Sets whether the layer is visible or not. | |
setZIndex(zIndex: number) |
Sets the zIndex of the layer. See also: zIndexing in Bing Maps V8 |
Events
The Layer class allows you to add events which are triggered when interacting with the IPimitive shapes that are in the layer. The benefit of this is that you only need to add the event on the layer and not on each individual shape. This results in less memory being used by the application and slightly faster response times by the events.
| Name | Arguments | Description |
|---|---|---|
click |
MouseEventArgs | Occurs when the mouse is used to click the map or when a touch end event occurs on an IPrimitive shape in the layer. |
dblclick |
MouseEventArgs | Occurs when the mouse is used to double click the map or when a touch end event occurs on an IPrimitive shape in the layer. |
mousedown |
MouseEventArgs | Occurs when the left mouse button is pressed or a touch start event occurs on an IPrimitive shape in the layer. |
mouseover |
MouseEventArgs | Occurs when the mouse cursor moves over top of the area covered by an IPrimitive shape in the layer. |
mouseout |
MouseEventArgs | Occurs when the mouse cursor moves out of the area covered by an IPrimitive shape in the layer. |
mouseup |
MouseEventArgs | Occurs when the left mouse button is lifted up or when the touch end event occurs on an IPrimitive shape in the layer. |
rightclick |
MouseEventArgs | Occurs when the right mouse button is used to click the map or when a long touch press occurs on an IPrimitive shape in the layer. |
Note for Bing Maps V7 developers: In the Bing Maps V7 SDK, a class called EntityCollection was used to create data layers on the map. This class has been deprecated and replaced with the Layer class. However, to minimize migration efforts we have added an EntityCollection class for backwards compatibility which wraps the Layer class. This wrapper flattens all child entity collections of an EntityCollection into a single layer. This may result in some rendering differences when compared to V7. This EntityCollection class should only be used if migrating an app from V7 that requires minimal code changes.