Class RuntimeMap

Represents a runtime instance of a Map Definition

Inheritance

System.Object

MapObservable

RuntimeMap

Implements

System.ComponentModel.INotifyPropertyChanged

Inherited Members

MapObservable._disableChangeTracking

MapObservable.SetField<T>(T, T, String)

MapObservable.ObservableSet<T>(T, T, Action<T>, String)

MapObservable.PropertyChanged

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: OSGeo.MapGuide.MaestroAPI.Mapping

Assembly: OSGeo.MapGuide.MaestroAPI.dll

Syntax

public class RuntimeMap : MapObservable, INotifyPropertyChanged

Remarks

If you want to use this instance with the Rendering Service APIs, it is important to set the correct meters per unit value before calling the Save() method, as an incorrect meters per unit value will produce incorrect images.

Also note that to improve the creation performance, certain implementations of IServerConnection offer a OSGeo.MapGuide.MaestroAPI.Mapping.IRuntimeMapSetup helper to return a series of layer definitions in a batch (fetching layer definitions one at a time is the main performance bottleneck for large maps), batching can improve creation times by:

HTTP: 2x
Local: 3x (if using MapGuide 2.2 APIs. As this takes advantage of the GetResourceContents() API introduced in 2.2). For older versions of MapGuide there is no batching.

In particular, the HTTP implementation of OSGeo.MapGuide.MaestroAPI.IServerConection uses the System.Threading.ThreadPool class to fetch multiple layer definitions in parallel. If your code uses this implementation, be aware of this face and the performance implications involved, as an excessively large thread pool size may negatively affect stability of your MapGuide Server.

Examples

How to create a RuntimeMap with the correct meters per unit value using the MgCoordinateSystem API

    IServerConnection conn = ConnectionProviderRegistry.CreateConnection("Maestro.Http",
        "Username", "Administrator",
        "Password", "admin",
        "Url", "http://localhost/mapguide/mapagent/mapagent.fcgi");

    //Create the Mapping Service. Some implementations of IServerConnection may not support this service, so
    //its best to inspect the capability object of this connection to determine if this service type is supported
    IMappingService mapSvc = (IMappingService)conn.GetService((int)ServiceType.Mapping);

    //Get our map definition
    ResourceIdentifier resId = new ResourceIdentifier("Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition");
    IMapDefinition mdf = (IMapDefinition)conn.ResourceService.GetResource(resId.ToString());

    //Calculate the meters per unit value, this requires the official MapGuide API. Otherwise, you need
    //to know this value up-front in order to render images with this instance
    double metersPerUnit = 1.0;
    if (!string.IsNullOrEmpty(mdf.CoordinateSystem))
    {
        MgCoordinateSystemFactory factory = new MgCoordinateSystemFactory();
        MgCoordinateSystem cs = factory.Create(mdf.CoordinateSystem);
        metersPerUnit = cs.ConvertCoordinateSystemUnitsToMeters(1.0);
    }

    //Generate our runtime map resource id. This must be session-based
    ResourceIdentifier rtMapId = new ResourceIdentifier(resId.Name, ResourceTypes.RuntimeMap, conn.SessionID);

    //Create the runtime map using our meters per unit value
    RuntimeMap map = mapSvc.CreateRuntimeMap(rtMapId, mdf, metersPerUnit);

    //Set some display parameters for this map
    map.ViewScale = 75000;
    map.DisplayWidth = 1024;
    map.DisplayHeight = 1024;
    map.DisplayDpi = 96;

    //We have to save it first before we can render from it or use any other API that requires this
    //current map state. Remember to call Save() everytime you change the state of the map
    map.Save();

    //Now we can render a map
    using(Stream stream = mapSvc.RenderDynamicOverlay(map, null, "PNG"))
    {
        //Write this stream out to a file
        using (var fs = new FileStream("RenderMap.png", FileMode.OpenOrCreate))
        {
            int read = 0;
            do
            {
                read = source.Read(buf, 0, buf.Length);
                target.Write(buf, 0, read);
            } while (read > 0);
        }
    }

Constructors

| Improve this Doc View Source

RuntimeMap()

Declaration

protected RuntimeMap()

| Improve this Doc View Source

RuntimeMap(IServerConnection)

Initializes this instance

Declaration

protected RuntimeMap(IServerConnection conn)

Parameters

Type	Name	Description
IServerConnection	conn

Fields

| Improve this Doc View Source

_bgColor

The background color of the map

Declaration

protected Color _bgColor

Field Value

Type	Description
System.Drawing.Color

