[This documentation is preliminary and is subject to change.]

Shows the context menu at the specified client coordinates.

Syntax

popupMenu.showAsync(invocationPoint).done( /* Your success and error handlers */ );

Parameters

invocationPoint

Type: Point

The coordinates (in DIPs), relative to the window, of the user's finger or mouse pointer when the oncontextmenu event fired. The menu is placed above and centered on this point.

Note  For VB, C#, and C++, this window is the CoreWindow associated with the thread that is calling the context menu.

Return value

Type: IAsyncOperation<IUICommand>

A IUICommand object that represents the context menu command that was invoked by the user, after the ShowAsync call completes.

If no command is invoked, ShowAsync returns null.

Remarks

You can see complete code examples that demonstrate how to create and customize context menus in the Context menu sample on the Metro style app sample home page.

Examples

Before you can show a context menu, you must add an event listener for the oncontextmenu event. For example, the Context menu sample listens for the event on specific HTML elements, and then calls the scenario1AttachmentHandler function.

document.getElementById("scenario1Attachment").addEventListener("contextmenu", /*@static_cast(EventListener)*/scenario1AttachmentHandler, false);

The following example from the Context menu sample shows a context menu with a command that specifies a handler.

menu.commands.append(new Windows.UI.Popups.UICommand("Save attachment", function (command) {
    // Add command handler code here
    sdkSample.displayStatus("'" + command.label + "' selected");
}));
menu.showAsync({ x: e.clientX, y: e.clientY }).then(function(invokedCommand) {
    if (invokedCommand === null) {
        // The command is null if no command was invoked.
        sdkSample.displayStatus("Context menu dismissed");
    }
});

Set the Point coordinates to the clientX and clientY values on the oncontextmenu event (e in the example). This ensures that the context menu appears where the user's pointer or finger was located when the oncontextmenu event fired.

Additionally, make sure you check that a command was invoked and process that case as appropriate for your app. If the UICommand that is invoked has a callback function (onSaveAttachment in the example), the callback function will be executed. Otherwise, you may need to use UICommand.Id to identify and process the invoked command.

Requirements

See also

Adding context menus

Context menu sample

Guidelines and checklist for context menus

Reference

IUICommand

oncontextmenu

Point

PopupMenu

PopupMenu.Commands

UICommand

Build date: 5/22/2012