# Mojo.Menu

## Class Detail

Unlike all other widgets, Menu widgets are not declared in your scene view file, but are simply instantiated and have their actions handled from within your assistant completely. Menu widgets are thought to be above the scene elements, attached to the scene's window rather than a point in the scene, so it wouldn't work for their position to be determined within the HTML.

With any of the menu functions, you need to set up a command handler, which will receive the command events according to the precedence rules within the commander stack. See the Developer Guide - Menus for more information on the command handlers.

## Summary

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

## Detail

### Mojo.Menu.appMenu

#### Overview

The Application Menu appears in the upper-left corner of the screen when the user taps the left-hand side of the status bar. It includes some system-defined and some application-defined actions, and is intended to have an application-wide scope for the most part. The application list contains a few required actions: Edit, which is a item group including Cut, Copy and Paste; Preferences and Help, both of which are disabled by default. You are free to add any other items to the menu, and to enable Preferences and/or Help by hooking them to the appropriate actions for your application.

#### Declaration

The app menu is not declared in the scene HTML.

#### Events

Events for menus are sent via the commander chain. Scenes are automatically registered on the commander chain. To receive events, implement a handleCommand function in your scene assistant. The event's command field will contain the command associated with the menu item selected, specified as part of the items array.

Example:

>     handleCommand: function(event) {
>       if (event.type === Mojo.Event.command) {
>           switch (event.command) {
>               ...
>           }
>       }
>     }

#### Instantiation

>     this.controller.setupWidget(Mojo.Menu.appMenu,
>     this.attributes = {
>       omitDefaultItems: true
>     },
>     this.model = {
>       visible: true,
>       items: [
>           {label: "About My App ...", command: 'do-myAbout'},
>           Mojo.Menu.editItem,
>           { label: "Preferences...", command: 'do-myPrefs' },
>           { label: "Help...", command: 'do-myHelp' }
>       ]
>     });

Note that in the above example, the default app menu items ("Preferences", "Edit", and "Help") will not be displayed. However, the Edit menu items are still desired, so in the "items" list, Mojo.Menu.editItem is added. If rich text edit menu items are required, but the defaults are being omitted, include Mojo.Menu.styleEditItem instead.

#### Attribute Properties

Attribute Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
omitDefaultItems | Boolean | Optional | False | If true, then default menu items will not be added to this menu.
richTextEditMenu | Boolean | Optional | False | If true, then the edit menu will also include Bold/Italics/Underline. (Only if `omitDefaultItems` is `false`. See note below.)

#### Model Properties

Model Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
label | String | Optional | Null | Not displayed, future.
visible | Boolean | Optional | TRUE | Current visibility of this menu.
items | Array | Required | List items for this menu. See the table below. |

#### List Items

List Item | Type | Required | Default | Description
--- | --- | --- | --- | ---
label | String | Optional | Null | User visible label for this item, not rendered for groups.
icon | String | Optional | None | CSS class for icon to display in this item.
iconPath | String | Optional | None | Path to image to display in menu item, relative to app's directory.
width | Integer | Optional | None | Calculated based on item's width - specifies the width in pixels of this menu item. Overrides default calculations. Ignored for groups.
items | Array | Optional | None | If specified, this item is a "group" that visually ties the child items together.
toggleCmd | String | Optional | None | Only used when "items" is specified. Specify this property to make this group a "toggle group". This string is the command of the currently selected "choice" item in this group, and this property is modified by the widget when a different choice is made.
command | String | Optional | None | Specify to make this item a "choice". It will then respond to a user tap by sending a `mojo-command` event through the commander chain with this string as the `command` property.
disabled | Boolean | Optional | False | Menu choice is disabled when this is true. Only used for items which also specify `command`.
submenu | String | Optional | Null | Specify to make this item a submenu item. It will then respond to a user tap by displaying the named menu as a popup submenu.
template | String | Optional | Null | Path to HTML template for custom content to be inserted instead of a standard menu item. The template is rendered using this item model object for property substitution.
checkEnabled | Boolean | Optional | False | If truthy, a `Mojo.Event.commandEnable` event will be sent through the commander chain each time this menu item is displayed or invoked via keyboard shortcut. If a commander calls `preventDefault()` on the event, then the menu item's model will be modified to disable the menu item. Otherwise it will be enabled. This can be used to lazily update the enable state of items in the app-menu or submenus.
Mojo.Menu.editItem | Boolean | Optional | None | If `omitDefaultItems` is `true`, retain the Edit menu items.
Mojo.Menu.styleEditItem | Boolean | Optional | None | If `omitDefaultItems` is `true`, retain the Edit menu items with formatting options.

#### Methods

The app menu does not have any methods.

### Mojo.Menu.commandMenu

#### Overview

The Command Menu presents items at the bottom of the screen, and is similar to the View Menu in most ways. Items will include variable-sized buttons, that can be combined into groups, and in a horizontal layout from left to right. As with the View Menu, button widths can be adjusted from within the items property width, and the framework adjusts the space between the buttons automatically.

#### Declaration

The command menu is not declared in the scene HTML.

#### Events

Events for menus are sent via the commander chain. Scenes are automatically registered on the commander chain. To receive events, implement a handleCommand function in your scene assistant. The event's command field will contain the command associated with the menu item selected, specified as part of the items array.

Example:

>     handleCommand: function(event) {
>       if (event.type === Mojo.Event.command) {
>           switch (event.command) {
>               ...
>           }
>       }
>     }

#### Instantiation

>     this.controller.setupWidget(Mojo.Menu.commandMenu,
>       this.attributes = {
>           spacerHeight: 0,
>           menuClass: 'no-fade'
>       },
>       this.model = {
>           visible: true,
>           items: [
>               {icon: "back", command: "do-Previous"},
>               { icon: 'forward', command: 'do-Next'}
>           ]
>       }
>     );

