Documents produced with FlashPaper 1.0 support a limited number of functions.

This version of FlashPaper does not work well when embedded in other Flash
documents.

function isFlashPaperDocument() Returns true if this is a FlashPaper-generated

SWF file.

function onPageChanged(newPageNumber) Called by the Flash document

when the page number changes. Default function does nothing. Can be overwritten
by a container that wants to trap this event.

function getCurrentPage() Returns the current page number.

function setCurrentPage(pageNumber) Sets the current page number,

changing the view if necessary, to ensure that at least part of the specified page is
visible.

function getNumberOfPages() Returns the total number of pages in the

document.

Note: The FlashPaper 1.0 viewer did not implement function getNumberOfPages()
correctly and may return undefined as the value.

FlashPaper 1.01 supports the functions supported by FlashPaper 1.0 and adds
support for several other useful functions.

function getViewerType() Returns a string that describes the type of the viewer.
The standard Macromedia-provided viewer always returns Macromedia FlashPaper
Default Viewer.

function getViewerVersion() Returns an integer indicating the revision of this

particular viewer type. FlashPaper 1.01 viewer returns the integer 2.

function getLoadedPages() Returns the number of pages loaded so far. This is

always an integer between 0 and getNumberOfPages(), inclusive.

function showPrevNextUI( flag ) Hides or displays the Previous Page/Next Page

user interface.

function showPrintUI( flag ) Hides or displays the Print user interface.

function printTheDocument() Opens the Print dialog box. This call behaves as if
the user had clicked the Print button. Returns true if successful, false if not.

Note: The SWF file must be completely loaded for function printTheDocument() to
succeed; if it returns false, that is generally because the document has not yet fully
loaded.

function showZoomUI( flag ) Hides or displays all magnification-related user

interface controls.

function setCurrentZoom(percent) Sets the current zoom to the given

percentage. In addition to numeric values, you can pass width to fit the width into
the view, and page to fit the page into the view.

function getCurrentZoom() Returns the current zoom level. Only numeric values
are returned (never width or page). If the viewer doesn't support varying zoom
levels, this function returns zero.
function onZoomChanged(percent) Called by the document when the zoom
level changes. Default function does nothing. Can be overwritten by a container
that wants to trap this event.

function setSize( w, h ) Sets the display size of the SWF file, in pixels. Returns
true if resize was successful, false if not. This call should not be used unless the
SWF file is embedded inside another SWF file.

Note: This call returns false until at least the first page of the document loads, so
you may need to call it repeatedly until it returns true.

A FlashPaper 2.0 document exposes a single function at the root level:

function getIFlashPaper():FlashPaper.IFlashPaper;

This returns an object that implements the IFlashPaper interface. If this function is
not defined, then the SWF file is not a FlashPaper 2.0 document. If this function
exists, but returns a value of null or undefined, then the SWF file is a FlashPaper 2.0
document, but has not yet loaded enough to access the API; you must wait for it to
load more fully and call it again. For more information, see Loading FlashPaper 2.0
documents into Flash.

The IFlashPaper interface in ActionScript 2.0 looks like this:

interface FlashPaper.IFlashPaper
{
function addListener(listener:Object):Void;
function removeListener(listener:Object):Void;
function getViewerType():String;
function getViewerVersion():Number;
function getCurrentPage():Number;
function setCurrentPage(pageNumber:Number):Void;
function getNumberOfPages():Number;
function getLoadedPages():Number;
function showUIElement(part:String, flag:Boolean):Void;
function printTheDocument():Boolean;
function setCurrentZoom(percent:Object):Void;
function getCurrentZoom():Number;
function setSize(w:Number, h:Number):Boolean;
function goToLinkTarget(linktarget:String, window:Object):Void;
function enableScrolling(flag:Boolean):Boolean
function getCurrentTool():String;
function setCurrentTool(tool:String):Boolean;
function getTextSelectionRange():FlashPaper.SelectionRange;
function setTextSelectionRange(sel:FlashPaper.SelectionRange,
skipBroadcast:Boolean):Void;
function getSelectedText():String;
function getSidebarWidth():Number;
function setSidebarWidth(w:Number):Void;
function getFindText():String;
function setFindText(s:String):Void;
function findNext():Boolean;
function getVisibleArea():Object;
function setVisibleArea(area:Object, skipBroadcast:Boolean):Void;
};

That's a lot of functions—let's take a look at each one.

The following functions are supported by the IFlashPaper interface:

addListener(listener:Object):Void; Adds or removes a listener for various
events. Your listener can receive the following events:

onPageChanged(newPageNumber:Number):Void Broadcast when the current page

