PrintJob


Object   |   +-PrintJob public class PrintJob extends Object

The PrintJob class lets you create content and print it to one or more pages. This class, in addition to offering improvements to print functionality provided by the print() method, lets you render dynamic content offscreen, prompt users with a single Print dialog box, and print an unscaled document with proportions that map to the proportions of the content. This capability is especially useful for rendering and printing dynamic content, such as database content and dynamic text.

Additionally, with properties populated by PrintJob.start(), your document can read your user's printer settings, such as page height, width, and orientation, and you can configure your document to dynamically format Flash content that is appropriate for the printer settings. These user layout properties are read-only and cannot be changed by Flash Player.

Availability: ActionScript 1.0; Flash Player 7

Property summary

Modifiers

Property

Description

 

orientation:String [read-only]

The image orientation for printing.

 

pageHeight:Number [read-only]

The height of the actual printable area on the page, in points.

 

pageWidth:Number [read-only]

The width of the actual printable area on the page, in points.

 

paperHeight:Number [read-only]

The overall paper height, in points.

 

paperWidth:Number [read-only]

The overall paper width, in points.


Properties inherited from class Object

constructor (Object.constructor property), __proto__ (Object.__proto__ property), prototype (Object.prototype property), __resolve (Object.__resolve property)


Constructor summary

Signature

Description

PrintJob()

Creates a PrintJob object that you can use to print one or more pages.


Method summary

Modifiers

Signature

Description

 

addPage(target:Object, [printArea:Object], [options:Object], [frameNum:Number]) : Boolean

Sends the specified level or movie clip as a single page to the print spooler.

 

send() : Void

Used following the PrintJob.start() and PrintJob.addPage() methods to send spooled pages to the printer.

 

start() : Boolean

Displays the operating system's print dialog boxes and starts spooling.


Methods inherited from class Object

addProperty (Object.addProperty method), hasOwnProperty (Object.hasOwnProperty method), isPropertyEnumerable (Object.isPropertyEnumerable method), isPrototypeOf (Object.isPrototypeOf method), registerClass (Object.registerClass method), toString (Object.toString method), unwatch (Object.unwatch method), valueOf (Object.valueOf method), watch (Object.watch method)


addPage (PrintJob.addPage method)

public addPage(target:Object, [printArea:Object], [options:Object],   [frameNum:Number]) : Boolean

Sends the specified level or movie clip as a single page to the print spooler. Before using this method, you must use PrintJob.start(); after calling PrintJob.addPage() one or more times for a print job, you must use PrintJob.send() to send the spooled pages to the printer.

