Important: there have been some major compatibility improvements for Air in version 2.1.0 - which, at the time of writing (2011/8/6) is still under development. This tutorial is meant to be followed using MegaZine3 version 2.1.0 or later. There will likely be issues with earlier versions.

This page will give very rudimentary step-by-step guide of how to get MegaZine3 running in an Air application.

[edit] Step 1: create project

If you already have your Air project you can skip directly to step 2.

In Flash Builder, select "New->Flex Project". You will see a screen like this (sorry for the German):

Fill in the desired project name, mark it as an Air app ("Desktop" type) and click "Finish", unless you need to set more nuanced settings.

[edit] Step 2: reference library

To work with MegaZine3 you'll need to reference the library in your project. The easiest way to do this is to simply place the megazine3-fat.swc file into you libs folder:

[edit] Step 3: the code

In the versions after the release of version 2.1 there is now a wrapper component available. So when using the nightlies or 2.1.1+ you can do the following when using the fat SWC:

<?xml version="1.0" encoding="utf-8"?>
<s:WindowedApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
			   xmlns:s="library://ns.adobe.com/flex/spark" 
			   xmlns:mx="library://ns.adobe.com/flex/mx"
			   xmlns:mp="de.mightypirates.megazine.flex.*">
	<fx:Script>
		<![CDATA[
			import de.mightypirates.megazine.Assets;
		]]>
	</fx:Script>
 
	<mp:MegaZine left="0" right="0" top="0" bottom="0"
			 addedToStage="Assets.init(loaderInfo)">
		<fx:XML>
			<book>
				<chapter>
					<page/>
					<page/>
				</chapter>
			</book>
		</fx:XML>
	</mp:MegaZine>
</s:WindowedApplication>

And you're done! If you're not using the fat SWC you can even skip the script block and the addedToStage event.

The old way to add an instance to your App is to create an mx:UIComponent in which you add an instance of MegaZine3. Assuming you have a blank application (new project), you'll modify it to something like this:

<?xml version="1.0" encoding="utf-8"?>
<s:WindowedApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
			   xmlns:s="library://ns.adobe.com/flex/spark" 
			   xmlns:mx="library://ns.adobe.com/flex/mx"
			   addedToStage="onInit()">
	<fx:Script>
		<![CDATA[
			import de.mightypirates.megazine.Assets;
			import de.mightypirates.megazine.MegaZine;
			private var mz:MegaZine;
			private function onInit():void {
				Assets.init(loaderInfo);
				mz = new MegaZine();
				container.addChild(mz);
				onResize();
				mz.loadXML(
					<book plugins="navigationbar">
						<chapter>
							<page/>
							<page/>
							<page/>
							<page/>
							<page/>
							<page/>
							<page/>
							<page/>
						</chapter>
					</book>);
			}
			private function onResize():void {
				if (mz) {
					mz.width = container.width;
					mz.height = container.height;
				}
			}
		]]>
	</fx:Script>
	<mx:UIComponent id="container" left="0" right="0" top="0" bottom="0" resize="onResize()"/>
</s:WindowedApplication>

The important points are:

• the script block, obviously. It creates a new instance, adds it to the container when the whole app becomes visible and takes care of resizing.
• the container (mx:UIComponent at the bottom), which will contain the book instance.

This will create a book with eight empty pages and the navigationbar plugin loaded.

[edit] Step 4: using .mz3 files

You can still use .mz3 files. To do that, change the mz.loadXML(...) to mz.load("name_of.mz3") and place the file plus your data files in the "src" folder of the project.

When using the wrapper component, you can simply supply it as a property:

<mp:MegaZine xmlFile="path/to/book.mz3"/>

[edit] Known issues

• SWFs can be a pain in Air, because they are a potentially huge security issue. The current, hopefully relatively sensible default of MegaZine3 is to allow loading local SWFs via the built-in caching loader -- which puts them in the same "Domain" the engine is running in, and loading remote SWFs using the normal Flash Loader.
• SWFTools' pdf2swf can generate pages that cause problems. This occurs, e.g., for pages with links. pdf2swf then embeds code that causes an error when executed in Air. As to my knowledge there is no way for the engine to catch that error, so it utterly breaks stuff. There is no workaround for this, yet.

See this and this entry in the swftools mailing list.