Printing

yFiles FLEX offers support for customized printing as well as a convenience method for common printing scenarios.

Using CanvasComponent's Printing Support

CanvasComponent's methods for printing support are listed in API Excerpt 4.14, “CanvasComponent support for printing”.

API Excerpt 4.14. CanvasComponent support for printing

// Print the current canvas content, scaled to fit the page
function print(bitmap:Boolean = true,
               borderSize:uint = 5,
               backgroundFill:* = 0xFFFFFF,
               printRect:Rectangle = null,
               canvasSprite:Sprite = null):void

The print method takes the current content rectangle of the CanvasComponent into account for scaling the content down to fit the page. Note that if the content rectangle is smaller than the printable page size, the content will not scale up to fit the page. The actual printing is done by a CanvasPrinter. This class offers a number of options which allow to customize the print output. It is described in detail in the section called “Advanced Printing using CanvasPrinter” below.

Advanced Printing using CanvasPrinter

Since version 1.3.2, yFiles FLEX offers the class CanvasPrinter which can be used to print the CanvasComponent allowing various customizations.

API Excerpt 4.15. Basic properties and methods of CanvasPrinter

// The canvas component to print.
public function get canvas():CanvasComponent
public function set canvas( value:CanvasComponent ):void

// Prints the contents of the canvas.
public function print():void

// The portion of the canvas that will be printed, in world coordinates.
public function get printRectangle():Rectangle
public function set printRectangle( value:Rectangle ):void

Note that before calling print() the CanvasComponent has to be set either via the canvas parameter of the constructor or the canvas property.

Specifying the part of the canvas that should be printed is done in world coordinates using the printRectangle property. Unless a clipping rectangle is explicitly provided that way, the entire contents of the canvas, i.e., the rectangle as returned by the CanvasComponent's contentRect property, is printed. Example 4.12, “Printing a canvas's currently visible contents” shows how to print the currently visible contents of a control.

Example 4.12. Printing a canvas's currently visible contents

public function printVisible(GraphCanvasComponent graphCanvas):void {
  // Print the currently visible contents of the given canvas component
  var printer:CanvasPrinter = new CanvasPrinter(graphCanvas);
  var viewPort:IRectangle = graphCanvas.viewPort;
  printer.printRectangle = new Rectangle(viewPort.x, viewPort.y, viewPort.width, viewPort.height);
  printer.scaleUpToFit = true;
  printer.print();
}

Table 4.7. Other properties of CanvasPrinter

Property Type Purpose
margin Rectangle A margin that is added between the printable bounds and the printed content.
centerContent Boolean Whether to center the printed content within the printable area.
scaleUpToFit Boolean Whether to scale up the output to fit the page if necessary.
scaleDownToFit Boolean Whether to scale down the output to fit the page if necessary.
backgroundColor * The color that will be used to fill the background of the printed document.
printAsBitmap Boolean Whether to use bitmap printing.

CanvasPrinter offers the possibility to print on multiple pages. The number of pages can be set via the vPages and hPages properties. If a margin is set, it will not be added to each individual page, but to the combined printable area.

API Excerpt 4.16. Properties for multi page printing

//The number of page rows to use for multi page printing.
public function get vPages():Number
public function set vPages( value:Number ):void

//The number of page columns to use for multi page printing.
public function get hPages():Number
public function set hPages( value:Number ):void

Customized Printing using Flex printing support

If one wants to customize further using standard Flex printing support, a Sprite containing a complete copy of the current canvas content can be retrieved using createSprite(). This sprite can then be printed using the Flex SDK's PrintJob API.

API Excerpt 4.17. CanvasComponent: creating a copy of the current canvas

// Create a Sprite object containing the current canvas content
function createSprite():PrintSprite

When the createSprite() method returns, some asynchronous painting routines might still be in progress. Therefore, if the returned sprite should be printed or exported to an image, the sprite's paintComplete property should be queried to determine if painting has finished:

Example 4.13. Waiting for asynchronous painting to finish

var printSprite:PrintSprite = canvasComponent.createSprite();
if(!printSprite.paintComplete) {
  var onPaintComplete:Function = function(evt:Event):void {
      printSprite.removeEventListener(Event.COMPLETE,onPaintComplete);
      myPrint(printSprite);
    };
  printSprite.addEventListener(Event.COMPLETE,onPaintComplete);
} else {
  myPrint(printSprite);
}