In Flex, you usually do printing in your application through FlextPrintJob.

According to Adobe, FlexPrintJob is:

• A class that prints one or more objects
• Automatically splits large objects for printing on multiple pages
• Scales the output to fit the page size

FlexPrintJob vs. Flash PrintJob

FlexPrintJob is a new print class introduced by Adobe for Flex. In Flash, there is a similar one, named PrintJob.

Here is how you call FlexPrintJob in Flex:

flexPrintJob.addObject(myPrintObject,scaleType)
- myPrintObject is the UIComponent you want to print
- scaleType specifies how to scale UIComponent to fit print page
  (e.g. matchWidth, matchHeight, fillPage, showAll)

To compare, here is how you call PrintJob in Flash:

printJob.addPage(Sprite(myPrintObject), rectangle, printJobOptions)
- myPrintObject is the UIComponent you want to print
- rectangle is the print area defined by a rectangle
- printJboOptions specifies print as a BitMap or in Vector format

So, what is the relationship between those two print classes?

FlexPrintJob is actually a wrapper for PrintJob class.

What does a wrapper class mean in this case? It means:

1.  FlexPrintJob eventually calls Flash PrintJob to finish the printing task.

2.  FlexPrintJob enhances the Flash PrintJob and simplifies its usage.

What is new in FlexPrintJob

Adobe claims that FlexPrintJob automatically slices large object for printing on multiple pages and scales the output to fit the page size.

To do so,  FlexPrintJob wraps the old Flash PrintJob in the following 8 steps:

Step 1:  Convert percentage width or height to explicit width or height

Step 2:  Calculate Scale Ratio based on Print Page Size and ScaleType (e.g. matchWidth)

Step 3:  Scale the print object to the required value

Step 4:  Find the number of pages required in vertical and horizontal

Step 5:  Create the print area in a shape of rectangle

Step 6:  Specify Print Options (BitMap or Vector)

Step 7:  Call Flash PrintJob to print each page

Step 8:  Restore from explicit width or height to percentage width or height

What is missing in FlexPrintJob

FlexPrintJob enhances the Flash PrintJob in terms of scaling the output to fit the page size. However, is it good enough to print large object on multiple pages?

Maybe… as long as you don’t mind cutting text in half or printing only 5% content of TextArea or DataGrid.

As a matter of fact, to really support multiple pages printing in Flex, it need to resolve the following 3 issues:

1. How to scale display objects from screen to printer?

2. How to print the full content of Scrollable Components such as TextArea or DataGrid?

3. How to find the right page breaker to avoid cutting objects (e.g. Text or Image) in half?

Through the implementation of FlexPrintJob, it does not provide good answers to issue#2 and issue#3. Therefore, when come to printing multiple pages in Flex, you often need extra helps like PrintDataGrid or FlexReport.

In the previous tutorial, we saw How to Print Multiple Pages Using Flex PrintDataGrid. It works fine when your application just contains one big DataGrid. In the real world, however, you often need a combination of contains and controls like VBox, HBox, Text, Image, plus DataGrid. Then guess what? You still have trouble with the Flex print job.

In fact, this is not the only challenge you are facing… How about the Print Preview function? Why do you need it? Because we are in recession! Oh, yeah, your boss would try to squeeze every penny for the sake of Cost Reduce. No one likes to see you print 100 pages then realize it is a wrong report. Plus saving paper is good for our mother earth.

Unfortunately,  till Flex 3,  Adobe has not provided a good solution to either Multiple Pages Printing or Print Preview (without client-side installation like PDF Printer).

FlexReport

As I mentioned before, my first Flex job was to find a better way to print multiple pages. So I did a lot of research on the 3rd party solutions. I was quite frustrated at that time. It seemed like everyone was focusing on Flex Layout, Animation, and Backend System Integration. Nobody cared about such a lower level job – Print. No wonder Adobe is not in hurry to provide a better support for Flex Print.

Finally, there was one open source project got my attention. It’s called FlexReport. After thoroughly reviewed its source code and demo application, I would have to say FlexReport is by far the closet solution to the Flex Print problem.

You can find the information about the FlexReport from the following URLs:

1. FlexReport Introduction
   http://www.kemelyon.com/bts/2008/01/14/flexreport/

2. FlexReport Demo Application
   http://www.kemelyon.com/flexreport/0_2rc1/

3. FlexReport Source File Download
   http://www.kemelyon.com/flexreport/srcview/FlexReport.zip

   Notes:
   If you counter any troubles to run the original FlexReport
   from the above link. You can Download My Working Version Here.
   I fixed some class reference problems and ran it fine in Flex 3.

