AIR application start-up options
Requirements
Prerequisite knowledge
General experience building HTML-based applications is suggested. For more details on getting started with this Quick Start, refer to Building the Quick Start sample applications with HTML.
User level
Intermediate
Required products
Sample files
The StartupOptions sample application, shown in Figure 1, demonstrates the following options on starting up an AIR application:
- How to register an application to be the default application for a file type
- How to set an application to start up automatically when the user logs in to the operating system
- What to do if the application was started up by the user double-clicking a document associated with the application
Note: This is a sample application provided, as is, for instructional purposes.
Testing the application
To test this application, follow these steps:
- Install the application from the AIR file. (Testing the application in ADL will limit some functionality.)
- Run the application.
Each time you invoke the application, the InvokeEvent log provides details of the InvokeEvent event (described later in this article).
- If the Register application to open foo files check box is not selected, select it.
This application uses the "foo" file extension as a registered file type.
- Select the Start at login check box.
- Type some text in the File contents text box.
- Click the Save document button, select a file name and location for the document, and click the Save button.
This saves a file of type "foo."
- Close the application.
- Double-click the document you saved in step 6.
- Close the application and log off of the operating system.
- Log into the operating system.
The application starts up at system login.
Understanding the code
Note: For more information about using AIR classes, see the Adobe AIR API Reference for HTML Developers. For information on using the AIR HTML Localizer Framework, see the "Localizing AIR applications" chapter in Building Adobe AIR Applications.
Registering a file type for the application
The application descriptor file of the application, application.xml, includes a fileType element. This element defines options for a file type that can be associated with the application:
<fileType>
<name>AIR.sample.file</name>
<extension>foo</extension>
<description>AIR start-up sample application file</description>
<contentType>text/plain</contentType>
<icon>
<image16x16>icons/TestDocument_16.png</image16x16>
<image32x32>icons/TestDocument_32.png</image32x32>
<image48x48>icons/TestDocument_48.png</image48x48>
<image128x128>icons/TestDocument_128.png</image128x128>
</icon>
</fileType>
This lets the application register as the default application to open files with the "foo" file extension. The operating system uses the description text to describe "foo" files (if the AIR application is set as the default application). The contentType element defines the MIME type for the file. (In this application, the file is a plain text file.) The icon element defines PNG files to use as the icon for "foo" files. (These PNG files are included in the source directory, and they must be packaged in the AIR file.)
The user interface of the application includes a Register application to open foo files check box. The init() function of the JavaScript in the index.html file checks to see if the application is already registered as the default application for the foo extension. If it is, it selects and disables this check box:
if (air.NativeApplication.nativeApplication.isSetAsDefaultApplication("foo"))
{
cbFileReg.checked = true;
}
If the application is not the default handler for foo files, the setFileRegistration() function sets (or removes) the application from being the foo file handler, in response to the user clicking the Register application to open "foo" files check box:
if (cbFileReg.checked)
{
air.NativeApplication.nativeApplication.setAsDefaultApplication("foo");
}
else
{
air.NativeApplication.nativeApplication.removeAsDefaultApplication("foo");
}
When the user installs the AIR application, if there is no other file registered to handle files with the "foo" exension, the AIR application becomes the default "foo" file handler automatically.
Setting the application to launch when the user logs into the operating system
The setStartup() function is a handler for the change event of the Start at login (cbStartAtLogin) check box. It sets the startAtLogin property of the NativeApplication object, based on the check box setting.
air.NativeApplication.nativeApplication.startAtLogin = cbStartAtLogin.checked;
When the startAtLogin property is set to true, the application launches automatically when the user logs into the operating system. It is a good practice to provide the user with a option to decide whether to have your application start at login (if the application has this feature).
Saving a custom file type
The foo file format is really just a text file that uses the "foo" file extension. The newFile() function lets the user select a path for the file:
function newFile()
{
file.browseForSave("Save a document.");
file.addEventListener(air.Event.SELECT, saveFile);
}
Once the user selects the file path, the saveFile() function saves the file to the chosen location. The file data is written as a UTF-encoded text file. The file content is based on the text in the fileContents textarea object.
function saveFile(event)
{
if (file.extension != "foo")
{
file = new air.File(file.nativePath + ".foo");
}
var stream = new air.FileStream();
stream.open(file, air.FileMode.WRITE);
stream.writeUTFBytes(fileContents.value);
stream.close();
currentFile.value = file.nativePath;
}
Determing how the application was invoked
The init() function sets an event handler for InvokeEvent events:
air.NativeApplication.nativeApplication.addEventListener(air.InvokeEvent.INVOKE, invokeHandler);
The InvokeEvent handler function (invokeHandler()) writes information on the application invocation, based on the properties of the InvokeEvent object.
log.value += new Date().toTimeString() + ": InvokeEvent.reason == " + event.reason + "";
log.value += " InvokeEvent.arguments.length == " + event.arguments.length + "\n";
for (i = 0; i < event.arguments.length; i++)
{
log.value += " InvokeEvent.arguments[" + i + "] == " + event.arguments[i] + "\n";
}
if (event.arguments.length > 0)
{
openFile(event.arguments[0]);
}
Data is displayed in the log textarea object. If the application is launched by the user double-clicking the AIR application icon, the InvokeEvent log displays the following information:
InvokeEvent.reason == standard
InvokeEvent.arguments.length == 0
InvokeEvent.reason == login
InvokeEvent.arguments.length == 0
InvokeEvent.reason == standard
InvokeEvent.arguments.length == 1
InvokeEvent.arguments[0] == [file path]
In this final case, where the application was invoked by the user double-clicking a file, the operating system passes the file path as an argument to the AIR application. The first element of the NativeApplication object's arguments array is the path to the file. The openFile() function uses this information to open the file and display its contents in the fileContents object:
currentFile.value = path;
file = new air.File(path);
var stream = new air.FileStream();
stream.open(file, air.FileMode.READ);
fileContents.innerHTML = stream.readUTFBytes(stream.bytesAvailable);
stream.close();
