PopupMenu PopupMenu PopupMenu PopupMenu Class

Represents a context menu.

Syntax

Declaration

public sealed class PopupMenupublic sealed class PopupMenuPublic NotInheritable Class 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).

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();

Constructors summary

Creates a new instance of the PopupMenu class.

Properties summary

Gets the commands for the context menu.

Methods summary

Shows the context menu at the specified client coordinates.

Shows the context menu above the specified selection.

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

Constructors

  • PopupMenu()
    PopupMenu()
    PopupMenu()
    PopupMenu()

    Creates a new instance of the PopupMenu class.

    public PopupMenu()public PopupMenu()Public Function PopupMenu() As

    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.

    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();
    

Properties

  • Commands
    Commands
    Commands
    Commands

    Gets the commands for the context menu.

    public IVector<IUICommand> Commands { get; }public IVector<IUICommand> Commands { get; }Public ReadOnly Property Commands As IVector<IUICommand>

    Property Value

    • The commands for the context menu.

    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.

    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));
    

Methods

  • ShowAsync(Windows.Foundation.Point)
    ShowAsync(Windows.Foundation.Point)
    ShowAsync(Windows.Foundation.Point)
    ShowAsync(Windows.Foundation.Point)

    Shows the context menu at the specified client coordinates.

    public IAsyncOperation<IUICommand> ShowAsync(Windows.Foundation.Point)public IAsyncOperation<IUICommand> ShowAsync(Windows.Foundation.Point)Public Function ShowAsync(Windows.Foundation.Point) As IAsyncOperation( Of IUICommand )

    Parameters

    • invocationPoint

      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

    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.

    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 Id to identify and process the invoked command.

  • ShowForSelectionAsync(Windows.Foundation.Rect)
    ShowForSelectionAsync(Windows.Foundation.Rect)
    ShowForSelectionAsync(Windows.Foundation.Rect)
    ShowForSelectionAsync(Windows.Foundation.Rect)

    Shows the context menu above the specified selection.

    public IAsyncOperation<IUICommand> ShowForSelectionAsync(Windows.Foundation.Rect)public IAsyncOperation<IUICommand> ShowForSelectionAsync(Windows.Foundation.Rect)Public Function ShowForSelectionAsync(Windows.Foundation.Rect) As IAsyncOperation( Of IUICommand )

    Parameters

    • selection

      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

    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.

    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
        };
    }
    
  • ShowForSelectionAsync(Windows.Foundation.Rect,Windows.UI.Popups.Placement)
    ShowForSelectionAsync(Windows.Foundation.Rect,Windows.UI.Popups.Placement)
    ShowForSelectionAsync(Windows.Foundation.Rect,Windows.UI.Popups.Placement)
    ShowForSelectionAsync(Windows.Foundation.Rect,Windows.UI.Popups.Placement)

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

    public IAsyncOperation<IUICommand> ShowForSelectionAsync(Windows.Foundation.Rect,Windows.UI.Popups.Placement)public IAsyncOperation<IUICommand> ShowForSelectionAsync(Windows.Foundation.Rect,Windows.UI.Popups.Placement)Public Function ShowForSelectionAsync(Windows.Foundation.Rect,Windows.UI.Popups.Placement) As IAsyncOperation( Of IUICommand )

    Parameters

    • selection

      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

      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

    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.

    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
        };
    }
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.MuseAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.UI.Popups.dll