Requirements
Prerequisite knowledge
This article is designed to give you an overview of the samples files. Although templates are provided to simplify the process, you will need to have a basic understanding of ActionScript, Flash components, and working with XML to take full advantage of the resources provided here.
Required products
Adobe Animate CC CS4 Adobe AIR
Sample files
AIR_Components.mxp (3237 KB)
AIR_ComponentSamples.zip (1795 KB)
AIR_BrowserProject.zip (763 KB)
User level
Intermediate

The Adobe AIR runtime has opened up the world of desktop applications to Flash Professional developers. In my own experience I've seen a need for the unique features of AIR when developing applications for e-learning and social networking sites. The challenge in these situations is that we often need a browser, but we don't want the navigation features or open environment of the standard browsers we use from day to day.
 
To address this challenge, we've developed a series of AIR components for Flash CS4 that can be used to manipulate the AIR ActionScript APIs, and built custom browser prototypes. The components are designed to speed up the development process and introduce the use of XML data sources to aide in creating a standard workflow in Flash Professional.
 
This article provides an overview of the AIR components extensions and the sample AIRBrowser application developed by Dave Gonzalez and myself (see Figure 1). Along the way you'll review a fully developed AIR application, learn about AIR concepts in Flash CS4, and walk away with the component package and workflow used to develop the application.
 
The AIR Browser application
Figure 1. The AIR Browser application
 
Note: Special thanks to our art director Bryan Purse for his design and illustration contributions to the AIR samples project!
 

 
Exploring the sample files and component workflow

The focus of this article is the sample browser application and the process that made it unique to developing it in Flash CS4. Before you dive into the browser sample, it will be helpful to understand the ins and outs of the Flash extensions package used to create the supplied files.
 
Refer to this page for information on how to navigate the sample files and use the AIR component extensions for your own work.
 
This section discusses the following topics:
 

 
Understanding the supplied files

The three files supplied with this article will allow you to install the AIR component extensions into Flash CS4, run simple example files demonstrating the components, and view a full-scale application project built from the extensions.
 
The following sections provide a quick inventory of what's.
 
 
MXP extensions installer (AIR_Components.mxp)
The MXP file installs the AIR components and supporting files into your Flash CS4 application interface. The installation includes:
 
  • AIR components (8)
    • AIRConextMenu
    • AIRFileManager
    • AIRNativeMenu
    • AIRNativeWindow
    • HTMLChrome
    • HTMLFooter
    • HTMLHeader
    • HTMLPane
  • FLA templates (2)
    • AIR Browser.fla
    • AIR Components.fla
  • ActionScript package
  • Custom actions (API list in Actions panel)
 
Components sample files (AIR_ComponentsSamples.zip)
The component samples include six FLA files demonstrating how the components work. These samples are focused on the basic usage of the components and are easier to reference than the full application sample. The ZIP file includes:
 
  • Sample_AIRContextMenu.fla
  • Sample_AIRFileManager.fla
  • Sample_AIRNativeMenu.fla
  • Sample_AIRNativeWindow.fla
  • Sample_HTMLChrome.fla
  • Sample_HTMLPane.fla
 
Sample application files (AIR_BrowserProject.zip)
The sample application folder includes a working AIR browser application that implements the AIR components. Beyond being a usable sample as presented, the source files are provided so that you may customize and expand upon the work. The ZIP file includes:
 
  • app-storage folder
    • catalog folder (storage for local content)
    • config folder (stores configuration XML)
    • help (stores help content)
    • images (stores image content)
    • Error.html
    • Start.html
    • TypeError.html
  • com folder (ActionScript package)
  • AIRBrowser.air (application installer)
  • AIRBrowser.fla (source file)
  • AIRBrowser.swf (exported file)
  • AIRBrowser-app.xml (descriptor file)
  • self_signed.p12 (temporary certificate)
Note: All sample files require Flash CS4 and AIR 1.5 to function properly.
 

 
Installing the AIR_Components.mxp file

The first thing to do is to install the AIR Component extensions for Flash CS4. The MXP file format works with the Adobe Extension Manager which is automatically installed when you load Flash onto your computer.
 
Follow these steps to install the extensions:
 
  1. First make sure that you have Flash CS4 Professional on your computer. The Extension Manager utility was automatically installed when you installed Flash CS4 Professional.
  2. Download the AIR_Components.mxp file and double-click it to launch the Extension Manager. Accept the prompts to install the extension.
  3. Launch Flash CS4 and check out the following locations where the extensions where placed:
    • File > New > Templates > AIR Components menu
    • Components panel
    • Actions panel
    • Global class packages
  4. Check out the new components by opening the Components panel from the Windows menu. Notice the new category called AIR Components containing eight components (see Figure 2).
The AIR Components category in the Flash CS4 Components panel
Figure 2. The AIR Components category in the Flash CS4 Components panel
 
  1. Select File > New > Templates to check out the supplied FLA templates (see Figure 3). Note the two template options available. One template is set up with the browser sample whereas the other one is blank but ready for development.
The New from Template dialog box showing the two supplied templates
Figure 3. The New from Template dialog box showing the two supplied templates
 
  1. Check out the component ActionScript API listed in the Actions panel under the AIR Components folder (see Figure 4). Open the Actions panel and note the AIR Components folder at the bottom of the classes list on the left (expand the classes list if necessary).
