The PDF Developer Junkie Blog

With the release of Acrobat X, there are a lot of big changes and a lot of great new stuff for developers to play with. With the help of Leonard Rosenthol, PDF Standards Architect, PDF guru and developer extraordinaire, I’ve compiled a list of the top things developers need to know about the new version.

Updating your plug-in to Work with Acrobat X

Here’s the good news… you probably don’t need to recompile your plug-in to make it work with Acrobat X. For the most part, even with all of the UI changes, we internally handle putting your tools and menu items in the right place for Acrobat X. Also, to the best of my knowledge, this is the first version of Acrobat for which developers don’t need to recompile their plug-in to make it work on either platform.

With the new Protected Mode in Reader X, there may be some work you’ll need to do to accommodate the sandboxed environment. More on Protected Mode later in this article.

Your Code and the New User Interface

If you haven’t heard already, the Acrobat and Reader user interface went through a major overhaul; the last time we updated the UI this dramatically was version 7. One of our primary goals was to improve the document consumption experience so we created a UI that allows you to focus on the document, not the tools. We also wanted the wide array of tools to be more discoverable so we grouped them into panels on the right and allow you to configure the Quick Tools bar at the top with the set of tools you use most
frequently.

With the simplification of the menus and the UI in general, there are some details that plug-in and JavaScript developers need to be aware of. In general, buttons and menu items added by plug-ins and by folder level JavaScripts are treated the same way.

Tool Buttons

Existing Acrobat 9 plug-ins will load their buttons into a new panel called “Plug-In” plus the name of the toolbar that you create; “Plug-In Foo” for example. If you installed a button into a toolbar that was in an earlier version of Acrobat but not in Acrobat X, you’ll see “Plug-In” plus the name of that toolbar. There are a few other details of interest…

• In the new UI, you cannot hide and show buttons. Internally, Acrobat X will translate hide and show to enable and disable so your code will still function, just a bit differently.
• Button names are the same with the exception that none of commenting tools are accessible from the Acrobat X API. In fact, the entire commenting pane is inaccessible to the new API.
• The QuickTools bar is inaccessible by the API though the Customization Wizard can be used to deploy a preconfigured set of tools.

Menus and Menu Items

All of the menu code works the same way that it did in Acrobat 9. However, the menus have been simplified in Acrobat X. Many menus that were in earlier versions simply don’t exist anymore – so if you attempt to install a menu item into a menu that no longer exists, the menu item won’t show
up anywhere.

Read Mode and the “Heads Up Display”

In short, the “Heads Up Display” (HUD) is not customizable. There are no APIs to HUD. You can’t use JavaScript to enter Read Mode, exit Read Mode or detect that the document is in Read Mode. Though it might seem like it, this wasn’t an oversight. There are some very sound engineering reasons why this is the case but I won’t go into those here.

Big Changes in the DDE Naming Convention

In the previous releases, it was possible that a PDF file would not open in the default handler if other applications were open. For example, even if Acrobat Reader was set as default handler for PDF files, the PDF files would open in Acrobat if Acrobat was installed and running. This could lead to issues, especially for sandboxing applications.

In this release, the PDF files open in the default handler even if other applications that can read PDF files are open. In the example cited earlier, the PDF now opens in Reader, even if Acrobat is running.

To implement this feature, there has been a change to the DDE naming convention—the DDE server name has been made unique for Acrobat and for Reader. The new naming convention is as follows:

Acroview{A|R}{MajorVersion} where {A|R} refer to Acrobat and Reader respectively.

For example, the name is AcroViewA10 for Acrobat X and AcroViewR10 for Reader 10.

For connecting to previous versions of Acrobat/Reader, the DDE connect string name continues to be “acroview”. You can get the correct name by using the “DDEAPPNAME” macro defined in WinAppSemaphore.h.

NOTE: Any scripts that have hard-coded references to the DDE name will have to be updated.

Protected Mode

