Accessing the AIR XML file descriptor through an AIR menu item with Flash CS4 (The Essential Guide to Flash CS4 AIR Development Highlight)

The Essential Guide to Flash CS4 AIR Development book is oriented to Flash developers interested in building desktop applications via Adobe AIR. You can order The Essential Guide to Flash CS4 AIR Development  on Amazon or buy it on local bookstore.

This is the fifth part of the series dedicated to AIR menus (Chapter 6 of the Essential Guide to Flash CS4 AIR Development). You can read the previous articles here:

• Creating AIR submenus for a native menu with Flash CS4 - Part 2 (The Essential Guide to Flash CS4 AIR Development Highlight)
• Creating AIR native menu with Flash CS4 - Part 1 (The Essential Guide to Flash CS4 AIR Development Highlight)
• Using the menuItemSelected() method with Flash CS4
• Working with AIR Application and Window menus 

We start assignig the menu to the main AIR  application. It will only contain one item: ‘App settings’ to which you will associate three elements with as many commands. These three elements will be constructed in the createFirstSubMenu() method . The following ActionScript code defines the createFirstSubMenu():

private function createFirstSubMenu():NativeMenuItem
{

Start by creating a local variable, subMenu , an instance of the NativeMenuItem class, which will be the return value of the method createFirstSubMenu() . When you create the NativeMenuItem object, you tell AIR which text label it will have (App settings in the following code). This NativeMenuItem child of the application menu will be a drop- down menu that contains some commands. To add these child elements to the following instance of the NativeMenuItem class , you have to instantiate an object of the NativeMenu class. This object will then be assigned to its subMenu property . The following code accomplishes
these tasks:

// create submenu
var subMenu:NativeMenuItem = new NativeMenuItem( "App settings" );
// initialize child container
subMenu.submenu = new NativeMenu();

Next, populate the submenu you’ve just created with three instances of the NativeMenuItem class. Then register a different event listener method on each of them for the selection event. Remember, to create an element of the menu, you generate an instance of the NativeMenuItem class. Then you tell the constructor method which label has to be associated with the object. At that point, register an event listener method for the Event.SELECT event . Finally, add the element you’ve created to the submenu. Do this through the addItem() method of the instance of the NativeMenu class, which is assigned to the subMenu property of the object of the NativeMenuItem class.

// create first child, register event listener for
// selection event and assign to submenu

var aboutCommand:NativeMenuItem = new NativeMenuItem( "About.." );
aboutCommand.addEventListener( Event.SELECT, getInformation );
subMenu.submenu.addItem( aboutCommand );

// create second child, register event listener for
// selection event and assign to submenu

var minimizeCommand:NativeMenuItem =
new NativeMenuItem( "Minimize" );
minimizeCommand.addEventListener( Event.SELECT,
minimizeApplication );
subMenu.submenu.addItem( minimizeCommand );

// create third child, register event listener for
// selection event and assign to submenu

var closeCommand:NativeMenuItem = new NativeMenuItem( "Close" );
closeCommand.addEventListener( Event.SELECT, closeApplication );

subMenu.submenu.addItem( closeCommand );
return subMenu;
}

All you have to do now is define the event listener functions you need for the selection events. Your menu will allow you to do the following:

1. Minimize the application
2. Close the application
3. Access the saved description in the XML configuration file of the AIR project

The closeApplication() method will call the immediate closure of the application and, consequently, all its open windows. To close the application, you use the exit() method of the static nativeApplication property of the NativeApplication class. The code follows:

// close application

private function closeApplication( e : Event ):void
{
NativeApplication.nativeApplication.exit();
}

To minimize the active window of the application, you launch the minimizeApplication() method , which uses the minimize() method of the instance of the NativeWindow class. Here’s the code:

// minimize application

private function minimizeApplication( e : Event ):void
{
stage.nativeWindow.minimize();
}

This is the complete ActionScript class that you’ve just created:

package com.comtaste.foed.essentialair.chapter6
{

import fl.controls.TextArea;
import flash.desktop.NativeApplication;
import flash.display.MovieClip;
import flash.display.NativeMenu;
import flash.display.NativeMenuItem;
import flash.display.NativeWindow;
import flash.events.Event;
import flash.filesystem.File;

public class Ch06p02 extends MovieClip
{
// onstage components
public var output:TextArea;
// class properties
private var menuRoot:NativeMenu;

public function Ch06p02()
{

super();
// generate native menu to use
createNativeMenu();
// assign to application menu if we are on Mac OS X
if ( NativeApplication.supportsMenu )
{
NativeApplication.nativeApplication.menu = menuRoot;
}
// assign to window menu if we are on Microsoft Windows
if ( NativeWindow.supportsMenu )
{
stage.nativeWindow.menu = menuRoot;
}
}

// create a complete native menu

private function createNativeMenu():void
{

// instantiate main menu object
menuRoot = new NativeMenu();
// append subMenus to menu root
menuRoot.addItem( createFirstSubMenu() );

}

private function createFirstSubMenu():NativeMenuItem
{

// create submenu
var subMenu:NativeMenuItem =
new NativeMenuItem( "App settings" );
// initialize child container
subMenu.submenu = new NativeMenu();
// create first child, register event listener for
// selection event and assign to submenu
var aboutCommand:NativeMenuItem =
new NativeMenuItem( "About.." );
aboutCommand.addEventListener( Event.SELECT, getInformation );
subMenu.submenu.addItem( aboutCommand );

// create second child, register event listener for
// selection event and assign to submenu
var minimizeCommand:NativeMenuItem =
new NativeMenuItem( "Minimize" );
minimizeCommand.addEventListener( Event.SELECT, minimizeApplication );
subMenu.submenu.addItem( minimizeCommand );
// create third child, register event listener for
// selection event and assign to submenu
var closeCommand:NativeMenuItem =
new NativeMenuItem( "Close" );
closeCommand.addEventListener( Event.SELECT,
closeApplication );
subMenu.submenu.addItem( closeCommand );
return subMenu;

}

// close application

private function closeApplication( e : Event ):void
{

NativeApplication.nativeApplication.exit();

}

// minimize application
private function minimizeApplication( e : Event ):void
{

stage.nativeWindow.minimize();

}
} // close class
} // close package