If this method returns false (for example, if you haven't called PrintJob.start() or the user canceled the print job), any subsequent calls to PrintJob.addPage() will fail. However, if previous calls to PrintJob.addPage() were successful, the concluding PrintJob.send() command sends the successfully spooled pages to the printer.

If you passed a value for printArea, the xMin and yMin coordinates map to the upper left corner (0,0 coordinates) of the printable area on the page. The user's printable area is described by the read-only pageHeight and pageWidth properties set by PrintJob.start(). Because the printout aligns with the upper left corner of the printable area on the page, the printout is clipped to the right and/or bottom if the area defined in printArea is bigger than the printable area on the page. If you haven't passed a value for printArea and the Stage is larger than the printable area, the same type of clipping takes place.

If you want to scale a movie clip before you print it, set its MovieClip._xscale and MovieClip._yscale properties before calling this method, and 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 the movie clip is printed at the scaled size.

The Flash Player printing feature supports PostScript and non-PostScript printers. Non-PostScript printers convert vectors to bitmaps.

Availability: ActionScript 1.0; Flash Player 7

Parameters

target:Object - A number or string; the level or instance name of the movie clip to print. Pass a number to specify a level (for example, 0 is the _root movie), or a string (in quotation marks [""]) to specify the instance name of a movie clip.

printArea:Object [optional] - An object that specifies the area to print, in the following format:

{xMin:topLeft, xMax:topRight, yMin:bottomLeft, yMax:bottomRight}

The coordinates you specify for printArea represent screen pixels relative to the registration point of the _root movie clip (if target = 0) or of the level or movie clip specified by target. You must provide all four coordinates. The width (xMax-xMin) and height (yMax-yMin) must each be greater than 0.

Points are print units of measurement, and pixels are screen units of measurement; points are a fixed physical size (1/72 inch), but the size of a pixel depends on the resolution of the particular screen. You can use the following equivalencies to convert inches or centimeters to twips or points (a twip is 1/20 of a point):

  • 1 point = 1/72 inch = 20 twips

  • 1 inch = 72 points = 1440 twips

  • 1 cm = 567 twips

You can't reliably convert between pixels and points; the conversion rate depends on the screen and its resolution. If the screen is set to display 72 pixels per inch, for example, one point is equal to one pixel.

Note

If you have previously used print(), printAsBitmap(), printAsBitmapNum(), or printNum() to print from Flash, you might have used a #b frame label to specify the area to print. When using the addPage() method, you must use the printArea parameter to specify the print area; #b frame labels are ignored.


If you omit the printArea parameter, or if it is passed incorrectly, the full Stage area of target is printed. If you don't want to specify a value for printArea but want to specify a value for options or frameNumber, pass null for printArea.

options:Object [optional] - A parameter that specifies whether to print as vector or bitmap, in the following format:

{printAsBitmap:Boolean}

The default value is false, which represents a request for vector printing. To print target as a bitmap, pass true for printAsBitmap. Remember the following suggestions when determining which value to use:

  • If the content that you're printing includes a bitmap image, use {printAsBitmap:true} to include any transparency and color effects.

  • If the content does not include bitmap images, omit this parameter or use {printAsBitmap:false} to print the content in higher quality vector format.

If options is omitted or is passed incorrectly, vector printing is used. If you don't want to specify a value for options but want to specify a value for frameNumber, pass null for options.

frameNum:Number [optional] - A number that lets you specify which frame to print; passing a frameNumber does not cause the ActionScript on that frame to be invoked. If you omit this parameter, the current frame in target is printed.

Note

If you have previously used print(), printAsBitmap(), printAsBitmapNum(), or printNum() to print from Flash, you might have used a #p frame label on multiple frames to specify which pages to print. To use PrintJob.addPage() to print multiple frames, you must issue a PrintJob.addPage() command for each frame; #p frame labels are ignored. For one way to do this programmatically, see the Example section.


Returns

Boolean - A Boolean value: TRue if the page is successfully sent to the print spooler; false otherwise.

Example

The following example shows several ways to issue the addPage() command:

my_btn.onRelease = function() {   var pageCount:Number = 0;     var my_pj:PrintJob = new PrintJob();     if (my_pj.start())   {   // Print entire current frame of the _root movie in vector format   if (my_pj.addPage(0)){     pageCount++;         // Starting at 0,0, print an area 400 pixels wide and 500 pixels high     // of the current frame of the _root movie in vector format     if (my_pj.addPage(0, {xMin:0,xMax:400,yMin:0,yMax:500})){     pageCount++;         // Starting at 0,0, print an area 400 pixels wide and 500 pixels high     // of frame 1 of the _root movie in bitmap format     if (my_pj.addPage(0, {xMin:0,xMax:400,yMin:0,yMax:500},       {printAsBitmap:true}, 1)){       pageCount++;             // Starting 50 pixels to the right of 0,0 and 70 pixels down,       // print an area 500 pixels wide and 600 pixels high       // of frame 4 of level 5 in vector format       if (my_pj.addPage(5, {xMin:50,xMax:550,yMin:70,yMax:670},null, 4)){       pageCount++;             // Starting at 0,0, print an area 400 pixels wide       // and 400 pixels high of frame 3 of the "dance_mc" movie clip       // in bitmap format       if (my_pj.addPage("dance_mc",         {xMin:0,xMax:400,yMin:0,yMax:400},{printAsBitmap:true}, 3)){         pageCount++;                 // Starting at 0,0, print an area 400 pixels wide         // and 600 pixels high of frame 3 of the "dance_mc" movie clip         // in vector format at 50% of its actual size         var x:Number = dance_mc._xscale;         var y:Number = dance_mc._yscale;         dance_mc._xscale = 50;         dance_mc._yscale = 50;                if (my_pj.addPage("dance_mc",           {xMin:0,xMax:400,yMin:0,yMax:600},null, 3)){         pageCount++;         }         dance_mc._xscale = x;         dance_mc._yscale = y;       }       }     }     }   }   }     // If addPage() was successful at least once, print the spooled pages.   if (pageCount > 0){   my_pj.send();   }   delete my_pj; }

See also

send (PrintJob.send method), start (PrintJob.start method)

orientation (PrintJob.orientation property)

public orientation : String [read-only]

The image orientation for printing. This property can be either "landscape" or "portrait". Note that this property is only available after a call to the PrintJob.start() method.

Availability: ActionScript 1.0; Flash Player 7

pageHeight (PrintJob.pageHeight property)

public pageHeight : Number [read-only]

The height of the actual printable area on the page, in points. Any user-set margins are ignored. Note that this property is only available after a call to the PrintJob.start() method.

Availability: ActionScript 1.0; Flash Player 7

pageWidth (PrintJob.pageWidth property)

public pageWidth : Number [read-only]

The width of the actual printable area on the page, in points. Any user-set margins are ignored. Note that this property is only available after a call to the PrintJob.start() method.

Availability: ActionScript 1.0; Flash Player 7

paperHeight (PrintJob.paperHeight property)

public paperHeight : Number [read-only]

The overall paper height, in points. Note that this property is only available after a call to the PrintJob.start() method.

Availability: ActionScript 1.0; Flash Player 7

paperWidth (PrintJob.paperWidth property)

public paperWidth : Number [read-only]

The overall paper width, in points. Note that this property is only available after a call to the PrintJob.start() method.

Availability: ActionScript 1.0; Flash Player 7

PrintJob constructor

public PrintJob()

Creates a PrintJob object that you can use to print one or more pages.

To implement a print job, use the following methods in sequence. You must place all commands relating to a specific print job in the same frame, from the constructor through PrintJob.send() and delete. Replace the [params] to the my_pj.addPage() method calls with your custom parameters.

// create PrintJob object var my_pj:PrintJob = new PrintJob(); // display print dialog box, but only initiate the print job // if start returns successfully. if (my_pj.start()) {     // use a variable to track successful calls to addPage   var pagesToPrint:Number = 0;     // add specified area to print job   // repeat once for each page to be printed   if (my_pj.addPage([params])) {   pagesToPrint++;   }   if (my_pj.addPage([params])) {   pagesToPrint++;   }   if (my_pj.addPage([params])) {   pagesToPrint++;   }   // send pages from the spooler to the printer, but only if one or more   // calls to addPage() was successful. You should always check for   successful   // calls to start() and addPage() before calling send().   if (pagesToPrint > 0) {   my_pj.send(); // print page(s)   } } // clean up delete my_pj; // delete object

You cannot create a second PrintJob object while the first one is still active. You cannot create a second PrintJob object (by calling new PrintJob()) while the first PrintJob object is still active, the second PrintJob object will not be created.

Availability: ActionScript 1.0; Flash Player 7

Example

See PrintJob.addPage().

See also

addPage (PrintJob.addPage method), send (PrintJob.send method), start (PrintJob.start method)

send (PrintJob.send method)

public send() : Void

Used following the PrintJob.start() and PrintJob.addPage() methods to send spooled pages to the printer. Because calls to PrintJob.send() will not be successful if related calls to PrintJob.start() and PrintJob.addpage() failed, you should check that calls to PrintJob.addpage() and PrintJob.start() were successful before calling PrintJob.send():

var my_pj:PrintJob = new PrintJob(); if (my_pj.start()) {   if (my_pj.addPage(this)) {   my_pj.send();   } } delete my_pj;

Availability: ActionScript 1.0; Flash Player 7

Example

See PrintJob.addPage() and PrintJob.start().

See also

addPage (PrintJob.addPage method), start (PrintJob.start method)

start (PrintJob.start method)

public start() : Boolean

Displays the operating system's print dialog boxes and starts spooling. The print dialog boxes let the user change print settings. When the PrintJob.start() method returns successfully, the following read-only properties are populated, representing the user's print settings:

Property

Type

Units

Notes

PrintJob.paperHeight

Number

Points

Overall paper height.

PrintJob.paperWidth

Number

Points

Overall paper width.

PrintJob.pageHeight

Number

Points

Height of actual printable area on the page; any user-set margins are ignored.

PrintJob.pageWidth

Number

Points

Width of actual printable area on the page; any user-set margins are ignored.

PrintJob.orientation

Number

Points

"Portrait" or "landscape."


After the user clicks OK in the Print dialog box, the player begins spooling a print job to the operating system. You should issue any ActionScript commands that affect the printout, and you can use PrintJob.addPage() commands to send pages to the spooler. You can use the read-only height, width, and orientation properties this method populates to format the printout.

Because the user sees information such as "Printing page 1" immediately after clicking OK, you should call the PrintJob.addPage() and PrintJob.send() commands as soon as possible.

If this method returns false (for example, if the user clicks Cancel instead of OK in the operating system's Print dialog box), any subsequent calls to PrintJob.addPage() and PrintJob.send() will fail. However, if you test for this return value and don't send PrintJob.addPage() commands as a result, you should still delete the PrintJob object to make sure the print spooler is cleared, as shown in the following example:

var my_pj:PrintJob = new PrintJob(); var myResult:Boolean = my_pj.start();    if(myResult) {    // addPage() and send() statements here    } delete my_pj;

Availability: ActionScript 1.0; Flash Player 7

Returns

Boolean - A Boolean value: TRue if the user clicks OK when the print dialog boxes appear; false if the user clicks Cancel or if an error occurs.

Example

The following example shows how you might use the value of the orientation property to adjust the printout:

// create PrintJob object var my_pj:PrintJob = new PrintJob(); // display print dialog box if (my_pj.start()) {   // boolean to track whether addPage succeeded, change this to a counter   // if more than one call to addPage is possible   var pageAdded:Boolean = false;     // check the user's printer orientation setting   // and add appropriate print area to print job   if (my_pj.orientation == "portrait") {   // Here, the printArea measurements are appropriate for an 8.5" x 11"   // portrait page.   pageAdded = my_pj.addPage(this,{xMin:0,xMax:600,yMin:0,yMax:800});   }   else {   // my_pj.orientation is "landscape".   // Now, the printArea measurements are appropriate for an 11" x 8.5"   // landscape page.   pageAdded = my_pj.addPage(this,{xMin:0,xMax:750,yMin:0,yMax:600});   }     // send pages from the spooler to the printer   if (pageAdded) {   my_pj.send();   } } // clean up delete my_pj;

See also

addPage (PrintJob.addPage method), send (PrintJob.send method)



ActionScript 2.0 Language Reference for Macromedia Flash 8
ActionScript 2.0 Language Reference for Macromedia Flash 8
ISBN: 0321384040
EAN: 2147483647
Year: 2004
Pages: 113

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