(as displayed in the toolbar) changes.

onZoomChanged(percent:Number):Void Broadcast when the current zoom level (as

displayed in the toolbar) changes.

onSelection():Void Broadcast when the current text selection in the document

changes. (For efficiency, the new selection is not passed as an argument; you
should call getTextSelectionRange() to get the new selection.)

onToolChanged(newTool:String):Void Broadcast when the currently active tool (as

displayed in the toolbar) changes.

onEnableScrolling(enable:Boolean):Void Broadcast when scrolling is enabled or

disabled, typically by a call to enableScrolling().

onVisibleAreaChanged():Void Broadcast when any aspect of the visible area of the

document changes, including zoom level and scroll position.

Other events might be broadcast, but those events might not be in future versions
of FlashPaper. You should not rely on undocumented events broadcast by this
mechanism.

removeListener(listener:Object):Void; Removes a listener added by

addListener(). If the given object is not a listener for this FlashPaper document, the
call does nothing.

getViewerType():String; Returns a string describing the type of user interface

that is included in the document. The standard Macromedia FlashPaper viewer
always returns the string Macromedia FlashPaper Default Viewer.

getViewerVersion():Number; Returns an integer indicating the version of the

user interface code in this particular document. The returned integers are arbitrary
and not necessarily consecutive, but larger numbers indicate recent revisions to the
viewer, and might indicate bug fixes or enhanced functionality. FlashPaper 2.01
shipped with a viewer version number of 218.

getCurrentPage():Number; Returns the current page number (as displayed in the

toolbar). The first page is page 1.

setCurrentPage(pageNumber:Number):Void; Sets the current page. The view

scrolls as necessary to ensure the page is visible, but does not adjust zoom.

getNumberOfPages():Number; Returns the total number of pages in the

document.

Note: All of the pages may not be able to be displayed yet, depending on the
connection speed.

getLoadedPages():Number; Returns the total number of pages loaded (and able

to be displayed) so far. This value must be between zero and getNumberOfPages(),
inclusive. When getLoadedPages() == getNumberOfPages(), the document is fully
loaded.
showUIElement(part:String, flag:Boolean):Void; Hides or displays part of the
user interface in the FlashPaper document. The currently supported, case-sensitive
values for part are the following:

"PrevNext" The Previous Page and Next Page toolbar buttons are hidden or shown.

Note: If these buttons are hidden, the Current Page text box is disabled, but not
hidden.

"Print" The Print toolbar button is hidden or shown.

"Tool" All tool selection buttons on the toolbar are hidden or shown.

"Zoom" All zoom-related controls on the toolbar are hidden or shown.

"Find" All text-search-related controls on the toolbar are hidden or shown.

"Pop" The Open Document in New Browser Window toolbar button is hidden or
shown.

"Sidebar" The sidebar (displaying the document outline) is hidden or shown.

Note: This value is ignored if the document does not contain an outline; documents
without outlines never show a sidebar.

"Page" The Current Page and Number of Pages fields in the toolbar are hidden or
shown.

"Overflow" The Overflow menu on the toolbar is hidden or shown.

Note: This menu appears only when the toolbar is too narrow to display all controls;
you cannot use this call to force the Overflow menu to be visible.

"ZoomKeys" This value doesn't affect the user interface; it is used to enable or
disable various keys used to zoom in or out of the document (for example, +, -, p,
w).

printTheDocument():Boolean; Simulates a user clicking the Print button. The

document must be fully loaded before you call this function. This function returns
false if the document is not fully loaded.

setCurrentZoom(percent:Object):Void; Sets the current zoom level. You can

pass a number indicating a zoom percentage (for example, 100 for a 100% view).
You can also pass the string width to zoom to the current fit-to-width magnification
for this document, or pass the string page for the fit-to-page magnification.

getCurrentZoom():Number; Returns the current zoom level.

Note: The zoom level always returns as a number; width and page are never
returned.

setSize(w:Number, h:Number):Boolean; Sets the display size of the document,

in pixels. This function returns true if resize was successful, false if resize was
unsuccessful. Generally speaking, this function fails (returns false) if the document
isn't fully loaded.

goToLinkTarget(linktarget:String, window:Object):Void; Handles an anchor or

URL link request.
If the given string is a string of the form anchor:foo, the current view shifts to that
anchor with a logical name of foo. The window argument is ignored in this case. If
foo is not a valid anchor name in the document, no action is taken.

For all other strings, getURL(linktarget, window) is called. (For more information, see
the ActionScript documentation for this function.)

enableScrolling(flag:Boolean):Boolean Used to prevent the user from scrolling

the document.

