|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface IMapServerLayout
Provides access to members that serve layout components of maps.
Some layout elements can change dynamically when accessed by IMapServerLayout. Data frames in the layout will reflect any changes in MapDescription. Scale bars, scale text, north arrow and legends linked to data frames will adjust to these changes. Two properties of IPageDescription, CustomGraphics and Extent, also provide dynamic utility. For example, use CustomGraphics to place dynamic titles for your exported layouts or use extent to "zoom in" on a portion of the layout page. Furthermore, the image type and size of the exported layout can also be controlled using the input parameter ImageDescription object in the method ExportLayout. Remember, this is the size of the image, not the size of the actual layout. The page size of the layout is determined in the map document. ImageDescription is also used with IMapServerLayout methods ExportLegend, ExportScaleBar and ExportNorthArrow .
Do not use IMapServerLayout to create new layouts or to create layouts "on-the-fly". You cannot change the actual page size of the map layout, reposition map elements on the layout nor can you add or remove layout elements such as titles, text, graphics, scale bars, north arrows and legends.
Use IMapServerLayout to export the existing map layout or to export a legend, north arrow or a scale bar of an existing map. Also use IMapServerLayout to convert screen coordinates to page coordinates on the layout and vice versa. Do not use IMapServerLayout to create new layouts or to create layouts "on-the-fly".
This interface is not supported by optimized MapServer.
| Method Summary | |
|---|---|
ILayoutImage |
exportLayout(IPageDescription pageDesc,
IImageDescription imageDesc)
Generates an image of the layout, based on the given page description object, and writes the image to a specified file on disk. |
IImageResult |
exportLegend(ILegend legend,
IMapDescription mapDesc,
IImageDisplay pMapDisplay,
IColor backgroundColor,
IImageDescription imageDesc)
Exports a legend to an image file. |
IImageResult |
exportNorthArrow(INorthArrow arrow,
IMapDescription mapDesc,
IColor backgroundColor,
IImageDescription imageDesc)
Exports a north arrow to an image file. |
IImageResult |
exportScaleBar(IScaleBar scalebar,
IMapDescription mapDesc,
IImageDisplay pMapDisplay,
IColor backgroundColor,
IImageDescription imageDesc)
Exports a scale bar to an image file. |
void |
fromPagePoints(IEnvelope pageExtent,
IImageDisplay pageDisplay,
IPointCollection pagePoints,
ILongArray[] screenXValues,
ILongArray[] screenYValues)
Converts a page coordinate to a screen location. |
IPageDescription |
getDefaultPageDescription()
The default page settings. |
IPointCollection |
toPagePoints(IEnvelope pageExtent,
IImageDisplay pageDisplay,
ILongArray screenXValues,
ILongArray screenYValues)
Converts a screen location to a page coordinate. |
| Method Detail |
|---|
IPageDescription getDefaultPageDescription()
throws IOException,
AutomationException
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
ILayoutImage exportLayout(IPageDescription pageDesc,
IImageDescription imageDesc)
throws IOException,
AutomationException
Use ExportLayout to retrieve a file (image or vector format) of the map's layout.
PageDescription refers to properties describing the actual map layout. These include the Height and Width of the layout in page Units , the layout page extent in page units, map descriptions for each map frame in the layout and any CustomGraphics to be placed in the layout. Size, resolution and file format are determined by the ImageDescription, which includes ImageDisplay and ImageType .
ExportLayout returns a LayoutImage object. The page Extent of the layout, an array of MapImages (data frames), can be gleaned from this object. In addition, the geographic MapExtent, MapScale and an array of VisibleLayers for each data frame in the layout can be retrieved from the MapImage object.
Do not use IMapServerLayout to create new layouts or to create layouts "on-the-fly". You cannot change the actual page size of the map layout, reposition map elements on the layout nor can you add or remove layout elements such as titles, text, graphics, scale bars, north arrows and legends. However, you can define the size and resolution of the output. How these parameters are defnied can affect the results. These effects are outlined below. You can also choose to export a clipped portion of the page layout.
Let's look at an example. An existing map layout has a portrait page orientation with a height of 11 inches and a width of 8.5 inches. The absolute scale for the map is 1:30,000,000. There are some layers within the map that are scale dependent. This scale is based on the page size of the layout and the relative size of the map's data frame.
You can export the layout to either a vector or an image type. This is specified by the ReturnType property of IImageType.
Exporting to vector format (e.g. PDF)
If you are exporting to a vector format, such as PDF, and want to retain the original size of the layout as specified in the map document the dimensions need not be set. Not specifying a Height and Width for IImageDisplay2, or specifying 0 for both, will cause the export result to maintain the original size of the layout as specified in the source map document. The Height and Width properties of IImageResult are read-only and are not used to make changes.
The the best results it is recommended that you do not specify Height or Width in the ImageDisplay. Let the page size set in the source map determine the size of our output.
If you have a raster layer in your map, or the map has transparency, you may want to increase the DeviceResolution set in IImageDisplay for better results. The map scale and layer visibility should not be affected. The size of ExportLayout result should be adjusted using the height and width properties of the ImageDisplay. You can increase or decrease the relative size of the map layout. Remember, you are not changing the size of the layout of the source map. You are changing the size of the exported result.
For example, you wish to reduce the image of the 11 inch by 8.5 inch layout described above by half. The DeviceResolution is set at 96. You will need to specify a height of 528 and a width of 408. Please note that the map scale does not change. The absolute scale of the map will be incorrect, though the scale bar should be correct since its size changes relative to the change in output size. This effect is similar to shrinking a printed map using a photocopying machine. The result will be 5.5 inches by 4.25 inches PDF.
Once you specify the height and width the value of the DeviceResolution will have an impact on the result. Think of 96 as a baseline for the layout's page (1 inch = 96 pixels). Values different from 96 will require appropriate adjustments in height and width. Using the example above, if the DeviceResolution was 300, the height and width needed to reduce the resulting layout to a PDF of 5.5 inches by 4.25 inches would be 1650 pixels by 1275 pixels.
Changing the aspect ratio (height x width) of the ExportLayout output will not change the aspect ratio of the map layout. For example, again using the layout example above, a height of 816 and a width of 1056 pixels are specified. This will not change the orientation of the page layout from portrait to landscape. Instead, the original portrait orientation of the layout will be maintained and will be fitted into the 816 x 1056 space. This will result in white space on either side of the layout.
Exporting to image format (e.g. JPG)
You can change the size of results using the height and width properties of IImageDisplay. For example, you wish to reduce the image of the 11 by 8.5 layout described above by half. You specify a height of 528 and a width of 408 for the image result. Please note that the map scale does not change. Remember, it is the output size of the image result that is being adjusted. Therefore, the absolute scale of the map will be incorrect, though the scale bar should be correct since its size changes relative to the change in output size. This effect is similar to shrinking or enlarging a printed map using a photocopying machine. When specifying a height and width for a raster format, the value set for DeviceResolution will have no affect on the result.
If you do not specify height or width (or use 0) the size of the image file will be a function of the DeviceResolution and the size of the layout page (where 1 inch = 96 pixels). For example, you specify a DeviceResolution of 96 for the above layout the result will be an image of 1056 pixels by 816 pixels. Increasing the DeviceResolution will increase the size of the output. For example, setting the DeviceResolution to 300 will result in an image of 3300 pixels by 2550 pixels.
Changing the aspect ratio (height x width) of the ExportLayout output will not change the aspect ratio of the map layout. For example, again using the layout example above, a height of 816 and a width of 1056 pixels are specified. This will not change the orientation of the page layout from portrait to landscape. Instead, the original portrait orientation of the layout will be maintained and will be fitted into the 816 x 1056 space. This will result in white space on either side of the layout.
In order to control the size of an exported image, IMapServerInit2 contains two properties: MaxImageHeight and MaxImageWidth. The default value for these properties is 1024 pixels.
Miscellaneous
If you wish to export a portion of the page layout use Extent on IPageDescription. The extent is in the page units of the map document.
Page space is an important component of ExportLayout. It exists for all map documents and the map services the documents are based on. This page space provides the default size of the exported layout (for best results you should use this default). Page space does not figure in ExportMapImage. Therefore, you will see differences in results when adjusting the Height, Width or DeviceResolution for a ExportLayout as compared to making similar adjustments for ExportMapImage.
Another important thing to consider when authoring a layout to be used with IMapServerLayout is to uncheck the "Use Printer Paper Settings" checkbox on the Page and Print Setup dialog in ArcMap before saving the map. Otherwise, the page setup may be dependent on a printer unavailable to the server or users. This may result in a rescaling of the map and unexpected results.
pageDesc - A reference to a com.esri.arcgis.carto.IPageDescription (in)imageDesc - A reference to a com.esri.arcgis.carto.IImageDescription (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
IImageResult exportLegend(ILegend legend,
IMapDescription mapDesc,
IImageDisplay pMapDisplay,
IColor backgroundColor,
IImageDescription imageDesc)
throws IOException,
AutomationException
Use ExportLegend to export a single image representing the map's legend. Use the input parameter ILegend to access the Legend object in order to customize the legend. If the MapDescription parameter is Nothing/Null the default map description is used. Use TransparentColor in IImageDisplay2 if you want the background to be transparent. Size, resolution and file format are determined by the ImageDescription object, which includes ImageDisplay and ImageType. ExportLegend results in an ImageResult object.
An ExportLegend result displays all visible layers in the map (default).
The default size of a legend is based on the number of layers, symbol size and length of label or description text. This size is likely to vary from map to map.
To best manage the size of the ExportLegend request keep either the width or the height set in ImageDisplay constant. This ImageDisplay object is part of the imageDesc parameter. Don't confuse this ImageDisplay object with the one that refers to the map (MapDisplay).
In order to ensure a constant size do not specify a height and width, or set a value of 0 for each, for the ImageDisplay. However, you can enter your own height or width values. For example, set the ImageDisplay width at 150 and set the height at 0. A setting of 0 will calculate a default value for best fit. The actual height value will adjust as the legend changes to accommodate changes in layer visibility. Depending on the symbols and text you have in youir legend, symbol and text size may not be constant as the number of legend items changes such as when you turn on or off map layers. Make sure to provide an adequate size to the legend to accomodate this. Otherwise, parts of the legend may be cut off or the legend may be illegible. You may need to experiment to find an adequate size. Remember, setting 0 for both the height and width will provide the most consistent and accurate results.
To achieve more control over the legend of a MapServer map use the ILegend input parameter or use GetLegendInfo on IMapServer.
legend - A reference to a com.esri.arcgis.carto.ILegend (in)mapDesc - A reference to a com.esri.arcgis.carto.IMapDescription (in)pMapDisplay - A reference to a com.esri.arcgis.carto.IImageDisplay (in)backgroundColor - A reference to a com.esri.arcgis.display.IColor (in)imageDesc - A reference to a com.esri.arcgis.carto.IImageDescription (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
IImageResult exportScaleBar(IScaleBar scalebar,
IMapDescription mapDesc,
IImageDisplay pMapDisplay,
IColor backgroundColor,
IImageDescription imageDesc)
throws IOException,
AutomationException
Use ExportScaleBar to retrieve the map's scale bar. To customize the scale bar pass in a ScaleBar object. If you pass in Nothing/Null for the input paramter ScaleBar, a default alternating scale bar is drawn. The scale is calculated according to the height and width of the the image (pMapDisplay). This ImageDisplay object refers to the map. Another ImageDisplay object will be used (as part of the imageDesc parameter) that refers to the Scale Bar image. A color background can be set for the ScaleBar swatch by using the backgroundColor parameter. If this is Nothing/Null a white background will be used. Use TransparentColor in IImageDisplay2 if you want the background to be transparent. Size, resolution and file format are determined by ImageDescription, which includes ImageDisplay and ImageType. ExportScaleBar returns an ImageResult object.
Use the height and width properties of IImageDisplay
(as part of the imageDesc parameter) to set the proper size of the
scalebar. Entering a 0 for either the height or the width for
ExportScaleBar output results in an error.
scalebar - A reference to a com.esri.arcgis.carto.IScaleBar (in)mapDesc - A reference to a com.esri.arcgis.carto.IMapDescription (in)pMapDisplay - A reference to a com.esri.arcgis.carto.IImageDisplay (in)backgroundColor - A reference to a com.esri.arcgis.display.IColor (in)imageDesc - A reference to a com.esri.arcgis.carto.IImageDescription (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
IImageResult exportNorthArrow(INorthArrow arrow,
IMapDescription mapDesc,
IColor backgroundColor,
IImageDescription imageDesc)
throws IOException,
AutomationException
Use ExportNorthArrow to export the map's north arrow. To customize the north arrow (e.g. size) or to change the type of north arrow marker pass in a NorthArrow object. If you pass in Nothing/Null for this input parameter, a standard north arrow is drawn. A color background can be set for the North Arrow swatch by using the backgroundColor parameter. If this is Nothing/Null a white background will be used. Use TransparentColor in IImageDisplay2 if you want the background to be transparent. Size, resolution and file format are determined by ImageDescription, which includes ImageDisplay and ImageType. ExportNorthArrow results in an ImageResult object.
The orientation of the NorthArrow is determined by the MapRotation property on IMapDescription.
ExportNorthArrow output does not require a size. A default size is calculated based on the size of the NorthArrowMarker symbol. Setting 0 for both the height and the width property of IImageDisplay for ExportNorthArrow output results in a default size that best fits the NorthArrowMarker symbol.
arrow - A reference to a com.esri.arcgis.carto.INorthArrow (in)mapDesc - A reference to a com.esri.arcgis.carto.IMapDescription (in)backgroundColor - A reference to a com.esri.arcgis.display.IColor (in)imageDesc - A reference to a com.esri.arcgis.carto.IImageDescription (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
IPointCollection toPagePoints(IEnvelope pageExtent,
IImageDisplay pageDisplay,
ILongArray screenXValues,
ILongArray screenYValues)
throws IOException,
AutomationException
Use ToPagePoints to convert pixel coordinates on the screen to page units coordinates on the layout.
pageExtent - A reference to a com.esri.arcgis.geometry.IEnvelope (in)pageDisplay - A reference to a com.esri.arcgis.carto.IImageDisplay (in)screenXValues - A reference to a com.esri.arcgis.system.ILongArray (in)screenYValues - A reference to a com.esri.arcgis.system.ILongArray (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void fromPagePoints(IEnvelope pageExtent,
IImageDisplay pageDisplay,
IPointCollection pagePoints,
ILongArray[] screenXValues,
ILongArray[] screenYValues)
throws IOException,
AutomationException
Use FromPagePoints to convert page unit coordinates on the layout to pixel coordinates on the screen.
pageExtent - A reference to a com.esri.arcgis.geometry.IEnvelope (in)pageDisplay - A reference to a com.esri.arcgis.carto.IImageDisplay (in)pagePoints - A reference to a com.esri.arcgis.geometry.IPointCollection (in)screenXValues - A reference to a com.esri.arcgis.system.ILongArray (in/out: use single element array)screenYValues - A reference to a com.esri.arcgis.system.ILongArray (in/out: use single element array)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||