AppJS - Menu API (Proposal 1)

gistfile1.js

// --- Specifications ---
// A menu specification is just an object.
// Each key provides a name for the menu item
// or sub-menu. The values can be a menu item
// or sub-men specification.
var spec = {
  File: {
    Open: { action: function() { // called when menu is selected }) },
    Close: { }
  },

  Edit: {
    Copy: { },
    SubMenu: {
      SubMenuItem: { }
    }
  }
};

// --- Presenting ---
// When you present a specification a menu
// will be created then merged into a host menu (ex: context menu).
// You can do multiple presentations to modify the host menu
// under certain scenarios. Each presentation returns a Menu instance
// to amend the changes you merged in and even remove them completely.

// Present my spec by inserting the menu into the window's menu bar.
// No operation performed on Mac OS X. See FLAG_APP_MENU example below.
var windowMenu = Menu.present(window, spec);

// Present the spec by inserting into a context menu of the window instead.
var contextMenu = Menu.present(window, Menu.FLAG_CONTEXT_MENU, spec);

// Present the spec in the application menu on Mac OS X.
// If no window is provided no operation will happen on Windows or Linux.
// To fallback to the window menu bar on these platforms provide a window as the host.
var appOrWindowMenu = Menu.present(window, Menu.FLAG_APP_MENU, spec),
    appMenuOnly     = Menu.present(Menu.FLAG_APP_MENU, spec);

// Present the spec in the dock menu on Mac OS X.
// No operation performed on Windows or Linux.
var dockMenu = Menu.present(Menu.FLAG_DOCK_MENU, spec);

// Present the spec into a tray item's menu.
var trayItemMenu = Menu.present(trayItem, spec);

// You may also specify the position in the host menu
// to insert the specification's menu.
Menu.present(0, spec);  // insert at beginning
Menu.present(-1, spec); // insert at end
Menu.present(1, spec);  // insert after first menu item

// --- Amending ---
// After you have presented a menu you can amend it by
// inserting, removing, showing, and hiding items.

// Hide the entire windowMenu we inserted into the host menu.
windowMenu.hide();

// Hide just a single menu item or sub-menu.
windowMenu.someItem.hide();

// Show an item we hide before.
windowMenu.someItem.show();

// Insert a new item. A menu specification is used to create the new item.
// Unlike present() no new Menu instance will be returned. You can access
// the new item just like any other item.
windowMenu.insert({newItem: { });
windowMenu.newItem;  // <-- new item access

// --- Loading specifications from JSON ---
// Since specifications are just objects it is trivial to load
// a specification from a JSON file.
var jsonSpec = JSON.parse(data);

// Will need to hook up action callbacks at runtime.
jsonSpec.Edit.Copy.action = function () { };