Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.printing 
PrintJob 
Packageflash.printing
Classpublic class PrintJob
InheritancePrintJob Inheritance EventDispatcher Inheritance Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The PrintJob class lets you create content and print it to one or more pages. This class lets you render content that is visible, dynamic or offscreen to the user, 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.

Use the PrintJob() constructor to create a print job.

Additionally, with the PrintJob class's properties, you can read your user's printer settings, such as page height, width, and image orientation, and you can configure your document to dynamically format Flash content that is appropriate for the printer settings.

Note: ActionScript 3.0 does not restrict a PrintJob object to a single frame (as did previous versions of ActionScript). However, since the operating system displays print status information to the user after the user has clicked the OK button in the Print dialog box, you should call PrintJob.addPage() and PrintJob.send() as soon as possible to send pages to the spooler. A delay reaching the frame containing the PrintJob.send() call delays the printing process.

Additionally, a 15 second script timeout limit applies to the following intervals:

  • PrintJob.start() and the first PrintJob.addPage()
  • PrintJob.addPage() and the next PrintJob.addPage()
  • The last PrintJob.addPage() and PrintJob.send()

If any of the above intervals span more than 15 seconds, the next call to PrintJob.start() on the PrintJob instance returns false, and the next PrintJob.addPage() on the PrintJob instance causes the Flash Player or Adobe AIR to throw a runtime exception.

View the examples



Public Properties
 PropertyDefined By
  AIR-only active : Boolean
[static] [read-only] Indicates whether a print job is currently active.
PrintJob
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  AIR-only copies : int
The number of copies that the print system prints of any pages subsequently added to the print job.
PrintJob
  AIR-only firstPage : int
[read-only] The page number of the first page of the range entered by the user in the operating system's Print dialog.
PrintJob
  AIR-only isColor : Boolean
[read-only] Indicates whether the currently selected printer at the current print settings prints using color (true) or grayscale (false).
PrintJob
  isSupported : Boolean
[static] [read-only] Indicates whether the PrintJob class is supported on the current platform (true) or not (false).
PrintJob
  AIR-only jobName : String
The name or title of the print job.
PrintJob
  AIR-only lastPage : int
[read-only] The page number of the last page of the range entered by the user in the operating system's Print dialog.
PrintJob
  AIR-only maxPixelsPerInch : Number
[read-only] The physical resolution of the selected printer, in pixels per inch.
PrintJob
  orientation : String
The image orientation for printing.
PrintJob
  pageHeight : int
[read-only] The height of the largest area which can be centered in the actual printable area on the page, in points.
PrintJob
  pageWidth : int
[read-only] The width of the largest area which can be centered in the actual printable area on the page, in points.
PrintJob
  AIR-only paperArea : Rectangle
[read-only] The bounds of the printer media in points.
PrintJob
  paperHeight : int
[read-only] The overall paper height, in points.
PrintJob
  paperWidth : int
[read-only] The overall paper width, in points.
PrintJob
  AIR-only printableArea : Rectangle
[read-only] The bounds of the printer media's printable area in points.
PrintJob
  AIR-only printer : String
Gets or sets the printer to use for the current print job.
PrintJob
  AIR-only printers : Vector.<String>
[static] [read-only] Provides a list of the available printers as String name values.
PrintJob
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  AIR-only supportsPageSetupDialog : Boolean
[static] [read-only] Indicates whether the Flash runtime environment supports a separate Page Setup dialog.
PrintJob
Public Methods
 MethodDefined By
  
Creates a PrintJob object that you can use to print one or more pages.
PrintJob
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
  
addPage(sprite:Sprite, printArea:Rectangle = null, options:PrintJobOptions = null, frameNum:int = 0):void
Sends the specified Sprite object as a single page to the print spooler.
PrintJob
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
Set the paper size.
PrintJob
  
Sends spooled pages to the printer after successful calls to the start() or start2() and addPage() methods.
PrintJob
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
Displays the operating system's Page Setup dialog if the current environment supports it.
PrintJob
  
Displays the operating system's Print dialog box and starts spooling.
PrintJob
  
