Mapping

Additional assembly information: Contents, Object Model Diagram
The mapping namespace contains classes that allow you to interact with the map in the ArcGIS Explorer application. This enables you to accomplish common mapping operations such a s zooming to a specific location or adding your own spatial data to the map. The map window within the ArcGIS Explorer application is represented by the MapDisplay class and provides methods for navigation, capturing user-defined shapes (tracking) and switching between 2D and 3D. In addition, you can also obtain a Map object from the MapDisplay; the Map allows you to add different types of content to the map, and arrange existing content into a logical hierarchy. An individual unit of map content can be described as a MapItem, for example a Note or a View. Layers are a subset of MapItems that reference geographic data.

See the following sections for more information about this namespace:

An introduction to MapItems
Map content is represented by a number of classes, all of which inherit from the MapItem abstract class. The MapItem class defines members like ID and Name that are shared by all concrete MapItem types. Each derived type of MapItem can be thought of as a building block of map content. When you add a MapItem to a Map it appears in the application table of contents, and if the MapItem has associated data or graphics, they will be drawn on the map. The table below gives a brief description of each MapItem type.

Table 1: MapItem Types

MapItem
Description
Folder
A container used to organize MapItems into logical groups
Note
A graphic shape tagged with text
View
A stored location in 2D or 3D space tagged with text
Link
A link to an external webpage, file or application
ImageOverlay
An image positioned on top of the map display
Layers
There are multiple Layer classes which allow visualization of spatial data: FeatureLayer, RasterLayer, ServiceLayer, KmlLayer, PackageLayer
KmlNode
A constituent part of a KmlLayer
PackageChildLayer
A constituent part of a PackageLayer
ServiceChildLayer
A constituent part of a ServiceLayer
Basemap
The background layers displayed in the map
MapItems can be broadly split between items that reference geographic data (Layer types) and items that do not rely on a geographic data source. As an end user of the ArcGIS Explorer application, you can create Notes, Folders, Views and Links, and you can do the same programmatically using MapItem types of the same name. Layer types are MapItems too, but they are slightly more complex. Each derived Layer class references spatial data held in storage or provided by a service.

MapItem Types

This section introduces the independent MapItem types, for more information on Layers please refer to: Visualizing spatial data using Layers.

Folder

The Folder class is used to organize MapItems into logical groups which becomes increasingly important when you are trying to present a lot of information in a Map. The Folder.ChildItems property is a MapItemCollection, just like Map.ChildItems, and similarly you can use the Add and Remove methods on MapItemCollection to control the content of the Folder.

Note

The Note class provides the ability to tag a Graphic with text, XML or HTML content. The Graphic class represents a simple shape comprising of a Geometry object and a Symbol. When a Note is added to a map, the associated graphic will be drawn on the map.
 
Use the Popup property to set the content and size for a Note pop-up. The content will be shown to in a pop-up window when a Notes pop-up is invoked. You would typically use a Note to store a graphic in the map alongside an explanation of what the graphic signifies.

View

The View class represents a view of the map (a Viewpoint) tagged with text, XML or HTML content. The Viewpoint class enables you to store a location in either 2D space (using an envelope and optional rotation) or 3D space (using an Observer\Target pair of points). View is similar to the Note class, in that you use the Popup property to set the content of the associated pop-up. You would usually use a View to remember a location and store an explanation of what the location signifies.

Link

The Link class represents a relation to a webpage, file or external application. Use the Path property to specify the path to a file\application, or the URL to a webpage. Links open externally to the ArcGIS Explorer application. Operating System defaults will determine the external application that is launched.

ImageOverlay

The ImageOverlay class represents an image positioned on top of the map. You can use either an in-memory bitmap, or the path to an image file to create an image overlay. The DisplayPosition enumeration determines the overlay position in relation to the map.

Basemap

The basemap contains one or more layers that are displayed as a single entity underneath all other layers in a map. The background layers provide context when working with other items in a map, such as layers and notes. The Map.Basemap property allows you to access or change the maps current basemap.
Although basemap derives from MapItem, it cannot be added to a MapItemCollection like other MapItem types; doing so will result in an ArgumentException. Use the Map.Basemap property to access or change the maps current basemap.

Visualizing spatial data using Layers

Layer MapItem Types

All layer types inherit from the layer abstract class, defining members common to all concrete layer types. Each layer type references spatial data held in storage, or provided by a service.
  • FeatureLayer—Spatial vector data stored in a shapefile or geodatabase.
  • RasterLayer—Raster data stored in a file or geodatabase.
  • ServiceLayer—Spatial data provided by a map service. Supported services are: ArcGIS Server (Map and Globe), ArcIMS, WMS and Bing Services. Composed of one or more ServiceChildLayers.
  • KmlLayer—Spatial vector data stored in a KML file (.kml). Composed of one or more KmlNodes.
  • PackageLayer—Spatial data stored in a layer package (.lpk). Composed of one or more PackageChildLayers.