How can FlexReport help you

The best way to see how much FlexReport can help you is to Try It. Download a copy and run it in your Flex Builder.

I found FlexReport was pretty cool in the following 3 areas:

1. Print preview
   Provides a nice preview by generating print pages through Bitmaps.
   Has a built-in PDF Printer, No extra software required to end users.

2. Report layout
   Creates dynamic reports without knowing how many pages in advance.

3. Multi-page text printing 
   Except PrintDataGrid, adds a PrintText for long Text printing.

What is FlexReport missing

The biggest problem of FlexReport is: it assumes your Flex Components (Controls and Contains) are mainly Vertical-Stacked. For example, you have a  TextArea at the top, then a DataGrid starting after the bottom of the TextArea, then an Image after the DataGrid.

However, many corporate forms are not like that, they usually mix Vertical and Horizontal Layout. For instance, you may have 3 Labels, 2 Text Areas, and 2 Images horizontal-aligned while other 2 DataGrids, 2 Texts, 3 Images vertical-aligned. FlexReport might give you some weird results in this case.

Conclusion

FlexReport is a nice solution to none-critical Flex printing  jobs. It enhances Flex Print function in terms of Print Preview, Report Layout, and Multi-page Text Printing. However,  FlexReport still has some issues to handle complex corporate reports especially with mixed Vertical and Horizontal Layout.

So, how can you further improve from FlexReport? To do so, you need to know some concepts and implementations of Flex Framework. This will be covered in our next tutorial – Understanding Flex Print Job from A to Z.

To start to print on a new page, you need to write a code like this:

printJob.addObject(targetComponent);

It  adds your component to FlexPrintJob. But how many pages is it going to take?

The typical example is DataGrid. It might contains 1 or 1000 records. There is no way we can predetermine the size when binding with a dynamic data provider. Plus how do you know where to put the page break, like record 1-17 on page 1,  18-30 on page 2 …?

Fortunately, Flex gives you a workaround to solve DataGrid printing issue. Here is how:

Things You Need

• mx.printing.FlexPrintJob
• mx.printing.PrintDataGrid

Steps You Do

1. Create a FlexPrintJob Instance     
   var flexPrintJob: FlexPrintJob = new FlexPrintJob();

2. Start FlexPrintJob
   flexPrintJob.start();

3. Create PrintDataGrid 
   var myPrintData:PrintDataGrid = new PrintDataGrid();
   Application.application.addChild(myPrintData);

4. Set PrintDataGrid's DataProvider(from DataGrid), Width, and Height
   myPrintData.dataProvider = myData.dataProvider;
   myPrintData.width = printJob.pageWidth;
   myPrintData.height = printJob.pageHeight;

5. Loop PrintDataGrid to Generate Multiple Print Pages
   printJob.addObject(myPrintData);
   while (myPrintData.validNextPage) {
   	  myPrintData.nextPage();
    	  printJob.addObject(myPrintData);
   }

6. Print
   printJob.send();

Sample Code

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    layout="absolute"
    initialize="init()">

    <mx:Script>
    	<![CDATA[
    	import mx.printing.PrintDataGrid;
    	import mx.printing.FlexPrintJob;
    	import mx.collections.ArrayCollection;

    	[Bindable]
    	public var dataSource:ArrayCollection = new ArrayCollection();

        private var totalRecords:Number = 100;

    	private function init():void {
		for (var i:int = 1; i<=totalRecords; i++) {
    		  var dataObject:Object = new Object();
    		  dataObject.Name = "Name #" + i;
    		  dataObject.Phone = "Phone #" + i;
    		  dataObject.Address = "Address #" + i;
    		  dataSource.addItem(dataObject);
    		}
    	}

    	private function doPrint():void {
    		var printJob:FlexPrintJob = new FlexPrintJob();
    	   	if (printJob.start()) {
       		  var myPrintData:PrintDataGrid = new PrintDataGrid();
     	   	  Application.application.addChild(myPrintData);
         	  myPrintData.dataProvider = myData.dataProvider;
    	   	  myPrintData.width = printJob.pageWidth;
    	   	  myPrintData.height = printJob.pageHeight;

    	   	  printJob.addObject(myPrintData);
    	   	  while (myPrintData.validNextPage) {
    	   		myPrintData.nextPage();
    	   		printJob.addObject(myPrintData);
    	   	  }
    	   	  Application.application.removeChild(myPrintData);

                  printJob.send();
    	        }
    	}

    	]]>
    </mx:Script>

    <mx:Panel title="Flex Tutorial - PrintDataGrid"
    	width="500" height="500"
    	horizontalCenter="0" verticalCenter="0"
    	horizontalAlign="center" verticalAlign="middle">

        <mx:DataGrid id="myData"
            dataProvider="{dataSource}"
            width="400" height="400" />

        <mx:Button label="Print" click="doPrint()"/>

    </mx:Panel>

