MessageDialog class

Applies to Windows and Windows Phone

Represents a dialog. The dialog has a command bar that can support up to three commands. If you don't specify any commands, then a default command is added to close the dialog.

The dialog dims the screen behind it and blocks touch events from passing to the app's canvas until the user responds.

Message dialogs should be used sparingly, and only for critical messages or simple questions that must block the user's flow.

Syntax


var messageDialog = new Windows.UI.Popups.MessageDialog(string);
var messageDialog = new Windows.UI.Popups.MessageDialog(string, string);

Attributes

[MarshalingBehavior(Standard)]
[Muse()]
[Version(0x06020000)]

Members

The MessageDialog class has these types of members:

Constructors

The MessageDialog class has these constructors.

ConstructorDescription
MessageDialog(String) Initializes a new instance of the MessageDialog class to display an untitled message dialog that can be used to ask your user simple questions.
MessageDialog(String, String) Initializes a new instance of the MessageDialog class to display a titled message dialog that can be used to ask your user simple questions.

 

Methods

The MessageDialog class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
ShowAsync Begins an asynchronous operation showing a dialog.

 

Properties

The MessageDialog class has these properties.

PropertyAccess typeDescription

CancelCommandIndex

Read/writeGets or sets the index of the command you want to use as the cancel command. This is the command that fires when users press the ESC key.

Commands

Read-onlyGets an array of commands that appear in the command bar of the message dialog. These commands makes the dialog actionable.

Content

Read/writeGets or sets the message to be displayed to the user.

DefaultCommandIndex

Read/writeGets or sets the index of the command you want to use as the default. This is the command that fires by default when users press the ENTER key.

Options

Read/writeGets or sets the options for a MessageDialog.

Title

Read/writeGets or sets the title to display on the dialog, if any.

 

Remarks

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

An example of a dialog, as created by the following example:

Message dialog with two commands

Examples

The following example shows how to add commands to a message dialog and display it. For the full code example, see Message dialog sample.


(function () {
    "use strict";
    var page = WinJS.UI.Pages.define("/html/cancelcommand.html", {
        ready: function (element, options) {
            document.getElementById("cancelCommand").addEventListener(
                "click", 
                cancelCommand_Click, false);
        }
    });

    // Click handler for the 'cancelCommand' button.
    // Demonstrates setting the command to be invoked when the 'escape' key is pressed.
    // Also demonstrates retrieval of the label of the chosen command and setting a 
    // callback to a function.
    // A message will be displayed indicating which command was invoked.
    // In this scenario, 'Try again' is selected as the default choice, and the 
    // 'escape' key will invoke the command named 'Close'
    function cancelCommand_Click() {
        // Create the message dialog and set its content
        var msg = new Windows.UI.Popups.MessageDialog(
            "No internet connection has been found.");

        // Add commands and set their command handlers
        msg.commands.append(new Windows.UI.Popups.UICommand(
            "Try again", 
            commandInvokedHandler));
        msg.commands.append(
            new Windows.UI.Popups.UICommand("Close", commandInvokedHandler));

        // Set the command that will be invoked by default
        msg.defaultCommandIndex = 0;

        // Set the command to be invoked when escape is pressed
        msg.cancelCommandIndex = 1;

        // Show the message dialog
        msg.showAsync();
    }

    function commandInvokedHandler(command) {
        // Display message
        WinJS.log && WinJS.log("The '" + command.label + "' command has been selected.", 
        "sample", "status");
    }
})();

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Popups
Windows::UI::Popups [C++]

Metadata

Windows.winmd

See also

Message dialog sample

 

 

Show:
© 2014 Microsoft