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.

The code looks like this:

private function createFirstSubMenu():NativeMenuItem
{

// create first submenu
var subMenu:NativeMenuItem = new NativeMenuItem( "My first custom submenu" );

// initialize child container
subMenu.submenu = new NativeMenu();

// create first submenu child
var subMenuItem1:NativeMenuItem = new NativeMenuItem( "menu 1 item 1" );

// register event listener for menu item
subMenuItem1.addEventListener( Event.SELECT, menuItemSelected );

// add item to submenu
subMenu.submenu.addItem( subMenuItem1 );

// create a second child, register event listener for
// selection event and assign to submenu
var subMenuItem2:NativeMenuItem = new NativeMenuItem( "menu 1 item 2" );
subMenuItem2.addEventListener( Event.SELECT, menuItemSelected );
subMenu.submenu.addItem( subMenuItem2 );

return subMenu;
}

private function createSecondSubMenu():NativeMenuItem
{
// create first submenu
var subMenu:NativeMenuItem =
new NativeMenuItem( "Second submenu" );

// initialize child container
subMenu.submenu = new NativeMenu();

// create first submenu child
var subMenuItem1:NativeMenuItem =
new NativeMenuItem( "menu 2 item 1" );

// register event listener for menu item
subMenuItem1.addEventListener( Event.SELECT, menuItemSelected );

// add item to submenu
subMenu.submenu.addItem( subMenuItem1 );

// add a separator item
// label will be ignored for separator items
var subMenuSeparator:NativeMenuItem =
new NativeMenuItem( "", true );

// add separator to menu
subMenu.submenu.addItem( subMenuSeparator );

// create a second child, register event listener for
// selection event and assign to submenu
var subMenuItem2:NativeMenuItem = new NativeMenuItem( "menu 2 item 2" );
subMenuItem2.addEventListener( Event.SELECT, menuItemSelected );
subMenu.submenu.addItem( subMenuItem2 );

// create a new item as an internal submenu
// using addSubmenu command
var childSubMenu:NativeMenuItem =
subMenu.submenu.addSubmenu( new NativeMenu(), "Nested menu" );

// initialize child container
childSubMenu.submenu = new NativeMenu();

// create a child, register event listener for
// selection event and assign to internal submenu
var subMenuItem3:NativeMenuItem =
new NativeMenuItem( "menu 2 nested item 1" );
subMenuItem3.addEventListener( Event.SELECT, menuItemSelected );
childSubMenu.submenu.addItem( subMenuItem3 );
return subMenu;

}

The two methods create two submenus. For each of the selectable items on the context menu, you register the menuItemSelected() method as an event listener for the SELECT event of the Event class . The event listener method accesses the instance of the NativeMenuItem class. The latter generates the selection event through the target variable of the instance of the Event class it receives as an argument of the method. Through the reference to the instance of the NativeMenuItem class , you access the text label of the element—the label property of the NativeMenuItem class. You write the text label in the body of the output TextArea on the stage of the Flash project. The following code accomplishes these tasks:

// called on click on native menu items
private function menuItemSelected( evt : Event ):void
{
var item:NativeMenuItem = evt.target as NativeMenuItem;
output.appendText( "NATIVE MENU CLICKED ON: "
+ item.label + File.lineEnding );
}

The menuItemSelected() method completes the steps that are required to create, populate, and make the native context menu assigned to the nativeBtn button work.

Nonnative context menus

The constructor method of the Ch06p03.as class contains the createContextMenu() method. You must execute this method in order to instantiate and populate the context menu that uses the ContextMenu class . Menus that are based on instances of the ContextMenu class have fewer functions than native menus that are based on the NativeMenu class.
The instances of the ContextMenu class can’t contain submenus, only top- level elements.
Furthermore, the selection events aren’t retransmitted to the root of the menu from the selected elements through the hierarchical structure, so you have to register the event listener functions straight on the single items. Because there can’t be any submenus, no display event is generated for the items that instantiate the ContextMenu class. The following code opens the createContextMenu() method :

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

