Using the FlexPrintJob class

You use the FlexPrintJob class to print one or more Flex objects, such as a Form or VBox container. For each object that you specify, Flex prints the object and all objects that it contains. The objects can be all or part of the displayed interface, or they can be components that format data specifically for printing. The FlexPrintJob class lets you scale the output to fit the page, and automatically uses multiple pages to print an object that does not fit on a single page.

You use the FlexPrintJob class to print a dynamically rendered document that you format specifically for printing. This capability is especially useful for rendering and printing such information as receipts, itineraries, and other displays that contain external dynamic content, such as database content and dynamic text.

You often use the FlexPrintJob class within an event listener. For example, you can use a Button control with an event listener that prints some or all of the application.

Note: The FlexPrintJob class causes the operating system to display a Print dialog box. You cannot print without some user action.

Build and send a print job

You print output by building and sending a print job.

  1. Create an instance of the FlexPrintJob class:

    var printJob:FlexPrintJob = new FlexPrintJob();
  2. Start the print job:

    printJob.start(); 

    This causes the operating system to display a Print dialog box.

  3. Add one or more objects to the print job and specify how to scale them:

    printJob.addObject(myObject, FlexPrintJobScaleType.MATCH_WIDTH); 

    Each object starts on a new page.

  4. Send the print job to the printer:

    printJob.send(); 
  5. Free up any unneeded objects.

Note: Because you are spooling a print job to the user’s operating system between your calls to the start() and send() methods, you should limit the code between these calls to print-specific activities. For example, the content should not interact with the user between the start() and send() methods.

The following sections detail the procedures to use in these steps.

Starting a print job

To start a print job, you create an instance of the FlexPrintJob class and call its start() method. This method prompts Flash Player or Adobe® AIR™ to spool the print job to the user’s operating system, which causes the user’s operating system to display a Print dialog box.

If the user selects an option to begin printing from the Print dialog box, the start() method returns a value of true. If the user cancels the print job, the return value is false. After the user exits the operating system Print dialog box, the start() method uses the printer information to set values for the FlexPrintJob object’s pageHeight and pageWidth properties, which represent the dimensions of the printed page area.

Note: Depending on the user’s operating system, an additional dialog box might appear until spooling is complete and the application calls the send() method.

Only one print job can be active at a time. You cannot start a second print job until one of the following has happened with the previous print job:

  • The start() method returns a value of false (the job failed).

  • The send() method completes execution following a successful call to the addObject() method. Because the send() method is synchronous, code that follows it can assume that the call completed successfully.

Adding objects to the print job

You use the addObject() method of the FlexPrintJob class to add objects to the print job. Each object starts on a new page; therefore, the following code prints a DataGrid control and a Button control on separate pages:

printJob.addObject(myDataGrid); 
printJob.addObject(myButton);

Scaling a print job

The scaleType parameter of the addObject() method determines how to scale the output. Use the following FlexPrintJobScaleType class constants to specify the scaling method:

Constant

Action

MATCH_WIDTH

(Default) Scales the object to fill the available page width. If the resulting object height exceeds the page height, the output spans multiple pages.

MATCH_HEIGHT

Scales the object to fill the available page height. If the resulting object width exceeds the page width, the output spans multiple pages.

SHOW_ALL

Scales the object to fit on a single page, filling one dimension; that is, it selects the smaller of the MATCH_WIDTH or MATCH_HEIGHT scale types.

FILL_PAGE

Scales the object to fill at least one page completely; that is, it selects the larger of the MATCH_WIDTH or MATCH_HEIGHT scale types.

NONE

Does not scale the output. The printed page has the same dimensions as the object on the screen. If the object height, width, or both dimensions exceed the page width or height, the output spans multiple pages.

If an object requires multiple pages, the output splits at the page boundaries. This can result in unreadable text or inappropriately split graphics. For information on how to format your print job to avoid these problems, see Printing multipage output.

The FlexPrintJob class includes two properties that can help your application determine how to scale the print job. These properties are read-only and are initially 0. When the application calls the start() method and the user selects the Print option in the operating system Print dialog box, Flash Player or AIR retrieves the print settings from the operating system. The start() method populates the following properties:

Property

Type

Unit

Description

pageHeight

Number

Points

Height of the printable area on the page; does not include any user-set margins.

pageWidth

Number

Points

Width of the printable area on the page; does not include any user-set margins.

Note: A point is a print unit of measurement that is 1/72 of an inch. Flex automatically maps 72 pixels to one inch (72 points) of printed output, based on the printer settings.

Completing the print operation

To send the print job to a printer after using the FlexPrintJobaddObject() method, use the send() method, which causes Flash Player or AIR to stop spooling the print job so that the printer starts printing.

After sending the print job to a printer, if you use print-only components to format output for printing, call removeChild() to remove the print-specific component. For more information, see Using a print-specific output format.

Example: A simple print job

The following example prints a DataGrid object exactly as it appears on the screen, without scaling:

<?xml version="1.0"?>
<!-- printing\DGPrint.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">

    <fx:Script>
        <![CDATA[
            import mx.printing.*;

            // Create a PrintJob instance.
            private function doPrint():void {
                // Create an instance of the FlexPrintJob class.
                var printJob:FlexPrintJob = new FlexPrintJob();

                // Start the print job.
                if (printJob.start() != true) return;

                // Add the object to print. Do not scale it.
                printJob.addObject(myDataGrid, FlexPrintJobScaleType.NONE);

                // Send the job to the printer.
                printJob.send();
            }
        ]]>
    </fx:Script>

    <mx:VBox id="myVBox">
        <mx:DataGrid id="myDataGrid" width="300">
            <mx:dataProvider>
                <fx:Object Product="Flash" Code="1000"/>
                <fx:Object Product="Flex" Code="2000"/>
                <fx:Object Product="ColdFusion" Code="3000"/>
                <fx:Object Product="JRun" Code="4000"/>
            </mx:dataProvider>
        </mx:DataGrid>
        <mx:Button id="myButton" 
            label="Print" 
            click="doPrint();"/>
    </mx:VBox>
</s:Application>

The executing SWF file for the previous example is shown below:

In this example, selecting the Button control invokes the doPrint() event listener. The event listener creates an instance of the FlexPrintJob class to print the DataGrid control, adds the DataGrid control to the print job using the addObject() method, and then uses the send() method to print the page.

To print the DataGrid and Button controls on your page, specify myVBox, the ID of the object that contains both controls, in the addObject() method’s object parameter. If want to print the DataGrid and Button controls on separate pages, specify each object in a separate addObject() method.

To print the DataGrid control so that it spans the page width, omit the second addObject() method parameter, or specify FlexPrintJobScaleType.MATCH_WIDTH. To print the DataGrid control with the largest size that fits on a single page, specify FlexPrintJobScaleType.SHOW_ALL. In the previous example, FlexPrintJobScaleType.SHOW_ALL has the same result as FlexPrintJobScaleType.MATCH_WIDTH because the DataGrid is short.

Print containers with a transparent background

Many Flex containers, such as the Spark Group and MX Box containers, are transparent by default. If you print a transparent container, the background color of anything behind the transparent container prints.

As an alternative to the Spark Group container, use a Spark BorderContainer or a SkinnableContainer with the backgroundColor property set. You can also define another container behind the Group with the appropriate background color. Or, set the backgroundColor property of the Application container.

For the MX Box and other containers, make sure to set the backgroundColor property.