Output

The Output library is used to create graphic output to devices, such as printers and plotters, and to graphic file formats, such as .pdf and .tiff. There are other objects in the ArcGIS system that generate drawing commands, and the Output objects are used to convert those commands to graphic output. Drawing instructions are typically generated by objects in the Display and Carto libraries.

Developers can extend the Output library for custom devices and export formats.

The printer objects provide access to the ArcGIS printer engines. Each printer engine processes drawing instructions into a format that can be rendered on a print device. Several of the objects in the Printer subsystem are helper objects that provide information and control for things such as PostScript fonts and printer paper.

Use Printer Paper Settings option

If the Use Printer Paper Settings check box on the Page and Print Setup dialog boxes is checked, the selected printer's information is stored in the map document. If the map document is subsequently opened in an environment that doesn't include that printer, ArcMap automatically unchecks the Use Printer Paper Settings check box, and the page size set in the map document is used. This can generate unexpected results. For more information and code examples, see How to check for a saved printer and clear the use printer paper settings option.

The Paper object is a key object required by the Printer object. The Paper object is responsible for maintaining properties related to the paper and printer used with the Printer object. In ArcMap, the Paper object is accessed through the Printer Setup section of the Page and Print Setup dialog box.

When working with an ArcGIS application such as ArcMap, a Paper object is automatically created based on the default printer for the system. To use another printer in the system, you must define a new Paper object and set it to the printer or plotter through the IPaper.PrinterName property. The Paper object can then be associated with the Printer object through the IPrinter.Paper property.

The Paper object is basically a wrapper for the Microsoft Graphical Device Interface (GDI) DevMode and DevNames parameters. The Windows GDI documentation in the Microsoft Developer Network (MSDN) library provides further details about these structures. 

The DevNames structure contains strings that identify the driver, device, and output port names of a printer. The DevMode data structure contains information about the device initialization and environment of a printer.

The Attach method is used by a Printer object when the IPrinter.Paper property is set. Typically, ArcObjects developers do not use this method.

QueryPaperSize is a useful method for interrogating the dimensions of the printer's currently selected form size.

When printing from page layout, the printer's currently selected form can be set to match the size already set up in the layout. You can obtain information related to the layout's selected page size by using properties and methods from the PageLayout IPage interface. For example, to read the page layout's page size and match it to an available form on a given printer, enumerate through the available forms on the printer using an IEnumNamedID enumerator and select any matching form by comparing the page dimensions with the results returned by QueryPaperSize. For more details about this process and code examples, see How to enumerate through a printer's available page sizes.

The export objects provide access to the graphic file export drivers. These objects expose properties and methods that control resolution, bit depth, compression options, and so on. See the Export active view sample for an example of the export process.

Image format exports

The image format export objects render drawing commands into a bitmap that can be persisted into one of the following raster image formats:

If the drawing commands are generated by a map object, the IWorldFileSettings interface allows you to output the image coordinates and transform them to a world file. The IWorldFileSettings2 interface contains a parameter for data frame rotation. This allows the export of a correct world file for a rotated data frame. Use the IWorldFileSettings2.MapRotation property to specify data frame rotation - it can be populated from the active view ScreenDisplay.IDisplayTransformation.Rotation parameter. For an example, see How to initialize a world file with rotation.

For rasters smaller than 8 MB, the export object reads a device-independent bitmap from memory, converting it to the target image format. In cases where bitmap size is larger than 8 MB, the bitmap is exported to a temporary Enhanced Metafile (.emf) file, which is subsequently parsed and rendered to the target image format. You can override this size threshold by creating the registry key HKCU\Software\ESRI\Output and adding a DWORD value named esriExportRasterBufferSizeMB.

Microsoft font smoothing/ClearType and ArcGIS image exports

Font smoothing settings on the machine can negatively affect image exports from ArcGIS by increasing the color depth of the image. Some symptoms of this include "salt and pepper" patterns across previously solid-colored areas of an image or color interpretation problems. To ensure quality output from ArcGIS image exporters, you can disable the font smoothing option until your exports are complete. For code examples, see How to evaluate and change Windows font smoothing or ClearType during exports. For information on how to implement these functions, see Export active view.

Vector format exports

The vector export objects translate ArcGIS native drawing commands into one of the following vector graphic formats:

The objects expose properties and methods that control things such as font embedding, inserted image resolution and downsampling, and several format-specific items. One vector export feature, the Picture Symbol option, demonstrates how to set these options. For more information, see How to set the picture symbol vectorization settings for vector exports.

In ArcGIS, PDF export has the ability to retain many of the layers in the ArcMap map document as layers in the Portable Document Format (PDF). These PDF layers can be viewed and turned on and off independently in Adobe Acrobat or Adobe Reader. This option can be controlled using the IPDFExport2.ExportPDFLayersAndFeatureAttributes property. 

Map documents that were authored in ArcMap with the Data Driven Pages option enabled can output multiple pages to a printer or multipage PDF document. This allows for print and export of simple map books from ArcGIS. Data driven page output functionality is accessed through the PrintAndExport class. It is not possible to author or enable data driven pages via ArcObjects code. The primary automation for creating map books in ArcGIS is through Python scripting and the arcpy.mapping module.

Checking for data driven pages

If your application needs to determine if a Map document has the Data Driven Pages option enabled, use the IPrintAndExport.PageCount property. A value of zero indicates that pages are not enabled. A value greater than zero indicates pages are enabled and provides the current page count.

Printing and exporting data driven pages

To export the set of data driven pages to a single PDF document with multiple pages, use IPrintAndExport.ExportPages. To print the set of data driven pages through one of the printer classes, use IPrintAndExport.PrintPages.

As part of the Data Driven Pages output process, first create and configure a PrintAndExportPageOptions object. This object allows you to select which pages will be output and to control the suppression of selection symbology.

The Output Image Quality setting on the Export and Print dialog boxes affects the resampling of raster layers at print or export time. The setting changes the ResampleRatio property of the active view. Lower numbers result in better quality at the expense of resource consumption and performance. Higher numbers result in faster printing and lower resource consumption at the expense of quality. For raster output formats, set the Output Image Quality option to esriRasterOutputBest (1). For vector exports, the value can be set at any integer value between 1 and 5 or by using the esriResampleRatio constants.

Output image quality and the PrintAndExport class

When printing or exporting via the PrintAndExport class, the output image quality will be automatically gathered from the Export or Printer object's ResampleRatio property and applied to the active view.

Output image quality and fine-grained print and export

For cases where fine-grained control of the output process is necessary, you must author application logic to apply output image quality to the active view. PageLayout is a composite view that contains one or more data frames (maps). In this case, each data frame must be enumerated, and its ResampleRatio must be set. For an example of how to set the output image quality for either type of active view, see How to set output image quality.