A layer can be connected to, and disconnected from its underlying data source. Depending on the layer type, it is sometimes possible to access the underlying spatial data for a layer once it has been connected. For example, when a FeatureLayer is connected, it is possible to access the underlying spatial data using the Table property.

Connecting a Layer to a Data Source

The data referenced by a layer can only be drawn on the map if the layer is connected. Use the Connect and Disconnect methods to control connection state.
A layer cannot be connected if the data source is not accessible, or if the specified connection credentials are incorrect. To diagnose a connection problem, use the Layer.ConnectionStatus property. This class provides feedback about why a layer could not be connected.

Changing FeatureLayer symbology

The FeatureLayer.Renderer property specifies how spatial data should be symbolized when it is added to a map. The Renderer property is always populated with a FeatureRenderer object. Use the SetSymbol method to specify the symbol you would like to use to represent the data in the layer. The symbol type used for the renderer will depend on the geometry type of the FeatureLayer.
If the renderers symbol is not set, the FeatureLayer will be symbolized using the ArcGIS Explorer default for the geometry type.

Symbols

The Symbol class specifies how geometrical shapes are drawn when they are added to a map. Symbol types vary according to the geometry being symbolized. The table below indicates the type of symbol that should be used for a specified geometry, and ArcGIS Explorer symbol defaults.
Geometry Type
Symbol Type
ArcGIS Explorer Default
Point and Multipoint
Marker
Orange Stickpin
Polyline
Line
Red Solid Line
Polygon and Multipatch
Fill
Red Solid Fill

Creating Symbols