The AIR Components API listing installed into the Actions panel
Figure 4. The AIR Components API listing installed into the Actions panel
 
Note that the editable ActionScript package is installed in the Configuration > Classes folder in your Flash CS4 user settings folder as well.
 
You can manage and remove the extensions by running the Extension Manager again (Help > Manage Extensions). If you need to disable, update, or remove extensions in Flash CS4, use this route to do so.
 

 
Creating a pre-configured AIR file using the supplied templates

To gain full access to the extension features in Flash CS4, you have to do two things; create an AIR FLA file and set its ActionScript classpath to the LocalData path. The easiest way to accomplish this is by using the supplied templates available from the File > New command.
 
Follow these steps to open a supplied FLA template file:
 
  1. After you've installed the AIR Components.mxp extension, you can open a supplied template from the File > New command.
  2. Open Flash CS4 and choose the File > New command. In the New Document dialog box, select the Templates tab and then select the AIR Components category (see Figure 3).
  3. Choose the AIR Browser template and press OK.
    The FLA template opens with pre-populated content on the Stage and in the Library.
     
  4. Change the publish properties to AIR 1.5 format first. The FLA template is provided in the ActionScript 3.0 format so that the file associations defined in the AIR Settings properties will be unique to your project file.
  5. Choose File > Publish Settings. Click the Flash tab and choose Adobe AIR 1.5 from the Player menu. Click OK.
  6. Save the file with a unique name. Publishing to the AIR format exports a couple of different files so it's usually a good idea to save the FLA into a folder set aside for your project.
  7. Run the Test Movie command to see the default template in action.
  8. Check out the supplied code on the actions layer. You can experiment by adding your own code to the mix.

 
Creating a manually configured AIR file

You may also convert any existing FLA into the correct configuration by adjusting its publish settings properties.
 
Follow these steps to manually configure a FLA file:
 
  1. First make sure you're working in an ActionScript 3.0 file. You can't convert an ActionScript 2.0 FLA file into an AIR FLA file.
  2. Open the Publish Settings dialog box for the FLA by choosing File > Publish Settings.
  3. In the Formats tab of the dialog box, deselect the publish HTML option as you won't need it.
  4. Click the Flash tab and switch the Player menu to Adobe AIR 1.5.
  5. Finally, click the Settings button next to the Script menu to launch the Advanced ActionScript 3.0 Settings dialog box. Click the plus icon and enter the generic path ( $(LocalData)/Classes ) to the Classes folder inside your user configuration files (see Figure 5). This step gives the FLA file access to the ActionScript package installed by the Extension Manager into Configuration folder's Classes folder.
The FLA file's Publish Settings and Advanced ActionScript 3.0 Settings dialog boxes
Figure 5. The FLA file's Publish Settings and Advanced ActionScript 3.0 Settings dialog boxes
  1. Click OK in each dialog box to accept the changes. You're now ready to add components to the file.
  2. Save the file.
You can open the ActionScript package by browsing to your Flash CS4 Configuration folder. The location is different depending on your operating system. The path looks like this on my Windows XP machine:
 
C:\Documents and Settings\Dan Carr\Local Settings\Application Data\Adobe\Flash CS4\en\Configuration\Classes\com
For more information on configuration folder locations, see the ActionScript Publish Settings documentation.
 

 
Adding AIR components to your file

After your file is configured correctly, you're ready to start working with the components. The workflow is simple; you either open a supplied template where the components are already in the library, or you drag components from the Components panel to the Library panel in your FLA. Once the components are in the Library, you can implement them using ActionScript.
 
Follow these steps to add a component to your FLA file:
 
  1. Follow one of the routes above for configuring the FLA file.
  2. If the components are not already in the Library, open the Components panel and drag the components you want to use to your FLA file's Library.
  3. When using the HTML UI components, you drag them to the Stage and place them as desired. When using the native OS components, you can either drag them to the Stage to create an instance or you can directly import the class in ActionScript and use the new keyword to create the instance.
  4. Next steps will usually include naming the instances on the Stage and then setting up ActionScript code to initialize the components and catch events from user interaction. You can add code to the Timeline (as demonstrated in the AIR components sample FLA files), or add code to an ActionScript class (as demonstrated in the AIR Browser sample FLA).
  5. Save the file.
Tip: If you're using the AIRNativeMenu component, you'll want to set the Stage size to 800 × 620. The layout is designed for an 800 × 600 frame, but the native menu offsets the graphics downward by 20 pixels.
 

 
Reviewing the component sample files

Now that you're up to speed on the layout of the files, take a few minutes to explore the component examples in the AIR_ComponentsSamples.zip file.
 
Follow these steps to explore the sample files:
 
  1. Download and unzip the AIR_ComponentsSamples.zip file.
  2. Open each of the six sample files in Flash CS4.
  3. Take a look at the ActionScript code located on the actions layer on frame 1 of the main Timeline.
  4. Take a look in the Library to see the files which the component uses. (In the cases where the Library is empty, notice where the component is explicitly imported in the ActionScript to create the instance.)
  5. Run the Controls > Test Movie command to see the AIR APIs in action.
