[Tutorial] ActionScript Interaction (EN)

[Florian Nücke]

ActionScript Interaction

If you load your own swf files into the engine you might want to interact with it, to allow for more specialized behavior - e.g. an animation starting when the page the clip resides on becomes visible. Here is how to connect your code to the engine.


Setup / Connecting

To get a reference to the engine, all you have to do is add a function to the root of your swf, named megazineSetup. It comes in multiple flavors, so pick the one you need:

Code: (actionscript3)

// This will pass a reference to the instance of the engine,
// the page the swf resides in, if it's on the odd or even page,
// and a reference to the graphics library used for building the gui.
megazineSetup(megazine:IMegaZine, page:IPage, even:Boolean, library:ILibrary)
 
// Like the first, but no reference to the library.
megazineSetup(megazine:IMegaZine, page:IPage, even:Boolean)
 
// Only a reference to the engine itself.
megazineSetup(megazine:IMegaZine)

This function is called by the engines as soon as the swf is ready, passing the paramaters so that the swf can work with those later on. Therefore it normally makes sense to store the parameters in some local variables.
For more information on the classes (IMegaZine, IPage, ILibrary) please refer to the API.


Referencing other elements

If you wish to communicate between a loaded swf and another element in the book there are two steps:
1) In the XML set the id attribute of the element that should be referenced, e.g. myElement.

Code: (xml)

<img src="some.swf" id="myElement"/>

2) In the swf that should reference the element use the following code to get a reference:

Code: (actionscript3)

// Assuming the variable holding the reference to the engine is named 'mz'
var element:AbstractElement = mz.getElementById("myElement").element;

If you have two swfs that should communicate:

Code: (actionscript3)

// Continuing from above
var swf:DisplayObject = element.swf; // For this to work the element must be of class Image

Then you can access everything in your swf using the swf variable.


Using events

To give an example on using events, here is how you would check when the page the swf resides on becomes visible:

Code: (actionscript3)

var mz:IMegaZine;
function megazineSetup(mz:IMegaZine, page:IPage, even:Boolean):void {
    page.addEventListener(even ? MegaZineEvent.VISIBLE_EVEN : MegaZineEvent.VISIBLE_ODD, onPageVisible);
}
 
function onPageVisible(e:MegaZineEvent):void {
    // Page is now visible
}

For more event types see the API, namely for IMegaZine and IPage.


Sources

To compile your code when using the interfaces/classes, make sure to have the sources that come with the releases placed in your include path, and you'll need to import them by adding the following statements at the very top of your code:

Code: (actionscript3)

import de.mightypirates.megazine.IMegaZine;
import de.mightypirates.megazine.IPage;
import de.mightypirates.megazine.elements.AbstractElement;
import de.mightypirates.megazine.gui.ILibrary;

And for the example to work (using the event) you'll additionally need

Code: (actionscript3)

import de.mightypirates.megazine.events.MegaZineEvent;

Alternatively, if you don't care for the types you can just declare all of the variables of type Object (or *), of course. Using the classes is much recommended, though, otherwise typos or wrong assumptions can be a real pain.