com.esri.arcgis.carto
Interface IMapDescription2

All Superinterfaces:

Serializable

All Known Implementing Classes:

MapDescription

public interface IMapDescription2
extends Serializable

Provides access to the available properties of a map description object.

Remarks

Use IMapDescription2 to access map settings that can be changed on the server object without changing the state of the underlying fine-grained ArcObjects that the map document is based on. Please note the difference between IMapServerInfo and IMapDescription. MapServerInfo is used to retrieve information about a map, such as the name of the map, the background color or the spatial extent for the map. These settings cannot be changed without direct access to the map document or the fine-grained ArcObjects it is based on.

Map settings of the Server object can be permanently changed by accessing fine-grained ArcObjects. This is accomplished using IMapServerObjects. This should be done with objects in a non-pooled environment. Changing the state of pooled objects this way will lead to unexpected results.

When To Use

Use the IMapDescription interface to access read and write properties of a map (data frame).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

The following example demonstrates how to access the MapDescription object from a MapServer object using the Server API:

// Initialize the code for Server usage and connect to the Server

new ServerInitializer().initializeServer(domain, user, password);

ServerConnection connection = new ServerConnection();

connection.connect(host);



// Once connected, get the SOM and SOC...

IServerObjectManager som = connection.getServerObjectManager();

IServerContext sc = som.createServerContext("usa", "MapServer");



// Obtain a MapServer object from the ServerContext...

MapServer mapServer = (MapServer)sc.getServerObject();



// Get the MapDescription object. This contains all the settings

// and properties for the current map in the Server Object Container...

MapDescription mapDescription = (MapDescription)mapServer.getServerInfo(mapServer.getDefaultMapName()).getDefaultMapDescription();

Method Summary

IFillSymbol	getBackgroundSymbol() Background symbol of the Map.
IGraphicElements	getCustomGraphics() Custom graphics.
ILayerDescriptions	getLayerDescriptions() A collection of Layer Description objects, each describing a layer within the map (data frame).
IMapArea	getMapArea() The display area of the map (data frame).
double	getMapRotation() The angle/rotation of the map (data frame) in degrees, measured anti-clockwise.
String	getName() The name of the map (data frame).
IColor	getSelectionColor() The default selection color.
ISpatialReference	getSpatialReference() The spatial reference of the map (data frame).
IColor	getTransparentColor() The color that is transparent (100 %).
void	setBackgroundSymbol(IFillSymbol fillSymbol) Background symbol of the Map.
void	setCustomGraphics(IGraphicElements elements) Custom graphics.
void	setLayerDescriptions(ILayerDescriptions layerDescriptions) A collection of Layer Description objects, each describing a layer within the map (data frame).
void	setMapArea(IMapArea area) The display area of the map (data frame).
void	setMapRotation(double angleDegrees) The angle/rotation of the map (data frame) in degrees, measured anti-clockwise.
void	setName(String name) The name of the map (data frame).
void	setSelectionColor(IColor color) The default selection color.
void	setSpatialReferenceByRef(ISpatialReference spatialReference) The spatial reference of the map (data frame).
void	setTransparentColor(IColor color) The color that is transparent (100 %).

Method Detail

getName

String getName()
               throws IOException,
                      AutomationException

The name of the map (data frame).

Remarks

If two (or more) data frames have the same name in the map document, MapServer adds a distinctive number at the end of the second name. E.g. Layers and Layers2.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The name

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setName

void setName(String name)
             throws IOException,
                    AutomationException

The name of the map (data frame).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