| Improve this Doc View Source

_dataExtent

The data extent

Declaration

protected IEnvelope _dataExtent

Field Value

Type	Description
IEnvelope

| Improve this Doc View Source

_dispHeight

The display height

Declaration

protected int _dispHeight

Field Value

Type	Description
System.Int32

| Improve this Doc View Source

_dispWidth

The display width

Declaration

protected int _dispWidth

Field Value

Type	Description
System.Int32

| Improve this Doc View Source

_dpi

The dpi

Declaration

protected int _dpi

Field Value

Type	Description
System.Int32

| Improve this Doc View Source

_getRes

The GetResourceContents command

Declaration

protected IGetResourceContents _getRes

Field Value

Type	Description
IGetResourceContents

| Improve this Doc View Source

_mapSrs

The Coordinate System WKT of the map

Declaration

protected string _mapSrs

Field Value

Type	Description
System.String

| Improve this Doc View Source

_mapSvc

The mapping service

Declaration

protected IMappingService _mapSvc

Field Value

Type	Description
IMappingService

| Improve this Doc View Source

_name

The name of the map

Declaration

protected string _name

Field Value

Type	Description
System.String

| Improve this Doc View Source

_viewCenter

The view center

Declaration

protected IPoint2D _viewCenter

Field Value

Type	Description
IPoint2D

| Improve this Doc View Source

_viewScale

The view scale

Declaration

protected double _viewScale

Field Value

Type	Description
System.Double

| Improve this Doc View Source

ClassId

MapGuide internal class id

Declaration

protected const int ClassId = 11500

Field Value

Type	Description
System.Int32

| Improve this Doc View Source

layerDefinitionCache

A cache of Layer Definition objects. Used to reduce lookup time of the same layer definitions

Declaration

protected Dictionary<string, ILayerDefinition> layerDefinitionCache

Field Value

Type	Description
System.Collections.Generic.Dictionary<System.String, ILayerDefinition>

| Improve this Doc View Source

MgBinaryVersion

MapGuide internal value

Declaration

protected const int MgBinaryVersion = 262144

Field Value

Type	Description
System.Int32

| Improve this Doc View Source

Z_ORDER_INCREMENT

The amount to increment the Z order for successive layers being added

Declaration

public const double Z_ORDER_INCREMENT = 100

Field Value

Type	Description
System.Double

| Improve this Doc View Source

Z_ORDER_TOP

The draw order of the topmost layer

Declaration

public const double Z_ORDER_TOP = 100

Field Value

Type	Description
System.Double

Properties

| Improve this Doc View Source

BackgroundColor

Gets or sets the color of the background. Check the SupportsMutableBackgroundColor to see if setting the background color is allowed.

Declaration

public virtual Color BackgroundColor { get; set; }

Property Value

Type	Description
System.Drawing.Color	The color of the background.

Exceptions

Type	Condition
System.NotSupportedException	Thrown if the operation is not supported

| Improve this Doc View Source

CoordinateSystem

Gets or sets the coordinate system in WKT format. Check the SupportsMutableCoordinateSystem to see if setting the coordinate system WKT is allowed.

Declaration

public virtual string CoordinateSystem { get; set; }

Property Value

Type	Description
System.String	The coordinate system in WKT format.

Exceptions

Type	Condition
System.NotSupportedException	Thrown if the operation is not supported

| Improve this Doc View Source

CurrentConnection

Gets the IServerConnection that is attached to this instance

Declaration

public IServerConnection CurrentConnection { get; }

Property Value

Type	Description
IServerConnection

| Improve this Doc View Source

DataExtent

Gets or sets the data extent.

Declaration

public virtual IEnvelope DataExtent { get; set; }

Property Value

Type	Description
IEnvelope	The data extent.

| Improve this Doc View Source

DisplayDpi

Gets or sets the display dpi.

Declaration

public virtual int DisplayDpi { get; set; }

Property Value

Type	Description
System.Int32	The display dpi.

| Improve this Doc View Source

DisplayHeight

Gets or sets the display height.

Declaration

public virtual int DisplayHeight { get; set; }

Property Value

Type	Description
System.Int32	The display height.

| Improve this Doc View Source

DisplayWidth

Gets or sets the display width.

Declaration

public virtual int DisplayWidth { get; set; }

Property Value

Type	Description
System.Int32	The display width.

| Improve this Doc View Source

FiniteDisplayScaleCount

Gets the number of finite display scales

Declaration

public int FiniteDisplayScaleCount { get; }

Property Value

Type	Description
System.Int32

