sproutcore 1.4.0-java

data/lib/frameworks/sproutcore/frameworks/desktop/panes/alert.js

@@ -0,0 +1,410 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('panes/panel');
+sc_require('views/button');
+/** 
+  button1 : 1st button from the right. default:OK
+  button2 : 2nd button from the right. Optional. Could be Cancel or 2nd action.
+  button3 : 1st button from the left. Optional. Could be Cancel or alternative option.
+*/
+/** 
+  Passed to delegate when alert pane is dismissed by pressing button 1
+*/
+SC.BUTTON1_STATUS = 'button1';
+
+/** 
+  Passed to delegate when alert pane is dismissed by pressing button 2
+*/
+SC.BUTTON2_STATUS = 'button2';
+
+/** 
+  Passed to delegate when alert pane is dismissed by pressing button 3
+*/
+SC.BUTTON3_STATUS = 'button3';
+
+/** @class
+  Displays a preformatted modal alert pane.
+  
+  Alert panes are a simple way to provide modal messaging that otherwise 
+  blocks the user's interaction with your application.  Alert panes are 
+  useful for showing important error messages and confirmation dialogs.  They
+  provide a better user experience than using the OS-level alert dialogs.
+  
+  h1. Displaying an Alert Pane
+  
+  The easiest way to display an alert pane is to use one of the various 
+  class methods defined on SC.AlertPane, passing the message and an optional
+  detailed description and caption.  
+  
+  There are four variations of this method can you can invoke:  
+  
+  - *warn()* - displays an alert pane with a warning icon to the left.
+  - *error()* - displays an alert with an error icon to the left
+  - *info()* - displays an alert with an info icon to the left
+  - *plain()* - displays an alert w/o any icon
+  - *show()* - displays an alert with a customizable icon to the left
+  
+  In addition to passing a message, description and caption, you can also customize
+  the title of the button 1 (OK) and add an optional button 2 and 3 (Cancel or Extra).  Just
+  pass these titles of these buttons to enable them or null to disable then.
+  
+  Additionally, you can pass a delegate object as the last parameter.  This
+  delegate's 'alertPaneDidDismiss()' method will be called when the pane
+  is dismissed, passing the pane instance and a key indicating which 
+  button was pressed.
+  
+  h1. Examples
+  
+  Show a simple AlertPane with an OK button:
+  
+  {{{
+    SC.AlertPane.warn("Could not load calendar", "Your internet connection may be unavailable or our servers may be down.  Try again in a few minutes.");
+  }}}
+  
+  Show an AlertPane with a customized OK title (title will be 'Try Again'):
+  
+  {{{
+    SC.AlertPane.warn("Could not load calendar", "Your internet connection may be unavailable or our servers may be down.  Try again in a few minutes.", "Try Again");
+  }}}
+  
+  Show an AlertPane with a custom OK, a Cancel button and an Extra button, 
+  each with custom titles.  Also, pass a delegate that will be invoked when
+  the user's dismisses the dialog.
+  
+  {{{
+
+    MyApp.calendarController = SC.Object.create({
+      alertPaneDidDismiss: function(pane, status) {
+        switch(status) {
+          case SC.BUTTON1_STATUS:
+            this.tryAgain();
+            break;
+            
+          case SC.BUTTON2_STATUS:
+            // do nothing
+            break;
+            
+          case SC.BUTTON3_STATUS:
+            this.showMoreInfo();
+            break;
+        }
+      },
+      
+      ...
+    });
+    
+    SC.AlertPane.warn("Could not load calendar", "Your internet connection may be unavailable or our servers may be down.  Try again in a few minutes.", "Try Again", "Cancel", "More Info...", MyApp.calendarController);
+  }}}
+  
+  @extends SC.PanelPane
+  @since SproutCore 1.0
+*/
+SC.AlertPane = SC.PanelPane.extend({
+  
+  classNames: 'sc-alert',
+  
+  /**
+    The delegate to notify when the pane is dismissed.  If you set a 
+    delegate, it should respond to the method:
+    
+    {{{
+      alertPaneDidDismiss: function(pane, status)
+    }}}
+    
+    The status will be on of SC.BUTTON1_STATUS, SC.BUTTON2_STATUS or SC.BUTTON3_STATUS
+    depending on which button was clicked.
+    
+    @property {Object}
+  */
+  delegate: null,
+
+  /**
+    The icon URL or class name.  If you do not set this, an alert icon will
+    be shown instead.
+    
+    @property {String}
+  */
+  icon: 'sc-icon-alert-48',
+
+  /**
+    The primary message to display.  This message will appear in large bold
+    type at the top of the alert.
+    
+    @property {String}
+  */
+  message: "",
+
+  /**
+    An optional detailed decription.  Use this string to provide further 
+    explanation of the condition and, optionally, ways the user can resolve
+    the problem.
+    
+    @property {String}
+  */
+  description: "",
+  
+  displayDescription: function() {
+    var desc = this.get('description');
+    if (!desc || desc.length === 0) return desc ;
+    
+    desc = SC.RenderContext.escapeHTML(desc); // remove HTML
+    return '<p class="description">' + desc.split('\n').join('</p><p class="description">') + '</p>';
+  }.property('description').cacheable(),
+
+  /**
+    An optional detailed caption.  Use this string to provide further 
+    fine print explanation of the condition and, optionally, ways the user can resolve
+    the problem.
+    
+    @property {String}
+  */
+  caption: "",
+  
+  displayCaption: function() {
+    var caption = this.get('caption');
+    if (!caption || caption.length === 0) return caption ;
+    
+    caption = SC.RenderContext.escapeHTML(caption); // remove HTML
+    return '<p class="caption">' + caption.split('\n').join('</p><p class="caption">') + '</p>';
+  }.property('caption').cacheable(),
+  
+  /**
+    The button view for the button 1 (OK).
+    
+    @property {SC.ButtonView}
+  */
+  buttonOne: SC.outlet('contentView.childViews.1.childViews.1'),
+
+  /**
+    The button view for the button 2 (Cancel).
+    
+    @property {SC.ButtonView}
+  */
+  buttonTwo: SC.outlet('contentView.childViews.1.childViews.0'),
+
+  /**
+    The button view for the button 3 (Extra).
+    
+    @property {SC.ButtonView}
+  */
+  buttonThree: SC.outlet('contentView.childViews.2.childViews.0'),
+
+  /**
+    The view for the button 3 (Extra) wrapper.
+    
+    @property {SC.View}
+  */
+  buttonThreeWrapper: SC.outlet('contentView.childViews.2'),
+  
+  layout: { top : 0.3, centerX: 0, width: 500 },
+
+  /** @private - internal view that is actually displayed */
+  contentView: SC.View.extend({
+    
+    useStaticLayout: YES,
+    
+    layout: { left: 0, right: 0, top: 0, height: "auto" },
+		
+    childViews: [
+      SC.View.extend(SC.StaticLayout, {
+        classNames: ['info'],
+
+        render: function(context, firstTime) {
+          var pane = this.get('pane');
+          var blank = SC.BLANK_IMAGE_URL ;
+          if(pane.get('icon') == 'blank') context.addClass('plain');
+          context.push('<img src="'+blank+'" class="icon '+pane.get('icon')+'" />');
+          context.begin('h1').attr('class', 'header').text(pane.get('message') || '').end();
+          context.push(pane.get('displayDescription') || '');
+          context.push(pane.get('displayCaption') || '');
+          context.push('<div class="separator"></div>');
+        }
+      }),
+
+      SC.View.extend({
+        layout: { bottom: 13, height: 24, right: 18, width: 466 },
+        childViews: ['cancelButton', 'okButton'],
+        classNames: ['text-align-right'],
+        cancelButton : SC.ButtonView.extend({
+            useStaticLayout: YES,
+            actionKey: SC.BUTTON2_STATUS,
+            localize: YES,
+            titleMinWidth: 64,
+            layout: { right: 5, height: 'auto', width: 'auto', bottom: 0 },
+            theme: 'capsule',
+            title: "Cancel", 
+            isCancel: YES,
+            action: "dismiss",
+            isVisible: NO
+          }),
+
+        okButton : SC.ButtonView.extend({
+            useStaticLayout: YES,
+            actionKey: SC.BUTTON1_STATUS,
+            localize: YES,
+            titleMinWidth: 64,
+            layout: { left: 0, height: 'auto', width: 'auto', bottom: 0 },
+            theme: 'capsule',
+            title: "OK", 
+            isDefault: YES,
+            action: "dismiss"
+          })
+      }),
+      
+      SC.View.extend({
+        layout: { bottom: 13, height: 24, left: 18, width: 150 },
+        isVisible: NO,
+        childViews: [
+          SC.ButtonView.extend({
+            useStaticLayout: YES,
+            actionKey: SC.BUTTON3_STATUS,
+            localize: YES,
+            titleMinWidth: 64,
+            layout: { left: 0, height: 'auto', width: 'auto', bottom: 0 },
+            theme: 'capsule',
+            title: "Extra", 
+            action: "dismiss",
+            isVisible: NO
+          })]
+      })]
+  }),
+
+  /**
+    Action triggered whenever any button is pressed.  Notifies any delegate
+    and then hides the alert pane.
+  */
+  dismiss: function(sender) {
+    var del = this.delegate;
+    if (del && del.alertPaneDidDismiss) {
+      del.alertPaneDidDismiss(this, sender.get('actionKey'));
+    }
+    this.remove(); // hide alert
+  },
+  
+  /** @private 
+    Executes whenever one of the icon, message, description or caption is changed.
+    This simply causes the UI to refresh.
+  */
+  alertInfoDidChange: function() {
+    var v = this.getPath('contentView.childViews.0');
+    if (v) v.displayDidChange(); // re-render message
+  }.observes('icon', 'message', 'displayDescription', 'displayCaption')
+});
+
+/** @private
+  internal method normalizes arguments for processing by helper methods.
+*/
+SC.AlertPane._normalizeArguments = function(args) {
+  args = SC.A(args); // convert to real array
+  var len = args.length, delegate = args[len-1];
+  if (SC.typeOf(delegate) !== SC.T_STRING) {
+    args[len-1] = null;
+  } else delegate = null ;
+  args[7] = delegate ;
+  return args ;
+};
+
+/**
+  Displays a new alert pane according to the passed parameters.  Every 
+  parameter except for the message is optional.  You can always pass the 
+  delegate as the last parameter and it will be used, even if you omit items
+  in between.
+  
+  If you need to pass other parameters but you want to omit some others 
+  in between, pass null and the related UI item will be hidden
+  
+  Note that if you pass an icon, it should be 48 x 48 in size.
+  
+  @param {String} message the primary message
+  @param {String} description an optional detailed description
+  @param {String} caption an optional detailed fine print caption
+  @param {String} button1Title optional unlocalized title for button 1 (OK)
+  @param {String} button2Title optional unlocalized title for button 2 (Cancel)
+  @param {String} button3Title optional unlocalized title for button 3 (extra)
+  @param {String} iconUrl optional URL or class name for icon.
+  @param {Object} delegate optional delegate to notify when pane is dismissed
+  @returns {SC.AlertPane} new alert pane
+*/
+SC.AlertPane.show = function(message, description, caption, button1Title, button2Title, button3Title, iconUrl, delegate) {
+  
+  // get the delegate and normalize the rest of the params
+  var args = this._normalizeArguments(arguments);
+  
+  // create basic AlertPane
+  var ret = this.create({
+    message: args[0] || '',
+    description: args[1] || null,
+    caption: args[2] || null,
+    icon: args[6] || 'sc-icon-alert-48',
+    delegate: args[7]
+  });
+  
+  // customize buttons as needed
+  var buttonKeys = 'buttonOne buttonTwo buttonThree'.w(), button, title;
+  for(var idx=0;idx<3;idx++) {
+    button = ret.get(buttonKeys[idx]);
+    title = args[idx + 3];
+    if (title) {
+      button.set('title', title).set('isVisible', YES);
+      if(title=='?') button.set('titleMinWidth', 0);
+      if (idx==2) {
+        var button_wrapper = ret.get('buttonThreeWrapper');
+        button_wrapper.set('isVisible', YES);
+      }
+    }
+  }
+  var show = ret.append() ; // make visible.
+  ret.adjust('height', ret.childViews[0].$().height()) ;
+  ret.updateLayout() ;
+  return show ;
+};
+
+/**
+  Displays a warning alert pane.  See SC.AlertPane.show() for complete details. 
+  
+  @returns {SC.AlertPane} the pane
+*/
+SC.AlertPane.warn = function(message, description, caption, button1Title, button2Title, button3Title, delegate) {
+  var args = this._normalizeArguments(arguments);
+  args[6] = 'sc-icon-alert-48';
+  return this.show.apply(this, args);
+};
+
+
+/**
+  Displays a info alert pane.  See SC.AlertPane.show() for complete details. 
+  
+  @returns {SC.AlertPane} the pane
+*/
+SC.AlertPane.info = function(message, description, caption, button1Title, button2Title, button3Title, delegate) {
+  var args = this._normalizeArguments(arguments);
+  args[6] = 'sc-icon-info-48';
+  return this.show.apply(this, args);
+};
+
+/**
+  Displays a error allert pane.  See SC.AlertPane.show() for complete details. 
+  
+  @returns {SC.AlertPane} the pane
+*/
+SC.AlertPane.error = function(message, description, caption, button1Title, button2Title, button3Title, delegate) {
+  var args = this._normalizeArguments(arguments);
+  args[6] = 'sc-icon-error-48';
+  return this.show.apply(this, args);
+};
+
+/**
+  Displays a plain all-text allert pane w/o icon.  See SC.AlertPane.show() for complete details. 
+  
+  @returns {SC.AlertPane} the pane
+*/
+SC.AlertPane.plain = function(message, description, caption, button1Title, button2Title, button3Title, delegate) {
+  var args = this._normalizeArguments(arguments);
+  args[6] = 'blank';
+  return this.show.apply(this, args);
+};

