Class: SC.MenuPane


Extends SC.PickerPane.

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.

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', checkbox: YES, keyEquivalent: 'ctrl_a' },
  { title: 'Selected Menu Item', keyEquivalent: ['backspace', 'delete'] },
  { 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
});

Observing User Selections

To determine when a user clicks on a menu item, you can observe the selectedItem property for changes.

Defined in: menu.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.PickerPane:
displayProperties, isAnchored, isModal, pointerOffset, preferMatrix, preferType, removeAction, removeTarget, renderDelegateName, repositionOnWindowResize
Fields borrowed from SC.PalettePane:
modalPane
Fields borrowed from SC.PanelPane:
acceptsKeyPane, ariaDescribedBy, ariaLabel, ariaLabelledBy, contentView, isPanelPane
Fields borrowed from SC.Pane:
currentWindowSize, firstResponder, isKeyPane, isMainPane, isPane, page, rootResponder, touchZ, wantsTouchIntercept, zIndex
Fields borrowed from SC.View:
acceptsFirstResponder, acceptsMultitouch, ariaHidden, attributeBindings, autoMixins, backgroundColor, childViewLayout, childViewLayoutOptions, childViews, childViewsNeedLayout, classNameBindings, concatenatedProperties, createdByParent, designMode, enabledState, firstKeyView, hasLayout, hasTouch, hasVisibility, isBuildingIn, isBuildingOut, isChildViewLayoutLive, isEnabled, isFixedHeight, isFixedPosition, isFixedSize, isFixedWidth, isKeyResponder, isTextSelectable, isView, isVisible, lastKeyView, layerLocationNeedsUpdate, layerNeedsUpdate, layout, modeAdjust, nextKeyView, pane, parentView, previousKeyView, shouldInheritCursor, shouldInheritEnabled, tagName, themeName, toolTip, touchBoundary, transitionAdjust, transitionAdjustOptions, transitionHide, transitionHideOptions, transitionIn, transitionInOptions, transitionOut, transitionOutOptions, transitionShow, transitionShowOptions, useStaticLayout
Fields borrowed from SC.Responder:
hasFirstResponder, isFirstResponder, responderContext
Fields borrowed from SC.Object:
isDestroyed, isObject, nextProperty, object, property, target, toInvalidate
Fields borrowed from SC.Observable:
isObservable
Fields borrowed from SC.DraggablePaneSupport:
isDraggablePane

Instance Methods

Field Detail

acceptsMenuPane Boolean

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.

Default value:
YES
anchor SC.View

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.

ariaRole String
The WAI-ARIA role for menu pane.
Default value:
'menu'
classNames Array
Default value:
['sc-menu']
See:
SC.View#classNames
controlSize String

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 by specifying them in the menuRenderDelegate. For example:

MyTheme.menuRenderDelegate = SC.BaseTheme.menuRenderDelegate.create({
  'sc-tiny-size': {
    itemHeight: 20,
    itemSeparatorHeight: 9,
    menuHeightPadding: 6,
    submenuOffsetX: 2
  }
});

Changing the controlSize once the menu is instantiated has no effect.

Default value:
SC.REGULAR_CONTROL_SIZE
escapeHTML Boolean
If true, title of menu items will be escaped to avoid scripting attacks.
Default value:
YES
exampleView SC.View

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 value:
SC.MenuItemView
isContextMenuEnabled Boolean
Disable context menu.
Default value:
NO
isSubMenu Boolean
`YES` if this menu pane was generated by a parent `SC.MenuPane`.
Default value:
NO
itemActionKey String

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.

Default value:
"action"
itemCheckboxKey String

The name of the property that determines whether the menu item should display a checkbox.

Default value:
"checkbox"
itemDisableMenuFlashKey String

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.

Default value:
"disableMenuFlash"
itemExampleViewKey String
The name of the property that determines whether a unique exampleView should be created for the item .
Default value:
"exampleView"
itemHeight Number

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.

Default value:
itemHeight from theme if present, or 20.
itemHeightKey String
The name of the property that contains the height for each item.
Default value:
"height"
itemIconKey String
The name of the property that contains the icon for each item.
Default value:
"icon"
itemIsEnabledKey String
The name of the property that determines whether the item is enabled.
Default value:
"isEnabled"
itemKeyEquivalentKey String

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.

Default value:
"keyEquivalent"
itemLayerIdKey String
The name of the property that determines whether layerID should be applied to the item .
Default value:
"layerId"
items Array

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.

Default value:
[]
itemSeparatorHeight Number

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.

Default value:
itemSeparatorHeight from theme, or 9.
itemSeparatorKey String

The name of the property that determines whether the item is a menu separator.

Default value:
"isSeparator"
itemShortCutKey String

The name of the property that contains the shortcut to be displayed.

The shortcut should communicate the keyboard equivalent to the user.

Default value:
"shortcut"
itemSubMenuKey String
The name of the property that contains an optional submenu for each item.
Default value:
"subMenu"
itemTargetKey String

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.

Default value:
"target"
itemTitleKey String
The name of the property that contains the title for each item.
Default value:
"title"
itemToolTipKey String
The name of the property that contains the tooltip for each item.
Default value:
"toolTip"
itemValueKey String
The name of the property that contains the value for each item.
Default value:
"value"
localize Boolean
Whether the title of menu items should be localized before display.
Default value:
YES
menuHeight Number

The height of the menu pane. This is updated every time menuItemViews is recalculated.

Default value:
0
menuHeightPadding Number

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.

Default value:
menuHeightPadding from theme, or 6
selectedItem SC.Object

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.

Default value:
null
submenuOffsetX Number

The amount of offset x while positioning submenu.

If you don't specify a value, the padding will be inferred from the controlSize.

Default value:
submenuOffsetX from theme, or 2
SC.MenuPane.TINY_MENU_ITEM_HEIGHT
Default metrics for the different control sizes.

Instance Method Detail

becomeMenuPane()

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
closeOpenMenus()
closeOpenMenusFor(menuItem)
Parameters:
menuItem
createMenuItemViews()

Processes the displayItems and creates menu item views for each item.

Override this method to change how menuItemViews is calculated.

Returns:
Array
currentMenuItem(key, value)
Parameters:
key
value
didAppendToDocument()

Called when the pane is attached. Takes on menu pane status.

We don't call sc_super() here because PanelPane sets the current pane to be the key pane when attached.

displayItems()

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.

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.

insertText(chr)
Parameters:
chr
keyUp(evt)
Parameters:
evt
menuItemViewForContentIndex(Number)
Returns the menu item view for the content object at the specified index.
Parameters:
Number
idx the item index
Returns:
SC.MenuItemView
instantiated view
menuItemViews()

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.

This calls createMenuItemViews. If you want to override this property, override that method.

popup(anchorViewOrElement, (preferMatrix))

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.

Parameters:
anchorViewOrElement SC.View
the view or element to which the menu should anchor.
(preferMatrix) Array
The prefer matrix used to position the pane.
resignMenuPane()

Remove the menu pane status from the pane. This will simply set the menuPane on the rootResponder to `null.

Returns:
SC.Pane
receiver
rootMenu()

If this is a submenu, this property corresponds to the top-most parent menu. If this is the root menu, it returns itself.

selectMenuItemForString(buffer)
Parameters:
buffer
willRemoveFromDocument()

Called when the pane is detached. Closes all submenus and resigns menu pane status.

We don't call sc_super() here because PanelPane resigns key pane when detached.

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)