You should check to see if the PrintJob.start() method returns true before executing addPage() and send() calls, in case the user has cancelled the print job. A simple way to check whether these methods have been cancelled before continuing is to wrap them in an if statement, as follows:

if (myPrintJob.start()) 
{ 
    // addPage() and send() statements here 
}

If PrintJob.start() is true, meaning the user has selected Print (or Flash Player or AIR has initiated a Print command), the addPage() and send() methods can be called.

Also, to help manage the printing process, Flash Player and AIR throw exceptions for the PrintJob.addPage() method, so that you can catch errors and provide information and options to the user. If a PrintJob.addPage() method fails, you can also call another function or stop the current print job. You catch these exceptions by embedding addPage() calls within a try..catch statement, as in the following example. In the example, [params] is a placeholder for the parameters specifying the actual content you want to print:

if (myPrintJob.start()) 
{ 
    try 
    { 
        myPrintJob.addPage([params]); 
    } 
    catch (error:Error) 
    { 
        // Handle error,  
    } 
    myPrintJob.send(); 
}

After the print job starts, you can add the content using PrintJob.addPage() and see if that generates an exception (for example, if the user has cancelled the print job). If it does, you can add logic to the catch statement to provide the user (or Flash Player or AIR) with information and options, or you can stop the current print job. If you add the page successfully, you can proceed to send the pages to the printer using PrintJob.send().

If Flash Player or AIR encounters a problem sending the print job to the printer (for example, if the printer is offline), you can catch that exception, too, and provide the user (or Flash Player or AIR) with information or more options (such as displaying message text or providing an alert within an animation). For example, you can assign new text to a text field in an if..else statement, as the following code shows:

if (myPrintJob.start()) 
{ 
    try 
    { 
        myPrintJob.addPage([params]); 
    } 
    catch (error:Error) 
    { 
        // Handle error.  
    } 
    myPrintJob.send(); 
} 
else 
{ 
    myAlert.text = "Print job canceled"; 
}

For a working example, see Example: Scaling, cropping, and responding.

Once the user clicks OK in the Print dialog box and PrintJob.start() returns true, you can access the properties defined by the printer’s settings. These include the paper width, paper height (pageHeight and pageWidth), and content orientation on the paper. Because these are printer settings, not controlled by Flash Player or AIR, you cannot alter these settings; however, you can use them to align the content you send to the printer to match the current settings. For more information, see Setting size, scale, and orientation.

You can manually set the print job to spool each page as vector graphics or a bitmap image. In some cases, vector printing will produce a smaller spool file, and a better image than bitmap printing. However, if your content includes a bitmap image, and you want to preserve any alpha transparency or color effects, you should print the page as a bitmap image. Also, a non-PostScript printer automatically converts any vector graphics to bitmap images.

You specify bitmap printing in the third parameter of PrintJob.addPage(), by passing a PrintJobOptions object with the printAsBitmap parameter set to true, as follows:

var options:PrintJobOptions = new PrintJobOptions(); 
options.printAsBitmap = true; 
myPrintJob.addPage(mySprite, null, options);

If you don’t specify a value for the third parameter, the print job will use the default, which is vector printing.

ActionScript 3.0 does not restrict a PrintJob object to a single frame (as did previous versions of ActionScript). However, because the operating system displays print status information to the user once 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 will delay the printing process.

In ActionScript 3.0, there is a script time-out limit of 15 seconds. Therefore, the time between each major statement in a print job sequence cannot exceed 15 seconds. In other words, the 15-second script time-out limit applies to the following intervals:

• Between PrintJob.start() and the first PrintJob.addPage()

• Between PrintJob.addPage() and the next PrintJob.addPage()

• Between the last PrintJob.addPage() and PrintJob.send()

If any of these intervals spans 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 Flash Player or AIR to throw a run-time exception.