Build a Custom File Extension AIR App

This tutorial will explain how to make your own file extensions in Adobe AIR. I'll show you how to build a small application, save the positions of a couple movieclips within it, and reload them when the application is launched.

Follow along and see if you can come up with your own uses for Custom File Extensions..

Please upgrade your Flash Player

Step 1: Setting up the Document

Open a new Flash Air document, name it "saveFile", and save it in a new folder. Then, open a new ActionScript file, give it the same name, and save it into the same folder as the newly created Flash document.

If the prompt screen doesn't appear when Flash starts, simply create a new Flash ActionScript 3 document. Save the file, then go to Commands > AIR - Application and Installer Settings. Flash will convert the file to an Air document.

In the properties panel of the Flash document, type "saveFile" into the Document class field. This will associate the new ActionScript file (our document class) with the Flash document.

Step 2: Adding the Controls

Create a black square with a height of 52, set the width to be the stage width, and align it to the bottom-left of the stage. Give the square an alpha of 33. In the components panel, drag out three buttons and place them on top of the black square.

Give one of the buttons an instance name of "open" and change its label to say "Open". The next button will have an instance name of "save" and its label will be "Save". The third buttons name will be "image" and have a label of "Image". Spread them out however you want, select all three buttons and the black square and turn them into a single movieclip that has an instance name of "footer".

Step 3: Little Circles

On the stage, create a red circle with a height and width of 50px. Convert it to a movieclip, then in the dialog box, press the "Advanced" button. Under "Linkage" check the "Export for ActionScript" box. Give it a class name of "Red" and click "OK".

Next, create a blue circle that is the same size as the red circle. Convert it to a movieclip, export it for ActionScript and give it a class name of "Blue". Delete the two circles from the stage, so that the only remaining movieclip is the footer movieclip.

Step 4: Download the Adobe JPEG Encoder

Go to http://code.google.com/p/as3corelib/ and download the as3corelib zip folder. With the JPEG encoder, we'll be able to save an image of our little cirlces.

Step 5: The Document Class Skeleton

This is the basic frame where we'll put all our code.


package {
	import flash.display.Sprite;

	public class saveFile extends Sprite
	{
		
		public function saveFile()
		{
			
		}
	}
}

Step 6: The Imports

Here are the import statements to make the Air application work. These will go in the file right below the package declaration and above the public class statement.


import com.adobe.images.JPGEncoder;
	
	import flash.desktop.NativeApplication;
	import flash.display.BitmapData;
	import flash.display.MovieClip;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.events.InvokeEvent;
	import flash.events.MouseEvent;
	import flash.filesystem.File;
	import flash.filesystem.FileMode;
	import flash.filesystem.FileStream;
	import flash.net.FileFilter;
	import flash.utils.ByteArray;

Step 7: The Variables and Set up Functions

Here are the variables that we're using to create the two little circles on the stage. The offset variables will be used later for the dragging and dropping of the circles.

I have also assigned an invoke event listener to the NativeApplication. This will fire when the application is either launched or when the custom file is clicked. The invoke function will check to see how the app was launched. If it was from a file, it will load the file. If not, it will call the init function.


public class saveFile extends Sprite
	{
		private var red:MovieClip;
		private var blue:MovieClip;
		private var currentClip:MovieClip;
		private var xOffset:Number;
		private var yOffset:Number;
		
		public function saveFile()
		{
			NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvoke);
			movieClips();
			listeners();
		}
		private function init():void
		{
			var sw:int = stage.stageWidth;
			var sh:int = stage.stageHeight-footer.height;
			red.x = sw * Math.random();
			red.y = sh * Math.random();
			blue.x = sw * Math.random();
			blue.y = sh * Math.random();
		}
		private function movieClips():void
		{
			red= new Red();
			blue = new Blue();
			this.addChildAt(red, 0);
			this.addChildAt(blue, 1);
			this.addChildAt(footer, 2);
		}

Step 8: The Listeners Function

This function simply sets up the event listeners for all the buttons and circles on the stage.


private function listeners():void
		{
			red.addEventListener(MouseEvent.MOUSE_DOWN, onDown);
			blue.addEventListener(MouseEvent.MOUSE_DOWN, onDown);
			footer.open.addEventListener(MouseEvent.CLICK, openClick);
			footer.save.addEventListener(MouseEvent.CLICK, saveClick);
			footer.image.addEventListener(MouseEvent.CLICK, imageClick);
		}

Step 9: Moving the Little Circles

Here we set up the functions to move the circles around the stage.


private function onDown(event:MouseEvent):void
		{
			currentClip = event.target as MovieClip;
			xOffset = mouseX - currentClip.x;
			yOffset = mouseY - currentClip.y;
			currentClip.removeEventListener(MouseEvent.MOUSE_DOWN, onDown);
			this.addEventListener(MouseEvent.MOUSE_UP, onUp, false, 0, true);
			this.addEventListener(MouseEvent.MOUSE_MOVE, onMove, false, 0, true);
		}
		private function onMove(event:MouseEvent):void
		{
			currentClip.x = mouseX - xOffset;
			currentClip.y = mouseY - yOffset;
			event.updateAfterEvent();
		}
		private function onUp(event:MouseEvent):void
		{
			this.removeEventListener(MouseEvent.MOUSE_MOVE, onMove);
			this.removeEventListener(MouseEvent.MOUSE_UP, onUp);
			currentClip.addEventListener(MouseEvent.MOUSE_DOWN, onDown, false, 0, true);
		}

Step 10: Saving the Image

