Printing in Flash (in 1,000,000,000 simple steps)

If there is one thing that really irritates me, it is when programmers and developers write tutorials or help sections that are targeted to users with the same level of expertise as themselves. Granted some skill sets do require a certain degree of knowledge, and tasks related to specific applications can vary between novice, intermediate, and expert. However, Help documentation should not be written with the assumption that he/she understands the application fully. Help documentation should be more than just reference information. In fact, a reference section should be a separate appendices that can be easily scannable.

In writing the LiveDocs, Printing a Page, the Flash developers have provided some information on how to use the PrintJob class as part of AS 3.0. The problem is that for the novice user, some of this seems like Ancient Greek, or possibly Sanskrit.

Part 1: Printing with the PrintJob Class

In Flash, it is possible to create a function to:

• Start a print job
• Adding additional pages
• Check to see if the user has canceled the print job
• Specify whether to use bitmap or vector rendering
• Set the page size, scale, and orientation
• Specifying the printable area of content
• Converting screen size to page size
• Printing multipage print jobs

LiveDocs, Basics of Printing

Since there is so much to cover, this tutorial is only intended to scratch the surface of the PrintJob class. We will focus primarily on starting a print job and sending a page to the printer, specifying whether the print job should be a bitmap or vector rendering, and specifying the print area.

Before we begin we need something to print. Since we have been using custom classes, I included the Splat.as file from Module 8 and the Pi.as (or Ball.as depending on how others named the file). Let’s get started.

1. Open up a new Flash AS3.0 fla file. Save this file as prj_print1.fla to a new folder labeled [lastname]_printTutorial. Next create a new AS3 .AS file and name it PrintExample1.as. Be sure to set the Document class of prj_print1.fla to the new AS file.
2. In our PrintExample1.as file, lets import the packages and classes we will need to print a page. Here I have just added wild cards (*) of the printing, display, and events packages. I could have just been really specific and put import flash.printing.PrintJob, but I like to have my code as flexible as possible in development. Later when, I am done I will go through and clean up the code to be more specific, but for now this works for me.

   package {
   
   	import flash.printing.*;
   	// This will add the PrintJob, PrintJobOptions,
   	// and PrintJobOrientation classes
   
   	import flash.display.*;
   	// This is to import the Sprite class. I probably
   	// just list Sprite, but I will wait until all is done
   
   	import flash.events.*;
   	// And this adds any event I may need to
   	// create my necessary event handlers
   
   }

3. Next, it’s time to create our custom class

   public class PrintExample1 extends Sprite

4. If we are going to print something, we will need something to print. Pretty obvious? If we don’t define our content, then the end result will be just a blank page. That works in a minimalistic, David Byrne kinda way, but let’s see what we are doing.I create a new Sprite called _content to contain all my content.

   private var _content:Sprite = new Sprite();

5. The next thing I want to do is pull in actual content to be printed. For this exercise I pulled in the Splat.as from Module 8, and the Ball.as (or Pi.as) from Module 9. Any will do. In fact, the TextField class, Rectangle class, and MovieClip Class can also be added, but for simplicity I chose two simple assignments from previous modules. I also created a PrintButton symbol and linked it as a class. So let’s call those classes:

   public var pi:Pi;
   public var twinkles:Splat;
   private var printBtn:PrintBtn;

6. Now that we have our custom classes called into our PrintExample1 file, lets create our function. Note, for the most part this is all review.

   public function PrintExample1(){ // Let's create our function
   	// First add the Print button. I am adding it
   	// outside of the _content Sprite because I don't
   	// want it to show up in my print out
   	printBtn = new PrintBtn();
   	printBtn.x = 18;
   	printBtn.y = 510;
   	printBtn.width = 108.2;
   	printBtn.height = 30;
   	addChild(printBtn);
   
   	// Next create the printJob handler
   	printBtn.addEventListener(MouseEvent.MOUSE_UP, printJob);
   
   	// Now add the _content Sprite to the stage
   	addChild(_content);
   
   	// Add the tinkles Splat to the _content Sprite
   	twinkles = new Splat();
   
   	_content.addChild(twinkles);
   	// Add my circle and tell the compiler what properties
   	//  (color, size and position) I want the circle to
   	pi = new Pi(0xFFCC00, 75);
   	pi.x = 30;
   	pi.y = 30;
   	pi.alpha = .65;
   	_content.addChild(pi);
   }

7. The last thing we need to do is to create our printJob function

   private function printJob(event:MouseEvent) {
   	// Call the _print instance as part of the PrintJob class
   	var _print:PrintJob = new PrintJob();
   
   	// Starts the OS's printing process by opening the printer
   	// dialogue, adding the read-only properties,
   	// and prepares the page to be sent to the spooler
   	_print.start();
   
   	// addPage add what is actually going to be printed
   	// (the Sprite object and any subsequent children)
   	_print.addPage(_content);
   
   	// send finishes the print job and send the page
   	// to the print spooler.
   	_print.send();
   }

8. To quote Martha, “SAVE! Test the movie. (Control -> Test movie or Command/Control + return).” Try to print.

You can see an example of Part 1 here

Part 2: Vector or Bitmap (PrintJobOptions)

So now I have my PrintJob class constructed. Its working fine, I can print to whichever printer I choose — I am happy. By default, Flash is setup to tell the printer that everything in a printable area should be rendered as vector art. What if you want to add an JPEG image or Gif or PNG or whatever flavor of bitmapped imagery you may have. Well, you need to tell Flash to tell the printer to render the printer as a bitmap, and you do that with the PrintJobOptions. PrintJobOptions has one main property — printAsBitmap. This property is a boolean type meaning it is either true, or it is false. By default, as I said earlier, the printAsBitmap property is set to false rendering all imagery as vector art. If we wanted to render the artwork as bitmap, we just set the value to true. Here’s how.

1. First, save prj_print1.fla as prj_print2.fla, and PrintExample1 as PrintExample2. Make the necessary changes in regards to Document class and packages.
2. Next, I added an imag of an album, set the linkage so that the album was now a custom Album class, added the class as variable to PrintExample2.as as public var album:Album; and added some properties to make the everything pretty.

   var scale:Number = 234;
   album = new Album();
   album.x = 421;
   album.y = 127;
   album.width = scale;
   album.height = scale;
   album.rotation += 7;_content.addChild(album);

3. I then add following lines to my print function.

   var printOption:PrintJobOptions = new PrintJobOptions();
   printOption.printAsBitmap = true;
   // renders the print job as a bitmap rather than a vector.

4. The last thing I need to do is to tell the print job how to handle it. The addPage() method actually passes several function. The first is what is to be printed, the second is the area to print, or printArea which will be covered shortly, the third is PrintJobOptions, and the fourth is the frame number to print. It is important to note that the arguments need to be passed in this order:

   addPage(sprite:Sprite, printArea:Rectangle = null, options:PrintJobOptions = null, frameNum:int = 0)

5. You can decide which ones to pass, but you must follow this order. You can ommit the ones on the end if there is no change to their default value, but you cannot remove the ones in the middle (at least this is how I understand it). For example:

   _print.addPage(_content, null, printOption);
   // null is the value for the printArea property
   // and will be covered in the next lesson. Notice that I
   // ommited the frameNum property. If I were,
   // to include it, I would simply write
   // (_content, null, null, myFrameNum);

6. The final print job function should look like this:

   private function printJob(event:MouseEvent) {
   	var _print:PrintJob = new PrintJob();
   	_print.start();
   	var printOption:PrintJobOptions = new PrintJobOptions();
   	printOption.printAsBitmap = true;
   	_print.addPage(_content, null, printOption);
   	_print.send();
   	_print = null;
   }

7. To quote Martha, “SAVE! Test the movie. (Control -> Test movie or Command/Control + return).” Try to print.

You can see an example of Part 2 here

Part 3: The printArea

The last thing that I want to demostrate is the the printArea. The printArea does exactly what it sounds like it does, defines the print area. More importantly it helps to set the size of your print job. If you have a flash movie that you know is bigger than a typical page, and only want to print part of it, then you can define the printArea. This tells the Flash compiler, the OS, and the printer only to print that one part that you have defined. This two is pretty easy and can be done with a few modification.

1. First, resave prj_print2.fla and PrintExample2.as as prj_print3.fla and PrintExample3. make any necessary class changes.
2. Next, lets go ahead and deine our specific classes:

   import flash.printing.PrintJob;
   	import flash.printing.PrintJobOptions;
   	import flash.printing.PrintJobOrientation;
   	import flash.display.Sprite;
   	import flash.events.MouseEvent;
   
    	// And to help finish out are printArea we add the
   	// Rectangle class.
   	import flash.geom.Rectangle;

3. Next, we add a new variable to our variable list called content area:

   private var contentArea:Rectangle = new Rectangle(0,0,550,550);
   // We have positioned this new Rectangle to fall at
   // 0x and 0y and have a dimension of 550px by 550px.
   // This will be our printArea.

4. Finally, we need to tell the addPage() params that there is now a print area:

   _print.addPage(_content, contentArea, printOption);

5. To quote Martha, “SAVE! Test the movie. (Control -> Test movie or Command/Control + return).” Try to print.

You can see an example of Part 3 here

Complete versions of the source code used for this tutorial: Print Tutorial Files (.zip)

Resources
Adobe Live Docs: Basics of Printing
ActionScript 3.0 Language and Components Reference

• PrintJob
• PrintJobOptions
• PrintJobOrientation

NoPonies by PonyForXmas: ActionScript 3 Print all Items on Stage