At this point you've explored the extensions that compose the core of the sample files. Understanding the components is an important step as they are the building blocks for all the elements in the application. They add consistency in the approach and help to speed the workflow along.
 
See the AIR components API section for more details on programming with the supplied files.
 
Next you'll explore the structure of the browser application.
 

 
Exploring the AIR browser sample application

The original idea for the sample project was to create a focused navigation browser for e-learning and social networking applications. Often in e-learning development there is a need to browse to the Internet for content without being able to navigate outside of the intended set of pages. Beyond that, e-learning developers creating SWF content often want to disable all navigation in the browser so that the navigation can exist in the movie in a specialized way.
 
The AIR browser application is intended to be a proof of concept addressing this topic. This implementation allows the developer to define a fixed set of URLs which the browser may navigate to. The user can navigate anywhere that the target content will allow and can bookmark pages of interest along the way.
 
The application is intended to show how a browser can be configured with a fixed range of navigation to create focus on a task or a topic. In this case, the sample content is focused on resources for developing with AIR in Flash CS4 Professional. The browser name, theme, and target content can be configured as desired.
 
This section describes how the browser application works and how you can modify the supplied files to create own version.
 
This section discusses the following topics:
 

 
Previewing the application

You can preview the AIR Browser application by running the supplied FLA file in Flash CS4 or by installing the AIR application using the AIRBrowser.air file. To get the full effect the end user will see, start by installing the AIR application.
 
Follow these steps to explore the project folder:
 
  1. Download and unzip the AIR_BrowserProject.zip file.
  2. Open the AIR_BrowserProject folder and double-click the AIRBrowser.air file to launch the AIR install badge.
  3. Click through the installation prompts until the application is successfully installed on your computer.
  4. Browse to launch the application through your applications menu. On startup you should see the default start page for the browser. Click the menu in the location bar to select a destination or use the View > Go to menu for navigation.
  5. Click the bookmark button in the header to save a bookmark. View your saved bookmarks in the Bookmarks menu.
  6. Select View > Full Screen (F11) to toggle the browser into full screen view.
  7. Select Help > Contents and Index (F1) to launch the help window.
  8. Choose File > Exit to quit all windows when you're ready.
As you explore the browser interface you'll notice that it implements many of the features that you use in your browser from day to day. The big difference is that the experience is focused on a specific set of content.
 
The following table provides a quick breakdown of features accessible through the menu.
 
Table 1. AIR Browser features
 
File Open Allows you to browse and open an HTML, XML, or SWF file. Shows the type error page if the selected file is an unsupported type.
Close Closes the current page and shows the start page.
Print Prints the page.
Import Imports the bookmarks or catalog XML file, adds the items to the menu, and saves the file in the application storage directory. Currently this feature overwrites the existing bookmarks or catalog XML definition.
Export Exports the bookmarks or catalog XML list to a location on the desktop.
Exit Closes all windows and exits the application
Bookmarks Add Adds the current page to the bookmarks list.
Remove Removes the current page from the bookmarks list (if it exists in the list).
Saved list Display a list of saved bookmarks (duplicates are allowed).
View Location Toggles the visibility of the location bar.
Status Toggles the visibility of the status bar.
Go To List Submenu (see Go To feature below)
Stop Stops the current page from loading.
Reload Reloads the current page.
Full Screen Toggles full screen mode.
Go To Back Navigates backward in the page history.
Forward Navigates forward in the page history.
Home Navigates to the first page in the catalog list.
URL List Displays the catalog list of navigable links.
Help Contents and Index Displays a popup window containing the help document defined in the settings XML file.
About Us Displays a popup window containing the about us image defined in the settings XML file.

 
Reviewing the project folder

The AIR_BrowserProject folder contains the files that define the configuration, text localization, and content for the browser. While I'm developing the project, I work with the source files in this folder and use them to publish the AIR installer. The project folder's structure mirrors the structure of the installed application folder.
 
Follow these steps to explore the project folder:
 
  1. Return to the AIR_BrowserProject folder.
    Note that the root folder structure includes the com ActionScript package, the AIRBrowser.fla file, and all the other source files necessary to publish the AIR file (see Figure 6). If you work with the source files in this way, the FLA file can automatically see the ActionScript package next to it and does not require a special classpath configuration. In this case you simply make sure the FLA file is set to publish to the AIR 1.5 format.
     
The root folder of the AIR browser application project
Figure 6. The root folder of the AIR browser application project
 
  1. Open the com folder and drill down into the subfolders to explore the contents of the ActionScript package.
  2. Go back to the root folder and open the app-storage folder to see the application configuration files (see Figure 7). Explore the folders to check out the content.
The app-storage folder containing the browser's configuration files
Figure 7. The app-storage folder containing the browser's configuration files
 
  1. Go back to the root folder and double-click the AIRBrowser.fla file to open it in Flash CS4 (see Figure 8).
The workspace of the AIRBrowser FLA file
Figure 8. The workspace of the AIRBrowser FLA file
 