name - The name (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMapArea

IMapArea getMapArea()
                    throws IOException,
                           AutomationException

The display area of the map (data frame).

Remarks

MapArea contains the abstract IMapArea interface. With this interface you can retrieve the extent of a map or bookmark (IMapServerBookmark). If you want to change the extent of a map use IMapExtent, ICenterAndSize, ICenterAndScale and IFeatureExtent. By default, the MapArea object is of type MapExtent.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A reference to a com.esri.arcgis.carto.IMapArea

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMapArea

void setMapArea(IMapArea area)
                throws IOException,
                       AutomationException

The display area of the map (data frame).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

area - A reference to a com.esri.arcgis.carto.IMapArea (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLayerDescriptions

ILayerDescriptions getLayerDescriptions()
                                        throws IOException,
                                               AutomationException

A collection of Layer Description objects, each describing a layer within the map (data frame).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A reference to a com.esri.arcgis.carto.ILayerDescriptions

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setLayerDescriptions

void setLayerDescriptions(ILayerDescriptions layerDescriptions)
                          throws IOException,
                                 AutomationException

A collection of Layer Description objects, each describing a layer within the map (data frame).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

layerDescriptions - A reference to a com.esri.arcgis.carto.ILayerDescriptions (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMapRotation

double getMapRotation()
                      throws IOException,
                             AutomationException

The angle/rotation of the map (data frame) in degrees, measured anti-clockwise.

Remarks

Map rotation is a property of a map. An exported map image or exported layout image should respect the map rotation value. However, once a MapServer Object has been added to ArcMap it is now a layer and this rotation value is dropped. The reason for this is, in ArcMap, when a layer is added to a map, the layer adjusts to fit the spatial reference and existing rotation of the map. If the default rotation of a new ArcMap document is zero, a MapServer object layer will lose any rotation when added to a new ArcMap session. The MapRotation value does not change, only the display of the MapServer Layer.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The angleDegrees

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMapRotation

void setMapRotation(double angleDegrees)
                    throws IOException,
                           AutomationException

The angle/rotation of the map (data frame) in degrees, measured anti-clockwise.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

angleDegrees - The angleDegrees (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSpatialReference

ISpatialReference getSpatialReference()
                                      throws IOException,
                                             AutomationException

The spatial reference of the map (data frame).

Remarks

Use SpatialReference to retrieve or set a spatial reference for a map. If the spatial reference for a map has been changed, remember to assign the new spatial reference to any subsequent geometry used to change the map area or identify or select features.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A reference to a com.esri.arcgis.geometry.ISpatialReference

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSpatialReferenceByRef

void setSpatialReferenceByRef(ISpatialReference spatialReference)
                              throws IOException,
                                     AutomationException

The spatial reference of the map (data frame).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

spatialReference - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCustomGraphics

IGraphicElements getCustomGraphics()
                                   throws IOException,
                                          AutomationException

Custom graphics.

Remarks

Use CustomGraphics to display text or geometric shapes on the map. When interacting with the display of labels, CustomGraphics will honor the Feature Weight value for the default graphics layer set in the Label Weight Ranking dialog in the map document. A setting of High, the ArcMap default, will result in labels not drawing within the bounds of the custom graphics. If the Feature Weight for the default graphics layer is None, Low or Medium labels will draw within the bounds of the custom graphics. With None, all labels should display. With Low or Medium, the amount of labels that draw may vary.

Please note that the optimized MapServer only supports the esriSFSSolid style of ISimpleFillSymbol. For other types of fills, use other fill symbol types such as ILineSymbol. For hollow symbols, you should use IColor::NullColor with esriSFSSolid instead of using the esriSFSNull style.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

The following sample code shows how to add a MarkerSymbol graphic to your map:

// Initialize the code for Server usage and connect to the Server

new ServerInitializer().initializeServer(domain, user, password);

ServerConnection connection = new ServerConnection();

connection.connect(host);



// Once connected, get the SOM and SOC...

IServerObjectManager som = connection.getServerObjectManager();

IServerContext sc = som.createServerContext("usa", "MapServer");



// Obtain a MapServer object from the ServerContext...

MapServer mapServer = (MapServer)sc.getServerObject();



// Get the MapDescription object. This contains all the settings

// and properties for the current map in the Server Object Container...

MapDescription mapDescription = (MapDescription)mapServer.getServerInfo(mapServer.getDefaultMapName()).getDefaultMapDescription();



// Create a Point object for the location of the MarkerSymbol graphic

Point point = (Point)sc.createObject(Point.getClsid());

point.putCoords(-89.32472229, 43.6044464111);



// The GraphicsElements is the container for any graphic elements

// you want added to the map image display. Create this on the 

// Server Context...

GraphicElements graphicElements = (GraphicElements)sc.createObject(GraphicElements.getClsid()); 



// The SimpleMarkerSymbol will be used to symbolize the graphic element

// on the map image display. Create an instance on the Server Context.

SimpleMarkerSymbol simpleMarkerSymbol1 = (SimpleMarkerSymbol)sc.createObject(SimpleMarkerSymbol.getClsid()); 

simpleMarkerSymbol1.setStyle(esriSimpleMarkerStyle.esriSMSDiamond); // not required. Default is circle.

simpleMarkerSymbol1.setSize(20); 



// The MarkerElement is the graphic element for holding the MarkerSymbol and the 

// geometry for displaying the graphic in a geographic location.

MarkerElement markerElement1 = (MarkerElement)sc.createObject(MarkerElement.getClsid()); 

markerElement1.setSymbol(simpleMarkerSymbol1); 

markerElement1.setGeometry(point); 



// Add the MarkerElement to the GraphicElements, then pass the

// GraphicElements to the MapDescription.

graphicElements.add(markerElement1);



mapDescription.setCustomGraphics(graphicElements); 



// Create an ImageType object in the same server context as

// the MapServer objects. Use it to determine the file-type of

// the output image as well as the URL used to reference the

// output image.

ImageType imageType = (ImageType)sc.createObject(ImageType.getClsid());

imageType.setFormat(esriImageFormat.esriImageJPG);

imageType.setReturnType(esriImageReturnType.esriImageReturnURL);



// Create an ImageDisplay object in the server context to

// hold dimension and resolution information about the output

// image.

ImageDisplay imageDisplay =(ImageDisplay)sc.createObject(ImageDisplay.getClsid());

imageDisplay.setHeight(400);

imageDisplay.setWidth(600);

imageDisplay.setDeviceResolution(96.0);



// Create an ImageDescription object to hold the ImageType

// and ImageDisplay objects for the call to the

// MapServer.exportMapImage method below.

ImageDescription imageDescription = (ImageDescription)sc.createObject(ImageDescription.getClsid());

imageDescription.setDisplay(imageDisplay);

imageDescription.setType(imageType);



IMapImage image = mapServer.exportMapImage(mapDescription, imageDescription);

Returns:

A reference to a com.esri.arcgis.carto.IGraphicElements

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setCustomGraphics

void setCustomGraphics(IGraphicElements elements)
                       throws IOException,
                              AutomationException

Custom graphics.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

elements - A reference to a com.esri.arcgis.carto.IGraphicElements (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getTransparentColor

IColor getTransparentColor()
                           throws IOException,
                                  AutomationException

The color that is transparent (100 %).

Remarks

Setting a transparent color is valid only for image formats that support transparency. These include: png, png24 and gif.

A transparent color can also be set in ImageDisplay2. The color set for ImageDisplay2 takes precedence over the transparent color set in the MapDescription. In such cases this property will be ignored.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A reference to a com.esri.arcgis.display.IColor

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setTransparentColor

void setTransparentColor(IColor color)
                         throws IOException,
                                AutomationException

The color that is transparent (100 %).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

color - A reference to a com.esri.arcgis.display.IColor (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSelectionColor

IColor getSelectionColor()
                         throws IOException,
                                AutomationException

The default selection color.

Description

The color with which all selected features in the map are drawn.

Remarks

Set this property when you wish to change the default selection color for all layers in the map. The ArcMap default selection color is cyan. This color applies to all layers within the map. If you want to use different selection colors for individual layers, use SelectionColor on ILayerDescription2. The default selection symbols for a map are: a circle for points, a solid line for lines and a hollow fill (solid outline) for polygons. If you want to change the selection symbol for a layer, use SelectionSymbol on ILayerDescription.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A reference to a com.esri.arcgis.display.IColor

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSelectionColor

void setSelectionColor(IColor color)
                       throws IOException,
                              AutomationException

The default selection color.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

color - A reference to a com.esri.arcgis.display.IColor (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getBackgroundSymbol

IFillSymbol getBackgroundSymbol()
                                throws IOException,
                                       AutomationException

Background symbol of the Map.

Remarks

If the background symbol and color are not explicitly set in the original map document (.mxd), the default background symbol a solid-filled symbol with an off-white color (RGB value of 253,253,253).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A reference to a com.esri.arcgis.display.IFillSymbol

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setBackgroundSymbol

void setBackgroundSymbol(IFillSymbol fillSymbol)
                         throws IOException,
                                AutomationException

Background symbol of the Map.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

fillSymbol - A reference to a com.esri.arcgis.display.IFillSymbol (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.