In-Depth Coverage of the UcompOS Menu Bar

The menu bar feature on the UcompOS Portal can be customized in a number of different ways.  This article will discuss the basics of the UcompOS menu bar, and also provide a look at some of the features that have been recently added to the menu bar including support for keyboard shortcuts.

Attaching a Menu Bar to a UcompOS Application

The common paradigm of using the menu bar is to have a custom menu bar implementation appear while a particular UcompOS application is in focus.

There are two ways to go about doing this.

The first is to attach an XML model for the menu bar to the particular UcompOS application’s manifest file.

Below is an example of a simple menu bar model that would be placed in the UcompOS application manifest file as a child of the root application element.

	<menu>
		<menuitem label="File">
			<menuitem label="Open"/>
			<menuitem label="Close"/>
			<menuitem label="Quit"/>
		</menuitem>
		<menuitem label="Edit">
			<menuitem label="Copy"/>
			<menuitem label="Paste"/>
		</menuitem>
	</menu>

You can also add a custom menu bar implementation to a UcompOS application at run-time.

This is accomplished using the UcompOSMenuBarProxy class that is built into the UcompOS SDK.

UcompOSMenuBarProxy is a Singleton, meaning it is instantiated via a static method.

It offers a setMenuBar() method that accepts a parameter model of type XML (String in the JavaScript SDK).

Below is a simple example of the UcompOSMenuBarProxy’s setMenuBar() method at work:

var menuBarModel:XML = new XML("<menu><menuitem label='File'><menuitem label='Open' data='open'/><menuitem label='Close' data='close'/></menuitem></menu>");
UcompOSMenuBarProxy.getInstance().setMenuBar(menuBarModel);

If you have done any coding in Flex and added your own XML dataProvider to a Flex MenuBar implementation, the above example should look familiar.  The XML data model we are using is based on the model that is used inside of Flex.

The Base UcompOS Menu Item

By default, UcompOS Portal implementations will have a base menu bar item that is perpetually viewable throughout the user’s session.  This is analogous to the Mac OS X Operating System’s menu bar implementation that has a base menu bar item on the left of the menu bar represented by Apple’s trademark logo.

The base menu bar option is shown above.

Overriding the Base Menu Item

You can replace the built-in UcompOS menu bar item with your own custom implementation in one of two ways.

One such way is by adding a baseMenu element to one of your UcompOS application’s manifest files.

Below is an example of this:

<baseMenu>
	<menuitem label="Company X">
		<menuitem label="About Our Company" data="about"/>
	</menuitem>
</baseMenu>

This would replace the base UcompOS menu bar item with an option labeled “Company X” that has an “About Our Company” sub option.

Below is an example of the custom base menu bar for the Educator 2 software I am building on top of the UcompOS RXF:

The other way would be to use the UcompOSMenuBarProxy class and to override the base menu item at run-time.

The second parameter of the UcompOSMenuBarProxy’s setMenuBar() method is an optional Boolean property named baseMenu that defaults to false.

When you pass in a true value for this parameter, the menu bar model you pass to setMenuBar() will become the base menu item.

There can only be one base menu item at a time throughout your entire UcompOS implementation.  If UcompOS Application A sets the base menu item, then UcompOS Application B sets the base menu item later, it will override the base menu item set by UcompOS Application A.

It is planned at some point that the UcompOS Dock Manifest will indicate which UcompOS Applications have the privilege of setting the base menu item which could be an important consideration in large collaborative development environments.

Sharing a Menu Bar Across Multiple UcompOS Applications

In some implementations, you may want one menu bar implementation to be used across multiple applications.

To do this, you would declare one of your applications as the default application.  This is accomplished in one of two ways: in the Dock Manifest by passing a default=”true” attribute to an <application/> element, or at run time with the UcompOSGlobalManagerProxy’s isDefaultApplication property.

When a default application is set on the UcompOS Portal, then any UcompOS Applications that have the following menu bar models:

	<menu default="true"/>

will use the Menu Bar implementation that is assigned to the application that has been declared as the default application.

As a note of caution, only one application can be declared as the default at a time on the UcompOS Portal.  If you try to declare an application as the default while another application has already been defined as the default, a run-time error will occur.  This is by design, and you must set the isDefaultApplication property of the UcompOSGlobalManagerProxy to false before you can set it to true for another application.

As is the case with setting base menu items, I am considering setting it up at the Dock Manifest level such that it is articulated ahead of time which applications can declare themselves as the default.

Menu Bar Icons

The model for the UcompOS menu bar supports the icon attribute for menuitem elements.  The value of the icon attribute should be the full URL to an image of type GIF, JPG, or PNG.

You can use any sized icon but it is recommended you use an icon sized at 18×18.

Below is an example of a menu bar implementation with icons:

Menu Bar Separators

In the image above, notice there is a separator between the “Delete” and “Close” options.

This is accomplished with the following menuitem element:

	<menuitem type="separator"/>

Window-Specific Menu Bars

In some UcompOS applications, you may spawn many different UcompOS windows and load a variety of different sub-applications into each window instance.

Each window instance may need their own unique menu bar implementation.

The UcompOSWindowProxy class offers a setMenuBar() method that allows you to attach a custom menu bar implementation to individual UcompOS Window instances.

The menu bar will come into view whenever the window it is attached to comes into focus.  When the window closes, the menu bar will return to the existing menu bar implementation attached to the UcompOS application in focus.

Menu Bar Events

Obviously, if you go through the trouble of implementing a custom menu bar, you want to know when the user has selected an option on the menu bar.

When an item is selected on the menu bar, an event of type UcompOSMenuBarProxy.ITEM_CLICK is dispatched to any listening UcompOSMenuBarProxy instances.

A strict protocol that must be recognized is that only menuitem elements that have a data property will dispatch a UcompOSMenuBarProxy.ITEM_CLICK event.

Let’s look at a very simple code-based example:

package
{
 
	import com.ucompass.ucompos.sdk.proxycomponents.UcompOSMenuBarProxy;
	import com.ucompass.ucompos.sdk.events.SDKEvent;
	import com.ucompass.ucompos.sdk.SDKClient;
 
	public class MenuBarExample extends Sprite
	{
 
		public function MenuBarExample()
		{
			var menuBarModel:XML = new XML("<menu><menuitem label='File'><menuitem label='Select Me' data='testData'/></menuitem></menu>");
			SDKClient.getInstance(this);
			UcompOSMenuBarProxy.getInstance().setMenuBar(menuBarModel);
			UcompOSMenuBarProxy.getInstance().addEventListener(UcompOSMenuBarProxy.ITEM_CLICK,eventHandler);
		}
 
		private function eventHandler(event:SDKEvent):void
		{
			trace("The user said "+event.data.label);
			trace("The associaed data is "+event.data.data);
		}
 
	}
 
 
}

UcompOSMenuBarProxy.ITEM_CLICK events are only dispatched to UcompOS entities in the scope of the UcompOS application in focus when the menu item was selected.  So if UcompOS Application B has implemented a custom menu bar, and UcompOS Application A is in focus, no menu events will be dispatched to UcompOS Application B.

Keyboard Shortcut Commands

In applications where you load a lot of functionality onto the menu bar, keyboard shortcut commands can be a very convenient feature for your users, and, perhaps as importantly, they can help your applications address important accessibility standards crucial for many public-use applications.

To add a keyboard shortcut command to a menu item, you use the shortcutKey attribute to the menuitem element in a menu bar model.

For instance:

	<menu>
		<menuitem label="File">
			<menuitem label="Print" data="print" shortcutKey="ALT-P"/>
		</menuitem>
	</menu>

In the above example, when the user presses the ALT key and the P key simultaneously, the action that will take place will be exactly the same as if the user would have chosen the Print option with the mouse.

Below is an example of a similar implementation from Educator 2: