Marco Casario | RIAvolutionize the web

Creating native menus dynamically in AIR with Flash CS4

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.

 

In the last tutorial you've learned how to create and access pop- up menus in AIR applications with Flash CS4.

The menus you’ve created in that examples so far have all been generated through predefined ActionScript code. If you wanted to change the label of an item on the menu, change the order of the items, or remove or add elements, you would have to recompile the Flash project. You would also have to generate a new installation file for the application, or provide an update, if the application supports updates.

When you’re developing real applications, it’s advisable to create applications that don’t need to be recompiled every time you make minor changes. If your user had to update the whole application (not just a few configuration files) every week or every month, you’d probably lose your audience quite quickly.

To avoid or at least limit these situations, you can extend the NativeMenu class . You can create a class that allows the menu items to be generated dynamically from an XML structure. Because native menus are hierarchal, it’s relatively easy to represent a native menu skeleton to an XML structure. Another advantage is the possibility of changing the localization

of the menu of the application by loading different XML documents.

First, you have to define the structure of the XML document so that each item on the menu is represented by a MenuItem node . The attributes of each node will define the properties to be assigned to the corresponding instance of the NativeMenuItem class that will be created. You can also embed MenuItem nodes in other MenuItem nodes to generate submenus.

A MenuItem node will have the following skeleton:

 

<MenuItem label="" isSeparator="" mnemonicIndex="" keyEquivalent="" name="" select="" />

 

The attributes provided allow you to define the structure and behavior of the corresponding menu items. Here is an analysis of the attributes:

label : This is the text label that will be assigned to the element, be it a command

or a submenu.

isSeparator : This is a Boolean value that specifies if the element will be a separator or not. If the value is true, the element will be a separator, so all other attributes will be ignored.

mnemonixIndex : This specifies the index that corresponds to the letter of the text label that is recognized as a shortcut key. You can use this shortcut when you are exploring the items on the menu with the keyboard arrows. This parameter can

only be applied in AIR projects with window and application menus.

 

keyEquivalent : This specifies the letter that will select an item on the menu when it’s pressed in conjunction with the Ctrl key on Windows or the Cmd key on Mac OS X. In order for this shortcut to work, the application has to be active and in the

foreground. This parameter can only be applied to window and application menus.

name : This is a unique ID that doesn’t depend on the localization of the element.

select : This is the name of the method that has to be called upon a selection

event. This attribute allows you to easily activate, deactivate, or change the functions

 

Creating and accessing pop- up menus in AIR applications with Flash CS4

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.

Reading my previous AIR tutorials, you’ve worked with menus that are associated with tangible elements of your applications,
such as the following:

• Context menus that are activated on objects on the stage
• Context menus associated with icons in the system tray or dock bar
• Menus associated with windows and menus of the application itself

AIR applications also allow you to create pop- up menus . These are native menus like all
the other ones you’ve seen so far—the only difference is that pop- up menus aren’t natively
associated with any element on the interface of the application. It’s up to the developer to
define and implement the logic and the way in which a pop- up menu can be activated. An
AIR application can have any number of pop- up menus.
You can show a pop- up menu anywhere on the stage. It can be activated in the following
ways: if the user clicks a button, if the mouse rolls over any object, if the user presses
a combination of keys, and on any other condition you want for your application.

Activating pop- up menus

The NativeMenu class has the display() method to activate a pop- up menu. Every time
this method is called, the pop- up menu appears at the specified coordinates. The display()
method requires the three following arguments:
Destination stage : Specifies which stage has to display the pop- up menu. If the
AIR application is on only one NativeWindow- type window, the destination stage is
automatically the window that displays the application. If you’re making a multiwindow
application, you will have to specify the stage of the window you want to
display the pop- up menu on.
Coordinate (X axis) : Specifies the position on the X axis of the pop- up menu. This
coordinate specifies the position from the top left corner of the menu. The coordinate
will apply to the stage you’ve specified as a first argument of the function.
Coordinate (Y axis) : Specifies the position on the Y axis where you want to display
the pop- up menu. This coordinate specifies the position from the top left corner of
the menu. The coordinate will apply to the stage you’ve specified as a first argument
of the function.

Creating Dock and System tray icon menus with AIR

Many applications offer context menus associated with the application’s icon. On Windows systems, these menus are located in the system tray. If you’re working on a Mac OS X system, you’ll find these menus in the dock bar. Generally, these menus have shortcuts for the most common functions of the application you’re using. These menus might also contain commands that must be accessible even when the application is minimized or hidden by the desktop.

