PopupMenu PopupMenu PopupMenu PopupMenu Class

Definition

Represents a context menu.

public : sealed class PopupMenu : IPopupMenupublic sealed class PopupMenu : IPopupMenuPublic NotInheritable Class PopupMenu Implements IPopupMenu// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

Provide users with a context menu by adding an event listener for the "contextmenu" event. For example, the Context menu sample listens for the event on specific HTML elements, and then calls the scenario1AttachmentHandler function.

document.getElementById("attachment").addEventListener("contextmenu", attachmentHandler, false);

To customize the context menu, call preventDefault on the event to suppress the default, and then create a new, empty context menu menu as shown in the Context menu sample.

e.preventDefault(); // Prevent the default context menu.
var menu = new Windows.UI.Popups.PopupMenu();

Remarks

context menu can show a maximum of six commands. This limit helps to ensure that the context menu remains uncluttered, usable, and directly relevant to users.

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

Note

: This class is not agile, which means that you need to consider its threading model and marshaling behavior. For more info, see Threading and Marshaling (C++/CX) and Using Windows Runtime objects in a multithreaded environment (.NET).

Constructors

PopupMenu() PopupMenu() PopupMenu() PopupMenu()

Creates a new instance of the PopupMenu class.

public : PopupMenu()public PopupMenu()Public Sub New()// You can use this method in JavaScript.

Examples

To customize the context menu, call preventDefault on the oncontextmenu event (e in the example) to suppress the default context menu, and then create a new, empty context menu menu as shown in the Context menu sample.

e.preventDefault(); // Prevent the default context menu.
var menu = new Windows.UI.Popups.PopupMenu();

Remarks

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

See Also

Properties

Commands Commands Commands Commands

Gets the commands for the context menu.

public : IVector<IUICommand> Commands { get; }public IList<IUICommand> Commands { get; }Public ReadOnly Property Commands As IList<IUICommand>// You can use this property in JavaScript.
Value
IVector<IUICommand> IList<IUICommand> IList<IUICommand> IList<IUICommand>

The commands for the context menu.

Examples

Add your commands to the context menu after you create a new PopupMenu. Create a UICommand object for each command and append the commands to the context menu.

The Context menu sample creates and appends a new UICommand that specifies a handler function, which runs if the command is invoked.

menu.commands.append(new Windows.UI.Popups.UICommand("Open with", onOpenWith));

The Context menu sample also creates and appends a new UICommand that specifies a command identifier, which can be used to determine the command that has been invoked.

menu.commands.append(new Windows.UI.Popups.UICommand("Copy", null, 1));

The Context menu sample places a separator between its "Copy" and "Highlight" commands like this.

menu.commands.append(new Windows.UI.Popups.UICommand("Copy", null, 1));
menu.commands.append(new Windows.UI.Popups.UICommandSeparator);
menu.commands.append(new Windows.UI.Popups.UICommand("Highlight", null, 2));
menu.commands.append(new Windows.UI.Popups.UICommand("Look up", null, 3));

Remarks

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

See Also

Methods

ShowAsync(Point) ShowAsync(Point) ShowAsync(Point) ShowAsync(Point)

Shows the context menu at the specified client coordinates.

public : IAsyncOperation<IUICommand> ShowAsync(Point invocationPoint)public IAsyncOperation<IUICommand> ShowAsync(Point invocationPoint)Public Function ShowAsync(invocationPoint As Point) As IAsyncOperation( Of IUICommand )// You can use this method in JavaScript.
Parameters
invocationPoint
Point Point Point 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.

Returns

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.

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("attachment").addEventListener("contextmenu", attachmentHandler, false);
menu.commands.append(new Windows.UI.Popups.UICommand("Save attachment", onSaveAttachment));

// We don't want to obscure content, so pass in the position representing the selection area.
// We registered command callbacks; no need to handle the menu completion event
menu.showAsync(pageToWinRT(e.pageX, e.pageY)).then(function (invokedCommand) {
    if (invokedCommand === null) {
        // The command is null if no command was invoked.
        WinJS.log && WinJS.log("Context menu dismissed", "sample", "status");
    }
});

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.

Remarks

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

See Also

ShowForSelectionAsync(Rect) ShowForSelectionAsync(Rect) ShowForSelectionAsync(Rect) ShowForSelectionAsync(Rect)

