Using MXML for AIR NativeMenus

NativeMenus for AIR have been somewhat of a pain since each item in a menu can take 3-4 lines of code or more to write once you add the listener, the key shortcuts, etc. Then when you’ve got 20 items or so you have an unreadable unmanageable mess to deal with. Very unFlexy. So I set about making it work in MXML with the advantages of readability, conciseness, and don’t forget bindability. This makes it a much cleaner solution than a component which creates a commonly used menu or using XML data providers to define the menus.

First I created a Menu class which extends NativeMenu. Because of the way MXML works we will need to set our menu’s items in one go rather than using the addItem and addItemAt methods. So I created an items setter to complement the items getter which is part of NativeMenu.

public function set items(value:Array):void
{
	while (numItems)
		removeItemAt(0);
	for each (var item:NativeMenuItem in value)
		addItem(item);
}

I want all of the MXML tags under my <Menu> tag to be the MenuItems, so in order to tell the compiler where those go I also added a metadata tag at the top of my class.

[DefaultProperty("items")]

Now moving on to the items themselves I created a MenuItem class. I wanted some more magic here since this is where all the hassle goes. First thing I wanted to do was to make a simple way to define the key shortcut. In code you have to add a keyEquivalent letter and a keyEquivalentModifiers entry for each modifier key. Way too complex for MXML. So I created a getter/setter called shortcut that parsed a string and added the pieces for you. Now I could have shortcuts that looked like “Ctrl+P” and “Cmd+Shift+F” in the MXML. Very readable. Much better. (I also set Cmd to Ctrl when on Windows since Mac Cmd shortcuts are usually the same as Windows Ctrl.)

public function get shortcut():String
{
	if (!keyEquivalent && !keyEquivalentModifiers.length)
		return "";

	var shortcut:String = "";

	if (keyEquivalentModifiers.indexOf(Keyboard.COMMAND) != -1)
		shortcut += "Cmd+";
	if (keyEquivalentModifiers.indexOf(Keyboard.CONTROL) != -1)
		shortcut += "Ctrl+";
	if (keyEquivalentModifiers.indexOf(Keyboard.ALTERNATE) != -1)
		shortcut += "Alt+";
	if (keyEquivalentModifiers.indexOf(Keyboard.SHIFT) != -1)
		shortcut += "Shift+";

	shortcut += keyEquivalent;

	return shortcut;
}

public function set shortcut(value:String):void
{
	var keys:Array = value.toLowerCase().split("+");
	var mods:Array = [];
	var theKey:String;
	var os:String = Capabilities.os.substr(0, 3).toLowerCase();

	for each (var key:String in keys)
	{
		if (key == "cmd" && os == "mac")
			mods.push(Keyboard.COMMAND);
		else if (key == "cmd")
			mods.push(Keyboard.CONTROL);
		else if (key == "ctrl")
			mods.push(Keyboard.CONTROL);
		else if (key == "alt")
			mods.push(Keyboard.ALTERNATE);
		else if (key == "shift")
			mods.push(Keyboard.SHIFT)
		else if (!theKey)
			theKey = key;
		else
			throw new Error(value + " is an invalid menu shortcut");
	}

	keyEquivalentModifiers = mods;
	keyEquivalent = theKey;
}

Next I tackled submenus. I created a getter/setter called items (same as the menu now) which let you specify your submenu’s items directly underneath the parent item. I figured it’s not a common use-case to add listeners on the submenu itself. I also added the metadata to make MXML items inside of a MenuItem map to the “items” property.

[DefaultProperty("items")]
public class MenuItem extends NativeMenuItem
{
...
...
public function get items():Array
{
	if (submenu)
		return submenu.items;
	else
		return [];
}

public function set items(value:Array):void
{
	submenu = new Menu();
	Menu(submenu).items = value;
}

Now our items can have their subitems directly under them in the MXML.

Finally I looked at adding support for the mnemonicIndex property to get set. For those of you who don’t know what this is, it tells AIR which letter in the menu to underline and allow a key-stroke to select it (I believe it is a Windows feature, but may be supported on Mac as well….somehow). Very important for accessibility. So I figured I’ll just have an underscore denote which letter should be, such as “_File” would say that “F” is the mnemonic letter.

public override function set label(value:String):void
{
	var index:int = value.indexOf("_");
	if (index != -1)
	{
		mnemonicIndex = index;
		value = value.substring(0, index) + value.substring(index + 1);
	}
	super.label = value;
}

Nicely done. We now have our label set and our mnemonic letter specified with just the label property, and this lends itself to setting the mnemonic letter separately for other languages as it is part of the label text.

I quickly added a MenuSeparator which just extended NativeMenuItem and set the isSeparator value in the constructor to true. This was for readability in the MXML.

The last thing I wanted to do is to add support for menu differences between Ma, Windows and Linux. This was a last minute idea because menus can look differently, behave differently, or have different shortcuts between the two systems. So I added a property to MenuItem called “os” which should be a string of “mac”, “win”, “lin” or a combination of them such as “win/lin”. Then I added to the Menu items setter code that would skip over adding items which were set for an OS that was not the current one. This allows two items with the same name to be specified but with different shortcuts, or two submenus that are different on different OSes.

Now I could define menus in MXML like this:

<ui:Menu id="mainMenu">
	<ui:MenuItem label="_File">
		<ui:MenuItem label="_New" shortcut="Cmd+N" select="newDocument()"/>
		<ui:MenuItem label="_Open" shortcut="Cmd+O" select="openDocument()"/>
		<ui:MenuSeparator/>
		<ui:MenuItem label="_Close" shortcut="Cmd+W" select="closeDocument()" enabled="{document != null}" os="mac"/>
		<ui:MenuItem label="_Close" shortcut="Ctrl+F4" select="closeDocument()" enabled="{document != null}" os="win"/>
		<ui:MenuSeparator/>
		<ui:MenuItem label="_Save" shortcut="Cmd+S" select="saveDocument()" enabled="{document != null}"/>
		<ui:MenuItem label="Save _As" shortcut="Cmd+Shift+S" select="saveAsDocument()" enabled="{document != null}"/>
		<ui:MenuItem label="E_xit" shortcut="Cmd+Q" select="close()" os="mac"/>
		<ui:MenuItem label="E_xit" shortcut="Alt+F4" select="close()" os="win"/>
	</ui:MenuItem>
</ui:Menu>

The final result was:

[DefaultProperty("items")]
public class Menu extends NativeMenu
{