When the "Image" button is clicked, it will call the "imageClick" function. This function opens up a dialog save box and you can give your image any name you want. When the user names the image, it will call the "imageSave" function. Inside that function, we use the JPGEncoder class to create the image. The Air app then saves the image and listens for the "onClose" function. That function simply reassigns the little circles to the stage from the temp sprite that was created.


private function imageClick(event:MouseEvent):void
		{
			var file:File = File.desktopDirectory;
			file.browseForSave("Save Image");
			file.addEventListener(Event.SELECT, imageSave);
		}
		private function imageSave(event:Event):void
		{
			var temp:Sprite = new Sprite();
			var len:int = this.numChildren;
			temp.addChild(red);
			temp.addChild(blue);
			var bitmapData:BitmapData = new BitmapData(stage.stageWidth, stage.stageHeight);
			bitmapData.draw(temp);
			var jpg:JPGEncoder = new JPGEncoder(100);
			var byteArray:ByteArray = jpg.encode(bitmapData);
			var saveFile:File = File(event.target);
			var directory:String = saveFile.url;
			if(directory.indexOf(".jpg") == -1)
			{
				directory += ".jpg";
			}
			var file:File = new File();
			file = file.resolvePath(directory);
			var fileStream:FileStream = new FileStream();
			fileStream.addEventListener(Event.CLOSE, onClose);
			fileStream.openAsync(file, FileMode.WRITE);
			fileStream.writeBytes(byteArray);
			fileStream.close();
		}
		private function onClose(event:Event):void
		{
			this.addChildAt(red, 0);
			this.addChildAt(blue, 1);
		}

(Editor's note: Commenter Jesse has let us know that the way the File class works has changed since this tutorial was published. See his comment for more details on how to make your code compatible.)

Step 11: Saving the File

After we've moved the little circles around a bit, we can then save their location for further editing. Here we create our custom file. First we put coordinates into an array, then the arrays are put inside an object. The object is written to a file with our custom file extension. You can give it any extension you want.

After that, we set the app to be the default application for the newly created file extension.


private function saveClick(event:Event):void
		{
			var file:File = File.desktopDirectory
			file.browseForSave("Save");
			file.addEventListener(Event.SELECT, onSaveSelect);
		}
		private function onSaveSelect(event:Event):void
		{
			var object:Object = {};
			var redArray:Array = [red.x, red.y];
			var blueArray:Array = [blue.x, blue.y];
			object.RED = redArray;
			object.BLUE = blueArray;
			var saveFile:File = File(event.target);
			var directory:String = saveFile.url
			if(directory.indexOf(".tuts") == -1)
			{
				directory += ".tuts";
			}
			var file:File = new File();
			file = file.resolvePath(directory);
			var fileStream:FileStream = new FileStream();
			fileStream.open(file, FileMode.WRITE);
			fileStream.writeObject(object);
			fileStream.close();
			NativeApplication.nativeApplication.setAsDefaultApplication("tuts");
		}

Step 12: Opening the File

If you want to open your newly created file, simply click the "Open" button. A dialog box appears that looks only for that file extension. The app will then read the object inside the file and places the little circles accordingly.


private function openClick(event:MouseEvent):void
		{
			var file:File = File.desktopDirectory;
			file.addEventListener(Event.SELECT, onSelect);
			file.browseForOpen("Open",[new FileFilter("Tuts Files (*.tuts)", "*.tuts")]);
		}
		private function onSelect(event:Event):void
		{
			var file:File = File(event.target);
			var fileStream:FileStream = new FileStream();
			fileStream.open(file, FileMode.READ);
			var object:Object = fileStream.readObject();
			red.x = object.RED[0];
			red.y = object.RED[1];
			blue.x = object.BLUE[0];
			blue.y = object.BLUE[1];
			fileStream.close();
		}

Step 13: Invoking the App

This is the invoke function. Without this function, if you were to launch the application from your new file, it wouldn't know to load it. This function checks to see what told it to open. If it was a file, then it will load that file. If it wasn't, then it simply calls the "init" function which gives the circles a random placement.


private function onInvoke(event:InvokeEvent):void
		{
			if(event.currentDirectory != null && event.arguments.length > 0)
			{
				var directory:File = event.currentDirectory;
				var file:File = directory.resolvePath(event.arguments[0]);
				var fileStream:FileStream = new FileStream();
				fileStream.open(file, FileMode.READ);
				var object:Object = fileStream.readObject();
				red.x = object.RED[0];
				red.y = object.RED[1];
				blue.x = object.BLUE[0];
				blue.y = object.BLUE[1];
				fileStream.close();
			} else
			{
				init();
			}
		}

Step 14: The Publish Settings

When the file is all tested and working correctly, we are ready to publish. Go to Commands > AIR - Application and Installer Settings, and bring up the publish settings.

Step 15: Setting up the Custom File Extension

In the Air publish settings, click on the advanced settings.

It will bring up another dialog box. Click on the "plus" button to add a file extension.

Fill out the file descriptions, select your custom icons, and click "OK" until you're back to the first publish settings window.

Step 16: Publish Your File

The last thing to do is to publish your file. Click on the "Publish AIR File" button. You will need to create a certificate to sign the app with. Simply click "Create" to bring up the settings.

Fill out the form and click "OK". Flash will prompt you when the certificate is created. When the certificate is made, enter the password and your file will be created.

Conclusion

This was just a basic example of what can be done with this technique. You could also create some kind of drawing application where you could either save out what you've drawn, or keep editing it. Or if you wanted to create a custom MP3 player, and have your own playlist file format. The possibilities are endless..

I hope you enjoyed following the tut.