Shows the context menu above the specified selection.

public : IAsyncOperation<IUICommand> ShowForSelectionAsync(Rect selection)public IAsyncOperation<IUICommand> ShowForSelectionAsync(Rect selection)Public Function ShowForSelectionAsync(selection As Rect) As IAsyncOperation( Of IUICommand )// You can use this method in JavaScript.
Parameters
selection
Rect Rect Rect Rect

The coordinates (in DIPs) of the selected rectangle, relative to the window. The context menu is placed directly above and centered on this rectangle such that selection is not covered.

Note

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

Returns

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

If no command is invoked, ShowForSelectionAsync returns null.

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("attachment").addEventListener("contextmenu", attachmentHandler, false);
// We don't want to obscure content, so pass in the position representing the selection area.
menu.showForSelectionAsync(clientToWinRTRect(document.selection.createRange().getBoundingClientRect())).then(function (invokedCommand) {
    if (invokedCommand !== null) {
        switch (invokedCommand.id) {
            case 1: // Copy
                var selectedText = window.getSelection();
                copyTextToClipboard(selectedText);
                var message = "'Copy' button clicked and '" + /*@static_cast(String)*/selectedText + "' copied to clipboard";
                WinJS.log && WinJS.log(message, "sample", "status");
                break;
            case 2: // Highlight
                // Add command handler code here.
                WinJS.log && WinJS.log("'Highlight' button clicked", "sample", "status");
                break;
            case 3: // Look up
                // Add command handler code here.
                WinJS.log && WinJS.log("'Look up' button clicked", "sample", "status");
                break;
            default:
                break;
        }
    } else {
        // The command is null if no command was invoked.
        WinJS.log && WinJS.log("Context menu dismissed", "sample", "status");
    }
});

Additionally, the Context menu sample uses two helper functions (getSelectionRect and getclientCoordinates) to set the coordinates for the selection rectangle.

// Converts from client to WinRT coordinates, which take scale factor into consideration.
function clientToWinRTRect(rect) {
    var zoomFactor = document.documentElement.msContentZoomFactor;
    return {
        x: (rect.left + document.documentElement.scrollLeft - window.pageXOffset) * zoomFactor,
        y: (rect.top + document.documentElement.scrollTop - window.pageYOffset) * zoomFactor,
        width: rect.width * zoomFactor,
        height: rect.height * zoomFactor
    };
}

Remarks

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

See Also

ShowForSelectionAsync(Rect, Placement) ShowForSelectionAsync(Rect, Placement) ShowForSelectionAsync(Rect, Placement) ShowForSelectionAsync(Rect, Placement)

Shows the context menu in the preferred placement relative to the specified selection.

public : IAsyncOperation<IUICommand> ShowForSelectionAsync(Rect selection, Placement preferredPlacement)public IAsyncOperation<IUICommand> ShowForSelectionAsync(Rect selection, Placement preferredPlacement)Public Function ShowForSelectionAsync(selection As Rect, preferredPlacement As Placement) As IAsyncOperation( Of IUICommand )// You can use this method in JavaScript.
Parameters
selection
Rect Rect Rect Rect

The coordinates (in DIPs) of the selected rectangle, relative to the window.

Note

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

preferredPlacement
Placement Placement Placement Placement

The preferred placement of the context menu relative to the selection rectangle.

The context menu is positioned in the preferredPlacement if the menu fits in the window and does not cover the selection. If the context menu does not fit in the preferred placement, another placement that does not cover the selection is used. If the context menu does not fit anywhere else, a placement that partially or wholly covers the selection is used.

Returns

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

If no command is invoked, ShowForSelectionAsync returns null.

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("attachment").addEventListener("contextmenu", attachmentHandler, false);
// Converts from client to WinRT coordinates, which take scale factor into consideration.
function clientToWinRTRect(rect) {
    var zoomFactor = document.documentElement.msContentZoomFactor;
    return {
        x: (rect.left + document.documentElement.scrollLeft - window.pageXOffset) * zoomFactor,
        y: (rect.top + document.documentElement.scrollTop - window.pageYOffset) * zoomFactor,
        width: rect.width * zoomFactor,
        height: rect.height * zoomFactor
    };
}

Remarks

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

See Also

See Also