PDF Documents inside Director

November 2, 1999
by Mike Weiland

Your boss or client comes to you with the great idea of incorporating the company's newsletters from the last 10 years into your latest CD. The newsletters are saved as Adobe Acrobat PDF files and your task is to embed the newsletters into Director. "Horse hockey" you say, "can't be done cross platform." But using the PDF Xtra from Integration New Media makes all this possible.

A PDF document is Adobe's Portable Document Format (PDF). PDFs were born from the need to transfer documents between users and companies and retain their original design. The beauty of the PDF document is that it preserves all of the fonts, formatting, colors, and graphics of any source document. So if I create a document with my own fonts, images and layout, make a PDF document out of it and email it to my mother, she does not have to have the fonts installed on her computer, nor the images, nor the software I used to create the original document. With Adobe Reader, the document will open up exactly as I initially layed it out.

Adobe has the commercially available Acrobat to view and create PDF files. Acrobat retails for around $250 and has several utilities for the creation of PDF files and accommodates the viewing of PDF documents. Adobe has also made available Acrobat Reader. The free Acrobat Reader software has only one function and that is to read PDF documents. You cannot create PDF documents with Acrobat Reader. The big plus with Acrobat Reader is the fact that it can be freely distributed on CD-ROM or via the web. Plus, according to Adobe more than 40 million people already have the Reader. (NOTE: The commercial version of Acrobat is referred to as just Acrobat while the free reader is referred to as Acrobat Reader.)

Getting Director and PDFs to interact together has been possible before by using xtras such as BuddyAPI, MasterApp or AcroView. But all these solutions call up the Adobe Reader as an external application, forcing you to leave your Director projector. There is one other possibility of using an ActiveX control to embed PDF documents into Director, but this is a PC-only solution. Integration New Media (the maker of the V-12 Database Xtra) has recently raised the bar in the Director/PDF integration world. The rest of this article assumes that you have their PDF Xtra installed in Director along with the PDF XtraBehaviorLibrary.cst cast. Get a demo version of the xtra along with the external cast from http://www.integration.qc.ca/products/PDFXtra . And if you don't have Acrobat or a version of the Acrobat Reader you will need to download a copy of the Acrobat Reader.

To install the PDF Xtra

Make sure Director is not running,
Place the PDF Xtra in the Xtras folder. This folder is located in the same place as the Director application.
Restart Director.
Choose File : Preferences : General and make sure Animate in Background is turned on.
Make sure the Insert : Media Element menu contains a new entry named PDF Document.

The PDF Xtra by Integration New Media (INM) allows the embedding of PDF documents into Director. The PDF Xtra is an asset xtra, meaning it creates a new cast member type of PDF. It also has Lingo support so most functions can be scripted in Lingo as well. The PDF Xtra is available for MacOS 7.5.1+ (PPC only) and Windows 95/98/NT, and needs Adobe Acrobat 4.0 or Acrobat Reader 4.0 to be installed or running from a CD. It works in versions 5+ of Director. Embedding of a PDF is straight forward and simple:

Open Director
From the Insert Menu select Media Element and then select PDF document

Notice that this created a new cast member in your internal cast.