The Symbol class contains a number of static properties which return pre-configured symbols. You can also use the static CreateLine and CreateFill methods to create symbols with other colors. The color, size and outline can still be modified after a symbol has been created. You can create your own custom marker symbol from an image file or in-memory bitmap. An image file can be specified using a URI or a local path.
If a local path to an image is used to create a custom MarkerSymbol, the image will be saved to the map document. If a URI is used, the image will be referenced rather than embedded- only the URI will be stored in the map document.
The code example below illustrates how to obtain a Marker, Line and Fill symbol using the static properties and methods.
[C#] 
//Create pre-configured Symbols
Symbol flagMarker = Symbol.Marker.Flag.Checkered;
Symbol purpleLine = Symbol.Line.Solid.Purple;

//Change symbol properties
Symbol orangeFill = Symbol.Fill.Solid.Orange;
orangeFill.OutlineColor = Color.Black;

//Use static methods to create your own symbols
Symbol customMarker = Symbol.CreateMarker(@"C:\Images\car.jpg");
Symbol azureLine = Symbol.CreateLine(Color.Azure);
Symbol greenFill = Symbol.CreateFill(Color.Green);
[VB.NET] 
'Create pre-configured Symbols
Dim flagMarker As Symbol = Symbol.Marker.Flag.Checkered
Dim purpleLine As Symbol = Symbol.Line.Solid.Purple

'Change Symbol properties
Dim orangeFill As Symbol = Symbol.Fill.Solid.Orange
orangeFill.OutlineColor = Color.Black

'Use static methods to create your own symbols
Dim customMarker As Symbol = Symbol.CreateMarker("C:\Images\car.jpg")
Dim azureLine As Symbol = Symbol.CreateLine(Color.Azure)
Dim greenFill As Symbol = Symbol.CreateFill(Color.Green)

Layer Drawing Order

The drawing order of Layers in a Map is controlled using a LayerOrderCollection object obtained from the Map.LayerDrawingOrder property. You cannot add or remove layers directly from the LayerOrderCollection: the contents of the collection are driven by the layers currently contained by the map. Each layer has a DrawIndex property that returns the indexed position within the LayerDrawingOrder collection. When a layer is added to the map, it is automatically added at a DrawIndex of zero, which means it draws on top of other layers in the map. The LayerOrderCollection class has methods to change the order in which layers are drawn on the map: Move, MoveUp, MoveDown, MoveToTop and MoveToBottom.
The basemap will always draw underneath all layers, notes and graphics in a Map.

Managing map content: The Map class
The Map class represents a container of MapItems. A Map cannot be explicitly instantiated; it is always obtained using the Map property on MapDisplay. The Map.ChildItems property enables you to manage the content stored by a map. ChildItems is a MapItemCollection: add a MapItem to the collection and it will be added to the map in the application. The ArcGIS Explorer application will respond in different ways depending on the type of MapItem you add. All ChildItems will be displayed in the application table of contents, however only MapItems with associated graphics or spatial data will be displayed in the map. The code example below illustrates how instantiate a FeatureLayer (a type of MapItem), add the layer to the Map.
[C#] 
//Instantiate a layer connected to the mountains shapefile   
try
{
    //Instantiate a layer using the mountains table in the Scotland geodatabase
    FeatureLayer mountainsLayer = FeatureLayer.OpenShapefile(@
        "C:\Data\mountains.shp");

    //Obtain the Map from the Application
    Map map = Application.ActiveMapDisplay.Map;

    //Add the layer to the map
    map.ChildItems.Add(mountainsLayer);
}

catch (ConnectionException ex)
{
    //Could not connect to the mountains shapefile- print the error message
    System.Diagnostics.Debug.Print(ex.Message);
}
[VB.NET] 
Try
'Instantiate a layer using the mountains table in the Scotland geodatabase
Dim mountainsLayer As FeatureLayer = FeatureLayer.OpenShapefile("C:\Data\mountains.shp")

'Obtain the Map from the Application
Dim map As Map = Application.ActiveMapDisplay.Map

'Add the layer to the map
map.ChildItems.Add(mountainsLayer)

Catch ex As ConnectionException
'Could not connect to the mountains shapefile- print the error message
System.Diagnostics.Debug.Print(ex.Message)
End Try
Changes to map content can be monitored using the Application.MapItemChanged event. By hooking into the event, you can find out when the status of a MapItem has changed, and how it has changed. Refer to the MapItemChangedStatus enumeration for more details.
When a map is saved, all MapItems contained by the map are saved to a map file (.nmf). There is currently no way to save a map file programmatically.

How to use the MapDisplay
The MapDisplay class represents the display that you see when you open the ArcGIS Explorer application. MapDisplay is a utility class, which not only provides access to the Map for controlling content, but also bundles together a variety of functionality. For example map navigation, tracking and adding temporary graphics to the map.
A new MapDisplay object cannot be explicitly instantiated; it must be obtained from the static Application.ActiveMapDisplay property.
Storing locations in 2D and 3D
The Viewpoint class represents a location in either 2D or 3D space. All MapItems have a Viewpoint property, as does the MapDisplay. When a MapItem is double-clicked in the contents window, the application will automatically navigate the map to the associated Viewpoint. A 2D Viewpoint can be instantiated with an Envelope and rotation. A 3D Viewpoint can be created with a pair of points: an Observer and a Target.

Once a Viewpoint has been created with either an Envelope with rotation or Observer\Target, the Viewpoint mode cannot be modified-i.e. a Viewpoint instantiated with an Envelope cannot also store Observer\Target information, and vice versa. Attempting to combine 2D and 3D Viewpoints will cause an InvalidOperationException to be thrown.
Navigation
The MapDisplay methods that are prefixed with ‘Zoom’ enable you to navigate programmatically. The ZoomTo method is overloaded to allow for a variety of different inputs. The Viewpoint overload is particularly useful. A Viewpoint is a class that represents a stored location in either 2D or 3D space, and every MapItem has a Viewpoint property. Therefore it is theoretically possible to ZoomTo any type of MapItem.
Tracking
The MapDisplay methods that are prefixed with ‘Track’ enable you to capture shapes drawn onto the map by an end-user. There is a different Track method for each type of shape that you might want to capture. The Track methods behave in a synchronous manner i.e. when you call TrackPoint, the thread executing your code will wait until the end-user has clicked a point the map. When the end-user clicks on the Map, a Point object is returned. There is an alternative to the synchronous approach- the asynchronous methods that are prefixed with ‘BeginTrack’. The advantage of this approach is that the thread executing your code does not need to wait whilst tracking is taking place. In order to retrieve feedback from the Tracking session, it is necessary to provide a TrackDelegate to the BeginTrack method. A TrackDelegate is a pointer to a method that deals with feedback during the tracking process. The code inside the delegate is executed on a separate thread. Whilst the tracking is taking place, the application provides the delegate with information about the shapes that have been captured (TrackingInfo) and the status of the tracking session (TrackStatus).
Adding Temporary Graphics
The Graphic class represents a simple shape containing a geometry object and a symbol. The MapDisplay.Graphics property represents a temporary collection of graphic objects drawn on the map. The graphics in the collection do not become part of the map content; even if the map is saved the graphics are lost when the application closes. Alternatively use the Note class if you need to store a graphic in a map. A Note can be created using a graphic, and because Notes are a type of MapItem, they can be added to the Map.
Adding Temporary Images
ImageOverlays are typically added to the Map so that they appear in the contents window and are saved with the map document. However, it is also possible to add ImageOverlays directly to the MapDisplay using the MapDisplay.ForegroundOverlays property. Any image overlays added in this way are temporary as they will not appear in the contents window and will not get saved with the map document.
Graphics and ImageOverlays are always drawn on top of all layers in the map.