| Improve this Doc View Source

Groups

The collection of groups in this map

Declaration

public RuntimeMapGroupCollection Groups { get; }

Property Value

Type	Description
RuntimeMapGroupCollection

| Improve this Doc View Source

IsDirty

Gets whether this instance has state changes which require a call to Save()

Declaration

public virtual bool IsDirty { get; protected set; }

Property Value

Type	Description
System.Boolean	`true` if this instance is dirty; otherwise, `false`.

| Improve this Doc View Source

IsValidForRendering

Gets whether this map is valid for rendering

Declaration

public bool IsValidForRendering { get; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

LayerRefreshMode

Gets the layer refresh mode.

Declaration

public virtual int LayerRefreshMode { get; }

Property Value

Type	Description
System.Int32	The layer refresh mode.

| Improve this Doc View Source

Layers

The collection of layers in this map

Declaration

public RuntimeMapLayerCollection Layers { get; }

Property Value

Type	Description
RuntimeMapLayerCollection

| Improve this Doc View Source

MapDefinition

Gets or sets the map definition resource id

Declaration

public virtual string MapDefinition { get; }

Property Value

Type	Description
System.String	The map definition resource id.

| Improve this Doc View Source

MapExtent

Gets or sets the map extents. Inspect the OSGeo.MapGuide.MaestroAPI.Mapping.RuntimeMap.SupportsMutableMapExtents to determine if setting the map extents is allowed

Declaration

public virtual IEnvelope MapExtent { get; set; }

Property Value

Type	Description
IEnvelope	The map extents.

Exceptions

Type	Condition
System.NotSupportedException	Thrown if the operation is not supported

| Improve this Doc View Source

MetersPerUnit

Gets the meters per unit value. Check the SupportsMutableMetersPerUnit to see if setting the meters per unit value is allowed.

Declaration

public virtual double MetersPerUnit { get; set; }

Property Value

Type	Description
System.Double	The meters per unit.

Exceptions

Type	Condition
System.NotSupportedException	Thrown if the operation is not supported

| Improve this Doc View Source

Name

Gets or sets the name.

Declaration

public string Name { get; set; }

Property Value

Type	Description
System.String	The name.

| Improve this Doc View Source

ObjectId

Gets or sets the object id.

Declaration

public virtual string ObjectId { get; }

Property Value

Type	Description
System.String	The object id.

| Improve this Doc View Source

ResourceID

Gets or sets the resource ID. When setting, if the name of this map has not been specified already, the name will be set based on this resource id

Declaration

public string ResourceID { get; set; }

Property Value

Type	Description
System.String	The resource ID.

| Improve this Doc View Source

ResourceType

Gets the type of the resource.

Declaration

public ResourceTypes ResourceType { get; }

Property Value

Type	Description
ResourceTypes	The type of the resource.

| Improve this Doc View Source

Selection

Gets the selection set

Declaration

public virtual MapSelection Selection { get; }

Property Value

Type	Description
MapSelection	The selection.

| Improve this Doc View Source

SessionId

Gets or sets the session id.

Declaration

public virtual string SessionId { get; }

Property Value

Type	Description
System.String	The session id.

| Improve this Doc View Source

StrictSelection

If true, any selections made against this map are validated to ensure the layer(s) being selected have identity properties

Declaration

public bool StrictSelection { get; set; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

SupportsMutableBackgroundColor

Gets whether the background color of this map can be modified at runtime

Declaration

public virtual bool SupportsMutableBackgroundColor { get; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

SupportsMutableCoordinateSystem

Gets whether the coordinate system of this map can be modified at runtime

Declaration

public virtual bool SupportsMutableCoordinateSystem { get; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

SupportsMutableExtents

Gets whether extents of this map can be modified at runtime

Declaration

public virtual bool SupportsMutableExtents { get; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

SupportsMutableMetersPerUnit

Gets whether the meters-per-unit value of this map can be modified at runtime

Declaration

public virtual bool SupportsMutableMetersPerUnit { get; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

TileFormat

Gets the tile format. Only applicable for MapGuide Open Source 4.0 or later

Declaration

public virtual string TileFormat { get; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

TilePixelRatio

Gets the tile pixel ratio. Only applicable for MapGuide Open Source 4.0 or later

Declaration

public virtual int TilePixelRatio { get; }

Property Value

Type	Description
System.Int32

| Improve this Doc View Source

TileSetDefinition

Gets or sets the tile set definition resource id. Only applicable if the Map Definition used to create this map contains a reference to a tile set

Declaration

public virtual string TileSetDefinition { get; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

TileSetProvider

Gets the tile set provider. Only applicable for MapGuide Open Source 4.0 or later

Declaration

public virtual string TileSetProvider { get; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

ViewCenter

Gets or sets the view center.

Declaration

public virtual IPoint2D ViewCenter { get; }

Property Value

Type	Description
IPoint2D	The view center.

| Improve this Doc View Source

ViewScale

Gets or sets the view scale.

Declaration

public virtual double ViewScale { get; set; }

Property Value

Type	Description
System.Double	The view scale.

| Improve this Doc View Source

WatermarkUsage

Gets the watermark usage. Not applicable for version of MapGuide older than 2.3

Declaration

public virtual int WatermarkUsage { get; }

Property Value

Type	Description
System.Int32

Methods

| Improve this Doc View Source

ClearChanges()

Clears all tracked changes

Declaration

protected void ClearChanges()

| Improve this Doc View Source

ConvertTiledGroupsToNonTiled()

Convers all tiled groups in this map to untiled groups. All layers within these groups are convered to dynamic layers

Declaration

public void ConvertTiledGroupsToNonTiled()

| Improve this Doc View Source

Deserialize(MgBinaryDeserializer)

Initializes this instance from the specified binary stream

Declaration

public virtual void Deserialize(MgBinaryDeserializer d)

Parameters

Type	Name	Description
MgBinaryDeserializer	d

| Improve this Doc View Source

GetFiniteDisplayScaleAt(Int32)

Gets the finite display scale at the specified index

Declaration

public double GetFiniteDisplayScaleAt(int index)

Parameters

Type	Name	Description
System.Int32	index

Returns

Type	Description
System.Double

| Improve this Doc View Source

GetGroupByName(String)

Gets the group by its specified name

Declaration

[Obsolete("Use the indexer of the Groups property instead")]
public RuntimeMapGroup GetGroupByName(string name)

Parameters

Type	Name	Description
System.String	name	The name.

Returns

Type	Description
RuntimeMapGroup

| Improve this Doc View Source

GetGroupsOfGroup(String)

Gets the groups of the specified group.

Declaration

public RuntimeMapGroup[] GetGroupsOfGroup(string groupName)

Parameters

Type	Name	Description
System.String	groupName	Name of the group.

Returns

Type	Description
RuntimeMapGroup[]

| Improve this Doc View Source

GetLayerByObjectId(String)

Gets the layer by object id.

Declaration

public RuntimeMapLayer GetLayerByObjectId(string id)

Parameters

Type	Name	Description
System.String	id	The id.

Returns

Type	Description
RuntimeMapLayer

| Improve this Doc View Source

GetLayersOfGroup(String)

Gets the layers of the specified group

Declaration

public RuntimeMapLayer[] GetLayersOfGroup(string groupName)

Parameters

Type	Name	Description
System.String	groupName	Name of the group.

Returns

Type	Description
RuntimeMapLayer[]

| Improve this Doc View Source

GetLegendImageStream(String, Double, Int32, Int32, String, Int32, Int32)

Convenience method for rendering a layer style icon

Declaration

public Stream GetLegendImageStream(string layerDefinitionID, double scale, int width, int height, string format, int geomType, int themeCategory)

Parameters

Type	Name	Description
System.String	layerDefinitionID
System.Double	scale
System.Int32	width
System.Int32	height
System.String	format
System.Int32	geomType
System.Int32	themeCategory

Returns

Type	Description
System.IO.Stream

| Improve this Doc View Source

IndexOfLayer(String)

Gets the index of the first layer whose name matches the specified name

Declaration

public int IndexOfLayer(string layerName)

Parameters

Type	Name	Description
System.String	layerName

Returns

Type	Description
System.Int32

| Improve this Doc View Source

InitialiseDisplayParameters(Int32, Int32)

Sets the width, height and initial view scale

Declaration

public void InitialiseDisplayParameters(int width, int height)

Parameters

Type	Name	Description
System.Int32	width
System.Int32	height

| Improve this Doc View Source

OnPropertyChanged(String)

Raises the OSGeo.MapGuide.MaestroAPI.Mapping.RuntimeMap.PropertyChanged event

Declaration

protected override void OnPropertyChanged(string propertyName)

Parameters

Type	Name	Description
System.String	propertyName

Overrides

MapObservable.OnPropertyChanged(String)

| Improve this Doc View Source

QueryMapFeatures(String, Int32, Boolean, String, QueryMapOptions, Nullable<Int32>)

Convenience method for performing selection based on the given geometry

Declaration

public virtual string QueryMapFeatures(string wkt, int maxFeatures, bool persist, string selectionVariant, QueryMapOptions extraOptions, int? requestData = null)

Parameters

Type	Name	Description
System.String	wkt
System.Int32	maxFeatures
System.Boolean	persist
System.String	selectionVariant
QueryMapOptions	extraOptions
System.Nullable<System.Int32>	requestData

Returns

Type	Description
System.String

| Improve this Doc View Source

Render(String)

Convenience method for rendering a bitmap of the current map

Declaration

public Stream Render(string format)

Parameters

Type	Name	Description
System.String	format

Returns

Type	Description
System.IO.Stream

| Improve this Doc View Source

RenderDynamicOverlay(MapSelection, String, Boolean)

Convenience method for rendering a dynamic overlay of the current map

Declaration

[Obsolete("Use the version of RenderDynamicOverlay that is not marked Obsolete")]
public Stream RenderDynamicOverlay(MapSelection sel, string format, bool keepSelection)

Parameters

Type	Name	Description
MapSelection	sel
System.String	format
System.Boolean	keepSelection

Returns

Type	Description
System.IO.Stream

| Improve this Doc View Source

RenderDynamicOverlay(MapSelection, String, Color, Int32)

Convenience method for rendering a dynamic overlay of the current map

Declaration

public Stream RenderDynamicOverlay(MapSelection selection, string format, Color selectionColor, int behaviour)

Parameters

Type	Name	Description
MapSelection	selection
System.String	format
System.Drawing.Color	selectionColor
System.Int32	behaviour	A bitmask for the rendering behaviour (1 = Render Selection, 2 = Render Layers, 4 = Keep Selection, 8 = Render Base Layers)

Returns

Type	Description
System.IO.Stream

| Improve this Doc View Source

RenderDynamicOverlay(String, Boolean)

Convenience method for rendering a dynamic overlay of the current map

Declaration

[Obsolete("Use the version of RenderDynamicOverlay that is not marked Obsolete")]
public Stream RenderDynamicOverlay(string format, bool keepSelection)

Parameters

Type	Name	Description
System.String	format
System.Boolean	keepSelection

Returns

Type	Description
System.IO.Stream

| Improve this Doc View Source

RenderMapLegend(Int32, Int32, Color, String)

Convenience method for rendering the legend for this map

Declaration

public Stream RenderMapLegend(int width, int height, Color color, string format)

Parameters

Type	Name	Description
System.Int32	width
System.Int32	height
System.Drawing.Color	color
System.String	format

Returns

Type	Description
System.IO.Stream

| Improve this Doc View Source

Save()

Saves this instance. The changes are propagated back to the MapGuide Server

Declaration

public virtual void Save()

| Improve this Doc View Source

Serialize(MgBinarySerializer)

Serializes this instance to the specified binary stream

Declaration

public virtual void Serialize(MgBinarySerializer s)

Parameters

Type	Name	Description
MgBinarySerializer	s

| Improve this Doc View Source

SerializeLayerData(MgBinarySerializer)

Serializes the layer data to the specified binary stream

Declaration

protected void SerializeLayerData(MgBinarySerializer s)

Parameters

Type	Name	Description
MgBinarySerializer	s

| Improve this Doc View Source

SetViewCenter(Double, Double)

Sets the view center

Declaration

public virtual void SetViewCenter(double x, double y)

Parameters

Type	Name	Description
System.Double	x	The center X coordinate
System.Double	y	The center Y coordinate

| Improve this Doc View Source

ToMapDefinition(Boolean)

Converts this instance to an equivalent Map Definition

Declaration

public IMapDefinition ToMapDefinition(bool useOriginalAsTemplate)

Parameters

Type	Name	Description
System.Boolean	useOriginalAsTemplate	If true, the converted Map Definition will use core settings from the original Map Definition used to create this instance

Returns

Type	Description
IMapDefinition

| Improve this Doc View Source

UpdateMapDefinition(IMapDefinition)

Updates and replaces the layer/group structure of the specified Map Definition with the layer/group structure of this Runtime Map

Declaration

public void UpdateMapDefinition(IMapDefinition newMdf)

Parameters

Type	Name	Description
IMapDefinition	newMdf

Events

| Improve this Doc View Source

LayerAdded

Raise when a layer is added to the map

Declaration

public event LayerEventHandler LayerAdded

Event Type

Type	Description
LayerEventHandler

Implements

System.ComponentModel.INotifyPropertyChanged