Understanding xamMap

Data mapping in xamMap allows you to bind MapElement properties to values in the data source. To do so, before reading in a Shapefile with a ShapeFileReader, you must set the DataMapping property of that reader.

The DataMapping property takes a semicolon delimited string of key-value pairs. The tokens are case-sensitive and determine the column and property to be mapped. The following is an example of a data mapping, given a Shapefile of the U.S states:

In XAML:

This example binds the Caption property of the map elements to the data of the STATE_ABBR column from the Shapefile. What displays is a map of the US states with each state showing a caption of its abbreviated state name.

You can also save the data of a column to an arbitrary property for an element:

In XAML:

This XAML snippet will save the data of the STATE_ABBR column to a property named STATE_ABBREVIATIONS for each element. If you do not specify a data mapping, when xamMap reads in a Shapefile, all data columns are mapped to arbitrary properties in each element with the same name as the columns. You can access properties by passing in the property name to the GetProperty method of an element. For example, passing in "STATE_ABBR" will get the state name abbreviation for an individual element, if no explicit data mapping is set. You can also set a property by using the SetProperty method and passing in the property name and the value to set.

The xamMap control uses the popular Shapefile format as the source for its map data. A Shapefile is a geospatial vector data format that describes points, polylines, and polygons. A Shapefile commonly refers to a collection of files, generally with extensions ".shp", ".shx", and ".dbf", using a common prefix name; eg, "states."

The xamMap control can display points, polylines, or polygons vector data, for things such as cities, roads, and states, depending on the Shapefile. The control uses one layer for every Shapefile.

A MapLayer object is the means of displaying Shapefile data in xamMap. You can display multiple Shapefiles by using multiple layers.

You can use a ShapeFileReader object to read in the contents of a Shapefile and display the contents in a layer. The Shapefile must be placed in the ClientBin folder of the Web project. Further, you can perform a data mapping between the data of the Shapefile and properties of the map’s elements to display more information.

For more information on reading a Shapefile and using data mapping, see Binding Shapefiles.

Map elements represent the graphical shapes, lines, and polygons on a given layer. They provide the means for interacting with shapes displayed by xamMap. Map elements take their properties from the layer they are on; these properties can also be set individually. For more information on map elements, see Display Map Elements.

The xamMap control acts as a container for child controls, panes, and shape rectangles. These elements together help make up the visual representation of the map.

The following is a list of the panes available in xamMap:

To lay out these different elements, xamMap contains a collection of layers and a xamDock™ panel to define the contents of the map body and specify the positioning of the controls, respectively.

If the children of the map are not placed in the Layers collection, they are routed to the LogicalChildren collection, and will be rendered as children of the xamDock control. As such, their dock position can be set using the xamDock.Edge attached property.

The map layers and all their elements are contained within the map viewport, which is docked centrally in the control area.

The viewport is the visible region of the map, reserved for displaying geospatial data. The viewport has the following features:

The xamMap control allows content panning and zooming . This can be done in a number of ways:

You can restrict panning and zooming using the IsPannable and IsZoomable boolean properties.

Zooming works by increasing the xamMap control’s window scale, which is represented by the WindowScale property. The factor of increase or decrease in the window scale is controlled by the WindowZoomBase property. By default, this property has a value of 1.3; by increasing the zoom level by 1, the window scale is multiplied by 1.3; by decreasing the zoom level by 1, the window scale is divided by 1.3.

To determine the zoom level based on the WindowScale value, use the xamMap control’s ScaleToZoom method.

You can set a minimum and maximum zoom level in xamMap by setting the WindowZoomMinimum and WindowZoomMaximum properties.

The xamMap control uses map projections to visualize map shapes. A map projection is a systematic process of converting a spherical surface to or from a planar representation; therefore, any map of geographic data requires the use of a map projection. The xamMap control uses map projections to transform geodetic coordinates to and from Cartesian coordinates.

Naturally, there is distortion when using map projections because it is impossible to accurately depict the surface of the Earth on a flat map. Certain projections are more accurate than others for certain characteristics of a map; it is up to the cartographer to decide which projection best fits their criteria.

The xamMap control provides a wide selection of map projections. The ShapefileReader assumes no input projection; however, input projections can be configured using the ShapeFileReader object’s CoordinateSystem property. For more information on changing coordinate system, please refer to Change Map Coordinate System section.

For more detail information on map projections, please refer to the following online resources: