Menu Mojo

Menus are a common part of almost every modern application. A webOS application can have standard menus available in every scene or context-sensitive menus that vary between scenes. It can have dropdown menus, floating menus, or button-based menus.

Like simple widgets, menus are instantiated by setupWidget(). Unlike simple widgets, however, menus use the commander chain to propagate menu commands between stage assistants and scene assistants. The commander chain will be covered at the end of the tutorial.

Mojo supports four types of menu widgets: Application Menu, View Menu, Command Menu and Submenu. The first three types are very similar, each using a single model definition with an array containing the menu items. They are instantiated in the usual way by a call to setupWidget(), specifying the menu type, attributes and model. The types include:

Mojo.Menu.appMenu
Mojo.Menu.viewMenu
Mojo.Menu.commandMenu

Selecting an item in a menu generates a command that is processed by a commander registered in the commander chain.

A menu's model is composed a visible property to set the menu to visible or invisible and an items array, which contains menu items and menu item groups. Menu items in groups represent a second level of selectable items. Each item can have a label and and icon (either a custom image or a standard framework icon) and a command value, which is propagated to the command chain when the item is selected. Submenus have many of the same model properties as the other menu types, but is instantiated and managed differently.

Menu widgets are different from standard widgets in that they are not declared in a scene's view file with an x-mojo-element; they are instantiated and handled completely from within the scene assistant. Menus are attached to the scene's window rather than the scene itself, so they always appear above other scene elements and cannot be positioned using HTML or CSS.

Let's take a closer look at the different menu types.

Application Menus

The application menu is a conventional desktop-application-style menu that drops down from the top left corner of the screen when the user taps there.

It is intended to have application-wide scope, and contains a few required items:

Edit (an item group containing Cut, Copy, Paste)
Preferences
Help

The last two are disabled by default (visible but greyed out and un-tappable), but can be enabled and handled within your application.

Application Menu properties include:

richTextEditItems: can be set to true when a RichTextEdit widget is included in the scene, adding Bold, Italic and Underline to the Edit menu.
omitDefaultItems: set to true to enable Preferences and Help. Setting to true requires you to re-add the items with your own definitions. To override some items but not others, you can use system constants to repalce the items that aren't changing.

Click here for an example of how to set up an application menu.

View Menus

A view menu is a menu that is displayed as variable sized buttons across the top of the scene.

View menus can be used to display action buttons that initiate an action, popup a submenu or toggle a setting. Items are rendered from left to right. Button widths can be adjusted from within the items property width and the framework adjusts the space between the buttons automatically.

Typically, the view menu is used for actionable buttons, buttons with an attached submenu, or header displays.

Click here for an example of how to set up a view menu.

Command Menus

Command menus are just like view menus, but appear at the bottom of the screen instead of the top.

Click here for an example of how to set up a command menu.

Submenus

Submenus can be displayed after tapping an option in one of the other menu types, or any element in a page (similar to how a context-sensitive menu pops up when you right click in most desktop-based applications).

mojo submenu

When the user chooses an item in the menu, the onChoose() callback function is called (in the scope of the scene assistant) with the command property of the chosen item as an argument. If the user taps outside the popup menu, the menu is dismissed and the onChoose() function is called with undefined.

Click here for an example of how to set up a submenu.

Commander Chain

The commander chain is "a model for propagating commands through the app, stage and scene controllers". It is an array of handlers ordered like a stack. Each command sent to the chain is propagated through the all handlers in the active scene controller, followed by all handlers in the active stage controller or until a handler calls Event.stopPropagation().

Commanders are registered implicitly when dialogs are instantiated, or by declaring a handleCommand() method as a stage assistant or scene-assistant method. They can also be registered explicitly by calling the pushCommander method from the stage controller or scene controller. The command is then removed when the scene assitant is popped or the application is closed.

Three types of events can propagate through the commander chain: