WinJS.UI.Menu object

Displays a lightweight popup that is used to temporarily show menu commands related to what the user is currently doing. You should only show a menu in response to a user tap or click. Unlike a MessageDialog, a menu is always dismissed when the user taps or clicks outside of it.

Note Use a context menu, not a flyout, for contextual actions on a text selection.

Syntax

<div data-win-control="WinJS.UI.Menu" />
var object = new WinJS.UI.Menu();

Members

The Menu object has these types of members:

  • Constructors
  • Events
  • Methods
  • Properties

Constructors

The Menu object has these constructors.

Constructor Description
Menu

Creates a new Menu object.

Events

The Menu object has these events.

Event Description
onafterhide

Occurs immediately after the Menu is hidden.

onaftershow

Occurs immediately after the Menu is displayed.

onbeforehide

Occurs before the Menu is hidden

onbeforeshow

Occurs immediately before a hidden Menu is displayed.

Methods

The Menu object has these methods.

Method Description
addEventListener

Registers an event handler for the specified event.

dispose

Releases resources held by this Menu. Call this method when the Menu is no longer needed. After calling this method, the Menu becomes unusable.

getCommandById

Returns the MenuCommand object identified by id.

hide

Hides the Menu, if visible, regardless of other states.

hideCommands

Hides the specified commands of the Menu.

removeEventListener

Removes an event handler that the addEventListener method registered.

show

Shows the Menu, if hidden, regardless of other states.

showat

Shows the Menu, if hidden, regardless of other states, top and left aligned at specified coordinates or at the location of the mouse event object.

showCommands

Shows the specified commands of the Menu.

showOnlyCommands

Shows the specified commands of the Menu while hiding all other commands.

Properties

The Menu object has these properties.

Property Access type Description

alignment

Read/write

Gets or sets the default alignment to be used for this Menu.

anchor

Read/write

Gets or sets the default anchor to be used for this Menu.

commands

Write-only

Sets the MenuCommand objects that appear in the menu

disabled

Read/write

Gets or sets a value that indicates whether the Menu is disabled.

element

Read-only

Gets the DOM element that hosts the Menu.

hidden

Read-only

Gets a value that indicates whether the Menu is hidden or in the process of becoming hidden.

placement

Read/write

Gets or sets the placement to be used for this Menu relative to the target object.

Remarks

Known Issues

Menus should be direct children of document.body. Otherwise, it is possible to mask event detection on the Menu due to stacking context effects. This is because event detection for other elements is blocked while the Menu is open. So, if the Flyout is a child of one of those blocked elements, it too will be blocked. This behavior is typical for all overlaying controls.

Styling the Menu

To customize a Menu, you can define your own styles for these CSS classes (defined by the Windows Library for JavaScript style sheets):

CSS class Description

win-command

Styles the commands in the Menu.

win-menu

Styles the entire Menu control.

Note There are several CSS classes that are shared between multiple WinJS controls. To limit your custom styles to a specific control, assign the control an ID or custom class name and use that as part of your style selector.

Requirements

Minimum WinJS version

WinJS 1.0

Namespace

WinJS.UI

See also

WinJS.UI Namespace

MenuCommand

Flyout

Displaying popups

Laying out your UI

HTML flyout control sample

Designers

Command patterns

Flyout

Guidelines for flyouts

Context menu

Guidelines for context menus