by Jeff Swartz

Jeff Swartz

Created

10 October 2011

Requirements
Prerequisite knowledge

General experience of building applications
with Flex Builder or the Flex SDK is
suggested. For more details on getting
started with this Quick Start, refer to
Building the Quick Start sample
applications with Flex
.
Required products

Sample files

User level

Intermediate
 
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
Figure 1. This sample application shows how to use various application start-up options.
 
Note: This is a sample application provided, as is, for instructional purposes.
 
This sample application includes the following files:
 
  • StartupOptionsFlex.mxml: The main application file in MXML for Flex; includes the code discussed in this article
  • StartupOptionsFlex-app.xml: The AIR application descriptor file
  • Sample AIR icon files

 
Testing the application

To test this application, follow these steps:
 
  1. Install the application from the AIR file. (Testing the application in ADL will limit some functionality.)
  2. Run the application.
    Each time you invoke the application, the InvokeEvent log provides details of the InvokeEvent event (described later in this article).
     
  3. 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.
     
  4. Select the Start at login check box.
  5. Type some text in the File contents text box.
  6. Click the Save document button, select a filename and location for the document, and click the Save button.
    This saves a file of type "foo."
     
  7. Close the application.
  8. Double-click the document you saved in step 6.
  9. Close the application and log off of the operating system.
  10. Log into the operating system.
    The application starts up at system login.
     

 
Understanding the code

Note: This article does not describe all of the Flex components used in the MXML code for the file. For more information, see the ActionScript 3 Reference for the Flash Platform.
 
 
Registering a file type for the application
The application descriptor file of the application, StartupOptionsFlex-app.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() method of the main MXML 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 (nativeApplication.isSetAsDefaultApplication("foo")) { cbFileReg.selected = true; cbFileReg.enabled = false; }
If the application is not the default handler for foo files, the setFileRegistration() method 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.selected) { nativeApplication.setAsDefaultApplication("foo"); } else { 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() method 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.
 
nativeApplication.startAtLogin = cbStartAtLogin.selected;
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 an 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() method lets the user select a path for the file:
 
private function newFile():void { file.browseForSave("Save a document."); file.addEventListener(Event.SELECT, saveFile); }
Once the user selects the file path, the saveFile() method 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 TextInput object.
 
private function saveFile(event:Event):void { if (file.extension != "foo") { file = file.parent.resolvePath(file.name + ".foo"); } var stream:FileStream = new FileStream(); stream.open(file, FileMode.WRITE); stream.writeUTFBytes(fileContents.text); stream.close(); currentFile.text = file.nativePath; }
 
Determing how the application was invoked
The init() function sets an event handler for InvokeEvent events:
 
nativeApplication.addEventListener(InvokeEvent.INVOKE, invokeHandler);
The InvokeEvent handler function (invokeHandler()) writes information on the application invocation, based on the properties of the InvokeEvent object.
 
log.text += new Date().toTimeString() + ": InvokeEvent.reason == " + event.reason + "\n"; log.text += " InvokeEvent.arguments.length == " + event.arguments.length + "\n"; for (var i:int = 0; i < event.arguments.length; i++) { log.text += " InvokeEvent.arguments[" + i + "] == " + event.arguments[i] + "\n"; } if (event.arguments.length > 0) { openFile(event.arguments[0]); }
Data is displayed in the log text field. 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
If the application is launched automatically when the user logs into the operating system, the InvokeEvent log displays the following information:
 
InvokeEvent.reason == login InvokeEvent.arguments.length == 0
If the application is launched when the user double-clicks a foo file (a file with the "foo" file extension), the InvokeEvent log displays the following information:
 
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() method uses this information to open the file and display its contents in the fileContents object:
 
itemFileOpened.enabled = true; currentFile.text = path; file = new File(path); var stream:FileStream = new FileStream(); stream.open(file, FileMode.READ); fileContents.text = stream.readUTFBytes(stream.bytesAvailable); stream.close();