When scrolling is disabled, the following is true:

• The scroll bar is disabled, but visible.

• Panning (using the pointing hand) is disabled.
• Scrolling using the mouse wheel is disabled.

The return value is the previous value of this flag.

getCurrentTool():String; Returns the currently active tool. If no tool is active, an

empty string is returned.

The following are currently supported values:

• "" (no tool)

• "pan" (hand tool)
• "select" (text selection tool)

setCurrentTool(tool:String):Boolean; Makes the given tool the active tool. This

function returns false if the argument is invalid or the given tool is disabled.

The following are currently supported values:

• "" (no tool)

• "pan" (hand tool)
• "select" (text selection tool)

getTextSelectionRange():FlashPaper.SelectionRange; Returns an object

describing the current text selection. If no text is selected, this function returns null.

Note: Unlike the object returned by getVisibleArea(), this call always returns a
FlashPaper.SelectionRange, which is a well-defined object that you can examine,
decompose, or construct new instances of.

setTextSelectionRange(sel:SelectionRange, skipBroadcast:Boolean):Void;
Selects the given range of text. You may pass null to deselect all text. Invalid ranges
are clipped to document ranges (this allows you to set a range that begins with zero
and ends with a large number, such as 999999, to select the entire document).

If skipBroadcast is false (or omitted), onVisibleAreaChanged() is broadcast to

listeners as necessary. If skipBroadcast is true, onVisibleAreaChanged() is never
broadcast to listeners.

Note: Unlike the object expected by setVisibleArea(), this call always expects a
FlashPaper.SelectionRange, which is a well-defined object that you can examine,
decompose, or construct new instances of.

getSelectedText():String; Returns the selected text as a Unicode string. If no text

is selected, an empty string is returned.
getSidebarWidth():Number; Returns the width of the sidebar. A document with
no outline always returns zero.

setSidebarWidth(w:Number):Void; Sets the width of the sidebar. Pass zero to

hide the sidebar completely. A document with no outline ignores this call.

getFindText():String; Returns any text in the Find text box as a Unicode string.

setFindText(s:String):Void; Sets the text in the Find text box to a Unicode string
value. This call does not perform a find operation or alter the current selection.

findNext():Boolean; Searches for the text in the Find text box. The search begins
from the end of the current selection. To start from the beginning of the document,
call setSelectionRange(null) first. Returns true if text is found, false if not. If text is
found, the specific range can be found by calling getTextSelectionRange().

getVisibleArea():Object; Returns an object describing the current visible area of

the document.

You can use the return value to do one of the following:

• Pass to setVisibleArea().

This can be useful if the same document is being viewed on multiple

computers, and you want to keep the visible areas in sync.

• Compare with a previous value returned by getVisibleArea() to determine if

the viewable area has changed.

The returned object should be considered an opaque data type. Don't try to
decompose the returned object, because its contents and format will probably
change in future versions. The only public member of the object we guarantee in
future versions of the method is:

function equals(that:Object):Boolean;

You can use this to compare two visible areas to determine if they are the same.

setVisibleArea(area:Object, skipBroadcast:Boolean):Void; Adjusts the

currently visible page/zoom/scroll to match the visible area described by the area
object.

If skipBroadcast is false (or omitted), onVisibleAreaChanged() is broadcast to

listeners as necessary. If skipBroadcast is true, onVisibleAreaChanged() is never
broadcast to listeners.

This object must be one previously returned by getVisibleArea. Don't try to

construct your own object, because the contents and format will probably change in
future versions

Several methods in IFlashPaper use or return an object of type

FlashPaper.SelectionRange. This is a simple class that is defined as follows:

class FlashPaper.SelectionRange
{
public var headPageIdx:Number;
public var headCharIdx:Number;
public var tailPageIdx:Number;
public var tailCharIdx:Number;
 function equals(that:FlashPaper.SelectionRange):Boolean
{
return this.headPageIdx == that.headPageIdx &&
this.headCharIdx == that.headCharIdx &&
this.tailPageIdx == that.tailPageIdx &&
this.tailCharIdx == that.tailCharIdx;
}
};

It is legal and acceptable to decompose these objects, or to construct them

yourself, because their structure and contents are guaranteed to remain compatible
in future versions of FlashPaper.

It's important to understand is that a FlashPaper document is a SWF file; you can
load it as you would any other SWF file using loadMovie(), loadMovieNum(),
MovieClipLoader, and so on.

One important thing to watch for is the size of MovieClip after loading. As with all
SWF files loaded in Flash using loadMovie() and related calls, the MovieClip resizes
itself to the native size of the loaded SWF file, which is always 550 x 400 for
FlashPaper 2.0 documents.

