When a file type is associated with your AIR application, then every associated file of that type will open itself in your AIR application. This gives you great opportunities to work with external files in your AIR application. Registering Custom File Types discusses how to register a file type with your AIR application.
Before you begin, you should note that you make associations for an AIR application when installing the application, not at compile or debug time. This means you can’t test file associations until you package and install your application. When your application is packaged, the application descriptor XML file is read, and the file associations are set. This is not automatically done if another application on the system is already the default application; in other words, the AIR application install process does not override an existing file type association. If you want to take over the association from another application, take a look at Setting and Removing an Application as the Default Application for a File Type.
You want to register a custom file type so that the operating system will associate it with your AIR application.
Use the fileTypes
element in
the application descriptor file to declare the file types associated
with your AIR application.
Associations between your application and a file type must be
declared in the application descriptor file. Depending on your
environment and compiler settings, this descriptor file is typically the
-app.xml file in your Adobe AIR
project, characterized by the application
root nodes. In that XML file, you
can manipulate, for example, the initial, minimum, and maximum width and
height; the initial position of your main AIR application window (see
Chapter 2); and the file type
associations.
An empty fileTypes
node in the
application descriptor file typically looks like this:
<fileTypes> <fileType> <name></name> <extension></extension> <description></description> <contentType></contentType> <icon> <image16x16></image16x16> <image32x32></image32x32> <image48x48></image48x48> <image128x128></image128x128> </icon> </fileType> </fileTypes>
For each file type you want to register, you need to define a
fileType
node in the fileTypes
element in your application
descriptor XML file. The name
and
extension
values are required, but
the description
and contentType
values are optional. The name
value is the name the system displays for
the registered file. The extension
is
the extension for the file (not including the preceding period). You can
use the same name
for multiple
extensions.
The description
is shown to the
user by the operating system user interface, such as when the user looks
at the file properties.
The contentType
property helps the operating system locate the best application to
open a file in some special circumstances, such as when the extension is
not recognized. The contentType
property is required
for any fileType
property defined in the application
descriptor file. The value of the contentType
node is the name of the MIME type
for the files.
MIME stands for Multipurpose Internet Mail Extensions, and MIME types form standard ways of classifying file types. You can find an overview of common MIME types and their corresponding file extensions at http://www.webmaster-toolkit.com/mime-types.shtml.
Last but not least, you can also specify an icon
for the file extension. The icon files
must be included in the AIR installation file because they are not
packaged automatically.
Setting an icon for the file extension is also optional. The path specified is relative to the installed AIR application root directory at runtime. Icon files must be in the PNG format, but you can specify different icon sizes. When all sizes are not provided, the closest size is scaled to fit for a given use of the icon by the operating system.
The following example shows a full fileTypes
node from an application descriptor
XML file:
<fileTypes> <fileType> <name>Example.myOwnFileType</name> <extension>koen</extension> <description>This is a custom fileType that has my name </description> <contentType>text/plain</contentType> <icon> <image16x16>KOEN16.PNG</image16x16> <image32x32>KOEN32.PNG</image32x32> <image48x48>KOEN48.PNG</image48x48> <image128x128>KOEN128.PNG</image128x128> </icon> </fileType> </fileTypes>
According to the previous fileTypes
node, if the user double-clicks a
file called file.koen, then the
associated AIR application will launch.
To retrieve the path to the specific file, you need to
write a handler function for the InvokeEvent
object dispatched by the NativeApplication
object. The NativeApplication
object represents the AIR
application, and it can dispatch application-level events. If you want
to open the file, you can use that specific path.
When the AIR application is invoked a second time, another instance of the application is not started. Instead, the first instance receives an additional invoke event.
If your AIR application is already running when the user
double-clicks the associated file, AIR will immediately dispatch the
InvokeEvent
object to the running AIR
application.
The following code illustrates how your AIR application can handle an invoke event dispatched by the runtime when an associated file is opened:
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" applicationComplete="init()" > <mx:Script > <![CDATA[ private function init():void{ this.nativeApplication.addEventListener(InvokeEvent.INVOKE,invokeHandler); } private function invokeHandler(event:InvokeEvent):void{ pathLabel.text = event.arguments[0]; } ]]> </mx:Script> <mx:Label id="pathLabel" x="86" y="97" text="" fontSize="15"/> </mx:WindowedApplication>
The following code shows how your AIR application can handle the invoke event that is dispatched by AIR when an associated file is opened:
<html > <head> <title>Recipe 14.1: File association</title> <script src="AIRAliases.js" type="text/javascript"></script> <script type="text/javascript"> function init(){ air.NativeApplication.nativeApplication.addEventListener (air.InvokeEvent.INVOKE,invokeHandler); } function invokeHandler(event){ document.getElementById("textOutput1").innerHTML = event.arguments[0]; } </script> </head> <body onLoad="init()"> <div id="textOutput1">...</div> </body> </html>
You want to check whether an AIR application is (still) the default application for a given file type on the user’s computer.
Use the isSetAsDefaultApplication
method from the
NativeApplication
class.
The AIR application installer does not override existing file associations, and file associations on a user’s system can change at any time (for example, when another program is installed). The best practice, therefore, is to verify that the expected file associations are in place when your application starts.
To determine whether an AIR application is the default application
for a file type, you have to check the Boolean
return value from the isSetAsDefaultApplication
method. This method
is part of the NativeApplication
object that represents the AIR application.
The following code implements this little check mechanism. This code is placed into a function that is executed when the application is completely loaded:
private function init():void{ if (NativeApplication.nativeApplication.isSetAsDefaultApplication("koen"){ // *.koen files are already associated with this AIR app }else{ //ask user to associate *.koen files with this AIR app } }
The following code implements this little check mechanism. This code is placed into a function that is executed when the application is completely loaded:
function init(){ if (air.NativeApplication.nativeApplication.isSetAsDefaultApplication("koen"){ // *.koen files are already associated with this AIR app }else{ //ask user to associate *.koen files with this AIR app } }
Use the setAsDefaultApplication
or removeAsDefaultApplication
method
from the NativeApplication
class.
AIR applications can manage associations for the file types that were originally declared in the application descriptor file (Registering Custom File Types). Even if a user has manually created an association between a file type and your AIR application, trying to set it as the default application will result in a runtime exception.
Suppose you declared a file type association in the descriptor file but the association is broken because another installed application took over the association. Because you originally defined the association, you can now set your AIR application as the default application.
To do this, you call the setAsDefaultApplication
method and pass the
file type extension as a parameter. This is a method of the nativeApplication
object that represents the
AIR application.
In the same way, you can remove an existing file type association
by using the removeAsDefaultApplication
method.
The following code shows how removeAsDefaultApplication
and setAsDefaultApplication
work. By using these
two file type management methods, you can make sure your AIR
application is always able to open the right files.
To set your AIR application to the default application for a file type, use the following code:
this.nativeApplication.setAsDefaultApplication("koen");
To remove your AIR application as the default application for a file type, use the following code:
this.nativeApplication.removeAsDefaultApplication("koen");
In Getting the Path of the Default Application for a File Type you can see a full ActionScript example that also shows these two file type management methods.
The following code shows how removeAsDefaultApplication
and setAsDefaultApplication
work. By using these
two file type management methods, you can make sure your AIR
application is always able to open the right files.
To set your AIR application as the default application for a file type, use the following code:
air.NativeApplication.nativeApplication.setAsDefaultApplication("koen");
To remove your AIR application as the default application for a file type, use the following code:
air.NativeApplication.nativeApplication.removeAsDefaultApplication("koen")
In Getting the Path of the Default Application for a File Type you can see a full JavaScript example that also shows these two file type management methods.
You want to know the path of the default application that is currently associated with a given file type.
Use the getDefaultApplication
method from the NativeApplication
class.
If you want to know the path to the application that is associated
with a given file type, you can pass the extension of that file type to
the getDefaultApplication
method from
the nativeApplication
object.
In ActionScript, to get the path of the default application, use the following code:
var path:String = this.nativeApplication.getDefaultApplication("koen");
In JavaScript, to get the path of the default application, use the following code:
var path = air.NativeApplication.nativeApplication.getDefaultApplication("koen");
Keep in mind, however, that this function works only on file types that are defined in the application descriptor file.
The following code combines all the recipes from this chapter in one example:
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
layout="vertical" applicationComplete="init()">
<mx:Script>
<![CDATA[
private const FILE_EXTENSION:String = "acbtest";
private function init():void
{
trace("[ch14] app init : start");
this.nativeApplication.addEventListener(
InvokeEvent.INVOKE,
invokeHandler);
textOutput1.text = "nativeApplication.isSetAsDefaultApplication : " +
this.nativeApplication.isSetAsDefaultApplication(FILE_EXTENSION);
textOutput2.text = "File.applicationDirectory.nativePath : " +
File.applicationDirectory.nativePath;
if (this.nativeApplication.isSetAsDefaultApplication(FILE_EXTENSION))
{
// remove the association
this.nativeApplication.removeAsDefaultApplication(FILE_EXTENSION)
}
else
{
//set this app as default
this.nativeApplication.setAsDefaultApplication(FILE_EXTENSION);
}
textOutput3.text = "nativeApplication.isSetAsDefaultApplication : " +
this.nativeApplication.isSetAsDefaultApplication(FILE_EXTENSION);
textOutput4.text = "nativeApplication.getDefaultApplication : " +
this.nativeApplication.getDefaultApplication(FILE_EXTENSION);
}
private function invokeHandler(event:InvokeEvent):void
{
trace("[ch14] invokeHandler : " + event.arguments[0]); // trace the path
}
]]>
</mx:Script>
<mx:Label id="textOutput1" />
<mx:Label id="textOutput2" />
<mx:Label id="textOutput3"/>
<mx:Label id="textOutput4" />
</mx:WindowedApplication>
The following is the JavaScript:
<html> <head> <title>AIRCookbook CH14</title> <script src="AIRAliases.js" type="text/javascript"></script> <script type="text/javascript"> var FILE_EXTENSION = "koen"; function init() { air.trace("[ch14] app init : start"); air.NativeApplication.nativeApplication.addEventListener( air.InvokeEvent.INVOKE, invokeHandler); document.getElementById("textOutput1").innerHTML = "nativeApplication.isSetAsDefaultApplication : " + air.NativeApplication.nativeApplication.isSetAsDefaultApplication(FILE_EXTENSION); document.getElementById("textOutput2").innerHTML = "air.File.applicationDirectory.nativePath : " + air.File.applicationDirectory.nativePath; if (air.NativeApplication.nativeApplication.isSetAsDefaultApplication(FILE_EXTENSION)) { // remove the association air.NativeApplication.nativeApplication.removeAsDefaultApplication(FILE_EXTENSION) } else { //set this app as default air.NativeApplication.nativeApplication.setAsDefaultApplication(FILE_EXTENSION); } document.getElementById("textOutput3").innerHTML = "nativeApplication.isSetAsDefaultApplication : " + air.NativeApplication.nativeApplication.isSetAsDefaultApplication(FILE_EXTENSION); document.getElementById("textOutput4").innerHTML = "nativeApplication.getDefaultApplication : " + air.NativeApplication.nativeApplication.getDefaultApplication(FILE_EXTENSION); } function invokeHandler(event) { air.trace("[ch14] invokeHandler : " + event.arguments[0]); // trace the path } </script> </head> <body onload="init();"> <div id="textOutput1">...</div> <div id="textOutput2">...</div> <div id="textOutput3">...</div> <div id="textOutput4">...</div> </body> </html>