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


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.