	public function set items(value:Array):void
	{
		while (numItems)
			removeItemAt(0);

		var os:String = Capabilities.os.substring(0, 3).toLowerCase();

		for each (var item:NativeMenuItem in value)
		{
			if (item is MenuItem && MenuItem(item).os && MenuItem(item).os.toLowerCase().indexOf(os) == -1)
				continue;

			addItem(item);
		}
	}
}

------

[DefaultProperty("items")]
public class MenuItem extends NativeMenuItem
{
	public var os:String;

	public function MenuItem()
	{
		super(null, false);
	}

	public override function set label(value:String):void
	{
		var index:int = value.indexOf("_");
		if (index != -1)
		{
			mnemonicIndex = index;
			value = value.substring(0, index) + value.substring(index + 1);
		}
		super.label = value;
	}

	public function get items():Array
	{
		if (submenu)
			return submenu.items;
		else
			return [];
	}

	public function set items(value:Array):void
	{
		submenu = new Menu();
		Menu(submenu).items = value;
	}

	public function get shortcut():String
	{
		if (!keyEquivalent && !keyEquivalentModifiers.length)
			return "";

		var shortcut:String = "";

		if (keyEquivalentModifiers.indexOf(Keyboard.COMMAND) != -1)
			shortcut += "Cmd+";
		if (keyEquivalentModifiers.indexOf(Keyboard.CONTROL) != -1)
			shortcut += "Ctrl+";
		if (keyEquivalentModifiers.indexOf(Keyboard.ALTERNATE) != -1)
			shortcut += "Alt+";
		if (keyEquivalentModifiers.indexOf(Keyboard.SHIFT) != -1)
			shortcut += "Shift+";

		shortcut += keyEquivalent;

		return shortcut;
	}

	public function set shortcut(value:String):void
	{
		var keys:Array = value.toLowerCase().split("+");
		var mods:Array = [];
		var theKey:String;
		var os:String = Capabilities.os.substr(0, 3).toLowerCase();

		for each (var key:String in keys)
		{
			if (key == "cmd" && os == "mac")
				mods.push(Keyboard.COMMAND);
			else if (key == "cmd")
				mods.push(Keyboard.CONTROL);
			else if (key == "ctrl")
				mods.push(Keyboard.CONTROL);
			else if (key == "alt")
				mods.push(Keyboard.ALTERNATE);
			else if (key == "shift")
				mods.push(Keyboard.SHIFT)
			else if (!theKey)
				theKey = key;
			else
				throw new Error(value + " is an invalid menu shortcut");
		}

		keyEquivalentModifiers = mods;
		keyEquivalent = theKey;
	}
}

-----

public class MenuSeparator extends NativeMenuItem
{
	public function MenuSeparator()
	{
		super(null, true);
	}
}

Enjoy!

Update: I’ve put my code libraries up on Google Code. You can find the classes there. Following is an example app with a simple menu.

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication
	applicationComplete="initMenu()"
	xmlns:mx="http://www.adobe.com/2006/mxml"
	xmlns:ui="jac.ui.*">

	<mx:Script>
		<![CDATA[
			import jac.ui.Menus;

			private function initMenu():void
			{
				// utility to help merge the menu with Mac OS X's native menu
				// and to decide between the main menu on mac or window menu on
				// windows.
				Menus.initMainMenu(mainMenu, stage.nativeWindow)
			}
		]]>
	</mx:Script>