The AIR runtime allows you to manage and interact with the system tray and dock bar icons of your application. You can define context menus for them. On Microsoft Windows systems, the icons in the system tray don’t have any default context menus, so unless you have a specially prepared menu to display, it won’t provide a context menu. Mac OS X systems, on the other hand, have a default menu for dock bar icons. The menus you create will be added to the default menu provided by the operating system. You can’t modify or remove the default menus provided by the system for dock bar icons.
The application you will create in the next section will run on both Windows and Mac OS X.

Assigning a menu to an application icon

Start by opening the ch06p04.fla file in Flash CS4. The project, like the previous ones, only has an output TextArea. This TextArea will display the messages regarding the status of your application.

The project, as shown in Figure 6-13, displays an icon in the system tray or dock bar of the local system, which is why a symbol has been prepared in the library. The symbol is a movie clip: Application Icon, which represents the way you want to show the application icon. In the Symbol Properties panel, shown in Figure 6-14, the class name of the symbol has been specified: ApplicationIcon . This class name allows you to instantiate the symbol in the library via ActionScript.

 
Figure 6-13. The stage and Library panel of the ch06p04.fla project

Figure 6-14. The Symbol Properties panel

You access the document class of the Flash project by clicking the Edit class definition icon on the Document Properties panel. Like for the other projects in this chapter, the Flash project has been set up to not declare the variables automatically  for the elements on the stage. You’ll have to specify them yourself in the class associated with the project.

The class starts by declaring the namespace and the dependence on external classes, as shown here:

package com.comtaste.foed.essentialair.chapter6
{
import fl.controls.TextArea;
import flash.desktop.DockIcon;
import flash.desktop.NativeApplication;
import flash.desktop.SystemTrayIcon;
import flash.display.BitmapData;
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 Ch06p04 extends MovieClip
{

Then you declare two class properties: one that refers to the component of the TextArea class on the stage of the project, and one to contain the native menu that the application will use:

// onstage components
public var output:TextArea;
// class properties
private var menuRoot:NativeMenu;

SWF Search Engine Optimization Technology Center

Following Serge Jesper's topic "SEO fo Flash works" I wanted to point it out the new Search Engine Optimization Technology Center. It's a great point of reference for anyone involved in RIA development using Flash and Flex (SWF format).

The SEO Technology Center helps explain what the challenges are and provides practical steps, examples, and best practices that you can follow to overcome them.

Creating native and non-native AIR context menu with Flash CS4

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 sixth 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
  
• Accessing the AIR XML file descriptor through an AIR menu item with Flash CS4
• Working with AIR context menus with Flash CS4

Context menus appear at the cursor when the user right- clicks (on Windows) or Ctrl- clicks (on the Mac). Contrary to Flash applications for the Web, AIR applications don’t offer any default context menus, so it’s up to the developer to create and populate context menus for the application if necessary.
Context menus can be created with two different ActionScript classes:

• The NativeMenu class
• The ContextMenu class

You can only use the NativeMenu class for AIR applications, whereas you can use the ContextMenu class for both AIR applications and those that have been created to be executed in a web environment with Flash Player.

To create a native context menu, you populate the nativeMenuRoot context menu . This menu belongs to the NativeMenu class, in the body of the reateNativeMenu() method in the Ch06p03.as class . Here’s the code:

// create a complete native menu
private function createNativeMenu():void
{

Next, assign an instance of the NativeMenu class to the nativeMenuRoot class property .You add two submenus as the first elements of the menu, which are respectively generated by the createFirstSubMenu() and createSecondSubMenu() methods . To add elements to the menu, you use the addItem() method of the NativeMenu class:

// instantiate main menu object
nativeMenuRoot = new NativeMenu();

// append subMenus to menu root
nativeMenuRoot.addItem( createFirstSubMenu() );
nativeMenuRoot.addItem( createSecondSubMenu() );

After the two submenus, you add a separator element to the menu. Remember, you have to create an instance of the NativeMenuItem class to add an item separator, and then you assign the true Boolean value as a second argument to the constructor of the class, as shown here:

// append item separator to root of menu
var itemSeparator:NativeMenuItem = new NativeMenuItem( "", true );
nativeMenuRoot.addItem( itemSeparator );

Finally, you add two more elements after the separator. These elements aren’t submenus, but selectable items, so you register an event listener method for the selection event on each of them. The items are instances of the NativeMenuItem class.

// append command directly to root of menu
var subCommand1:NativeMenuItem =
new NativeMenuItem( "subCommand 1" );
subCommand1.addEventListener( Event.SELECT, menuItemSelected );
nativeMenuRoot.addItem( subCommand1 );
// append another command directly to root of menu
var subCommand2:NativeMenuItem =
new NativeMenuItem( "subCommand 2" );
subCommand2.addEventListener( Event.SELECT, menuItemSelected );
nativeMenuRoot.addItem( subCommand2 );
}

The createNativeMenu() method uses the createFirstSubMenu() and create SecondSubMenu() methods to define its first two elements. These methods are similar to
the ones you used in the ch06p01.fla project to instantiate and populate the items of a native menu.

Working with AIR context menus 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 sixth 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
  
• Accessing the AIR XML file descriptor through an AIR menu item with Flash CS4

As mentioned at the beginning of this chapter, context menus appear at the cursor when the user right- clicks (on Windows) or Ctrl- clicks (on the Mac). Contrary to Flash applications for the Web, AIR applications don’t offer any default context menus, so it’s up to the developer to create and populate context menus for the application if necessary.
Context menus can be created with two different ActionScript classes:

• The NativeMenu class
• The ContextMenu class

You can only use the NativeMenu class for AIR applications, whereas you can use the ContextMenu class for both AIR applications and those that have been created to be executed in a web environment with Flash Player. The ContextMenu class is less flexible and offers fewer possibilities to developers, regardless of the fact that it extends the NativeMenu  class.
The ContextMenu class extends the NativeMenu class in AIR applications as well as in traditional Flash applications. The NativeMenu class can be used only for AIR applications. Now you can create an AIR application that uses both types of context menus.

Creating context menus

In this section, you will create native and nonnative context menus. Start by opening the ch06p03.fla project in Flash CS4. You’ll notice that the stage of the project contains the following two buttons, in addition to the output TextArea:

• nativeBtn
• contextBtn

Next, you’ll associate a different context menu with each button and use the TextArea as a console for the application. Open the document class that is associated with the Flash project by clicking the Edit class definition icon in the Document Properties panel. Figure 6-9 displays the stage of the application.

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();
}

Working with AIR Application and Window menus (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 fourth 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

When you interact with a desktop application, you’re used to using general menus that guide you and introduce you to the functions you can choose from. For example, if you’re using a word-processing program and you want to know which formats you can save the document in, you will almost definitely look for the Save as command from the File menu, without even thinking about it. Likewise, if you need to copy the selected text, you’ll look for the Copy command from the Edit menu. These operations are strongly embedded in every user that has experience with modern computers. Regardless of any previous knowledge about the program you’re working on, the menu bar will always be a safe haven where you can look for the commands and functions you need.
Some modern software applications have interfaces that mimic the standards of many web applications. These applications don’t have traditional menus—they only provide icons in the application, and these are sometimes difficult to interpret. When users access one of these programs for the first time, they may feel disoriented, and may not even understand how to start using the application.
AIR puts users at ease by supporting a traditional menu bar that guides them through the features of your application. As mentioned at the beginning of the chapter, there are two types of menus  for AIR applications: application menus (on Mac OS X systems) and window menus (on Microsoft Windows systems).
To know which type of menu you can use in your application, AIR provides the supportsMenu property in the NativeApplication class as well as in the NativeWindow class . These are Boolean properties and they show whether the menus are supported at the application or window level. To check if application- level menus are supported, you can use the following  code:

If( NativeApplication.supportsMenu == true )
{
// code to manage application menu
}
To check if window menus are supported, you can use the following:
If( NativeWindow.supportsMenu == true )
{
// code to manage windows menu
}

The procedure to create application menus is identical to the procedure for window menus. The only thing that changes is the object you need to assign the menus to and how the end user will use them.

Using the menuItemSelected() method 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 preorder The Essential Guide to Flash CS4 AIR Development  on Amazon or buy it on local bookstore starting from 22nd December.

This is the thrid 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)

Next, you’ll employ the menuItemSelected() method , which will be launched each time the user selects one of the items on the context menu. When a selection event is generated, the event listener method receives an instance of the flash.events.Event class as an argument. The selection events are transmitted by the selected element on the menu, through the hierarchical structure of the menu, to the root element.
The object received as an argument has the two following properties:

• target
• currentTarget

If the event has been registered directly on the elements of the menu (like in this case), the two properties will have the same value. In this case, both properties refer to the instance of the selected NativeMenuItem class . However, if the event is registered on the root menu or on one of the roots of the submenus, the target property of the received event object will always refer to the selected element. The currentTarget property will always refer to the object the event is registered on.

When an item is selected, the menuItemSelected() method writes the label of the selected element in the TextArea, which acts as a text output console. Here’s the code:

// called on click on menu items
private function menuItemSelected( evt : Event ):void
{
// access NativeMenuItem instance selected
var item:NativeMenuItem = evt.target as NativeMenuItem;
// write in the textarea selected item's label
output.appendText( "CLICKED ON: " + item.label + File.lineEnding );
}