flash.printing

# PrintJob - AS3

Package | flash.printing
Class | public class PrintJob
Inheritance | PrintJob EventDispatcher 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.

Mobile Browser Support: This class is not supported in mobile browsers.

AIR profile support: This feature is supported on all desktop operating systems, but it is not supported on mobile devices or AIR for TV devices. You can test for support at run time using the `PrintJob.isSupported` property. See AIR Profile Support for more information regarding API support across multiple profiles.

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

More examples

Basics of printing
Printing a page

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | active : Boolean [static] [read-only] Indicates whether a print job is currently active. | PrintJob
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | copies : int The number of copies that the print system prints of any pages subsequently added to the print job. | PrintJob
|  | 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
|  | 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
|  | jobName : String The name or title of the print job. | PrintJob
|  | 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
|  | 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
|  | 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
|  | printableArea : Rectangle [read-only] The bounds of the printer media's printable area in points. | PrintJob
|  | printer : String Gets or sets the printer to use for the current print job. | PrintJob
|  | printers : Vector.<String> [static] [read-only] Provides a list of the available printers as String name values. | PrintJob
|  | supportsPageSetupDialog : Boolean [static] [read-only] Indicates whether the Flash runtime environment supports a separate Page Setup dialog. | PrintJob

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | PrintJob() Creates a PrintJob object that you can use to print one or more pages. | PrintJob
|  | 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
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | selectPaperSize(paperSize:String):void Set the paper size. | PrintJob
|  | send():void Sends spooled pages to the printer after successful calls to the start() or start2() and addPage() methods. | PrintJob
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | showPageSetupDialog():Boolean Displays the operating system's Page Setup dialog if the current environment supports it. | PrintJob
|  | start():Boolean Displays the operating system's Print dialog box and starts spooling. | PrintJob
|  | 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
|  | terminate():void Signals that the print job should be terminated without sending. | PrintJob
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher

Property Detail

### 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`

Related API Elements

PrintJob.start()
PrintJob.start2()
PrintJob.send()
PrintJob.terminate()

### 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`

### 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`

### 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`

### 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`.

### 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`

### 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`

Related API Elements

PrintJobOrientation class

### 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`

More examples

Setting size, scale, and orientation
Responding to page height and width

Related API Elements

PrintJob.printableArea

### 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`

More examples

Setting size, scale, and orientation
Responding to page height and width

Related API Elements

PrintJob.printableArea

### 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`

Related API Elements

PrintJob.paperArea

### 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`

Related API Elements

PrintJob.paperArea

### 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`

### 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`.

Copy

         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`

### 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>`

### 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`

Related API Elements

PrintJob.showPageSetupDialog()
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.

Related API Elements

PrintJob.addPage()
PrintJob.send()
PrintJob.start()
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

More examples

Printing a page
Setting size, scale, and orientation

Related API Elements

PrintJob.send()
PrintJob.start()
DisplayObject class

### 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.

Copy

         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.

Related API Elements

PaperSize
PrintJob.send()

### 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:

Copy

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

           myPrintJob.send();
         }

More examples

Printing a page

Related API Elements

PrintJob.addPage()
PrintJob.start()
PrintJob.start2()

### 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.

Copy

         import flash.printing.PrintJob;

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

Returns

| `Boolean` — `true` 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.

Related API Elements

PrintJob.supportsPageSetupDialog

### 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:

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` | String |  | `"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()`:

Copy

         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

More examples

Printing a page

Related API Elements

PrintJob.addPage()
PrintJob.send()

### 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:

Copy

         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

Related API Elements

PrintJob.addPage()
PrintJob.send()

### 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.

Examples How to use this example
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.
Copy

    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.

Copy

    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.
Copy

    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;
             }
         }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00