Next, assign an instance of the ContextMenu class to the contextMenuRoot variable to initialize the context menu that the contextBtn button will use:

// initialize context menu
contextMenuRoot = new ContextMenu();

Create an instance of the ContextMenuItem class . This will be the first element on the context menu you’re creating. You assign a text label to the object when you instantiate the ContextMenuItem class.

// create first item
var item1:ContextMenuItem = new ContextMenuItem( "First Item" );

Register an event listener method for the new item on the menu. When the user selects the item, it will execute the contextMenuItemSelected() method . The instances of the ContextMenuItem class don’t generate an Event.SELECT event when they’re selected, but a ContextMenuEvent.MENU_ITEM_SELECT event .

// register event listener for menu item
item1.addEventListener( ContextMenuEvent.MENU_ITEM_SELECT, contextMenuItemSelected );

Remember that the ContextMenu class extends the NativeMenu class . But it would be wrong to use the inherited methods to add child items to the menu. If you use native methods like addItem() , for example, the menu could be rendered wrong or not work properly.
The ContextMenu class requires its items to be added or removed via the customItems property . This property is an instance of the Array class that lists the instances of the ContextMenuItem class that will be displayed on the menu. Here’s an example of the customItems property:

// add item to context menu
contextMenuRoot.customItems.push( item1 );

In native menus, you’ve seen how to create elements that act as separators between various groups of items. Menus based on the ContextMenu class can also contain item separators. Unlike the NativeMenuItem class , the ContextMenuItem class allows you to define both the separator and the following item in the same instance. As with the NativeMenuItem class, to create an item separator, follow these steps:

1. Assign the true Boolean value to the constructor method as a second argument.
2. Create a new item for the context menu.
3. Specify that an item separator will have to come before the item itself.
4. Register the selection event for this item on the contextMenuItemSelected() event listener method, like you did for the first item on the context menu.
5. Add the item under the customItems array of the instance of the ContextMenu class you’re working on.

The following code accomplishes these tasks:

// create a separator
var itemSeparator:ContextMenuItem =
new ContextMenuItem( "second Item with separator before", true );

// register event listener for menu item
itemSeparator.addEventListener( ContextMenuEvent.MENU_ITEM_SELECT,
contextMenuItemSelected )

// add item to context menu
contextMenuRoot.customItems.push( itemSeparator );
}

To complete the class, and therefore the application, you have to define the contextMenuItemSelected() event listener method. The method acts like the
menuItemSelected() method —the only difference is that the event object it receives is an instance of the ContextMenuEvent class . Furthermore, its target property is a reference to an instance of the ContextMenuItem class instead of an object of the NativeMenuItem class .

Each time an element of the context menu based on the ContextMenu class is selected, its label will be written in the body of the output TextArea.
The following code completes the class:

// called on click on context menu items
private function contextMenuItemSelected( evt : ContextMenuEvent ):void
{
var item:ContextMenuItem = evt.target as ContextMenuItem;
output.appendText( "CONTEXT MENU CLICKED ON: "
+ item.label + File.lineEnding );
}

Now you’re ready to compile and test your application. To do so, go back to the ch06p03.fla project and start the compilation by selecting the Test Movie item from the Control menu, as shown in Figure 6-10.

Figure 6-10. The command to compile and test the movie

Now try interacting with the application by right- clicking (on Windows) or Ctrl- clicking (on the Mac) on the two buttons. When you click, the context menus should appear at the cursor.
Finally, try selecting different items to display the selection messages in the TextArea. You can see what the two context menus look like on Microsoft Windows XP in Figures 6- 11 and 6- 12:

Comments

[Buveyoga]

To study your own phrases over a day comprising such it is a fantastically important delight

[Laserto]

well, it has been the third time I visit your website. I can just feel quite comfortable to read article here. You are always the best!
http://www.laserto.com/

[MBT Shoes]

Never heard of that before, but thanks for opening up my eyes.