Represents a layer based on data stored in a KML file (.kml or .kmz).

Namespace:  ESRI.ArcGISExplorer.Mapping
Assembly:  ESRI.ArcGISExplorer (in ESRI.ArcGISExplorer.dll) Version: 2.0.0.900 (2.0.0.900)

Syntax

C#
public sealed class KmlLayer : Layer, 
	IMapItemParent
Visual Basic (Declaration)
Public NotInheritable Class KmlLayer _
	Inherits Layer _
	Implements IMapItemParent

Remarks

KML is an XML grammar and file format for modeling and storing documents, folders, placemarks (points, lines, polygons, 3D models) and images which can be draped on the map or positioned in relation to the map window. KML network links are also supported, so you can link to remote KML content.

The layer classes are a subset of MapItems that reference geographic data. A KmlLayer enables KML data (held in a .kml or .kmz file) to be added to the map and displayed by the ArcGIS Explorer application.

When a connected KmlLayer is added to the map, the related data is draped over the basemap (and any existing layers in the map). The layer must be in a connected state before data can be displayed. There are two ways to connect a layer to data:

1. Instantiate a KmlLayer and connect explicitly.

  • Create a new KmlLayer, populate the Path property and call KmlLayer.Connect()
  • A constructor is also provided to allow you to specify the URL or file path when you instantiate a layer. If the properties specified are incorrect, the KmlLayer will remain disconnected but no exception will be thrown; use the ConnectionStatus property to diagnose why a layer could not be connected.

2. Instantiate and connect with a single method call.

  • Use the static Open method to both instantiate a KmlLayer and connect to its underlying data source with a single method call.
  • If successful the Open method will return a connected KmlLayer object. In contrast to the Connect method, an exception will be thrown if the URL or file path specified for the KML file is incorrect. Therefore it is a good idea to wrap a call to the Open method with a try... catch block if you are unsure of the data source to which you are connecting.
  • The URL or file path you specify will be stored in the KmlLayer.Path property.

If a KmlLayer is added to the map in an unconnected state, no data will be displayed. The layer will still appear in the ArcGIS Explorer contents window with an exclamation mark to indicate the layer is not connected.

Once connected, you can access data dependent properties such as the geographical extent of the layer.

KML is typically composed of one or more KML features: a document, folder, placemark, network link or image. Each constituent feature is represented by a KmlNode object. Although the KmlLayer.ChildItems property is a MapItemCollection, it will always return a collection of KmlNode objects and you cannot add to the collection.

Inheritance Hierarchy

System..::.Object
  ESRI.ArcGISExplorer.Mapping..::.MapItem
    ESRI.ArcGISExplorer.Mapping..::.Layer
      ESRI.ArcGISExplorer.Mapping..::.KmlLayer

See Also