Written by: Patrick Mineault, , http://www.5etdemi.com
Difficulty Level: Beginner
Requirements: MX 2004
Topics Covered: Printjob class
Assumed Knowledge: actionscript

The PrintJob class

Handling printing in Flash is easier than ever with the new PrintJob class introduced in MX 2004. Gone are the old days of awkward frame labels and half-decent printing functions. Now, you finally have control over printing through actionscript. PrintJob requires Flash player 7 or later to run.

You can use PrintJob whenever you need to print something different than what's on stage. For example, movies that have an opaque background don't usually print well, but you can easily set up a PrintJob with more printer-friendly colors.

How it works

The PrintJob class works by taking the content a variety of movieclips, sending these to a spooler, and finally printing the content of the spooler. Here's how you would typically use the class:

  1. Create an instance of the PrintJob class
  2. Call the start method to bring up the print dialog
  3. Add pages to the spooler using addPage
  4. Empty the spooler and print the pages using send
  5. Delete the printjob

And a typical script:

btn.onRelease = function()
{
        var pj = new PrintJob();
        var success = pj.start();
        if(success)
        {
                pj.addPage (0, {xMin : 0, xMax: 400: yMin: 0, yMax: 400});
                pj.addPage("mc", {xMin : -300, xMax: 300, yMin: 400, yMax: 800});
                pj.send();
        }
        delete pj;
}

First, an instance of PrintJob is created. Then, the print job is started. The print dialog pops up at this point and the user selects print parameters. During this time, the Flash movie is frozen. Once the person cancels or accepts the print dialog, the script resumes on the next line. The start method returns either true or false depending on whether the person accepts or cancels the dialog.

After this time, the addPage method is repeatedly called to add new pages to the spooler. The send method is then called to empty the spooler and send it to the printer. After this, it's important to delete the print job to release the memory allocated to it.

The addPage method

The addPage method is the central method of the PrintJob class. It sends pages to the spooler. The signature for this method is:

pj.addPage(target[,printArea:Object, options:Object, frameNum:Number]):boolean;

The printArea object has the following properties

{xMin: <em> Number</em>, xMax: <em> Number</em>, yMin: <em> Number</em>, yMax: <em> Number</em>}

As for the options:

{printAsBitmap: <em> Boolean</em>}

That's a lot of options for a single method so let's study these parameters one by one. The target is the movieclip to be printed. The name of the movieclip should be in quotation marks. If you want to print the stage (_root), you should set this to 0 (as in _level0); to print a level, enter the number for that level.

Next, you need to specify the part of the movieclip that you want to print. The printArea is an object with properties xMin, xMax, yMin and yMax that define a rectangular area to be printed.

The options object has only one parameter, printAsBitmap, which can be either true or false. By default it is false; by setting it to true, you can enable alpha transparency and color effects to show up on the print.

Finally, in the case of a multiple frame movieclip, you may specify a frame number you wish to print.

The printArea

The Flash documentation is a bit cryptic concerning how the printArea is handled:

"If you want to scale a movie clip before you print it, set its MovieClip._xscale and MovieClip._yscale properties before calling this method, then set them back to their original values afterward. The scale of a movie clip has no relation to printArea . That is, if you specify that you print an area that is 50 x 50 pixels in size, 2500 pixels are printed. If you have scaled the movie clip, the same 2500 pixels are printed, but at the scaled size."

What's not mentionned here is why you would want to scale a movieclip before printing it. A pixel is always translated into a single point when printed. Contrarely to what you might expect, Flash won't automatically scale the movieclip to fit the printed paper, so if you need it scale, you'll have to implement that functionality yourself.

The Flash documentation uses a print area of 600 by 800. Where does this area come from? Well, it's pretty simple: the standard paper size is 8.5x11 inches. Knowing that the screen resolution for Windows is 72 dpi, multiplication gives us 612 by 792, or about 600 by 800. Now, it's important to understand that these numbers may vary: even though the exterior size is 612 by 792, many printers have interior borders. Couple that with the fact that other paper sizes (like A4) may be used, and you have a sticky situation on your hands.

Thankfully, after calling start on your printJob object and returning from the Print dialog, you'll have access to the following properties:

PrintJob.paperHeight
PrintJob.paperWidth
PrintJob.pageHeight
PrintJob.pageWidth
PrintJob.orientation

The first two are the outer dimensions of the printed page; the next two are the inner dimensions (within the borders). The last parameter is the orientation of the paper, either portrait or landscape.

If you want to print a movieclip to stretch to the size of the printed paper, you will have to scale the movieclip down or up before adding to the spooler. Another solution is to construct the movieclip to be printed on the fly using the drawing API and moving child movie clips around once you've received the page dimension information.

If you don't want to over-complicate things, your best bet is to keep your movieclip at a size around 612 by 792, and having relatively large margins so that your entire page shows up even if the person is using another paper size (ie: A4).

Saving trees

While you're testing out the PrintJob class, you can save some valuable paper by printing to a file using Acrobat Distiller. You'll probably want to test it out once on real paper though, as the margins in Acrobat are different than on typical printers.

If you need professional help with ActionScript, please visit 5etdemi.com for my portfolio and contact info. Happy flashing!