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.

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.

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.

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:

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:

Completing the print operation

To send the print job to a printer after using the FlexPrintJob addObject() 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 -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx: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();
            }
        ]]>
    </mx:Script>

    <mx:VBox id="myVBox">
        <mx:DataGrid id="myDataGrid" width="300">
            <mx:dataProvider>
                <mx:Object Product="Flash" Code="1000"/>
                <mx:Object Product="Flex" Code="2000"/>
                <mx:Object Product="ColdFusion" Code="3000"/>
                <mx:Object Product="JRun" Code="4000"/>
            </mx:dataProvider>
        </mx:DataGrid>
        <mx:Button id="myButton" 
            label="Print" 
            click="doPrint();"/>
    </mx:VBox>
</mx: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.