</mx:Application>

Conclusion

Adobe Flex provides PrintDataGrid to solve the problem of multiple pages printing. It works fine when your application mainly contains one big DataGrid.

However, life is not that simple. In many cases, you need to have a combination of different contains and controls like Canvas, VBox, HBox, Label, Text, Text Area, Image, plus DataGrid. Unfortunately, until Flex 3,  Adobe has not provided any better solution beyond FlexPrintJob and PrintDataGrid.

So, is there any 3rd party solution? I have done a lot of research. Eventually it narrows down to an open source project. This leads to our next tutorial – Printing Multiple Pages using FlexReport.

Things You Need

• mx.printing.FlexPrintJob

Steps You Do

1. Create a FlexPrintJob Instance     
   var flexPrintJob: FlexPrintJob = new FlexPrintJob();

2. Start FlexPrintJob
   flexPrintJob.start();

3. Add Target Component to FlexPrintJob 
   printJob.addObject(targetComponent);

4. Print
   printJob.send();

Sample Code

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    layout="absolute"
    initialize="init()">

    <mx:Script>
    	<![CDATA[
    	import mx.printing.FlexPrintJob;
    	import mx.collections.ArrayCollection;

    	[Bindable]
    	public var dataSource:ArrayCollection = new ArrayCollection();

        private var totalRecords:Number = 15; 

    	private function init():void {
		for (var i:int = 1; i<=totalRecords; i++) {
    		     var dataObject:Object = new Object();
    		     dataObject.Name = "Name #" + i;
    		     dataObject.Phone = "Phone #" + i;
    		     dataObject.Address = "Address #" + i;
    		     dataSource.addItem(dataObject);
    		}
    	}

    	private function doPrint():void {
    		var printJob:FlexPrintJob = new FlexPrintJob();
    	   	if (printJob.start()) {
    	            printJob.addObject(myData);
    		    printJob.send();
    		}
    	}

    	]]>
    </mx:Script>

    <mx:Panel title="Flex Tutorial - Print"
    	width="500" height="500"
    	horizontalCenter="0" verticalCenter="0"
    	horizontalAlign="center" verticalAlign="middle">

        <mx:DataGrid id="myData"
            dataProvider="{dataSource}"
            width="400" height="400" />

        <mx:Button label="Print" click="doPrint()"/>

    </mx:Panel>

</mx:Application>

Conclusion

Adobe Flex provides FlexPrintJob to handle the print request. It is very simple to use. However, the biggest challenge is printing multiple pages. In the above sample code, if you change the code,

From:

private var totalRecords:Number = 15;

To:

private var totalRecords:Number = 100;

It will generate 100 records in the DataGrid. Guess how many of them will be printed if you click the Print button?  Depends on your page and printer setting, maybe just 17-20. You will even see a ugly vertical scoll bar. The problem here is, FlexPrintJob itself can not SCOLL those Scollable Components like DataGrid or TextArea.

To resolve this problem, Adobe provides a workaround in Flex framework. In the next tutorial, we will see Printing Multiple Pages Using PrintDataGrid.

I know what you are thinking right now. Why should I care printing in Flex? Is Flex supposed to be used for creating cool stuffs rather than this kind of low-level system function? That was exactly what I thought at that time. But job is job, especially when the pay is good.

The interesting thing is I actually learned a lot from this printing job. Because it touched many key areas of Flex framework, such as: Container Framework, Component Construction, and Layout Management. The fact is, once you know something from inside out, you will feel some fun of doing it.

Over the next week, I want to write a series of 4 tutorials about How to Print in Flex. Here are the topics we will be covering:

1. Using Flex Build-in Print Function
2. Printing Multiple Pages using PrintDataGrid
3. Printing Multiple Pages using FlexReport
4. Understanding Flex Print Job from A to Z

To follow along with this series, make sure you subscribe to our RSS feed or bookmark and come back to this page.

Stay tuned for the next post of this tutorial series on Using Flex Build-in Print Function.