#### Attribute Properties

Attribute Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
spacerHeight | Integer | Optional | Calculated | If specified, the spacer div associated with this menu will be the given height in pixels. This affects the size of the scene content, and whether the view menu "pushes down" other content in the scene.
menuClass | String | Optional | .palm-default | Sets the style for the menu.

#### Model Properties

Model Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
label | String | Optional | Null | Not displayed, future.
visible | Boolean | Optional | TRUE | Current visibility of this menu.
items | Array | Required |  | List items for this menu. See the table below.

#### List Items

List Item | Type | Required | Default | Description
--- | --- | --- | --- | ---
label | String | Optional | Null | User visible label for this item, not rendered for groups.
icon | String | Optional | None | CSS class for icon to display in this item.
iconPath | String | Optional | None | Path to image to display in menu item, relative to app's director.
width | Integer | Optional | None | Calculated based on item's width - specifies the width in pixels of this menu item. Overrides default calculations. Ignored for groups.
items | Array | Optional | None | If specified, this item is a "group" that visually ties the child items together.
toggleCmd | String | Optional | None | Only used when "items" is specified. Specify this property to make this group a "toggle group". This string is the command of the currently selected "choice item in this group, and this property is modified by the widget when a different choice is made.
command | String | Optional | None | Specify to make this item a "choice". It will then respond to a user tap by sending a `mojo-command` event through the commander chain with this string as the `command` property.
disabled | Boolean | Optional | False | Menu choice is disabled when this is true. Only used for items which also specify `command`.
submenu | String | Optional | Null | Specify to make this item a submenu item. It will then respond to a user tap by displaying the named menu as a popup submenu.
template | String | Optional | Null | Path to HTML template for custom content to be inserted instead of a standard menu item. The template is rendered using this item model object for property substitution.
checkEnabled | Boolean | Optional | False | If truthy, a `Mojo.Event.commandEnable` event will be sent through the commander chain each time this menu item is displayed or invoked via keyboard shortcut. If a commander calls `preventDefault()` on the event, then the menu item's model will be modified to disable the menu item. Otherwise it will be enabled. This can be used to lazily update the enable state of items in the app-menu or submenus.

#### Methods

The command menu does not have any methods.

### Mojo.Menu.viewMenu

#### Overview

The View menu presents items as variable sized buttons, either singly or in groups across the top of the scene. The items are layed out in a horizontal sequence starting from the left of the screen to the right. The button widths can be adjusted from within the items property width, and the framework adjusts the space between the buttons automatically.

#### Declaration

The view menu is not declared in the scene HTML.

#### Events

Events for menus are sent via the commander chain. Scenes are automatically registered on the commander chain. To receive events, implement a handleCommand function in your scene assistant. The event's command field will contain the command associated with the menu item selected, specified as part of the items array.

Example:

>     handleCommand: function(event) {
>       if (event.type === Mojo.Event.command) {
>           switch (event.command) {
>               ...
>           }
>       }
>     }

#### Instantiation

>     this.controller.setupWidget(Mojo.Menu.viewMenu,
>       this.attributes = {
>           spacerHeight: 0,
>           menuClass: 'no-fade'
>       },
>       this.model = {
>           visible: true,
>           items: [
>               { icon: , command: , label: "  "},
>               { label: "My App Name", width: 210 },
>               { icon: '', command: '', label: "  "}
>           ]
>       }
>     );

#### Attribute Properties

Attribute Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
spacerHeight | Integer | Optional | Calculated | If specified, the spacer div associated with this menu will be the given height in pixels. This affects the size of the scene content, and whether the view menu "pushes down" other content in the scene.
menuClass | String | Optional | .palm-default | Sets the style for the menu.

#### Model Properties

Model Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
label | String | Optional | Null | Not displayed, future.
visible | Boolean | Optional | TRUE | Current visibility of this menu.
items | Array | Required |  | List items for this menu. See the table below.

#### List Items

List Item | Type | Required | Default | Description
--- | --- | --- | --- | ---
label | String | Optional | Null | User visible label for this item, not rendered for groups.
icon | String | Optional | None | CSS class for icon to display in this item.
iconPath | String | Optional | None | Path to image to display in menu item, relative to app's director.
width | Integer | Optional | None | Calculated based on item's width - specifies the width in pixels of this menu item. Overrides default calculations. Ignored for groups.
items | Array | Optional | None | If specified, this item is a "group" that visually ties the child items together.
toggleCmd | String | Optional | None | Only used when "items" is specified. Specify this property to make this group a "toggle group". This string is the command of the currently selected "choice item in this group, and this property is modified by the widget when a different choice is made.
command | String | Optional | None | Specify to make this item a "choice". It will then respond to a user tap by sending a `mojo-command` event through the commander chain with this string as the `command` property.
disabled | Boolean | Optional | False | Menu choice is disabled when this is true. Only used for items which also specify `command`.
submenu | String | Optional | Null | Specify to make this item a submenu item. It will then respond to a user tap by displaying the named menu as a popup submenu.
template | String | Optional | Null | Path to HTML template for custom content to be inserted instead of a standard menu item. The template is rendered using this item model object for property substitution.
checkEnabled | Boolean | Optional | False | If truthy, a `Mojo.Event.commandEnable` event will be sent through the commander chain each time this menu item is displayed or invoked via keyboard shortcut. If a commander calls `preventDefault()` on the event, then the menu item's model will be modified to disable the menu item. Otherwise it will be enabled. This can be used to lazily update the enable state of items in the app-menu or submenus.

#### Methods

The view menu does not have any methods.