Accessing the AIR XML file descriptor

Through ActionScript 3, you can access the XML document used by AIR’s runtime to execute your application correctly. Flash CS4 generates the XML document in the authoring phase. In this document, you can see a lot of information regarding the application in execution. The document also includes the description of the application, if provided by the developer.

Flash CS4 provides a specific menu that allows you to create the XML configuration file of the application. You can access this menu through the Edit AIR Settings button on the Document Properties panel in the Flash project. You can see the menu in Figure 6-7. Among the various fields, there is a Description field where you can provide a description of the application that will be presented to the user when the application is being installed.

The XML document that is automatically generated by Flash CS4’s menus for the ch06p02.fla project is the following:

<?xml version ="1.0" encoding="utf- 8" ?>

<application xmlns="http://ns.adobe.com/air/application/1.0">

<id>com.adobe.example.ch06p02</id>
<version>1.0</version>
<filename>ch06p02</filename>
<description>
Application developed to test application
and windows menus for Adobe Air desktop
applications.
</description>
<name>ch06p02</name>
<copyright></copyright>
<initialWindow>
<content>ch06p02.swf</content>
<systemChrome>standard</systemChrome>
<transparent>false</transparent>
<visible>true</visible>

</initialWindow>
<customUpdateUI>false</customUpdateUI>
<allowBrowserInvocation>false</allowBrowserInvocation>
<icon>
</icon>
</application>

Calling the getInformation() method has the following effects:

It accesses the XML descriptor document.
It extracts the description.
It displays it in the output TextArea.

Here’s an example of the getInformation() method:

// called on click on menu item "About.."
private function getInformation( evt : Event ):void
{

The content of the XML descriptor fiIe of the application is stored in the applicationDescriptor property of the NativeApplication class . Assign the value of this document to a local XML variable, appDescriptor, as shown here:

// access to application XML descriptor
var appDescriptor:XML =
NativeApplication.nativeApplication.applicationDescriptor;

To be able to access the nodes of the XML document, first you have to know which XML namespace they’ve been defined in. You can access this information through the namespace() method of the XML class , as shown here:

// retrieve XML descriptor namespace
var nsDeclaration:Namespace = appDescriptor.namespace();

Now you have the content of the XML descriptor file of the application. You’ve also defined the XML namespace to access. Next, you can use the E4X syntax to extract the information you’re interested in.

E4X is a programming language extension that adds native XML support to ECMAScript (which ActionScript is based on). E4X provides a simpler syntax for accessing XML documents and treats XML as a primitive data type.

The form you use for the XML query is the following:

//<XML instance>.<namespace>::<node name>
// read description node from XML

var informationText:String =
String( appDescriptor.nsDeclaration::description[ 0 ] );

Finally, write the definition extracted from the XML descriptor file of the application in the output TextArea.

To wrap the text in the TextArea, use the AIR lineEnding variable of the File class instead of the ActionScript Unicode \n sequence. This variable correctly reports the native line ending for the local operating system. This will be useful if the text gets copied and pasted into an external text document. Here’s the code:

// write into textare 'output' description contents
output.appendText( "Adobe Air, test application for " +
"menus functionalities." + File.lineEnding );
output.appendText( informationText + File.lineEnding );
}

This is the final getInformation( ) method:

// called on click
private function getInformation( evt : Event ):void
{
var appDescriptor:XML =
NativeApplication.nativeApplication.applicationDescriptor;
var nsDeclaration:Namespace = appDescriptor.namespace();
var informationText:String =
String( appDescriptor.nsDeclaration::description[ 0 ] );
output.appendText( "Adobe Air, test application for " +
+ "menus functionalities." + File.lineEnding );
output.appendText( informationText + File.lineEnding );
}

Your application is finished and is ready to use. To do so, go back to Flash, and run the application by selecting the Test Movie command from the Control menu. If you’re working in a Microsoft Windows environment, your application will use a window menu and will look like Figure 6-8. If, on the other hand, you’re working in a Mac OS X environment, it will use an application menu, like all native Mac OS X applications.

In the next part of this series you'll learn how to create and populate context menus for AIR applications.

Comments

[oppopsaspix]

Si, probabilmente lo e

[ugg outlet]

Your article very interesting, I have introduced a lot of friends look at this article, the content of the articles there will be a lot of attractive people to appreciate, I have to thank you for such an article.

[الاندرويد]

i cant figure the xml file that way as you mention here