PrintJob  - AS3

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.

Related API Elements

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

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.

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.

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

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.

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.

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.

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.

Related API Elements

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.

More examples

Related API Elements

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.

More examples

Related API Elements

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

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.

Related API Elements

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.

Related API Elements

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.

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.

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.

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.

Related API Elements

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.

Related API Elements

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

More examples

Related API Elements

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

Related API Elements

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

More examples

Related API Elements

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

Related API Elements

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:

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()

More examples

Related API Elements

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

Related API Elements

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.

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