AIR-only start2(uiOptions:PrintUIOptions = null, showPrintDialog:Boolean = true):Boolean
Optionally displays the operating system's Print dialog box, starts spooling, and possibly modifies the PrintJob read-only property values.
PrintJob
  
Signals that the print job should be terminated without sending.
PrintJob
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
Property Detail
AIR-only 

active

property
active:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Indicates whether a print job is currently active. A print job is active (the property value is true) in either of two conditions:

  • A Page Setup or Print dialog is being displayed.
  • The start() or start2() method has been called with a true return value, and the send() or terminate() method has not been called.

If this property is true and you call the showPageSetupDialog(), start(), or start2() method, the runtime throws an exception.



Implementation
    public static function get active():Boolean

See also

AIR-only 

copies

property 
copies:int

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

The number of copies that the print system prints of any pages subsequently added to the print job. This value is the number of copies entered by the user in the operating system's Print dialog. If the the number of copies was not displayed in the Print dialog, or the dialog was not presented to the user, the value is 1 (unless it has been changed by application code).



Implementation
    public function get copies():int
    public function set copies(value:int):void
AIR-only 

firstPage

property 
firstPage:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

The page number of the first page of the range entered by the user in the operating system's Print dialog. This property is zero if the user requests that all pages be printed, or if the page range was not displayed in the Print dialog, or if the Print dialog has not been presented to the user.



Implementation
    public function get firstPage():int
AIR-only 

isColor

property 
isColor:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Indicates whether the currently selected printer at the current print settings prints using color (true) or grayscale (false).

If a color-or-grayscale value can't be determined, the value is true.



Implementation
    public function get isColor():Boolean

isSupported

property 
isSupported:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10.1, AIR 2

Indicates whether the PrintJob class is supported on the current platform (true) or not (false).



Implementation
    public static function get isSupported():Boolean
AIR-only 

jobName

property 
jobName:String

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

The name or title of the print job. The job name is typically used by the operating system as the title of the job in the print queue, or as the default name of a job that is printed to a file.

If you have not called start() or start2() and you haven't set a value for the property, this property's value is null.

For each print job you execute with a PrintJob instance, set this property before calling the start() or start2() method.

The default value is null.



Implementation
    public function get jobName():String
    public function set jobName(value:String):void

Throws
IllegalOperationError — if code attempts to set the property while the active property is true.
AIR-only 

lastPage

property 
lastPage:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

The page number of the last page of the range entered by the user in the operating system's Print dialog. This property is zero if the user requests that all pages be printed, or if the page range was not displayed in the Print dialog, or if the Print dialog has not been presented to the user.



Implementation
    public function get lastPage():int
AIR-only 

maxPixelsPerInch

property 
maxPixelsPerInch:Number  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

The physical resolution of the selected printer, in pixels per inch. The value is calculated according to the current print settings as reported by the operating system.

If the resolution cannot be determined, the value is a standard default value. The default value is 600 ppi on Linux and 360 ppi on Mac OS. On Windows, the printer resolution is always available, so no default value is necessary.



Implementation
    public function get maxPixelsPerInch():Number

orientation

property 
orientation:String

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 9 - read only, AIR 1.0 - read only, AIR 2 - read-write

The image orientation for printing. The acceptable values are defined as constants in the PrintJobOrientation class.

