A Quick Glance at the FlashPaper API

You can find the FlashPaper 2 API fully documented in the FlashPaper 2 API documentation. A Flash movie clip consisting of a FlashPaper 2 document supports a getIFlashpaper() method that returns an object that implements the FlashPaper interface.

Once getIFlashpaper() returns the object, you can then call the other methods contained in the FlashPaper API using this object by assigning it to a variable, say, fp..

For example, you can display the current page in a FlashPaper document using fp.getCurrentPage(). You can change the current zoom mode using fp.setCurrentZoom(percent). You can also hide or show all the standard FlashPaper user interface elements, control the size of the document, return the text the user has selected, and so on.

Only documents created with FlashPaper 2 support the FlashPaper 2 API. Documents generated by FlashPaper 1 support a slightly different API, which is still supported, but deprecated, in FlashPaper 2.

See the FlashPaper 2 API documentation for a full list of FlashPaper 2 API calls and previous FlashPaper 1 methods.

The Basics of Importing a FlashPaper Document and Calling the API

The basic steps for importing a FlashPaper 2 document into your Flash FLA file and calling the FlashPaper 2 API are fairly straightforward. The essential steps are:

• Create a movie clip to hold the FlashPaper document you want to import.

  For example:
  var theDocMC_mc = this.createEmptyMovieClip("theDocMC",100);

  This creates a new (empty) movie clip at depth 100 on the Stage.

• Load the FlashPaper document, just as you would any other SWF file.

  You can use either the MoveClip.loadMovie() method or the ActionScript 2.0 MovieClipLoader() function.

• Call the method getIFlashPaper() on the movie clip that now holds the FlashPaper document:

  var fp = theDocMC_mc.getIFlashPaper();

  This returns the interface for the FlashPaper document that you can use to call the FlashPaper 2 API functions. For example:

  var pages_i = fp.getNumberOfPages()

  This returns the number of pages in the FlashPaper document.

Oops, Not So Fast…

Although the steps above provide the basic outline for importing a FlashPaper SWF and calling the FlashPaper 2 API, if you create a new Flash file with just the steps listed above, you will likely find that the FlashPaper interface (fp) is undefined and, hence, so is the number of pages (pages_i).

In other words, consider a Flash file like the following:

var theDocMC_mc = this.createEmptyMovieClip("theDocMC",100);
 theDocMC_mc.loadMovie("WhartonCentury.swf");
 var fp = theDocMC_mc.getIFlashPaper();
 var pages_i = fp.getNumberOfPages(); 
 trace("fp: " + fp); 
trace("pages_i: " + pages_i); 

Even though your FlashPaper document may display correctly, this code will very likely return undefined for both fp and pages_i, and none of the API functions will work.

The problem is that getIFlashPaper() doesn’t return a valid value until at least the first page of the FlashPaper document has loaded, so in your code, you need to verify that getIFlashPaper() has returned defined a value before calling the API.

There are a number of ways to do this. You can use the Flash Timeline to loop between frames until getIFlashPaper()is defined. In other words, load the external SWF file on one frame, leave the next frame blank, and then, on the third frame, check whether MovieClip.getIFlashPaper() returns a valid value and return to the previous (empty) frame if MovieClip.getIFlashPaper() doesn’t have a value.

You can also accomplish this by using a loop in ActionScript to repeatedly check the value returned by getIFlashPaper() before proceeding.