addPage (PrintJob.addPage method)

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

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

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

If you want to scale a movie clip before you print it, set its MovieClip._xscale and MovieClip._yscale properties before calling this method, and set them back to their original values afterward. The scale of a movie clip has no relation to printArea. That is, if you specify that you print an area that is 50 x 50 pixels in size, 2500 pixels are printed. If you have scaled the movie clip, the same 2500 pixels are printed, but the movie clip is printed at the scaled size.

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

Parameters

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

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

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

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

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

The conversion rate between pixels and points depends on the printer settings and whether the movie clip is scaled. An unscaled movie clip that is 72 pixels wide will print out one inch wide, with one point equal to one pixel, independent of screen resolution.

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

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

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

{printAsBitmap:Boolean}

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

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

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

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

Returns

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

Example

my_btn.onRelease = function()
{
    var pageCount:Number = 0;

    var my_pj:PrintJob = new PrintJob();
    
    if (my_pj.start())
    {
    // Print entire current frame of the _root movie in vector format
    if (my_pj.addPage(0)){
        pageCount++;

        // Starting at 0,0, print an area 400 pixels wide and 500 pixels high
        // of the current frame of the _root movie in vector format
        if (my_pj.addPage(0, {xMin:0,xMax:400,yMin:0,yMax:500})){
        pageCount++;

        // Starting at 0,0, print an area 400 pixels wide and 500 pixels high
        // of frame 1 of the _root movie in bitmap format
        if (my_pj.addPage(0, {xMin:0,xMax:400,yMin:0,yMax:500},
            {printAsBitmap:true}, 1)){
            pageCount++;

            // Starting 50 pixels to the right of 0,0 and 70 pixels down,
            // print an area 500 pixels wide and 600 pixels high
            // of frame 4 of level 5 in vector format
            if (my_pj.addPage(5, {xMin:50,xMax:550,yMin:70,yMax:670},null, 4)){
            pageCount++;

            // Starting at 0,0, print an area 400 pixels wide 
            // and 400 pixels high of frame 3 of the "dance_mc" movie clip 
            // in bitmap format
            if (my_pj.addPage("dance_mc",
                {xMin:0,xMax:400,yMin:0,yMax:400},{printAsBitmap:true}, 3)){
                pageCount++;

                // Starting at 0,0, print an area 400 pixels wide
                // and 600 pixels high of frame 3 of the "dance_mc" movie clip
                // in vector format at 50% of its actual size
                var x:Number = dance_mc._xscale;
                var y:Number = dance_mc._yscale;
                dance_mc._xscale = 50;
                dance_mc._yscale = 50;

                if (my_pj.addPage("dance_mc",
                    {xMin:0,xMax:400,yMin:0,yMax:600},null, 3)){
                pageCount++;
                }
                dance_mc._xscale = x;
                dance_mc._yscale = y;
            }
            }
        }
        }
    }
    }
    
    // If addPage() was successful at least once, print the spooled pages.
    if (pageCount > 0){
    my_pj.send();
    }
    delete my_pj;
}

addPage (PrintJob.addPage method)

Parameters

Returns

Example

See also