To set a different size (to fit into an existing layout), you would typically use code
similar to this:

dest_mc.loadMovie("foo.swf");
//
// wait for loading to complete
//
dest_mc._width = 300; // resize to 300x200
dest_mc._height = 200;

While this code works for Flash documents, it won't give you the desired result; it
produces a strangely squashed result. This happens because adjusting the _width
and _height fields on a MovieClip doesn't actually adjust the size—it adjusts the
scaling factor.

So, you need to tell the FlashPaper document to resize itself. You can easily do this,
using the setSize() call as follows:

dest_mc.loadMovie("foo.swf");
//
// wait for loading to complete
//
dest_mc.getIFlashPaper().setSize(300, 200); // resize to 300x200

This code almost works. The problem is the wait for loading to complete comment—
it requires waiting a variable number of frames, depending on various factors,
including the number of frames in the SWF file being loaded and connection speed.

One way to deal with this is to use the MovieClipLoader class provided in Flash
Player 7. However, FlashPaper 2.0 documents require Flash Player 6 or later, so
using this class might unnecessarily limit your deployment. So, there's an alternate
function that is safe for use with Flash Player 6 or later:

function loadFlashPaper(
path_s, // path of SWF to load
 dest_mc, // MC which we should replace with the SWF
width_i, // new size of the dest MC
height_i, // new size of the dest MC
loaded_o) // optional: object to be notified that loading is complete
{
var intervalID = 0;
var loadFunc = function()
{
dest_mc._visible = false;
var fp = dest_mc.getIFlashPaper();
if (!fp)
return;
if (fp.setSize(width_i, height_i) == false)
return;
dest_mc._visible = true;
clearInterval(intervalID);
loaded_o.onLoaded(fp);
}
intervalID = setInterval(loadFunc, 100);
dest_mc.loadMovie(path_s);
}

You can use this function to load a FlashPaper document into a MovieClip and resize
it appropriately when loading is complete.

Note: This function assumes that the SWF file being loaded is a FlashPaper
document. This function will execute forever for other SWF files, so use it with
caution.

Suppose you have an existing MovieClip named "fp_mc" that you want to replace
with a FlashPaper document, and you want the loaded document to be resized to be
the same size as the existing MovieClip. You could use the following code:

loadFlashPaper("MyFlashPaperDocument.swf",
fp_mc,
fp_mc._width,
fp_mc._height,
null);

If you want to do additional work when the document is fully loaded, you could also
use an optional listener object. This example scrolls to the last page of the
document and changes the document magnification to 33%:

var loadNotifier:Object = new Object;

loadNotifier.onLoaded = function(fp:Object):Void
{
fp.setCurrentZoom(33);
fp.setCurrentPage(fp.getNumberOfPages());
};

loadFlashPaper("MyFlashPaperDocument.swf",
fp_mc,
fp_mc._width,
fp_mc._height,
loadNotifier);

If you want to alter the FlashPaper document toolbar, or add a listener for various
events, onLoaded is an excellent place to do so. Here's an example that hides the
Print button and adds a listener that monitors the current page and zoom:

var loadNotifier:Object = new Object;

loadNotifier.onLoaded = function(fp:Object):Void
{
fp.showUIElement("Print", false);
fp.addListener(this);
};
loadNotifier.onPageChanged = function(newPageNumber:Number):Void
{
trace("You have scrolled to page "+newPageNumber);
};
loadNotifier.onZoomChanged = function(percent:Number):Void
{
trace("You have zoomed to "+percent+"%");
};

loadFlashPaper("MyFlashPaperDocument.swf",
fp_mc,
fp_mc._width,
fp_mc._height,
loadNotifier);

You can modify a few initial settings for Flash documents without using ActionScript;
instead, you override some settings in the URL of your SWF file, as follows:

foo.swf?INITIAL_VIEW=35&POPUP_ENABLED=false

In this example, the document is created with an initial zoom of 35%, and with the
Open In New Browser buttonhidden.

The currently defined settings are as follows:

INITIAL_VIEW Initial zoom level (numeric percentage, "width", or "page").

INITIAL_PAGE Initial page to display (numeric value).

INITIAL_BOOKMARK Name of outline entry to use for initial view.

POPUP_ENABLED If false, hide the Open In New Browser button.

HIDE_SIDEBAR If true, do not show the sidebar.

UIFONT Name of the font to use for the FlashPaper user interface.

UIFONTSIZE Sizes to use for Normal fonts in the FlashPaper user interface.

UISMALLFONTSIZE Sizes to use for Small fonts in the FlashPaper user interface.