	<ui:Menu id="mainMenu">
		<ui:MenuItem label="_File">
			<ui:MenuItem label="_New" shortcut="Cmd+N" select="trace('New')"/>
			<ui:MenuItem label="_Open" shortcut="Cmd+O" select="trace('Open')"/>
			<ui:MenuSeparator/>
			<ui:MenuItem label="_Save" shortcut="Cmd+S" select="trace('Save')"/>
			<ui:MenuItem label="Save _As" shortcut="Cmd+Shift+S" select="trace('Save As')"/>
			<ui:MenuSeparator/>
			<ui:MenuItem label="_Close" shortcut="Cmd+W" select="trace('Close');stage.nativeWindow.close()" os="mac"/>
			<ui:MenuItem label="_Close" shortcut="Ctrl+F4" select="trace('Close');stage.nativeWindow.close()" os="win"/>
			<ui:MenuItem label="E_xit" shortcut="Cmd+Q" select="trace('Exit');nativeApplication.exit()" os="mac"/>
			<ui:MenuItem label="E_xit" shortcut="Alt+F4" select="trace('Exit');nativeApplication.exit()" os="win"/>
		</ui:MenuItem>
	</ui:Menu>

</mx:WindowedApplication>

17 Responses to “Using MXML for AIR NativeMenus”

  1. Zeh Says:

    Nice. here’s a question, though – your menu sets “Ctrl+F4” as the window close in a PC. That doesn’t work, right? keyEquivalent only works with characters. You *can* set it to F4 and it’ll probably show, but it will be activated by Ctrl+F, not Ctrl+F4.

    Or have you managed to have it working with that code? I’ve been attempting to add some shortcuts there using F1, DEL, ENTER and things like that, with no success.

  2. Jacob Wright Says:

    Good point Zeh. I have it working correctly, but saw the code posted above is missing an important piece. In the shortcut setter the end is wrong. Instead of:

    keyEquivalentModifiers = mods;
    keyEquivalent = theKey;

    it was fixed to be:

    keyEquivalentModifiers = mods;
    if (“STRING_” + theKey.toUpperCase() in Keyboard)
    keyEquivalent = Keyboard[“STRING_” + theKey.toUpperCase()];
    else
    keyEquivalent = theKey;

    Hope that helps. It should work with the F-keys, the Home key, etc.

  3. franto Says:

    Hey Jac,

    I wanted to use your component with Flex SDK 3.3 but it doesnt works :( there is problems width mnemonicIndex = index; in MenuItem

    I really dont know, if it is problem with SDK 3.3 or anything else? Can you provide some simple AIR sample app which works?

    Thank you very much

  4. Jacob Wright Says:

    Hey franto, the problem is that they’ve updated the API a few times with AIR, so there’s little fixes for each version. They should be small fixes. I’ll have to look into it later, and take the time to put a swc out for each version of AIR that changed it.

  5. bludragon Says:

    Nice work, Jac! Any example yet? When I copy the code into my application, nothing happens when I run it. No “compiling window”, no program, nothing.

  6. bludragon Says:

    Actually, if you look at the following link from the Flex documentation, you can do this fairly easily using XML.

    http://livedocs.adobe.com/flex/3/html/help.html?content=FlexApolloComponents_12.html

  7. Jacob Wright Says:

    bludragon: Added an example and the code repository. Sounds like you have a bug. I may have fixed bugs with it. Not sure. And the Menus helper is really nice to get it up and going.

  8. Jacob Wright Says:

    Yeah, FlexMenu is an alternative, though the syntax isn’t near as easy as I’ve made it for shortcuts, and doing it in XML doesn’t provide databinding. You can see in the first example I have on this post that some of the menu items are enabled/disabled depending on a binding value.

  9. bludragon Says:

    Thanks for the example Jac! Yeah the “not running” problem is apparently a well-known bug with adl.exe not closing properly on Vista.

  10. Dee Says:

    Thank you!

  11. ouldfella Says:

    it doesn’t work in flex builder3
    how ?

  12. Jacob Wright Says:

    It should work. Make sure you’re using an AIR project.

  13. Nate Beck Says:

    Hey Jac,

    Have you tried this stuff in Flex 4 yet? I’m trying to get it to work. It requires me to put the mxml in .

    After I do that, I get an obscure error message:

    “In initializer for ‘items’, type Object is not assignable to target Array element type flash.display.NativeMenuItem.”

    Can you shed any light on this?

    Cheers,
    Nate

  14. Jacob Wright Says:

    For the benefit of others that follow, first be sure you are defining the menu in the section.

    So for you Nate, I may have fixed it. I believe the error you’re getting may be because of missing [ArrayElementType] tags. You can find the latest version of Menu.as, MenuItem.as, and MenuSeparator.as here:

    http://code.google.com/p/jacwright/source/browse/#svn/trunk/flash/jac_air/src/jac/ui

  15. Jacob Wright Says:

    Also, you can create MXML Components that are a menu definition. Just make the root tag be and then you can instantiate the menu elsewhere easy enough. Let me know if it’s not working.

  16. Andrew Westberg Says:

    I grabbed your latest off of GoogleCode, but when I set Alt+F4, the label in the menu is wrong and shows “Alt+”. I couldn’t figure out where the key shortcut label is being pulled from. Ideas?

  17. Jacob Wright Says:

    I’m not sure. Unfortunately I don’t have the time to look into it right now.