Image export divides into bitmap-based image file formats and the vector graphics file format EMF. Either group of export formats is provided by an implementation of interface IImageExporter. Figure 4.1, “Class hierarchy in the yWorks.Canvas.IO namespace” shows the hierarchy of image exporter types.

Figure 4.1. Class hierarchy in the yWorks.Canvas.IO namespace

Implementations of IImageExporter rely on a ContextConfigurator object which is given at creation time. The ContextConfigurator encapsulates information that determines the actual setup when exporting the contents of a CanvasControl to any of the supported file formats. It specifies:

Specifying the part of the canvas that should be exported is done in world coordinates, either at creation time or using the WorldBounds property. The CanvasControl's ContentRect and Viewport properties, for example, conveniently provide the world coordinates to specify the canvas's entire contents or the contents currently visible.

When using the Scale property to set the scaling factor explicitly, the pixel dimensions of an image are derived automatically. Vice versa, the scaling factor can also be derived automatically such that a desired image width or image height is achieved. The SetScaleForWidth and SetScaleForHeight methods volunteer to this end.

// 'myCanvas' is of type yWorks.Canvas.CanvasControl.

// The entire content as specified in the CanvasControl instance.
ContextConfigurator cc = new ContextConfigurator(myCanvas.ContentRect);
// Set the scaling factor such that we get the desired width for the exported
// content.
// Note that the margins are added to this width subsequently.
cc.SetScaleForWidth(400);

Class PixelImageExporter provides support for exporting the contents of a CanvasControl to a number of bitmap-based image file formats: BMP, GIF, JPG, PNG, and TIFF. The formats can be written to a given stream using the following methods:

void Export(CanvasControl canvas, Stream stream)
void Export(CanvasControl canvas, Stream stream, string format)
void Export(CanvasControl canvas, Stream stream, 
            ImageCodecInfo codecInfo, EncoderParameters parameters)

PixelImageExporter uses the ContextConfigurator object given at creation time to determine the setup for viewport size, resulting image size, etc. The actual output format is specified either directly when exporting or using the OutputFormat property. Both ways use MIME type notation to set the file format.

The BackColor and SmoothingMode properties affect all bitmap-based export formats. Further properties of class PixelImageExporter have a meaning only for specific file formats.

// 'myConfiguration' is of type yWorks.Canvas.ContextConfigurator.
// 'myCanvas' is of type yWorks.Canvas.CanvasControl.

PixelImageExporter ie = new PixelImageExporter(myConfiguration);
ie.BackColor = Color.FromArgb(128, 200, 2, 20);
try {
  ie.Export(myCanvas, new FileStream("MyPNGFile.png", FileMode.CreateNew), 
            "image/png");
}
catch (IOException ioEx) {
  // Something went wrong. Complain.
}

Image export is shown in tutorial demo application ImageExportForm.

EMF (Enhanced Metafile Format) is a vector graphics file format that is supported by the yFiles.NET graph visualization library for exporting the visual representation of a graph structure. It is the format of choice to add high-quality diagrams to Windows text processing and graphics applications like Microsoft Word or Microsoft PowerPoint®.

Class EmfImageExporter can be used to conveniently export the contents of a CanvasControl to EMF file format. Export is done using the ContextConfigurator object given at creation time. As an option, EmfImageExporter enables using the canvas's background color when exporting its contents.

// 'myConfiguration' is of type yWorks.Canvas.ContextConfigurator.
// 'myCanvas' is of type yWorks.Canvas.CanvasControl.

EmfImageExporter ie = new EmfImageExporter(myConfiguration);
ie.FillBackground(true); // Use the canvas's background color.
try {
  ie.Export(myCanvas, new FileStream("MyEMFFile.emf", FileMode.CreateNew));
}
catch (IOException ioEx) {
  // Something went wrong. Complain.
}

Tutorial demo application ImageExportForm shows how to export the contents of a CanvasControl to EMF file format.