Note: For AIR 2 or later, set this property before starting a print job to set the default orientation in the Page Setup and Print dialogs. Set the property while a print job is in progress (after calling start() or start2() to set the orientation for a range of pages within the job.



Implementation
    public function get orientation():String
    public function set orientation(value:String):void

See also

pageHeight

property 
pageHeight:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.

The height of the largest area which can be centered in the actual printable area on the page, in points. Any user-set margins are ignored. This property is available only after a call to the PrintJob.start() method has been made.

Note: For AIR 2 or later, this property is deprecated. Use printableArea instead, which measures the printable area in fractional points and describes off-center printable areas accurately.



Implementation
    public function get pageHeight():int

See also

pageWidth

property 
pageWidth:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 9, AIR 1.0

The width of the largest area which can be centered in the actual printable area on the page, in points. Any user-set margins are ignored. This property is available only after a call to the PrintJob.start() method has been made.

Note: For AIR 2 or later, this property is deprecated. Use printableArea instead, which measures the printable area in fractional points and describes off-center printable areas accurately.



Implementation
    public function get pageWidth():int

See also

AIR-only 

paperArea

property 
paperArea:Rectangle  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

The bounds of the printer media in points. This value uses the same coordinate system that is used for subsequent addPage() calls.



Implementation
    public function get paperArea():Rectangle

paperHeight

property 
paperHeight:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.

The overall paper height, in points. This property is available only after a call to the PrintJob.start() method has been made.

Note: For AIR 2 or later, this property is deprecated. Use paperArea instead, which measures the paper dimensions in fractional points.



Implementation
    public function get paperHeight():int

See also

paperWidth

property 
paperWidth:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.

The overall paper width, in points. This property is available only after a call to the PrintJob.start() method has been made.

Note: For AIR 2 or later, this property is deprecated. Use paperArea instead, which measures the paper dimensions in fractional points.



Implementation
    public function get paperWidth():int

See also

AIR-only 

printableArea

property 
printableArea:Rectangle  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

The bounds of the printer media's printable area in points. This value uses the same coordinate system that is used for subsequent addPage() calls.



Implementation
    public function get printableArea():Rectangle
AIR-only 

printer

property 
printer:String

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Gets or sets the printer to use for the current print job. The String passed to the setter and returned by the getter should match one of the strings in the Array returned by the printers() method. To indicate that the default printer should be used, set the value to null. On operating systems where the default printer cannot be determined, this property's value is null.

     import flash.printing.PrintJob;
     
     var myPrintJob:PrintJob = new PrintJob();
     myPrintJob.printer = "HP_LaserJet_1";
     myPrintJob.start();
     

Setting the value of this property attempts to select the printer immediately. If the printer selection fails, this property's value resets to the previous value. You can determine if setting the printer value succeeds by reading the value after attempting to set it, and confirming that it matches the value that was set.

The printer property of an active print job cannot be changed. Attempting to change it after calling the start() or start2() method successfully and before calling send() or terminate() fails.



Implementation
    public function get printer():String
    public function set printer(value:String):void
AIR-only 

printers

property 
printers:Vector.<String>  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Provides a list of the available printers as String name values. The list is not precalculated; it is generated when the function is called. If no printers are available or if the system does not support printing, the value is null. If the system supports printing but is not capable of returning a list of printers, the value is a Vector with a single element (its length property is 1). In that case, the single element is the actual printer name or a default name if the current printer name cannot be determined.



Implementation
    public static function get printers():Vector.<String>
AIR-only 

supportsPageSetupDialog

property 
supportsPageSetupDialog:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Indicates whether the Flash runtime environment supports a separate Page Setup dialog. If this property is true, you can call the showPageSetupDialog() method to display the operating system's page setup dialog box.



Implementation
    public static function get supportsPageSetupDialog():Boolean

See also

Constructor Detail

PrintJob

()Constructor
public function PrintJob()

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Creates a PrintJob object that you can use to print one or more pages. After you create a PrintJob object, you need to use (in the following sequence) the PrintJob.start(), PrintJob.addPage(), and then PrintJob.send() methods to send the print job to the printer.

For example, you can replace the [params] placeholder text for the myPrintJob.addPage() method calls with custom parameters as shown in the following code:

 // create PrintJob object
 var myPrintJob:PrintJob = new PrintJob();
  
 // display Print dialog box, but only initiate the print job
 // if start returns successfully.
 if (myPrintJob.start()) {
  
    // add specified page to print job
    // repeat once for each page to be printed
    try {
      myPrintJob.addPage([params]);
    }
    catch(e:Error) {
      // handle error 
    }
    try {
      myPrintJob.addPage([params]);
    }
    catch(e:Error) {
      // handle error 
    }
 
    // 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().
    myPrintJob.send();
 }
 

In AIR 2 or later, you can create and use multiple PrintJob instances. Properties set on the PrintJob instance are retained after printing completes. This allows you to re-use a PrintJob instance and maintain a user's selected printing preferences, while offering different printing preferences for other content in your application. For content in Flash Player and in AIR prior to version 2, you cannot create a second PrintJob object while the first one is still active. If you 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. So, you may check for the myPrintJob value before creating a second PrintJob.


Throws
IllegalOperationError — In Flash Player and AIR prior to AIR 2, throws an exception if another PrintJob object is still active.

See also

Method Detail

addPage

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

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.

Sends the specified Sprite object as a single page to the print spooler. Before using this method, you must create a PrintJob object and then use start() or start2(). Then, after calling addPage() one or more times for a print job, use send() to send the spooled pages to the printer. In other words, after you create a PrintJob object, use (in the following sequence) start() or start2(), addPage(), and then send() to send the print job to the printer. You can call addPage() multiple times after a single call to start() to print several pages in a print job.

If addPage() causes Flash Player to throw an exception (for example, if you haven't called start() or the user cancels the print job), any subsequent calls to addPage() fail. However, if previous calls to addPage() are successful, the concluding send() command sends the successfully spooled pages to the printer.

If the print job takes more than 15 seconds to complete an addPage() operation, Flash Player throws an exception on the next addPage() call.

If you pass a value for the printArea parameter, the x and y coordinates of the printArea Rectangle map to the upper-left corner (0, 0 coordinates) of the printable area on the page. The read-only properties pageHeight and pageWidth describe the printable area set by start(). Because the printout aligns with the upper-left corner of the printable area on the page, when the area defined in printArea is bigger than the printable area on the page, the printout is cropped to the right or bottom (or both) of the area defined by printArea. In Flash Professional, if you don't pass a value for printArea and the Stage is larger than the printable area, the same type of clipping occurs. In Flex or Flash Builder, if you don't pass a value for printArea and the screen is larger than the printable area, the same type of clipping takes place.

If you want to scale a Sprite object before you print it, set scale properties (see flash.display.DisplayObject.scaleX and flash.display.DisplayObject.scaleY) before calling this method, and set them back to their original values after printing. The scale of a Sprite object has no relation to printArea. That is, if you specify a print area that is 50 x 50 pixels, 2500 pixels are printed. If you scale the Sprite object, the same 2500 pixels are printed, but the Sprite object is printed at the scaled size.

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

Parameters

sprite:Sprite — The Sprite containing the content to print.
 
printArea:Rectangle (default = null) — A Rectangle object that specifies the area to print.

A rectangle's width and height are pixel values. A printer uses points as print units of measurement. Points are a fixed physical size (1/72 inch), but the size of a pixel, onscreen, depends on the resolution of the particular screen. So, the conversion rate between pixels and points depends on the printer settings and whether the sprite is scaled. An unscaled sprite that is 72 pixels wide prints out one inch wide, with one point equal to one pixel, independent of screen resolution.

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

If you omit the printArea parameter, or if it is passed incorrectly, the full area of the sprite parameter is printed.

If you don't want to specify a value for printArea but want to specify a value for options or frameNum, pass null for printArea.

 
options:PrintJobOptions (default = null) — An optional parameter that specifies whether to print as vector or bitmap. The default value is null, which represents a request for vector printing. To print sprite as a bitmap, set the printAsBitmap property of the PrintJobOptions object to true. Remember the following suggestions when determining whether to set printAsBitmap to true:
  • If the content you're printing includes a bitmap image, set printAsBitmap to true to include any alpha transparency and color effects.
  • If the content does not include bitmap images, omit this parameter 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:int (default = 0) — An optional number that lets you specify which frame of a MovieClip object to print. Passing a frameNum does not invoke ActionScript on that frame. If you omit this parameter and the sprite parameter is a MovieClip object, the current frame in sprite is printed.


Throws
Error — Throws an exception if you haven't called start() or the user cancels the print job

See also

AIR-only selectPaperSize

()method 
public function selectPaperSize(paperSize:String):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Set the paper size. The acceptable values for the paperSize parameter are constants in the PaperSize class. Calling this method affects print settings as if the user chooses a paper size in the Page Setup or Print dialogs.

You can call this method at any time. Call this method before starting a print job to set the default paper size in the Page Setup and Print dialogs. Call this method while a print job is in progress to set the paper size for a range of pages within the job.

     import flash.printing.PrintJob;
     import flash.printing.PaperSize;
     
     var myPrintJob:PrintJob = new PrintJob();
     myPrintJob.selectPaperSize(PaperSize.ENV_10);
     

Parameters

paperSize:String — The paper size to use for subsequent pages in the print job


Throws
ArgumentError — if the paperSize parameter is not one of the acceptable values defined in the PaperSize class.

See also

send

()method 
public function send():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.

Sends spooled pages to the printer after successful calls to the start() or start2() and addPage() methods.

This method does not succeed if the call to the start() or start2() method fails, or if a call to the addPage() method throws an exception. To avoid an error, check that the start() or start2() method returns true and catch any addPage() exceptions before calling this method. The following example demonstrates how to properly check for errors before calling this method:

     var myPrintJob:PrintJob = new PrintJob();
     if (myPrintJob.start()) {
       try {
         myPrintJob.addPage([params]);
       }
       catch(e:Error) {
          // handle error 
       }
     
       myPrintJob.send();
     }
     

See also

AIR-only showPageSetupDialog

()method 
public function showPageSetupDialog():Boolean

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Displays the operating system's Page Setup dialog if the current environment supports it. Use the supportsPageSetupDialog property to determine if Page Setup is supported.

     import flash.printing.PrintJob;
     
     var myPrintJob:PrintJob = new PrintJob();
     if (myPrintJob.supportsPageSetupDialog)
     {
         myPrintJob.showPageSetupDialog();
     }
     

Returns
Booleantrue if the user chooses "OK" in the Page Setup dialog. This indicates that some PrintJob properties may have changed. Returns false if the user chooses "Cancel" in the Page Setup dialog.

Throws
IllegalOperationError — if the system does not support Page Setup. Use the supportsPageSetupDialog property to determine if Page Setup is supported.
 
IllegalOperationError — if any print job (including the current one) is active.

See also

start

()method 
public function start():Boolean

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Player 9.

Displays the operating system's Print dialog box and starts spooling. The Print dialog box lets the user change print settings. When the PrintJob.start() method returns successfully (the user clicks OK in the Print dialog box), the following properties are populated, representing the user's chosen print settings:

PropertyTypeUnitsNotes
PrintJob.paperHeightNumberPointsOverall paper height.
PrintJob.paperWidthNumberPointsOverall paper width.
PrintJob.pageHeightNumberPointsHeight of actual printable area on the page; any user-set margins are ignored.
PrintJob.pageWidthNumberPointsWidth of actual printable area on the page; any user-set margins are ignored.
PrintJob.orientationString"portrait" (flash.printing.PrintJobOrientation.PORTRAIT) or "landscape" (flash.printing.PrintJobOrientation.LANDSCAPE).

Note: If the user cancels the Print dialog box, the properties are not populated.

After the user clicks OK in the Print dialog box, the player begins spooling a print job to the operating system. Because the operating system then begins displaying information to the user about the printing progress, you should call the PrintJob.addPage() and PrintJob.send() calls as soon as possible to send pages to the spooler. You can use the read-only height, width, and orientation properties this method populates to format the printout.

Test to see if this method returns true (when the user clicks OK in the operating system's Print dialog box) before any subsequent calls to PrintJob.addPage() and PrintJob.send():

     var myPrintJob:PrintJob = new PrintJob();
        if(myPrintJob.start()) {
          // addPage() and send() statements here
        }
     

For the given print job instance, if any of the following intervals last more than 15 seconds the next call to PrintJob.start() will return false:

  • PrintJob.start() and the first PrintJob.addPage()
  • One PrintJob.addPage() and the next PrintJob.addPage()
  • The last PrintJob.addPage() and PrintJob.send()

Returns
Boolean — A value of true if the user clicks OK when the Print dialog box appears; false if the user clicks Cancel or if an error occurs.

Throws
IllegalOperationError — in AIR 2 or later, if another PrintJob is currently active

See also

AIR-only start2

()method 
public function start2(uiOptions:PrintUIOptions = null, showPrintDialog:Boolean = true):Boolean

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Optionally displays the operating system's Print dialog box, starts spooling, and possibly modifies the PrintJob read-only property values.

The uiOptions parameter allows the caller to control which options are displayed in the Print dialog. See the PrintUIOptions class. This parameter is ignored if showPrintDialog is false.

Even when showPrintDialog is true, this method's behavior can differ from the start() method. On some operating systems, start() shows the Page Setup dialog followed by the Print dialog. In contrast, start2() never shows the Page Setup dialog.

In the following example, the min and max page settings in the Print dialog are set before the dialog is displayed to the user:

     import flash.printing.PrintJob;
     import flash.printing.PrintUIOptions;
     
     var myPrintJob:PrintJob = new PrintJob();
     var uiOpt:PrintUIOptions = new PrintUIOptions();
     uiOpt.minPage = 1;
     uiOpt.maxPage = 3;
     var accepted:Boolean = myPrintJob.start2(uiOpt);
     

Parameters

uiOptions:PrintUIOptions (default = null) — An object designating which options are displayed in the Print dialog that is shown to the user. If the showPrintDialog parameter is false, this value is ignored.
 
showPrintDialog:Boolean (default = true) — Whether or not the Print dialog is shown to the user before starting the print job

Returns
Boolean — A value of true if the user clicks OK when the Print dialog box appears, or if the Print dialog is not shown and there is no error; false if the user clicks Cancel or if an error occurs.

Throws
IllegalOperationError — If the Page Setup dialog is being displayed, or if another print job is currently active

See also

AIR-only terminate

()method 
public function terminate():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Signals that the print job should be terminated without sending. Use this method when a print job has already been initiated by a call to start() or start2(), but when it is not appropriate to send any pages to the printer. Typically, terminate() is only used to recover from errors.

After calling this method, the PrintJob instance can be reused. Wherever possible, the job's print settings are retained for subsequent use.

PrintJobExample_Simple.as

The following example show the basics of printing. A new PrintJob is created, and if started successfully, the addPage() method adds the sprite as a single page. The send() method spools the page to the printer.
package 
{ 
    import flash.printing.PrintJob; 
    import flash.display.Sprite; 
 
    public class BasicPrintExample extends Sprite 
    { 
        var myPrintJob:PrintJob = new PrintJob(); 
        var mySprite:Sprite = new Sprite();
        mySprite.graphics.beginFill(0x336699);
    mySprite.graphics.drawCircle(100, 100, 50);
 
        public function BasicPrintExample() 
        { 
            if (myPrintJob.start()) {
            try {
                myPrintJob.addPage(mySprite);
            }
            catch(e:Error) {
                // handle error 
            }
            myPrintJob.send();
        } 
    } 
}
PrintJobExample.as

The following example uses the class PrintJobExample to create a small document and then send the document to the printer. This is accomplished using the following steps:
  1. Declare two variables of type Sprite named sheet1 and sheet2.
  2. Call init(), which assigns a new Sprite instance to both sheet1 and sheet2 and then calls createSheet() using different arguments.
  3. createSheet() does the following:
    1. The Sprite object passed in is used to draw a rectangle with a light-gray background, a one-pixel black border, and that is 100 pixels wide by 200 pixels high at x = 0, y = 0.
    2. A new TextField object is created named txt with the same dimensions as the Sprite, the wordWrap property set to true, and the text property set to the String passed as an argument to createSheet().
    3. If the Object argument passed is not null, create a new Sprite instance named img that is used to draw a white rectangle using the coordinate and dimension properties of the Object passed. The white rectangle is added to the display list of the Sprite object using addChild().
    4. The txt TextField is added to the display list of the Sprite object using addChild().
  4. Back in the constructor, the print method that is enabled (not commented out) is called. Since the methods are very similar, printOnePerPage() is described below.
  5. printOnePerPage() does the following:
    1. Declare a new PrintJob object named pj and pagesToPrint as a uint.
    2. Open the operating system's native print dialog box and wait for user to click OK.
    3. Check the orientation and if Landscape is selected, throw an error and exit.
    4. Set up the page height and width for sheet1 and sheet2.
    5. Send sheet1 and sheet2 to the print spooler using addPage().
    6. If the number of pages to print is > 0, print all spooled pages.
  6. The draw() method is called, which re-sizes the two Sprite properties to fit on the stage and re-positions sheet2 such that it is just right of sheet1.

Note: the constructor is set up such that one of three printing methods (one sheet per page, two sheets per page, or printing on the top half of the page) can be selected, based on preference. This example will not work correctly unless exactly two of the print methods are disabled using code comments. The example is set up such that printOnePerPage() will be called.

package {
    import flash.printing.PrintJob;
    import flash.printing.PrintJobOrientation;
    import flash.display.Stage;
    import flash.display.Sprite;
    import flash.text.TextField;
    import flash.geom.Rectangle;
       
    public class PrintJobExample extends Sprite {
        private var sheet1:Sprite;
        private var sheet2:Sprite;
           
        public function PrintJobExample() {
            init();
            printOnePerPage();
//            printTwoPerPage();
//            printTopHalf();
            draw();
        }
        
        private function init():void {
            sheet1 = new Sprite();
            createSheet(sheet1, "Once upon a time...", {x:10, y:50, width:80, height:130});

            sheet2 = new Sprite();
            createSheet(sheet2, "There was a great story to tell, and it ended quickly.\n\nThe end.", null);
        }
        
        private function createSheet(sheet:Sprite, str:String, imgValue:Object):void {
            sheet.graphics.beginFill(0xEEEEEE);
            sheet.graphics.lineStyle(1, 0x000000);
            sheet.graphics.drawRect(0, 0, 100, 200);
            sheet.graphics.endFill();
            
            var txt:TextField = new TextField();
            txt.height = 200;
            txt.width = 100;
            txt.wordWrap = true;
            txt.text = str;
            
            if(imgValue != null) {
                var img:Sprite = new Sprite();
                img.graphics.beginFill(0xFFFFFF);
                img.graphics.drawRect(imgValue.x, imgValue.y, imgValue.width, imgValue.height);
                img.graphics.endFill();
                sheet.addChild(img);
            }
            sheet.addChild(txt);
        }
        
        private function printOnePerPage():void {
            var pj:PrintJob = new PrintJob();
            var pagesToPrint:uint = 0;
            if(pj.start()) {                
                if(pj.orientation == PrintJobOrientation.LANDSCAPE) {    
                    throw new Error("Without embedding fonts you must print one sheet per page with an orientation of portrait.");
                }
                
                sheet1.height = pj.pageHeight;
                sheet1.width = pj.pageWidth;
                sheet2.height = pj.pageHeight;
                sheet2.width = pj.pageWidth;

                try {
                    pj.addPage(sheet1);
                    pagesToPrint++;
                }
                catch(e:Error) {
                    // do nothing
                }

                try {
                    pj.addPage(sheet2);
                    pagesToPrint++;
                }
                catch(e:Error) {
                    // do nothing
                }

                if(pagesToPrint > 0) {
                    pj.send();
                }
            }
        }
        
        private function printTwoPerPage():void {
            var pj:PrintJob = new PrintJob();
            var pagesToPrint:uint = 0;
            if(pj.start()) {                
                if(pj.orientation == PrintJobOrientation.PORTRAIT) {
                    throw new Error("Without embedding fonts you must print two sheets per page with an orientation of landscape.");
                }
                
                sheet1.height = pj.pageHeight;
                sheet1.width = pj.pageWidth/2;
                sheet2.height = pj.pageHeight;
                sheet2.width = pj.pageWidth/2;

                var sheets:Sprite = new Sprite();
                sheets.addChild(sheet1);
                sheets.addChild(sheet2);
                sheets.getChildAt(1).x = sheets.getChildAt(0).width;
                try {
                    pj.addPage(sheets);
                    pagesToPrint++;
                }
                catch(e:Error) {
                    // do nothing
                }

                if(pagesToPrint > 0) {
                    pj.send();
                }
            }
        }

        private function printTopHalf():void {
            var pj:PrintJob = new PrintJob();
            var pagesToPrint:uint = 0;
            if(pj.start()) {                
                if(pj.orientation == PrintJobOrientation.PORTRAIT) {
                    throw new Error("Without embedding fonts you must print the top half with an orientation of landscape.");
                }
                
                sheet1.height = pj.pageHeight;
                sheet1.width = pj.pageWidth/2;
                sheet2.height = pj.pageHeight;
                sheet2.width = pj.pageWidth/2;

                var sheets:Sprite = new Sprite();
                sheets.addChild(sheet1);
                sheets.addChild(sheet2);
                sheets.getChildAt(1).x = sheets.getChildAt(0).width;
                try {
                    pj.addPage(sheets, new Rectangle(0, 0, sheets.width, sheets.height/2));
                    pagesToPrint++;
                }
                catch(e:Error) {
                    // do nothing
                }

                if(pagesToPrint > 0) {
                    pj.send();
                }
            }
        }


        private function draw():void {
            var sheetWidth:Number = this.stage.stageWidth/2;
            var sheetHeight:Number = this.stage.stageHeight;
            
            addChild(sheet1);
            sheet1.width = sheetWidth;
            sheet1.height = sheetHeight;
            
            addChild(sheet2);
            sheet2.width = sheetWidth;
            sheet2.height = sheetHeight;
            sheet2.x = sheet1.width;
        }        
    }
}
PrintJobExample.2.as

The following example demonstrates additional printing features. The example initializes the PrintJob settings for number of copies, paper size (legal), and page orientation (landscape). It forces the Page Setup dialog to be displayed first, then starts the print job by displaying the Print dialog.
 
package 
 { 
     import flash.display.Sprite; 
     import flash.display.Stage; 
     import flash.geom.Rectangle; 
     import flash.printing.PaperSize; 
     import flash.printing.PrintJob; 
    import flash.printing.PrintJobOrientation; 
    import flash.printing.PrintUIOptions; 
    import flash.text.TextField; 
      
     public class PrintJobExample extends Sprite 
     { 
         private var bg:Sprite; 
         private var txt:TextField; 
        private var pj:PrintJob; 
        private var uiOpt:PrintUIOptions; 
  
         public function PrintJobExample():void 
         { 
            var pj = new PrintJob(); 
            uiOpt = new PrintUIOptions(); 
            initPrintJob(); 
             initContent(); 
             draw(); 
             printPage(); 
         } 
          
         private function printPage():void 
         { 
            if (pj.supportsPageSetupDialog) 
            { 
                pj.showPageSetupDialog(); 
            }
            
             if (pj.start2(uiOpt, true)) 
             { 
                   try 
                 { 
                     pj.addPage(this, new Rectangle(0, 0, 100, 100)); 
                 } 
                 catch (error:Error) 
                 { 
                     // Do nothing. 
                 } 
                 pj.send(); 
             } 
             else 
             { 
                 txt.text = "Print job terminated"; 
                pj.terminate(); 
             } 
         } 
         
         private function initContent():void 
         { 
             bg = new Sprite(); 
             bg.graphics.beginFill(0x00FF00); 
             bg.graphics.drawRect(0, 0, 100, 200); 
             bg.graphics.endFill(); 
              
             txt = new TextField(); 
             txt.border = true; 
             txt.text = "Hello World"; 
         } 
          
        private function initPrintJob():void 
        { 
            pj.setPaperSize(PaperSize.LEGAL); 
            pj.orientation = PrintJobOrientation.LANDSCAPE; 
            pj.copies = 2; 
            pj.jobName = "Flash test print";
        } 
         
         private function draw():void 
         { 
             addChild(bg); 
             addChild(txt); 
             txt.x = 50; 
             txt.y = 50; 
         } 
     } 
}