Take a look at the main Timeline and the Library panel. Note that the Timeline doesn't contain any ActionScript code. This is because the application code is defined in an ActionScript class assigned as the document class of the FLA file.
 
  1. Click the outer bounds of the Stage outside the canvas area to show the Document properties in the Properties inspector. Note the classpath entered into the Class field in the inspector panel (see Figure 9).
The Document properties for the AIRBrowser FLA file
Figure 9. The Document properties for the AIRBrowser FLA file
 
  1. Click the pencil icon next to the classpath to open the AIRBrowser.as file in Flash CS4. Take a moment to explore the code. The majority of it is event handler functions that process events from the AIR components.
That's it for the source file preview. Next you'll look at how you can modify them.
 

 
Modifying the browser application

If you simply want to use the existing browser implementation without coding changes, you can modify a range of files in the app-storage/config folder.
 
Follow these steps to modify the application configuration files:
 
  1. Open the settings.xml file in Dreamweaver or another text editor. The settings file is used to store general application preferences, file path references, and text labels for localization.
  2. Edit the <title> node to change the title of the browser at the top of the window.
  3. Edit the <useTitleOnChrome> node to enable or disable the title in the window chrome.
  4. Edit the file path references and label references as desired in the remaining XML nodes.
  5. Save the file.
  6. Open the catalog.xml file in Dreamweaver. The catalog file contains a list of URLs that control the navigation of the browser. The catalog list appears in the location bar and in the View > Go To menu. The first item in the list is considered the "home" page.
  7. Add and remove <item> nodes as desired. See the NativeMenu XML Format section for details on formatting.
  8. Save the file.
  9. Open the bookmarks.xml file in Dreamweaver. The bookmarks file allows you to install an initial set of bookmarks if you choose to. Make sure to leave this file in the config folder even if you choose to delete all initial bookmark elements in the XML string.
  10. Add and remove <item> nodes as desired.
  11. Save the file.
  12. Open the menu.xml file in Dreamweaver. The menu file controls the native menu at the top of the browser window. You'll make modifications to this file to add and remove elements from the menu. For example, the ability to import and export catalog files may be undesirable. If so, simply delete that section of the menu XML file.
You can also modify the branding of the browser by changing the skins in the HTML UI components.
 
Follow these steps to change the branding of browser:
 
  1. Open the AIRBrowser.fla file from the project folder in Flash CS4.
  2. Double-click the graphics on the Stage that you want to edit. Keep clicking until you get down into the editing area containing the editable vector graphics. Change the graphics as desired.
  3. Return to the main Timeline and test the file. The layout code in the HTML UI component classes should be able to accommodate for changes to the graphics, but you may need to open the ActionScript source files for each HTML UI component to tweak the layout code as needed.
  4. Go through the Library and update the graphics as desired. Test the movie consistently as you go to make sure the edits are working without adverse effects on the layout.
  5. Save the file when you're done.
Lastly you can edit the default HTML pages and image content to change the personality of the browser.
 
Follow these steps to change the default HTML pages and image content:
 
  1. Open the Error.html and TypeError.html files (from the app-storage folder) in Dreamweaver. The error file appears when an error occurs with a page loading in the HTMLPane. The type error file appears when you try to open an unsupported file type in the browser. Edit the files as desired and save when finished.
  2. Open the Start.html file in Dreamweaver. The start file appears when the browser first launches and when the File > Close command is triggered. Update the file with your graphics and text and save when finished.
  3. Open the images in the app-storage/images folder and edit as desired. If you change the names of the files, make sure to update the paths in your HTML and XML files wherever references to the images occur.
By editing the files that configure the application you can create a range of looks for the browser matching whatever the needs of your target audience/content are.
 

 
Publishing the modified application

After you've made edits to the source files, you need to publish the project into an AIR installer file for distribution.
 
Note: The file path references to the icons, self-signed certificate, and app-storage items are saved with the absolute paths of the computer I developed the files on. You'll need to reset these paths in the AIR – Application & Installer Settings dialog box before publishing the file again.
 
Follow these steps to publish the modified project
 
  1. Start by configuring the AIR Settings properties. Select File > AIR Settings to launch the AIR Application & Settings dialog box (see Figure 10).
The AIR Settings dialog box
Figure 10. The AIR Settings dialog box
 
  1. Before publishing the file, update the general description information as desired. Click the Set Icon Images button to adjust the image paths or add your own icons. Click the Advanced Settings button to adjust the layout settings of the initial window. And finally click the plus and minus icons to adjust the paths of included content (make sure the paths are configured for your computer and not mine).
  2. To publish the file you'll need to click the Change button next to the Digital signature field. A digital signature is a certificate from a certificate authority (like VeriSign) that signs the installer as being trusted content supplied by you. During the installation process the user can see that the application is supplied by a trusted entity, which confirms that the installer file has not been maliciously changed since being distributed by its creator. The sample file uses a self-signed certificate that allows the publishing process to occur during testing, but presents the user with warnings during the installation process. You can create your own self-signed certificate in the Digital Signature dialog box by clicking the Create button (see Figure 11), or you can browse for the supplied self_signed.p12 file in the project folder. If you use the supplied file, the password is dcd.
The Digital Signature dialog box
Figure 11. The Digital Signature dialog box
 
