< Day Day Up >
Using the PrintJob Class
The PrintJob class is a built-in Flash class that gives the programmer control over what
can be printed in an SWF as well as how it's printed. To use the PrintJob class, a new
instance of the class must be created.
var myPrintJob:PrintJob = new PrintJob();
With this script, a new instance of the PrintJob class is created and referred to as
myPrintJob.
To tell the PrintJob object what content to print, you must use the addPage() method of
the PrintJob class. We'll get to this soon. Before you can use the addPage() method to add
all printable content to the print job, however, you must first call the start() method of the
PrintJob class:
var myPrintJob:PrintJob = new PrintJob();
var result:Boolean = myPrintJob.start();
The first line of this script creates the instance of the PrintJob class. The second line
invokes the start() method. The moment that the start() method is called, a pop-up
window (specific to the operating system) asks whether the user wants to proceed with
printing. If the user selects Print, the Boolean value true is returned and stored as the
value of the variable result. If the user doesn't have a printer installed or cancels the print
pop-up window, the Boolean value false is returned. This feature allows you to program
an application to react one way if the user successfully initializes the print option, and
another if the user cancels the print request or doesn't have a printer. For example:
var myPrintJob:PrintJob = new PrintJob();
var result:Boolean = myPrintJob.start();
if (result) {
//Successfully initialized print action
//Add pages to print here
} else {
//User does not have printer or user canceled print action
}
N
OTE
After the start() method is called but before the user responds to the pop-up window,
Flash is paused and no frames are executed. All animations and code halt until the user
responds.
If the value of result is true, the user has a printer and has chosen the Print option. It's
then time to use the addPage() method of the PrintJob class to add the printable content.
The syntax for invoking the addPage() method looks like this:
myPrintJob.addPage(target, printArea, options, frameNumber);
The addPage() method has four parameters:
• target. This option defines the timeline where the page lives that you want to print.
If this parameter is entered as a number, it's interpreted as pointing to a level of the
movie. If the value entered is a string, it points to a movie clip.
• printArea. This parameter expects an object with four properties: xMin, xMax,
yMin, and yMax. These properties together form a rectangle determining the
printable area of the target. All of these measurements are relative to the
registration point of the target. For example, if xMin has a value of -300, the left
border of the printable area is 300 pixels to the left of the registration point of the
target. By default, leaving the printArea parameter blank prints the entire
dimensions of the movie clip (or what can fit on the printed page).
• options. This setting specifies whether the page should be printed as a bitmap
image or as vector graphics. The parameter value needs to be an object with a
single property, printAsBitmap. This property has a Boolean value. If true, the
page is printed as a bitmap. If false, it's printed as vector graphics. By default,
leaving the options parameter blank prints the page as vector graphics. By printing
as a bitmap you can print movies that maintain their transparencies and color
effects, as shown onscreen.
• frameNumber. This parameter is a number specifying the frame within the target
to be printed. It works only with frame numbers, not frame labels. By default, if
this parameter is blank, the currently displayed frame of the target is printed.
All the parameters of the addPage() method are optional except target.
Let's look at some examples of this method in use. The following script creates a new
PrintJob class instance, starts the print request, and adds a page to be printed. The
currently displayed frame of the myClip_mc movie clip instance will be printed as vector
graphics.
var myPrintJob:PrintJob = new PrintJob();
var result:Boolean = myPrintJob.start();
if (result) {
myPrint.addPage("myClip_mc");
} else {
//User does not have printer or user canceled print action
}
To use the default value of a parameter, enter null. The following line adds Frame 5 of
the myClip_mc movie clip instance to the PrintJob class instance, and specifies that it
should be printed as a bitmap:
myPrint.addPage("myClip_mc", null, {printAsBitmap:true}, 5);
To specify the dimensions of a movie clip to be printed, you must define the printArea
(second parameter) using an object, as shown here:
myPrintJob.addPage(0, {xMin:30, xMax:250, yMin:27, yMax:300});
The target is level 0. This addPage() method instructs Flash to print all content in level 0
on the current frame that's shown between the x positions of 30 and 250, and the y
positions of 27 and 300. Only content found within these dimensions will be printed.
You can add pages from various timelines to a single PrintJob instance, allowing the user
to print content from those various timelines from a single Print dialog box:
myPrintJob.addPage("invitation_mc", null, {printAsBitmap:true}, 2);
myPrintJob.addPage("map_mc", null, {printAsBitmap:false}, 1);
myPrintJob.addPage(1, null, {printAsBitmap:true}, null);
myPrintJob.addPage("guestList_mc", null, {printAsBitmap:true}, 4);
To add all frames of a timeline to a print job, use a looping statement:
for(i = 1; i <= myMovieClip_mc._totalframes; ++1){
myPrintJob.addPage("myMovieClip_mc", null, null, i);
}
With each loop, a page is added to the print job. The current value of i specifies by which
frame in the myMovieClip_mc instance to print for that page. This loop continues until i
is greater than the number of frames in the instance.
TIP
Remember that a timeline needn't be visible to add frames from that timeline to a print
j
ob. This feature allows you to create hidden content in your movie that might only be
appropriate for printing purposes, such as coupons, instructions, or maps that don't fit into
your project's overall design.