Recipe 21.9. Printing Flash Content


Problem

You want to print content from Flash.

Solution

Use the PrintJob ActionScript class.

Discussion

When you want to print Flash content, you always have the option of allowing the user to select the Print option from the Flash Player context menu. However, that is neither an obvious UI action for the user, nor does it offer much control over what will print. Instead, the better way to manage printing of Flash content is to use the PrintJob class.

The PrintJob class enables you to print one or more pages of content while prompting the user with just one dialog box. The PrintJob class enables you to print content from any frame of any movie clip, and you can even specify printable regions and how to optimize the printing depending on whether the content uses bitmaps or vectors.

The first step when working with the PrintJob class is to construct a new instance, and assign that to a variable. You can construct a new instance by using the constructor method, as in the following example:

 var pjContent:PrintJob = new PrintJob(); 

Next, call the start( ) method in order to prompt the user with the Print dialog box. Flash doesn't allow you to print unless the user clicks OK from the dialog box. The start( ) method is synchronous. That means that the ActionScript interpreter halts when the start( ) method is called until the user clicks OK or Cancel from the Print dialog box. When the user clicks one of the buttons, a Boolean value is returned to Flash. If the user clicks OK, the value is true. If the user clicks Cancel, the value is false.

 var bOkayToPrint:Boolean = pjContent.start(); 

As previously mentioned, you can print only if the user clicks OK and the return value is TRue. If the user clicks Cancel, adding pages and sending them to the printer will not work. Therefore, you can use an if statement to test if the Boolean value returned from start( ) is true. Only if it is true do you want to add pages and send them to the printer.

 if(bOkayToPrint) {   // Code to add pages and send them to the printer. } 

You can use the addPage( ) method to add pages. At a minimum, the addPage( ) method requires one parameter specifying the movie clip to print. For example, if you have a movie clip called mText, the following adds that movie clip content as a page:

 pjContent.addPage(mText); 

Although adding a movie clip in that fashion may work in many cases, there are many cases in which additional parameters are necessary or in which you might need to scale and/or rotate the movie clip. For example, mText may need to span several pages. Or perhaps the movie clip is aligned to print in portrait mode (taller than it is wide), but the user has selected to print in landscape mode. You can manage all these settings by specifying additional parameters when calling addPage( ). You'll also need to retrieve values from the PrintJob object that specify the user's print settings.

When you call start( ) and the user is presented with the Print dialog box, he or she has the option of selecting the paper size as well as the print orientation. When the user clicks OK, those settings are sent back to Flash and stored in properties of the PrintJob object from which you called start( ). Specifically, you can retrieve the page dimensions from the pageWidth and pageHeight properties, and you can retrieve the orientation from the orientation property. The pageWidth and pageHeight properties return the dimensions of the printable page region in points (which are the equivalent of pixels, in this case). The orientation property will have a value of either portrait or landscape. You can then use those properties to determine how to add pages.

By default, Flash attempts to print the entire movie clip specified by the parameter to the addPage( ) method. Any content that extends beyond the printable region is cropped. Flash doesn't automatically scale the content, nor does it automatically span more than one page. If you want to scale the content to the printable region, you can set the _xscale/_yscale or _width/_height properties of the movie clip just before calling addPage( ). For example, the following scales mArtwork to the dimensions of the printable region, then adds the page:

 mArtwork._width = pjContent.pageWidth; mArtwork._height = pjContent.pageHeight; pjContent.addPage(mArtwork); 

Note that you'll want to reset the dimensions of the movie clip after sending the pages to the printer. Because the code executes before the frame refreshes, the user will not see the movie clip scale.

In the preceding example, mArtwork doesn't necessarily maintain the aspect ratio. If you need to scale the content while maintaining the aspect ratio, you need slightly more sophisticated ActionScript. First, you can determine the ratios of the widths and heights. You want to then scale the object by the lesser of those ratios.

 var nWidthRatio:Number = pjContent.pageWidth / mArtwork._width; var nHeightRatio:Number = pjContent.pageHeight / mArtwork._height; var nScale:Number = 100 * Math.min(nWidthRatio, nHeightRatio); mArtwork._xscale = nScale; mArtwork._yscale = nScale; pjContent.addPage(mArtwork); 

You may also need to rotate content depending on the page orientation the user has selected. If content is taller than it is wide and the user has selected landscape, you'll need to rotate the content by 90°.

 if(pjContent.orientation == "landscape") {   mArtwork._rotation = 90; } pjContent.addPage(mArtwork); 

In addition to the one required parameter for addPage( ), there are several optional parameters. You can specify a printable region, how to optimize the printing based on whether the content contains bitmaps, and what frame to print. The second parameter lets you specify the printable region by way of an object with xMin, xMax, yMin, and yMax properties. By default, Flash attempts to print the region starting at 0,0 and spanning the entire content in the lower-right quadrant of the movie clip. If you want to print content that appears above or to the left of 0,0, if you don't want to print some part of the default content, or if you want to start the page at a point that is not 0,0, you can specify the second parameter when calling addPage( ). The following code adds the region from 100,100 as the upper-left corner and 400,400 as the lower-right corner:

 pjContent.addPage(mArtwork, {xMin: 100, xMax: 400, yMin: 100, yMax: 400}); 

You can use the print area parameter to span a movie clip's content on several pages. For example, the following code causes mArtwork to span four pages:

 pjContent.addPage(mArtwork, {xMin: 0, xMax: 400, yMin: 0, yMax: 400}); pjContent.addPage(mArtwork, {xMin: 0, xMax: 400, yMin: 400, yMax: 800}); pjContent.addPage(mArtwork, {xMin: 400, xMax: 800, yMin: 0, yMax: 400}); pjContent.addPage(mArtwork, {xMin: 400, xMax: 800, yMin: 400, yMax: 800}); 

By default, Flash assumes that you are printing vector content, and optimizes the printing with that setting. However, if the content contains bitmaps, you'll want to tell Flash to optimize for bitmap printing. You can accomplish that by passing a third parameter to the addPage( ) method with a value of {printAsBitmap: true}. If you want to pass a third parameter, but you want to use the default print area, you can specify null as the second parameter.

 pjContent.addPage(mArtwork, null, {printAsBitmap: true}); 

The fourth parameter lets you specify a frame to print. By default, Flash assumes you want to print frame 1. You can optionally specify the frame number as follows:

 pjContent.addPage(mArtwork, null, null, 5); 

After you've added a page or pages, you can call send( ) to send to the printer.

 pjContent.send(); 

Then, regardless of whether the user clicked OK or Cancel, delete the PrintJob object. You should place the following code outside the if statement:

 delete pjContent; 




Flash 8 Cookbook
Flash 8 Cookbook (Cookbooks (OReilly))
ISBN: 0596102402
EAN: 2147483647
Year: 2007
Pages: 336
Authors: Joey Lott

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net