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>

I’ve been working with AIR quite a bit since my side project is in AIR. I thought it would be pretty cool to create an active record implementation in AIR since I’ve got one on the server side.

I have to use synchronous database connections for it so that everytime I access an object’s related properties I don’t have to use a callback, though it could be refactored to do that. Not my idea of fun though, and after an excellent presentation by Jason Williams, “Working with Persistent Data in AIR,” where he showed how fast it was to retrieve data from an AIR database I figured it would be just fine.

Currently I don’t have metadata allowing you to define how every property maps to a field in the database, nor do I have many “special case” hooks for this and that. I figured that any AIR app you write will be using a fresh database and not a legacy system. How many desktop apps using a SQLite database will you be updating with AIR and using the same database file? Maybe I’m wrong, but I don’t think so.

I also added a piece that you can run which will create and update database tables based off the ActiveRecord object’s properties. So you have a nice update mechanism for the database when you update your app using the updater api.

I’ll be open-sourcing the code when I have time (isn’t that always the case), but you can get the code now, test it out, and let me know what enhancements you’d like to see. Sorry, no documentation currently. If I like the ideas or they’re requested enough I’ll be sure to add them in. :)

Oh, and when you unzip it you’ll see “flight” is the package Tyler (my twin) and I are using for our projects. It started when he and Rob Taylor started a component set in AS2 under the name but AS3 and Flex 2 came out and they never finished. Maybe an AS3 set will happen someday.

Update: AIR Active Record is open sourced.