Adobe Reader X on Windows runs in Protected Mode by default. Protected Mode or “Sandboxing” is a technique for creating a confined execution environment for running untrusted programs. It leverages the operating system’s security controls under a “principle of least privileges.” Processes which could be subject to an attacker’s control run with limited capabilities and must perform actions such as reading and writing through a separate, trusted process. This means is that PDF-based attacks are confined to the sandbox. This is good – very, very good.

The Reader X sandbox design has two primary effects:

• All PDF processing such as PDF and image parsing , JavaScript execution, 3D rendering , etc. happens in the sandbox and are subject to its limits. For example, processes cannot access other processes.
• Processes that need to perform some action outside the sandbox boundary must do so through a trusted proxy called a “broker process.”

Target processes are essentially all processes invoked by the interaction of a PDF document and Reader X and which run inside an enabled sandbox. All application and plug-in code runs as target processes with restricted rights and without direct access to files, the registry, and other processes.

• Target processes are denied access to most objects and so do not have permission to perform actions such as, but not limited to…
• Writing to the user’s TEMP folder (or other untrusted locations)
• Writing user modified preferences (saving) to the registry.
• Launch a .docx attachment in Microsoft Word.
• Windows message broadcasts.
• Setting global Windows hooks via SetWindowsHookEx().

If your plug-in uses the Acrobat SDK APIs provided to you for file I/O, etc. then Reader X will handle all the brokering for you and you won’t even need to worry about the sandbox… unless you try to reference objects outside the trusted areas.   If you make direct Windows OS API calls which fall into low rights categories, writing to the registry, for example, you will need to create your own broker and a sample in the new SDK will show you how.

Support for 64 bit systems:

Adobe Acrobat X and Reader X are supported on 64 bit systems even though they remain 32 bit applications – so plug-ins will need to be 32 bit as well. However, there are some issues around browser support. If your plug-in is Windows only, you’re pretty much good to go. No changes are necessary for 3rd party plug-ins to work in the supported browsers on Windows. On the Mac, the browser plug-in is Universal (both 32 and 64bits) and your plug-ins will continue to load when in standalone mode and in a 32 bit
browser but not in a 64 bit browser. The supported browsers on Windows are IE 7.0, IE 8.0, Firefox 3.5, Firefox 3.6. On the Mac, they are Safari 4 for OS X 10.5.8 and OS X 10.6.4; Safari 5 for OS X 10.6.4.

New Acrobat X Portfolio SDK

Finally, a new PDF Portfolio SDK will be available along with a new set of tools that plug into Flash Builder 4 to support the process of creating, debugging, and packaging PDF Portfolio Layouts that have even more capabilities than previously available. Users will be able to experience your new enhanced PDF Portfolio Layouts in Acrobat X in a future release of Adobe Reader 9 that will be available at the beginning of 2011. There are four major components to the new set of tools.

The New Project Wizard: The New Project Wizard is an extension that automates the process of creating a basic navigator project. After running the wizard, you’ll have a basic navigator with all the code and resources you need to compile, package and deploy for use in Acrobat, it’s basically identical to one of the Layouts that we ship with Acrobat, so you know it’s been tested and is ready to go.

The Debug Launcher: The Debug Launcher is a Flash Builder launch configuration type that has been customized to support the
running and debugging of navigator projects in a Previewer application.

The Previewer Application: The Previewer Application is a simulation of the Acrobat and Reader PDF Portfolio runtime. It allows you to test your Layout in various flavors of Acrobat and in Reader with a virtual PDF that has different permission bits. It even lets you test your custom properties, metadata and localization strings, all without loading your Layout into Acrobat itself.

The Export Wizard: The Export Wizard packages all of the needed navigator resources into a single .nav file.

Finally, all of the custom components that we use in the Layouts that ship with Acrobat are available for you to either use as-is or
extend. This opens up opportunities to customize a PDF Portfolio Layout if you are a Flash Builder expert or just getting started. The image below is a PDF Portfolio with a custom theme or “skin”.

Because these tools are built on Flash Builder 4 and use the new skinning model, Flash Professional Designers can use their existing skills to create “Visual Themes” or skins for all of the skinnable components in the Acrobat Portfolio SDK. If you know how to skin a video player, you can skin these components – it’s that easy