AIR applications can render not only SWF and HTML content but also PDF content. AIR applications render PDF content using the HTMLLoader class, the WebKit engine, and the Adobe Reader browser plug-in. In an AIR application, PDF content can either stretch across the full height and width of your application or alternatively as a portion of the interface. The Adobe Reader browser plug-in controls display of PDF files in an AIR application, so modifications to the Reader toolbar interface (such as those for position, anchoring, and visibility) persist in subsequent viewing of PDF files in both AIR applications and the browser.

Contents

• Detecting PDF Capability
• Loading PDF content
• Scripting PDF content
• Known limitations for PDF content in AIR

Detecting PDF Capability

If the user does not have an installed version of Adobe Reader or Adobe Acrobat 8.1 or higher, PDF content will not display in an AIR application. To detect if a user can render PDF content, first check the HTMLLoader.pdfCapability property. This property is set to one of the following constants of the HTMLPDFCapability class:

The following code detects whether a user can display PDF content in an AIR application, and if not traces the error code that corresponds to the HTMLPDFCapability error object:

if(HTMLLoader.pdfCapability == HTMLPDFCapability.STATUS_OK) 
{
    trace("PDF content can be displayed");
}
else 
{
    trace("PDF cannot be displayed. Error code:", HTMLLoader.pdfCapability);
}

Loading PDF content

You can add a PDF to an AIR application by creating an HTMLLoader instance, setting its dimensions, and loading the path of a PDF.

The following example loads a PDF from an external site. Replace the URLRequest with the path to an available external PDF.

var request:URLRequest = new URLRequest("http://www.example.com/test.pdf");
pdf = new HTMLLoader();
pdf.height = 800;
pdf.width = 600;
pdf.load(request);
container.addChild(pdf);

You can also load content from file URLs and AIR-specific URL schemes, such as app and app-resource. For example, the following code loads the test.pdf file in the PDFs subdirectory of the application directory:

app:/js_api_reference.pdf

For more information on AIR URL schemes, see Using AIR URL schemes in URLs.

Scripting PDF content

You can use JavaScript to control PDF content just as you can in a web page in the browser.

JavaScript extensions to Acrobat provide the following features, among others:

• Controlling page navigation and magnification.
• Processing forms within the document
• Controlling multimedia events

This section provides basic examples for controlling page navigation and display scale factor. Full details on other JavaScript extensions for Adobe Acrobat are provided at the Adobe Acrobat Developer Center, at http://www.adobe.com/devnet/acrobat/javascript.html.

HTML-PDF communication basics

JavaScript in an HTML page can send a message to JavaScript in PDF content by calling the postMessage() method of the DOM object representing the PDF content. For example, consider the following embedded PDF content:

<object id="PDFObj" data="test.pdf" type="application/pdf" width="100%" height="100%"/>

The following JavaScript code in the containing HTML content sends a message to the JavaScript in the PDF file:

pdfObject = document.getElementById("PDFObj");
pdfObject.postMessage(["testMsg", "hello"]);

The PDF file can include JavaScript for receiving this message. You can add JavaScript code to PDF files in a number of contexts, including the document-, folder-, page-, field-, and batch-level contexts. This section discusses only the document-level context, which defines scripts that are evaluated when the PDF document opens.

A PDF file can add a messageHandler property to the hostContainer object. The messageHandler property is an object that defines handler functions to respond to messages. For example, the following code defines the function to handle messages received by the PDF file from the host container (which is the HTML content embedding the PDF file):

this.hostContainer.messageHandler = {onMessage: myOnMessage};

function myOnMessage(aMessage)
{
    if(aMessage[0] == "testMsg")
    {
        app.alert("Test message: " + aMessage[1]);
    }
    else
    {
        app.alert("Error");
    }
}

JavaScript code in the HTML page can call the the postMessage() method of the PDF object contained in the page. Calling this method sends a message ("Hello from HTML") to the document-level JavaScript in the PDF file:

<html>
    <head>
    <title>PDF Test</title>
    <script>
        function init()
        {
            pdfObject = document.getElementById("PDFObj");
            try {
                  pdfObject.postMessage(["alert", "Hello from HTML"]);
            } 
            catch (e)
            {
                alert( "Error: \n name = " + e.name + "\n message = " + e.message );
            }
        }
    </script>
    </head>
    <body onload='init()'>
        <object 
            id="PDFObj" 
            data="test.pdf" 
            type="application/pdf" 
            width="100%" height="100%"/>
    </body>
</html>

For a more advanced example, and for information on using Acrobat 8 to add JavaScript a PDF file, see Cross-scripting PDF content in Adobe AIR.

Scripting PDF content from ActionScript

ActionScript code (in SWF content) cannot directly communicate with JavaScript in PDF content. However, ActionScript can communicate with the JavaScript in the HTML page loaded in an HTMLLoader object that loads PDF content; and that JavaScript code can communicate with the JavaScript in the loaded PDF file. For more information, see Programming in HTML and JavaScript.

Known limitations for PDF content in AIR

PDF content in Adobe AIR has the following limitations:

• PDF content does not display in a window (a NativeWindow object) that is transparent (where the transparent property is set to true).
• The display order of a PDF file operates differently than other display objects in an Apollo application. Although PDF content clips correctly according to HTML display order, it will always sit on top of content in the AIR application's display order.
• PDF content does not display in a window that is in full-screen mode (when the displayState property of the Stage is set to StageDisplayState.FULL_SCREEN or StageDisplayState.FULL_SCREEN_INTERACTIVE).
• The visual properties of an HTMLLoader object that contains a PDF file cannot be changed. Changing an HTMLLoader object's filters, alpha, rotation, or scaling properties render the PDF file invisible until the properties are reset.
• The scaleMode property of the Stage object of the NativeWindow object containing the PDF content must be set to StageScaleMode.NO_SCALE.
• Clicking links to content within the PDF file update the scroll position of the PDF content. Clicking links to content outside the PDF file redirect the HTMLLoader object that contains the PDF (even if the target of a link is a new window).
• PDF commenting workflows do not function in AIR 1.0.

See also

• Cross-scripting PDF content in Adobe AIR