data/lib/frameworks/sproutcore/frameworks/desktop/panes/menu.js

@@ -0,0 +1,1115 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+require('panes/picker');
+require('views/menu_item');
+
+/**
+  @class
+
+  SC.MenuPane allows you to display a standard menu. Menus appear over other
+  panes, and block input to other views until a selection is made or the pane
+  is dismissed by clicking outside of its bounds.
+
+  You can create a menu pane and manage it yourself, or you can use the
+  SC.SelectButtonView and SC.PopupButtonView controls to manage the menu for
+  you.
+
+  h2. Specifying Menu Items
+
+  The menu pane examines the @items@ property to determine what menu items
+  should be presented to the user.
+
+  In its most simple form, you can provide an array of strings. Every item
+  will be converted into a menu item whose title is the string.
+
+  If you need more control over the menu items, such as specifying a keyboard
+  shortcut, enabled state, custom height, or submenu, you can provide an array
+  of content objects.
+
+  Out of the box, the menu pane has some default keys it uses to get
+  information from the objects. For example, to find out the title of the menu
+  item, the menu pane will ask your object for its @title@ property. If you
+  need to change this key, you can set the @itemTitleKey@ property on the pane
+  itself.
+
+  {{{
+    var menuItems = [
+      { title: 'Menu Item', keyEquivalent: 'ctrl_shift_n' },
+      { title: 'Checked Menu Item', isChecked: YES, keyEquivalent: 'ctrl_a' },
+      { title: 'Selected Menu Item', keyEquivalent: 'backspace' },
+      { isSeparator: YES },
+      { title: 'Menu Item with Icon', icon: 'inbox', keyEquivalent: 'ctrl_m' },
+      { title: 'Menu Item with Icon', icon: 'folder', keyEquivalent: 'ctrl_p' }
+    ];
+
+    var menu = SC.MenuPane.create({
+      items: menuItems
+    });
+  }}}
+
+  h2. Observing User Selections
+
+  To determine when a user clicks on a menu item, you can observe the
+  @selectedItem@ property for changes.
+
+  @extends SC.PickerPane
+  @since SproutCore 1.0
+*/
+
+SC.MenuPane = SC.PickerPane.extend(
+/** @scope SC.MenuPane.prototype */ {
+
+  classNames: ['sc-menu'],
+
+  // ..........................................................
+  // PROPERTIES
+  //
+
+  /**
+    The array of items to display. This can be a simple array of strings,
+    objects or hashes. If you pass objects or hashes, you can also set the
+    various itemKey properties to tell the menu how to extract the information
+    it needs.
+
+    @type String
+  */
+  items: [],
+
+  /**
+    The size of the menu. This will set a CSS style on the menu that can be
+    used by the current theme to style the appearance of the control. This
+    value will also determine the default itemHeight, itemSeparatorHeight,
+    menuHeightPadding, and submenuOffsetX if you don't explicitly set these
+    properties.
+
+    Your theme can override the default values for each control size. For
+    example, to set the height of menu items for small menus, you could set
+    {{{
+      SC.MenuPane.SMALL_MENU_ITEM_HEIGHT = 10;
+    }}}
+
+    Changing the controlSize once the menu is instantiated has no effect.
+
+    @type String
+    @default SC.REGULAR_CONTROL_SIZE
+  */
+  controlSize: SC.REGULAR_CONTROL_SIZE,
+
+  /**
+    The height of each menu item, in pixels.
+
+    You can override this on a per-item basis by setting the (by default)
+    @height@ property on your object.
+
+    If you don't specify a value, the item height will be inferred from
+    controlSize.
+
+    @type Number
+    @default null
+  */
+  itemHeight: null,
+
+  /**
+    The height of separator menu items.
+
+    You can override this on a per-item basis by setting the (by default)
+    @height@ property on your object.
+
+    If you don't specify a value, the height of the separator menu items will
+    be inferred from controlSize.
+
+    @type Number
+    @default null
+  */
+  itemSeparatorHeight: null,
+
+  /**
+    The height of the menu pane.  This is updated every time menuItemViews
+    is recalculated.
+
+    @type Number
+    @isReadOnly
+  */
+  menuHeight: 0,
+
+  /**
+    The amount of padding to add to the height of the pane.
+
+    The first menu item is offset by half this amount, and the other half is
+    added to the height of the menu, such that a space between the top and the
+    bottom is created.
+
+    If you don't specify a value, the padding will be inferred from the
+    controlSize.
+
+    @type Number
+    @default null
+  */
+  menuHeightPadding: null,
+
+  /**
+    The amount of offset x while positioning submenu.
+
+    If you don't specify a value, the padding will be inferred from the
+    controlSize.
+
+    @type Number
+    @default null
+  */
+  submenuOffsetX: null,
+
+  /**
+    The last menu item to be selected by the user.
+
+    You can place an observer on this property to be notified when the user
+    makes a selection.
+
+    @type SC.Object
+    @default null
+    @isReadOnly
+  */
+  selectedItem: null,
+
+  /**
+    The view class to use when creating new menu item views.
+
+    The menu pane will automatically create an instance of the view class you
+    set here for each item in the @items@ array. You may provide your own
+    subclass for this property to display the customized content.
+
+    @default SC.MenuItemView
+    @type SC.View
+  */
+  exampleView: SC.MenuItemView,
+
+  /**
+    The view or element to which the menu will anchor itself.
+
+    When the menu pane is shown, it will remain anchored to the view you
+    specify, even if the window is resized. You should specify the anchor as a
+    parameter when calling @popup()@, rather than setting it directly.
+
+    @type SC.View
+    @isReadOnly
+  */
+  anchor: null,
+
+  /**
+    YES if this menu pane was generated by a parent SC.MenuPane.
+
+    @type Boolean
+    @isReadOnly
+  */
+  isSubMenu: NO,
+
+  /**
+    Whether the title of menu items should be localized before display.
+
+    @type Boolean
+    @default YES
+  */
+  localize: YES,
+  
+  /**
+    Whether or not this menu pane should accept the “current menu pane”
+    designation when visible, which is the highest-priority pane when routing
+    events.  Generally you want this set to YES so that your menu pane can
+    intercept keyboard events.
+
+    @type Boolean
+    @default YES
+  */
+  acceptsMenuPane: YES,
+  
+  /**
+    Disable context menu.
+  */
+  isContextMenuEnabled: NO,
+
+  // ..........................................................
+  // METHODS
+  //
+
+  /**
+    Makes the menu visible and adds it to the HTML document.
+
+    If you provide a view or element as the first parameter, the menu will
+    anchor itself to the view, and intelligently reposition itself if the
+    contents of the menu exceed the available space.
+
+    @param SC.View anchorViewOrElement the view or element to which the menu
+    should anchor.
+    @param preferMatrix The prefer matrix used to position the pane.
+    (optional)
+  */
+  popup: function(anchorViewOrElement, preferMatrix) {
+    var anchor;
+    this.beginPropertyChanges();
+    if (anchorViewOrElement) {
+      anchor = anchorViewOrElement.isView ? anchorViewOrElement.get('layer') : anchorViewOrElement;
+    }
+    this.set('anchorElement',anchor) ;
+    this.set('anchor',anchorViewOrElement);
+    if (preferMatrix) this.set('preferMatrix',preferMatrix) ;
+
+    this.adjust('height', this.get('menuHeight'));
+    this.positionPane();
+
+    // Because panes themselves do not receive key events, we need to set the
+    // pane's defaultResponder to itself. This way key events can be
+    // interpreted in keyUp.
+    this.set('defaultResponder', this);
+    this.endPropertyChanges();
+
+    this.append();
+  },
+
+  /**
+    Removes the menu from the screen.
+
+    @returns {SC.MenuPane} receiver
+  */
+  remove: function() {
+    var parentMenu = this.get('parentMenu');
+
+    this.set('currentMenuItem', null);
+    this.closeOpenMenus();
+    this.resignMenuPane();
+
+    if (parentMenu) {
+      parentMenu.becomeMenuPane();
+    }
+
+    return sc_super();
+  },
+
+  // ..........................................................
+  // ITEM KEYS
+  //
+
+  /**
+    The name of the property that contains the title for each item.
+
+    @type String
+    @default "title"
+    @commonTask Menu Item Properties
+  */
+  itemTitleKey: 'title',
+
+  /**
+    The name of the property that determines whether the item is enabled.
+
+    @type String
+    @default "isEnabled"
+    @commonTask Menu Item Properties
+  */
+  itemIsEnabledKey: 'isEnabled',
+
+  /**
+    The name of the property that contains the value for each item.
+
+    @type String
+    @default "value"
+    @commonTask Menu Item Properties
+  */
+  itemValueKey: 'value',
+
+  /**
+    The name of the property that contains the icon for each item.
+
+    @type String
+    @default "icon"
+    @commonTask Menu Item Properties
+  */
+  itemIconKey: 'icon',
+
+  /**
+    The name of the property that contains the height for each item.
+
+    @readOnly
+    @type String
+    @default "height"
+    @commonTask Menu Item Properties
+  */
+  itemHeightKey: 'height',
+
+  /**
+    The name of the property that contains an optional submenu for each item.
+
+    @type String
+    @default "subMenu"
+    @commonTask Menu Item Properties
+  */
+  itemSubMenuKey: 'subMenu',
+
+  /**
+    The name of the property that determines whether the item is a menu
+    separator.
+
+    @type String
+    @default "separator"
+    @commonTask Menu Item Properties
+  */
+  itemSeparatorKey: 'separator',
+
+  /**
+    The name of the property that contains the target for the action that is triggered when the user clicks the menu item.
+
+    Note that this property is ignored if the menu item has a submenu.
+
+    @type String
+    @default "target"
+    @commonTask Menu Item Properties
+  */
+  itemTargetKey: 'target',
+
+  /**
+    The name of the property that contains the action that is triggered when
+    the user clicks the menu item.
+
+    Note that this property is ignored if the menu item has a submenu.
+
+    @type String
+    @default "action"
+    @commonTask Menu Item Properties
+  */
+  itemActionKey: 'action',
+
+  /**
+    The name of the property that determines whether the menu item should
+    display a checkbox.
+
+    @type String
+    @default "checkbox"
+    @commonTask Menu Item Properties
+  */
+  itemCheckboxKey: 'checkbox',
+
+  /**
+    The name of the property that contains the shortcut to be displayed.
+
+    The shortcut should communicate the keyboard equivalent to the user.
+
+    @type String
+    @default "shortcut"
+    @commonTask Menu Item Properties
+  */
+  itemShortCutKey: 'shortcut',
+
+  /**
+    The name of the property that contains the key equivalent of the menu
+    item.
+
+    The action of the menu item will be fired, and the menu pane's
+    @selectedItem@ property set to the menu item, if the user presses this
+    key combination on the keyboard.
+
+    @type String
+    @default "keyEquivalent"
+    @commonTask Menu Item Properties
+  */
+  itemKeyEquivalentKey: 'keyEquivalent',
+
+  /**
+    The name of the property that determines whether menu flash should be
+    disabled.
+
+    When you click on a menu item, it will flash several times to indicate
+    selection to the user. Some browsers block windows from opening outside of
+    a mouse event, so you may wish to disable menu flashing if the action of
+    the menu item should open a new window.
+
+    @type String
+    @default "disableMenuFlash"
+    @commonTask Menu Item Properties
+  */
+  itemDisableMenuFlashKey: 'disableMenuFlash',
+
+  /**
+    The array of keys used by SC.MenuItemView when inspecting your menu items
+    for display properties.
+
+    @private
+    @isReadOnly
+    @property Array
+  */
+  menuItemKeys: 'itemTitleKey itemValueKey itemIsEnabledKey itemIconKey itemSeparatorKey itemActionKey itemCheckboxKey itemShortCutKey itemHeightKey itemSubMenuKey itemKeyEquivalentKey itemTargetKey'.w(),
+
+  // ..........................................................
+  // INTERNAL PROPERTIES
+  //
+
+  /** @private */
+  preferType: SC.PICKER_MENU,
+
+  /**
+    Create a modal pane beneath the menu that will prevent any mouse clicks
+    that fall outside the menu pane from triggering an inadvertent action.
+
+    @type Boolean
+    @private
+  */
+  isModal: YES,
+
+  /**
+    The view that contains the MenuItemViews that are visible on screen.
+
+    This is created and set in createChildViews.
+
+    @property SC.View
+    @private
+  */
+  _menuView: null,
+
+  // ..........................................................
+  // INTERNAL METHODS
+  //
+
+  /**
+    If an itemHeight, itemSeparatorHeight, or menuHeightPadding have not been
+    explicitly set, we set them here based on the controlSize.
+
+    @returns {SC.MenuPane} the newly instantiated menu pane
+    @private
+  */
+  init: function() {
+    switch (this.get('controlSize')) {
+      case SC.TINY_CONTROL_SIZE:
+        this.setIfNull('itemHeight', SC.MenuPane.TINY_MENU_ITEM_HEIGHT);
+        this.setIfNull('itemSeparatorHeight', SC.MenuPane.TINY_MENU_ITEM_SEPARATOR_HEIGHT);
+        this.setIfNull('menuHeightPadding', SC.MenuPane.TINY_MENU_HEIGHT_PADDING);
+        this.setIfNull('submenuOffsetX', SC.MenuPane.TINY_SUBMENU_OFFSET_X);
+        break;
+      case SC.SMALL_CONTROL_SIZE:
+        this.setIfNull('itemHeight', SC.MenuPane.SMALL_MENU_ITEM_HEIGHT);
+        this.setIfNull('itemSeparatorHeight', SC.MenuPane.SMALL_MENU_ITEM_SEPARATOR_HEIGHT);
+        this.setIfNull('menuHeightPadding', SC.MenuPane.SMALL_MENU_HEIGHT_PADDING);
+        this.setIfNull('submenuOffsetX', SC.MenuPane.SMALL_SUBMENU_OFFSET_X);
+        break;
+      case SC.REGULAR_CONTROL_SIZE:
+        this.setIfNull('itemHeight', SC.MenuPane.REGULAR_MENU_ITEM_HEIGHT);
+        this.setIfNull('itemSeparatorHeight', SC.MenuPane.REGULAR_MENU_ITEM_SEPARATOR_HEIGHT);
+        this.setIfNull('menuHeightPadding', SC.MenuPane.REGULAR_MENU_HEIGHT_PADDING);
+        this.setIfNull('submenuOffsetX', SC.MenuPane.REGULAR_SUBMENU_OFFSET_X);
+        break;
+      case SC.LARGE_CONTROL_SIZE:
+        this.setIfNull('itemHeight', SC.MenuPane.LARGE_MENU_ITEM_HEIGHT);
+        this.setIfNull('itemSeparatorHeight', SC.MenuPane.LARGE_MENU_ITEM_SEPARATOR_HEIGHT);
+        this.setIfNull('menuHeightPadding', SC.MenuPane.LARGE_MENU_HEIGHT_PADDING);
+        this.setIfNull('submenuOffsetX', SC.MenuPane.LARGE_SUBMENU_OFFSET_X);
+        break;
+      case SC.HUGE_CONTROL_SIZE:
+        this.setIfNull('itemHeight', SC.MenuPane.HUGE_MENU_ITEM_HEIGHT);
+        this.setIfNull('itemSeparatorHeight', SC.MenuPane.HUGE_MENU_ITEM_SEPARATOR_HEIGHT);
+        this.setIfNull('menuHeightPadding', SC.MenuPane.HUGE_MENU_HEIGHT_PADDING);
+        this.setIfNull('submenuOffsetX', SC.MenuPane.HUGE_SUBMENU_OFFSET_X);
+        break;
+    }
+
+    return sc_super();
+  },
+
+  /**
+    Helper method that only sets a property if it is null.
+
+    @param {String} key the property to set
+    @param {Object} value
+    @private
+  */
+  setIfNull: function(key, value) {
+    if (this.get(key) === null) {
+      this.set(key, value);
+    }
+  },
+
+  /** @private
+    The render method is responsible for adding the control size class
+    name to the menu pane.
+
+    @param {SC.RenderContext} context the render context
+    @param {Boolean} firstTime YES if this is creating a layer
+  */
+  render: function(context, firstTime) {
+    context.addClass(this.get('controlSize'));
+
+    return sc_super();
+  },
+
+  /**
+    Creates the child scroll view, and sets its contentView to a new
+    view.  This new view is saved and managed by the SC.MenuPane,
+    and contains the visible menu items.
+
+    @private
+    @returns {SC.View} receiver
+  */
+  createChildViews: function() {
+    var scroll, menuView, menuItemViews;
+
+    scroll = this.createChildView(SC.MenuScrollView, {
+      borderStyle: SC.BORDER_NONE,
+      controlSize: this.get('controlSize')
+    });
+
+    menuView = this._menuView = SC.View.create();
+    menuItemViews = this.get('menuItemViews');
+    menuView.set('layout', { top: 0, left: 0, height : this.get('menuHeight')});
+    menuView.replaceAllChildren(menuItemViews);
+    scroll.set('contentView', menuView);
+
+    this.childViews = [scroll];
+
+    return this;
+  },
+
+  /**
+    When the pane is attached to a DOM element in the window, set up the
+    view to be visible in the window and register with the RootResponder.
+
+    We don't call sc_super() here because PanelPane sets the current pane to
+    be the key pane when attached.
+
+    @returns {SC.MenuPane} receiver
+  */
+  paneDidAttach: function() {
+    // hook into root responder
+    var responder = (this.rootResponder = SC.RootResponder.responder);
+    responder.panes.add(this);
+
+    // set currentWindowSize
+    this.set('currentWindowSize', responder.computeWindowSize()) ;
+
+    // update my own location
+    this.set('isPaneAttached', YES) ;
+    this.parentViewDidChange() ;
+
+    //notify that the layers have been appended to the document
+    this._notifyDidAppendToDocument();
+
+    this.becomeMenuPane();
+
+    return this ;
+  },
+
+  /**
+    Make the pane the menu pane. When you call this, all key events will
+    temporarily be routed to this pane. Make sure that you call
+    resignMenuPane; otherwise all key events will be blocked to other panes.
+
+    @returns {SC.Pane} receiver
+  */
+  becomeMenuPane: function() {
+    if (this.rootResponder) this.rootResponder.makeMenuPane(this) ;
+    return this ;
+  },
+
+  /**
+    Remove the menu pane status from the pane.  This will simply set the 
+    menuPane on the rootResponder to null.
+
+    @returns {SC.Pane} receiver
+  */
+  resignMenuPane: function() {
+    if (this.rootResponder) this.rootResponder.makeMenuPane(null);
+    return this ;
+  },
+
+  /**
+    The array of child menu item views that compose the menu.
+
+    This computed property parses @displayItems@ and constructs an SC.MenuItemView (or whatever class you have set as the @exampleView@) for every item.
+
+    @property
+    @type Array
+    @readOnly
+  */
+  menuItemViews: function() {
+    var views = [], items = this.get('displayItems'),
+        exampleView = this.get('exampleView'), item, view,
+        height, heightKey, separatorKey, defaultHeight, separatorHeight,
+        menuHeight, menuHeightPadding, keyEquivalentKey, keyEquivalent,
+        keyArray, idx,
+        len;
+
+    if (!items) return views; // return an empty array
+
+    heightKey = this.get('itemHeightKey');
+    separatorKey = this.get('itemSeparatorKey');
+    defaultHeight = this.get('itemHeight');
+    keyEquivalentKey = this.get('itemKeyEquivalentKey');
+    separatorHeight = this.get('itemSeparatorHeight');
+
+    menuHeightPadding = Math.floor(this.get('menuHeightPadding')/2);
+    menuHeight = menuHeightPadding;
+
+    keyArray = this.menuItemKeys.map(SC._menu_fetchKeys, this);
+
+    len = items.get('length');
+    for (idx = 0; idx < len; idx++) {
+      item = items[idx];
+      height = item.get(heightKey);
+      if (!height) {
+        height = item.get(separatorKey) ? separatorHeight : defaultHeight;
+      }
+      view = this._menuView.createChildView(exampleView, {
+        layout: { height: height, top: menuHeight },
+        contentDisplayProperties: keyArray,
+        content: item,
+        parentMenu: this
+      });
+      views[idx] = view;
+      menuHeight += height;
+
+      keyEquivalent = item.get(keyEquivalentKey);
+      if (keyEquivalent) {
+        this._keyEquivalents[keyEquivalent] = view;
+      }
+    }
+
+    this.set('menuHeight', menuHeight+menuHeightPadding);
+    return views;
+  }.property('displayItems').cacheable(),
+
+  /**
+    Returns the menu item view for the content object at the specified index.
+
+    @param {Number} idx the item index
+    @returns {SC.MenuItemView} instantiated view
+  */
+  menuItemViewForContentIndex: function(idx) {
+    var menuItemViews = this.get('menuItemViews');
+
+    if (!menuItemViews) return undefined;
+    return menuItemViews.objectAt(idx);
+  },
+
+  /**
+    An associative array of the shortcut keys. The key is the shortcut in the
+    form 'ctrl_z', and the value is the menu item of the action to trigger.
+
+    @private
+  */
+  _keyEquivalents: { },
+
+  /**
+    If this is a submenu, this property corresponds to the
+    top-most parent menu. If this is the root menu, it returns
+    itself.
+
+    @type SC.MenuPane
+    @isReadOnly
+    @property
+  */
+  rootMenu: function() {
+    if (this.get('isSubMenu')) return this.getPath('parentMenu.rootMenu');
+    return this;
+  }.property('isSubMenu').cacheable(),
+
+  /**
+    Close the menu if the user resizes the window.
+
+    @private
+  */
+  windowSizeDidChange: function(oldSize, newSize) {
+    this.remove();
+    return sc_super();
+  },
+
+  /**
+    Returns an array of normalized display items.
+
+    Because the items property can be provided as either an array of strings,
+    or an object with key-value pairs, or an exotic mish-mash of both, we need
+    to normalize it for our display logic.
+
+    If an @items@ member is an object, we can assume it is formatted properly
+    and leave it as-is.
+
+    If an @items@ member is a string, we create a hash with the title value
+    set to that string, and some sensible defaults for the other properties.
+
+    As a last resort, if an @items@ member is an array, we have a legacy
+    handler that converts the array into a hash. This behavior is deprecated
+    and is not guaranteed to be supported in the future.
+
+    A side effect of running this computed property is that the menuHeight
+    property is updated.
+
+    @displayItems@ should never be set directly; instead, set @items@ and
+    @displayItems@ will update automatically.
+
+    @property
+    @type Array
+    @isReadOnly
+  */
+  displayItems: function() {
+    var items = this.get('items'), localize = this.get('localize'),
+        itemHeight = this.get('itemHeight'), len,
+        ret = [], idx, item, itemType;
+
+    if (!items) return null;
+
+    len = items.get('length');
+
+    // Loop through the items property and transmute as needed, then
+    // copy the new objects into the ret array.
+    for (idx = 0; idx < len; idx++) {
+      item = items.objectAt(idx) ;
+
+      // fast track out if we can't do anything with this item
+      if (!item) continue;
+
+      itemType = SC.typeOf(item);
+      if (itemType === SC.T_STRING) {
+        item = SC.Object.create({ title: item,
+                                  value: item,
+                                  isEnabled: YES
+                               });
+      } else if (itemType === SC.T_HASH) {
+        item = SC.Object.create(item);
+      } else if (itemType === SC.T_ARRAY) {
+        item = this.convertArrayMenuItemToObject(item);
+      }
+      item.contentIndex = idx;
+
+      ret.push(item);
+    }
+
+    return ret;
+  }.property('items').cacheable(),
+
+  _sc_menu_itemsDidChange: function() {
+    var views = this.get('menuItemViews');
+    this._menuView.replaceAllChildren(views);
+    this._menuView.adjust('height', this.get('menuHeight'));
+  }.observes('items'),
+
+  /**
+    Takes an array of values and places them in a hash that can be used
+    to render a menu item.
+
+    The mapping goes a little something like this:
+    0: title
+    1: value
+    2: isEnabled
+    3: icon
+    4: isSeparator
+    5: action
+    6: isCheckbox
+    7: isShortCut
+    8: isBranch
+    9: itemHeight
+    10: subMenu
+    11: keyEquivalent
+    12: target
+
+    @private
+  */
+  convertArrayMenuItemToObject: function(item) {
+    SC.Logger.warn('Support for Array-based menu items has been deprecated.  Please update your menus to use a hash.');
+
+    var keys, fetchKeys = SC._menu_fetchKeys,
+        fetchItem = SC._menu_fetchItem, cur, ret = SC.Object.create(), idx, loc;
+
+    // Gets an array of all of the value keys
+    keys = this.menuItemKeys.map(fetchKeys, this);
+
+    // title
+    ret[keys[0]] = item[0];
+    ret[keys[1]] = item[1];
+    ret[keys[2]] = item[2];
+    ret[keys[3]] = item[3];
+    ret[keys[4]] = item[4];
+    ret[keys[5]] = item[5];
+    ret[keys[6]] = item[6];
+    ret[keys[7]] = item[7];
+    ret[keys[8]] = item[8];
+    ret[keys[9]] = item[9];
+    ret[keys[10]] = item[10];
+    ret[keys[11]] = item[11];
+    ret[keys[12]] = item[12];
+
+    return ret;
+  },
+
+  currentMenuItem: function(key, value) {
+    if (value !== undefined) {
+      if (this._currentMenuItem !== null) {
+        this.set('previousMenuItem', this._currentMenuItem);
+      }
+      this._currentMenuItem = value;
+      this.setPath('rootMenu.targetMenuItem', value);
+
+      return value;
+    }
+
+    return this._currentMenuItem;
+  }.property().cacheable(),
+
+  _sc_menu_currentMenuItemDidChange: function() {
+    var currentMenuItem = this.get('currentMenuItem'),
+        previousMenuItem = this.get('previousMenuItem');
+
+    if (previousMenuItem) {
+      if (previousMenuItem.get('hasSubMenu') && currentMenuItem === null) {
+
+      } else {
+        previousMenuItem.resignFirstResponder();
+        this.closeOpenMenusFor(previousMenuItem);
+      }
+    }
+
+    // Scroll to the selected menu item if it's not visible on screen.
+    // This is useful for keyboard navigation and programmaticaly selecting
+    // the selected menu item, as in SelectButtonView.
+    if (currentMenuItem && currentMenuItem.get('isEnabled')) {
+      currentMenuItem.scrollToVisible();
+    }
+  }.observes('currentMenuItem'),
+
+  closeOpenMenusFor: function(menuItem) {
+    if (!menuItem) return;
+
+    var menu = menuItem.get('parentMenu');
+
+    // Close any open menus if a root menu changes
+    while (menu && menuItem) {
+      menu = menuItem.get('subMenu');
+      if (menu) {
+        menu.remove();
+        menuItem.resignFirstResponder();
+        menuItem = menu.get('previousMenuItem');
+      }
+    }
+  },
+
+  closeOpenMenus: function() {
+    this.closeOpenMenusFor(this.get('previousMenuItem'));
+  },
+
+  //Mouse and Key Events
+
+  /** @private */
+  mouseDown: function(evt) {
+    this.modalPaneDidClick();
+    return YES ;
+  },
+
+  /** @private
+    Note when the mouse has entered, so that if this is a submenu,
+    the menu item to which it belongs knows whether to maintain its highlight
+    or not.
+
+    @param {Event} evt
+  */
+  mouseEntered: function(evt) {
+    this.set('mouseHasEntered', YES);
+  },
+
+  keyUp: function(evt) {
+    var ret = this.interpretKeyEvents(evt) ;
+    return !ret ? NO : ret ;
+  },
+
+  /**
+    Selects the next enabled menu item above the currently
+    selected menu item when the up-arrow key is pressed.
+
+    @private
+  */
+  moveUp: function() {
+    var currentMenuItem = this.get('currentMenuItem'),
+        items = this.get('menuItemViews'),
+        currentIndex, parentMenu, idx;
+
+    if (!currentMenuItem) {
+      idx = items.get('length')-1;
+    } else {
+      currentIndex = currentMenuItem.getPath('content.contentIndex');
+      if (currentIndex === 0) return YES;
+      idx = currentIndex-1;
+    }
+
+    while (idx >= 0) {
+      if (items[idx].get('isEnabled')) {
+        this.set('currentMenuItem', items[idx]);
+        items[idx].becomeFirstResponder();
+        break;
+      }
+      idx--;
+    }
+
+    return YES;
+  },
+
+  /**
+    Selects the next enabled menu item below the currently
+    selected menu item when the down-arrow key is pressed.
+
+    @private
+  */
+  moveDown: function() {
+    var currentMenuItem = this.get('currentMenuItem'),
+        items = this.get('menuItemViews'),
+        len = items.get('length'),
+        currentIndex, parentMenu, idx;
+
+    if (!currentMenuItem) {
+      idx = 0;
+    } else {
+      currentIndex = currentMenuItem.getPath('content.contentIndex');
+      if (currentIndex === len) return YES;
+      idx = currentIndex+1;
+    }
+
+    while (idx < len) {
+      if (items[idx].get('isEnabled')) {
+        this.set('currentMenuItem', items[idx]);
+        items[idx].becomeFirstResponder();
+        break;
+      }
+      idx++;
+    }
+
+    return YES;
+  },
+
+  insertText: function(chr, evt) {
+    var timer = this._timer, keyBuffer = this._keyBuffer;
+
+    if (timer) {
+      timer.invalidate();
+    }
+    timer = this._timer = SC.Timer.schedule({
+      target: this,
+      action: 'clearKeyBuffer',
+      interval: 500,
+      isPooled: NO
+    });
+
+    keyBuffer = keyBuffer || '';
+    keyBuffer += chr.toUpperCase();
+
+    this.selectMenuItemForString(keyBuffer);
+    this._keyBuffer = keyBuffer;
+
+    return YES;
+  },
+
+  performKeyEquivalent: function(keyEquivalent) {
+    //If menu is not visible
+    if (!this.get('isVisibleInWindow')) return NO;
+    
+    // Look for menu item that has this key equivalent
+    var menuItem = this._keyEquivalents[keyEquivalent];
+
+    // If found, have it perform its action
+    if (menuItem) {
+      menuItem.performAction(YES);
+      return YES;
+    }
+
+    // If escape key or the enter key was pressed and no menu item handled it,
+    // close the menu pane and return YES that the event was handled
+    if (keyEquivalent === 'escape'|| keyEquivalent === 'return') {
+      this.remove();
+      return YES;
+    }
+
+    return NO;
+
+  },
+
+  selectMenuItemForString: function(buffer) {
+    var items = this.get('menuItemViews'), item, title, idx, len, bufferLength;
+    if (!items) return;
+
+    bufferLength = buffer.length;
+    len = items.get('length');
+    for (idx = 0; idx < len; idx++) {
+      item = items.objectAt(idx);
+      title = item.get('title');
+
+      if (!title) continue;
+
+      title = title.replace(/ /g,'').substr(0,bufferLength).toUpperCase();
+      if (title === buffer) {
+        this.set('currentMenuItem', item);
+        item.becomeFirstResponder();
+        break;
+      }
+    }
+  },
+
+  /**
+    Clear the key buffer if the user does not enter any text after a certain
+    amount of time.
+
+    This is called by the timer created in the insertText method.
+
+    @private
+  */
+  clearKeyBuffer: function() {
+    this._keyBuffer = '';
+  },
+
+  /**
+    Close the menu and any open submenus if the user clicks outside the menu.
+
+    Because only the root-most menu has a modal pane, this will only ever get
+    called once.
+
+    @returns Boolean
+    @private
+  */
+  modalPaneDidClick: function(evt) {
+    this.remove();
+
+    return YES;
+  }
+});
+
+SC._menu_fetchKeys = function(k) {
+  return this.get(k) ;
+};
+SC._menu_fetchItem = function(k) {
+  if (!k) return null ;
+  return this.get ? this.get(k) : this[k] ;
+};
+
+/**
+  Default metrics for the different control sizes.
+*/
+SC.MenuPane.TINY_MENU_ITEM_HEIGHT = 10;
+SC.MenuPane.TINY_MENU_ITEM_SEPARATOR_HEIGHT = 2;
+SC.MenuPane.TINY_MENU_HEIGHT_PADDING = 2;
+SC.MenuPane.TINY_SUBMENU_OFFSET_X = 0;
+
+SC.MenuPane.SMALL_MENU_ITEM_HEIGHT = 16;
+SC.MenuPane.SMALL_MENU_ITEM_SEPARATOR_HEIGHT = 7;
+SC.MenuPane.SMALL_MENU_HEIGHT_PADDING = 4;
+SC.MenuPane.SMALL_SUBMENU_OFFSET_X = 2;
+
+SC.MenuPane.REGULAR_MENU_ITEM_HEIGHT = 20;
+SC.MenuPane.REGULAR_MENU_ITEM_SEPARATOR_HEIGHT = 9;
+SC.MenuPane.REGULAR_MENU_HEIGHT_PADDING = 6;
+SC.MenuPane.REGULAR_SUBMENU_OFFSET_X = 2;
+
+SC.MenuPane.LARGE_MENU_ITEM_HEIGHT = 60;
+SC.MenuPane.LARGE_MENU_ITEM_SEPARATOR_HEIGHT = 20;
+SC.MenuPane.LARGE_MENU_HEIGHT_PADDING = 0;
+SC.MenuPane.LARGE_SUBMENU_OFFSET_X = 4;
+
+SC.MenuPane.HUGE_MENU_ITEM_HEIGHT = 20;
+SC.MenuPane.HUGE_MENU_ITEM_SEPARATOR_HEIGHT = 9;
+SC.MenuPane.HUGE_MENU_HEIGHT_PADDING = 0;
+SC.MenuPane.HUGE_SUBMENU_OFFSET_X = 0;
+
+// If a menu pane exceeds the height of the viewport, it will
+// be truncated to fit. This value determines the amount by which
+// the menu will be offset from the top and bottom of the viewport.
+SC.MenuPane.VERTICAL_OFFSET = 23;