Double click the newly created PDF cast member, this opens the properties for the PDF. (see below)
Click the browse button and locate a PDF document to embed into our project. (If you can't find an available PDF document, the manual that came with the PDF Xtra makes a nice sample.)
Press OK to close the PDF properties.
Drag the PDF cast member to the stage.
Play the Director Movie.

Voila, a PDF file inside Director! To get a more detailed definition of the other options available in the PDF member options consult the PDF Xtra manual pages 7 to 9.

Now create a new Director movie and import the PDF document named PDF1.pdf (follow the steps above on using the PDF Xtra to insert a PDF document). Drag the new cast member to the stage and play the movie.

From this example you will see that we have styled text and graphics in a scrolling list, something that has been very hard to do in Director. The one drawback is that we are seeing the PDF documents toolbar. Bring up the PDF member options by double clicking on the member in the cast, deselect the Show Toolbar option. Close the PDF member options dialog box and play the movie. This time the toolbar is gone and you have a nice scroll bar.

The PDF Xtra is also scriptable and has a wide array of methods (18 sprite methods and 3 global methods) that can be used inside Director. The general syntax for the PDF Xtra are: MethodName(sprite whichsprite, parametersÉ)

-- go to page 18
PDF_GoToPage(sprite 3, 18)

Some methods of the PDF Xtra will return a value so they need to be set to a variable, field or the message window.

-- returns the current page number
set var = PDF_GetPageNumber( sprite 3 )

A few of the notable methods in the PDF Xtra

PDF_Open Opens the specified PDF document.
PDF_Print Prints the PDF document in the specified sprite.
PDF_GetAcrobatInfo Return a Lingo property list describing the presence and state of Adobe Acrobat or Acrobat Reader on the current computer.

Let's put some of these Lingo methods to work for us. Create a new Director movie, insert a PDF member into the cast and create 3 buttons on the stage using the Tool Palette.

Drag the PDF member to the stage and place it to the right of the 3 buttons that you just created. We need a behavior that will open a PDF document and we will use the prebuilt behavior in the PDF XtraBehaviorLibrary.cst to accomplish that. But first we need to link the external cast to our movie. Select Modify : Movie : Casts. This opens the Movie Casts window.

The Movie Casts window show all the casts (internal & external) for the current movie. Press the Link button and locate the PDF XtraBehaviorLibrary.cst. With this done press the OK button to close the Movie Casts window. Now that the PDF behavior library is now linked we can use its behaviors, switch to the PDF XtraBehaviorLibrary.

Drag the PDF_Open behavior to the first button and give it the values below.

Drag the same behavior to the second button and give it the values below.

Play your movie and click on the first two buttons and see your PDF file swap back and forth. The third button is for printing of the current PDF document.

Drag the PDF_Print behavior to the third button and give it the parameters below.

Notice in the print behavior that the behavior is defaulting to 9999 in the print to page parameter. This is due to the fact that we don't know off hand what the last page number is. Yes, there is the PDF_getNumberOfPages method, but this is not available in Acrobat Reader, so we fool the xtra a bit by specifying a larger number that could be reached.

Play the movie and press the print button. As long as you are hooked up to a printer then you should get a print of the PDF document.

As you noticed from the printing example, the PDF_getNumberOfPages command is not supported in Acrobat Reader. There are a few commands that are Acrobat only functions and there are some commands that are PC only. If you absolutely have to have a command that is Acrobat only, Integration New Media can license Acrobat at a very advantageous price for bundling with your project. Another limitation to the PDF Xtra is that other Director sprites cannot go over the top of the PDF. However, I did find that the PopUpMenu Xtra from UpdateStage could go over the top of the PDF document. Due to palette conflicts between Acrobat and Director, 8-bit display is not supported in the current version of the PDF Xtra.

To get around this make sure that the end user's computer is in 16-bit resolution or higher. A slightly lesser limitation is the fact that the visibility of the PDF sprite cannot be set; it is always on. To workaround this you can set the location of the sprite to someplace off the stage. An observation that I have made in my work with the xtra -- I found it better to place an empty PDF file into my stub projector. This way at startup the Reader program starts when nothing else is going on, and therefore doesn't interfere with any other functions that your application is trying to perform.

One of the biggest possibilities with the PDF Xtra is the ability to search across multiple PDF documents. This can be accomplished in conjunction with the V-12 Database Xtra by Integration New Media. These two products allow you to create a database of PDF documents that are searchable and display the appropriate PDF based on what was returned from the search and what the user clicked on. Integration New Media also provides a utility called the PDF Indexer that will search a folder for PDF files and extract all the text from the PDF files and indexes them into a V-12 database. Currently the PDF Indexer runs only on Windows and needs Acrobat 4.0 to function properly.

Did I mention that the PDF Xtra is Shockwave safe/downloadable and Verisign certified? Well it is so the possibilities of embedding PDF documents into your Shockwave files is very much a reality!

In conclusion, if you need to incorporate PDF documents into Director, then the PDF Xtra by Integration New Media is the way to go. It is the only PDF Xtra on the market that will embed a PDF file as a cast member in Director, across platforms and between Acrobat and Acrobat Reader.

Sample code (including PDF documents) are available for download in Mac (121K) or PC (90K) format. These movies are Director 7 format.

Mike Weiland is the Director of Technology for Wasatch Interactive Learning, an educational software company in Salt Lake City, UT. He can be reached at mike@wasatchnet.com, website http://www.wasatchnet.com/.