Tip: You should always use a digital certificate purchased for your business when publishing your application for public use. Using a self-signed certificate is fine for creating sample files and prototyping. For more information on digital signatures, refer to the article Digitally signing Adobe AIR applications or Code signing in Adobe AIR by Oliver Goldman.
 
  1. Click OK to close the dialog box and accept any prompts that pop up related to messages about the Timestamp feature (they are irrelevant for a self-signed file).
  2. Back in the Application and Settings dialog box, click the Publish AIR File button to export the installer. You should see a dialog box pop up with a success message when complete.
Tip: If the process didn't work, it's most likely because there's a problem with the descriptor file or location of one of the included assets. Make sure your icons are PNG images located in a folder in the root of the application directory and make sure the file path to the app-storage folder is correct.
 

 
Including local content in the AIR installer

Another approach to using this implementation of the browser is to include the content in the AIR installer so that it gets installed locally along with the application. This might be handy if you're distributing a collection of PDF or web content for offline use.
 
Follow these steps to publish the local content with the browser:
 
  1. Gather your content and place it into organized folders within the app-storage/catalog folder. Note the paths and file names of the files that will act as the index (primary navigation link) for each folder.
  2. Open the catalog.xml file (from the app-storage/config folder) in Dreamweaver, and replace the URLs in the <item> nodes with updated relative paths to the content in the catalog folder (that is, instead of entering http://www.mysite.com/lesson1/lesson_1.pdf, enter the relative path to a file like app-storage/catalog/lesson1/lesson_1.pdf). Make sure the relative paths will work for the OS of your target audience. Note that you can use the AIR URL schemes to create relative paths to content in the local sandbox; for example, using the prefix app: creates a relative path to the application installation directory.
  3. Save all the files and publish the AIR installer from Flash CS4. The app-storage folder containing the content is already included in the files to be published. Test the installer and tweak your installation as needed until you're happy with the results.
Note: You can also use the AIR installer as a means to update and version installations of the browser application and accompanying content. Creating a routine for updating the installation will be necessary if you need to change the target content over time. For more information on using the AIR application update process, refer to the articles Using the Adobe AIR update framework and Tips for building AIR applications that can be easily updated.
 

 
AIR components API

The whole point of working with components is to provide a foundation of reusable building blocks which can be leveraged across different projects. In this case, Dave and I built a series of simple components which form a browser in Flash CS4.
 
The component set includes the following controls and user interface elements:
 
Native OS Controls HTML UI Controls
AIRContextMenu
AIRFileManager
AIRNativeMenu
AIRNativeWindow
HTMLChrome
HTMLFooter
HTMLHeader
HTMLPane
This section lists the ActionScript APIs and notes for the eight component files.
 

 
Working with the ActionScript APIs

All components in the extension package extend MovieClip and therefore inherit the MovieClip API. The component package falls under these general specifications:
 
Language Version: ActionScript 3.0
Runtime Version: AIR 1.5
 
In most cases the components accept input and respond with events. The general workflow when using the components is to create a script that initializes data and then responds to events to create a meaningful experience.
 

 
Native OS controls

The native OS controls provide shortcuts for manipulating the AIR runtime APIs. This functionality is useful as the runtime figures out the correct relative local paths and OS chrome depending on the computer viewing the application. Menus and windows look familiar to users, Mac uses Mac chrome and Windows uses Windows chrome.
 
The following components are used to manipulate native OS controls.
 
 
AIRContextMenu
Package: com.dancarrdesign.utils
Inheritance: AIRContextMenu > AIRNativeMenu > AIRComponent > MovieClip
 
The AIRContextMenu class provides an XML-driven implementation of a single menu AIRNativeMenu, and applies it to the contextMenu property of any display object.
 
Properties
baseMenu : NativeMenu
 
Read-only. Returns a reference to the base menu item from which all other menus spawn. You can use this reference to access the menus through the standard NativeMenu API.
checkItems : Object
 
Read-only. Returns an associative list of NativeMenuItems activated with a checkable state.
menus : Array
 
Read-only. Returns a list of all menus in the control.
source : XML
 
Sets the source of the menus using an XML definition. See the NativeMenu XML Format section below for more information.
Methods
addMenu(src:XML) : void
 
Adds a NativeMenu to another NativeMenu based on an XML definition object.
addMenuItem(src:XML) : void
 
Adds a NativeMenuItem to a NativeMenu based on an XML definition object.
getMenuByName(name:String) : NativeMenu
 
Returns the NativeMenu object by name.
toggleCheck(menu:String, item:String, state:Boolean): void
 
Toggles the checked state of an item in a menu.
toggleEnabled(menu:String, item:String, state:Boolean) : void
 
Toggles the enabled state of an item in a menu.
Events
select
 
Dispatched when a menu item is selected. Returns an item property with the event object. The item property contains the XML definition of the item.
Please see the NativeMenu class for more information on the related AIR APIs.
 
 
AIRFileManager
Package: com.dancarrdesign.utils
Inheritance: AIRFileManager > AIRComponent > MovieClip
 
The AIRFileManager class provides a simple way to read and write XML files to the local file system.
 
Properties
fileData : XML
 
Holds the imported XML data from the last call made to the load method. Use this property to retrieve the data.
Methods
load(path:String, folder:uint=0, async=true) : void
 
Loads the specified file from a relative path on the local file system.
resolvePath(path:String, folder:uint=0) : File
 
Closes the window. Relative folder paths are represented using integers in the AIRFileManager. 0 - application storage directory
1 - application directory
2 - desktop directory
3 - documents directory
4 - user directory
save(src:*,path:String, folder:uint=0, async=true) : void
 
Saves the src value to a file in a relative path on the local file system.
saveAbsolute(src:*, path:String, async=true) : void
 
Saves the src value to a file located at a supplied absolute path..
Events
complete
 
Dispatched when the file finishes loading (only active when the asynchronous mode is turned off.
Please see the File class for more information.
 
 
AIRNativeMenu
Package: com.dancarrdesign.utils
Inheritance: AIRNativeMenu > AIRComponent > MovieClip
 
The AIRNativeMenu class provides an XML-driven implementation of a native OS menu bar.
 
Properties
baseMenu : NativeMenu
 
Read-only. Returns a reference to the base menu item from which all other menus spawn. You can use this reference to access the menus through the standard NativeMenu API.
checkItems : Object
 
Read-only. Returns a list of NativeMenuItems activated with a checkable state.
Menus : Array
 
Read-only. Returns a list of all menus in the control.
Source : XML
 
Sets the source of the menus using an XML definition. See the NativeMenu XML Format section below for more information.
Methods
addMenu(src:XML) : void
 
Adds a NativeMenu to another NativeMenu based on an XML definition object.
addMenuItem(src:XML) : void
 
Adds a NativeMenuItem to a NativeMenu based on an XML definition object.
getMenuByName(name:String) : NativeMenu
 
Returns the NativeMenu object by name.
toggleCheck(menu:String, item:String, state:Boolean): void
 
Toggles the checked state of an item in a menu.
toggleEnabled(menu:String, item:String, state:Boolean) : void
 
Toggles the enabled state of an item in a menu.
Events
select
 
Dispatched when a menu item is selected. Returns an item property with the event object. The item property contains the XML definition of the item.
Please see the NativeMenu class for more information on the related AIR APIs.
 
 
AIRNativeWindow
Package: com.dancarrdesign.utils
Inheritance: AIRNativeWindow > AIRComponent > MovieClip
 
The AIRNativeWindow class provides a utility for spawning native windows with content loaded by an HTTPLoader or a Loader object.
 
Properties
popupAlign : String = "middleCenter"
 
Sets the window's alignment. Options include; topLeft, topCenter, topRight, middleLeft, middleCenter, middleRight, bottomLeft, bottomMiddle, and bottomRight. Alignment is relative to the screen.
popupHeight : Number - 550
 
Sets the window's height.
popupWidth : Number = 400
 
Sets the window's width.
popupX : Number = 0
 
Sets the window's × location on the screen.
popupY : Number = 0
 
Sets the window's Y location on the screen.
source : String = ""
 
Sets the source URL to be loaded into the window.
title : String = ""
 
Sets the title of the window.
useHTTPLoader : Boolean = true
 
Causes the component to either load the source URL using the HTTPLoader (by default) or the Loader object.
windowOptions : NativeWindowInitOptions = {}
 
Sets the window init options object. See NativeWindowInitOptions documentation for more information.
Methods
activate() : void
 
Opens the window. Set your window properties before calling this method.
close() : void
 
Closes the window.
layout(width:Number, height:Number, align:String):void
 
Causes the window to lay out as specified.
loadHTTP(src:String):void
 
Loads a file using the HTTPLoader in ActionScript.
loadFile(src:String) : void
 
Loads a file using the Loader object in ActionScript.
Events
complete
 
Dispatched when the windows finishes loading content.
Please see the NativeWindow class for more information on the related AIR APIs.
 
Note: The native OS controls don't contain any graphics. They create their visual representation by manipulating the native OS controls.
 

 
HTML UI Controls

The HTML UI controls provide a template for building browser interfaces (see Figure 12). Ultimately they solve a number of challenges when working with the AIR APIs.
 
A diagram showing the anatomy of the HTML UI components
Figure 12. A diagram showing the anatomy of the HTML UI components
 
 
HTMLChrome
Package: com.dancarrdesign.html
Inheritance: HTMLChrome > AIRUIComponent > AIRComponent > MovieClip
 
The HTMLChrome class creates a scalable frame around the edge of the native window.
 
Properties
contextMenuSource : XML
 
Creates an AIRContextMenu for the header when set with the NativeMenu XML Format for context menus. Context menus are activated when a user right-clicks on the object containing the menu.
innerBounds : Rectangle
 
Inner measurements of the chrome frame.
innerHeight : Number = 0
 
Inner height of the frame.
innerWidth : Number = 0
 
Inner width of the frame.
innerX : Number = 0
 
Inner × location of the frame.
innerY : Number = 0
 
Inner Y location of the frame.
toolTipText : String
 
Creates a tooltip control which hovers over the object on roll over.
Methods
setSize(width:Number, height:Number) : void
 
Sets the size of the frame and resets the bounds measurements.
 
HTMLFooter
Package: com.dancarrdesign.html
Inheritance: HTMLFooter > AIRUIComponent > AIRComponent > MovieClip
 
The HTMLFooter class creates a status bar at the bottom of the native window.
 
Properties
contextMenuSource : XML
 
Creates an AIRContextMenu for the header when set with the NativeMenu XML Format for context menus. Context menus are activated when a user right-clicks on the object containing the menu.
settings : XML
 
XML settings data containing localized text labels for the status message.
status : Number = 0
 
Read-only. Returns the status state. state = 0 // waiting
state = 1 // done
state = 2 // error
toolTipText : String
 
Creates a tooltip control which hovers over the object on roll over.
Methods
clearStatus()
 
Clears the status message.
setSize(width:Number, height:Number) : void
 
Sets the size of the status bar.
setStatus(state:uint, msg:String) : void
 
Sets status message using a localized prefix: state = 0 // waiting
state = 1 // done
state = 2 // error
showLoadingAnimation(b:Boolean):void
 
Shows or hides the loading animation.
 
HTMLHeader
Package: com.dancarrdesign.html
Inheritance: HTMLHeader > AIRUIComponent > AIRComponent > MovieClip
 
The HTMLHeader class creates a scalable location bar at the top of the native window.
 
Properties
contextMenuSource : XML
 
Creates an AIRContextMenu for the header when set with the NativeMenu XML Format for context menus. Context menus are activated when a user right-clicks on the object containing the menu.
settings : XML
 
XML settings data containing localized text labels for the tooltips.
toolTipText : String
 
Creates a tooltip control which hovers over the object on roll over.
Methods
setButtonState(name:String, state:Boolean):void
 
Sets the enabled state of a button based on button name. Recognized values currently include; back and forward.
setLocation(loc:String) : void
 
Sets the text in the location bar field.
setSize(width:Number, height:Number) : void
 
Sets the size of the location bar.
Events
back
 
Dispatched when the back button is clicked.
bookmark
 
Dispatched when the bookmark button is clicked.
cancel
 
Dispatched when the cancel button is clicked.
forward
 
Dispatched when the forward button is clicked.
home
 
Dispatched when the home button is clicked.
reload
 
Dispatched when the reload button is clicked.
 
HTMLPane
Package: com.dancarrdesign.html
Inheritance: HTMLPane> AIRUIComponent > AIRComponent > MovieClip
 
The HTMLPane class creates a scalable scrollable HTML window.
 
Properties
contextMenuSource : XML
 
Creates an AIRContextMenu for the header when set with the NativeMenu XML Format for context menus. Context menus are activated when a user right-clicks on the object containing the menu.
host : HTMLLoader
 
Read-only. Returns a reference to the ComboBox instance in the header. You can use the reference to gain full access to the ComboBox API.
historyPosition : uint
 
Read-only. Current position in the page history.
historyLength : uint
 
Read-only. Total length of the page history.
loaded : Boolean = false
 
Read-only. Flag notifying whether a page has loaded yet or not.
location : String = ""
 
Read-only. The URL of the current page in String format.
source : String
 
Loads a new URL into the HTML pane. Used as a simple authortime parameter.*
timeoutLimit : Number = 30
 
Sets the timeout limit for the page. If a page request fails to load within this time limit, a timeOut event is dispatched.
toolTipText : String
 
Creates a tooltip control which hovers over the object on roll over.
Methods
Cancel():void
 
Cancels the current page from loading.
getHistoryAt(i:uint):HTMLHistoryItem
 
Returns a step in the page history in HTMLHistoryItem format.
historyBack():void
 
Navigates back in the page history.
historyForward():void
 
Navigates forward in the page history.
historyGo(i:uint):void
 
Navigates to a specified index in the page history.
load(src:String):void
 
Loads a new URL into the HTML pane.
refresh():void
 
Reloads the current page.
setSize(width:Number, height:Number) : void
 
Sets the size of the HTML area.
Events
boundsChange
 
Dispatched when the bounds of a page changes.
complete
 
Dispatched when a new page has completed loading.
locationChange
 
Dispatched when a new page is requested/
timeOut
 
Dispatched when a page fails to load after the timeoutLimit has been exceeded.
unhandledException
 
Dispatched when an unhandled JavaScript exception occurs.
* Note that the HTMLPane can be used in a very simple way as an authortime component. You can add the HTMLPane to the stage, open the Component Inspector panel, and enter a URL into the source field to assign the page to load. The HTMLPane component doesn't contain any navigation features. What you see is what you get, but it is worthy to note that a new user without ActionScript experience can fire up an HTML window in a Flash CS4 AIR file.
 
Refer to the HTMLLoader class for more information on the related AIR APIs.
 
Note: You can open the ActionScript package implementing these APIs by browsing to your Flash CS4 Configuration folder or the com folder in the AIR_BrowserProject folder.
 

 
NativeMenu XML format

The XML format implemented by the AIRNativeMenu and AIRContextMenu mirrors the ActionScript API for the NativeMenuItem object. The components are basically adaptors which parse the XML menu descriptions into the ActionScript API and paint the OS features to the screen.
 
In addition to managing the XML data source, the components provide a simple event structure where the XML description for each menu node is returned in the event during a selection. This allows for a quick and easy way to interpret menu generated events.
 
 
XML for AIRNativeMenus
The AIRNativeMenu creates a menu bar at the top of the window chrome (file, edit, view, and so on). The XML structure represents the menu bar by starting with a <menus> root node followed by any number of <menu> nodes. Each menu in the menu bar can have any number of regular items, submenu items, checkable items, disabled items, and separator items.
 
The following sample shows the XML that generates a simple menu bar:
 
<menus> <menu> <name>file</name> <label>File</label> <items> <item> <name>file_open</name> <label>Open</label> <keyEquivalent>o</keyEquivalent> <keyEquivalentModifier> CONTROL,COMMAND </keyEquivalentModifier> </item> <item> <isSeparator>1<isSeparator> </item> <item> <name>file_close</name> <label>Close</label> <keyEquivalent>w</keyEquivalent> <keyEquivalentModifier> CONTROL,COMMAND</keyEquivalentModifier> </item> </items> </menu> <menu> <name>view</name> <label>View</label> <items> <item> <name>view_fullScreen</name> <label>Full Screen</label> <keyEquivalent>f</ keyEquivalent> <keyEquivalentModifier> CONTROL,COMMAND </keyEquivalentModifier> </item> </items> </menu> </menus>
Note that the <menu> nodes contain three elements; name, label, and items. The <name> field is an ID that can be used for manipulating the menu in the AIRNativeMenu instance. The <label> field is the text that appears in the menu bar activator buttons. The <items> field holds a list of NativeMenuItems used to create the drop-down functionality for the menu.
 
Property Comments
name Name or ID of the menu. This value can be used as a key to help identify the node when it's part of a select event.
label The label that appears in the native menu.
items A list of NativeMenuItems described in XML format.
The <items> node contains a list of any number of <item> nodes. The configuration of the <item> nodes determines what kind of item is displayed in the menu. You basically have three options; regular item, submenu activator item, or separator item.
 
<item> <name>file_open</name> <label>Open</label> <enabled>1</enabled> <checked/> <isSeparator/> <keyEquivalent>o</keyEquivalent> <keyEquivalentModifiers>CONTROL,COMMAND</keyEquivalentModifiers> <menu/> <data> <url></url> </data> </item>
The <item> field contains nine properties which you can use to configure the state of each menu item.
 
Property Comments
name Name or ID of the menu. This value can be used as a key to help identify the node when it's part of a select event.
label The label that appears in the native menu.
checked Setting the <checked> field to 1 shows a check on the menu item. Setting the item to 0 activates the item as a being checkable, but doesn't show a check. Leaving this field empty disables the check feature for the item.
isSeparator Set the <isSeparator> field to 1 to activate the item as a separator line. In this case, all other values are ignored.
keyEquivalent
Set the <keyEquivalent> field to the hotkey shortcut you'd like to see appear next to the label. Use a lower case letter to represent only the letter. Use an upper case letter to represent SHIFT + [letter].
 
Note: AIR 1.5 supports single-digit keyEquivalent characters in the form of a letter. All other values will be ignored by the AIRNativeMenu component (including number keys, function keys, arrow keys, and the Esc key).
 
keyEquivalentModifier Set the <keyEquivalentModifer> field to a comma-separated list containing any combination of COMMAND, CONTROL, or ALTERNATE to associate the related modifier with the label and hotkey. (Note that the key features are purely for visual effect in the menu. You have to assign a KeyboardEvent listener to the stage to activate keyboard-driven shortcuts in the application.
menu Set this field to the <menu> XML format to nest a submenu as a menu item.
data Enter any data which you like in the <data> field. You can retrieve this data when you catch the select event from the menu. The sample file currently uses the data field to store a URL value for bookmark and catalog items.
The <name> and <label> fields are required, but you can use the other fields as needed.
 

 
XML for AIRContextMenus

The AIRContextMenu creates a context menu when you right-click on an item. A context menu is basically the same as a native menu except that there is only one menu appearing from an anchor point (click). Note that each AIRUIComponent subclass in the package contains a contextMenuSource property which accepts the XML format and creates a context menu on the object.
 
The XML format for a context is the same as the <items> field in the native menu format:
 
<items> <item> <name>open</name> <label>Open</label> <keyEquivalent>o</keyEquivalent> <keyEquivalentModifier>CONTROL,COMMAND </keyEquivalentModifier> </item> <item> <isSeparator>1<isSeparator> </item> <item> <name>close</name> <label>Close</label> <keyEquivalent>w</keyEquivalent> <keyEquivalentModifier>CONTROL,COMMAND </keyEquivalentModifier> </item> </items>
Note: The keyboard modifiers represented in the XML format are visually rendered in the native menu, but the Keyboard listeners have to be built separately in ActionScript.
 

 
Where to go from here

This set of samples demonstrates the possibilities of combining the Flash component workflow with the AIR ActionScript APIs. Although the AIR components are powerful, they provide foundation-level functionality for each feature. Our goal was to create a workflow for quickly prototyping AIR interfaces in Flash Professional. The next logical step will be to expand upon this foundation with new features and flexibility within the code package.
 
Spend some time exploring the code package that generates the component features and try to add some of your own ideas.
 
Here are some other resources you may find useful: