MetroDialogSettings is the one object every built-in dialog takes. It is the last argument of each Show...Async method, and it decides the button labels, the colours, the font sizes, the animations and how the dialog can be cancelled.

var settings = new MetroDialogSettings
               {
                   AffirmativeButtonText = "Delete",
                   NegativeButtonText = "Keep",
                   ColorScheme = MetroDialogColorScheme.Accented
               };

var result = await this.ShowMessageAsync("Delete the file?", "This cannot be undone.",
                                         MessageDialogStyle.AffirmativeAndNegative, settings);

Not every dialog type reads every setting — a progress dialog has no affirmative button to label. The reference below says which reads what, and each dialog page repeats the part that applies to it.

Where the settings come from

Pass null — or leave the argument off — and the dialog falls back to the window's MetroDialogOptions, which every MetroWindow creates for itself in its constructor. So the order is: the argument, then the window's options, then the defaults.

That makes MetroDialogOptions the place for defaults that should hold across a window:

<mah:MetroWindow x:Class="MyApp.MainWindow"
                 xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls">

    <mah:MetroWindow.MetroDialogOptions>
        <mah:MetroDialogSettings AffirmativeButtonText="Yes"
                                 NegativeButtonText="No"
                                 ColorScheme="Accented" />
    </mah:MetroWindow.MetroDialogOptions>

</mah:MetroWindow>

or from code:

this.MetroDialogOptions.ColorScheme = MetroDialogColorScheme.Accented;

Settings are read when the dialog is created, so changing the object after a dialog is up has no effect on it.

await this.ShowLoginAsync("Sign in", "Message", new LoginDialogSettings(this.MetroDialogOptions));

Reference

The three font sizes are only applied when they are not NaN, which is what they start as — leaving one alone keeps the theme's value rather than setting it to zero.

Buttons

The one a press of return stands for

DefaultButtonFocus names the button that is marked in the accent colour, the one somebody is being nudged towards.

Left alone it holds nothing, and each dialog then marks what it has always marked: the one that says no in a message dialog, the one that carries on in an input or a login dialog. Name a button and that one is marked instead.

await this.ShowInputAsync("Delete", "Which file?",
                          new MetroDialogSettings { DefaultButtonFocus = MessageDialogResult.Negative });

The caret waits in the field of an input or a login dialog whichever button is marked, since filling that in is what somebody has come to do.

The four button labels cover the most a dialog can show. A message dialog uses as many as its MessageDialogStyle asks for, an input and a login dialog use the first two, and a progress dialog uses only NegativeButtonText for its cancel button.

Nothing here controls whether a button appears. That is the MessageDialogStyle argument for a message dialog, NegativeButtonVisibility in LoginDialogSettings, and the isCancelable argument of ShowProgressAsync.

Colour scheme

MetroDialogColorScheme has three values. Theme draws the dialog in the current theme's background and foreground, Inverted in the inverse theme — light-on-dark under a light theme — and Accented fills it with the accent colour.

Inverted throws if the current theme has no inverse to switch to, which is the case for a custom theme that was never registered as part of a light/dark pair.

The colour of the message

MessageForeground is on develop and ships with the next release. It is not in 2.4.11.

The message and the title of a dialog both take its Foreground, so setting that colours the whole dialog. MessageForeground colours the message alone, which is what a warning usually wants:

await this.ShowMessageAsync("Careful", "This cannot be undone.",
                            MessageDialogStyle.AffirmativeAndNegative,
                            new MetroDialogSettings { MessageForeground = Brushes.Red });

All four dialogs that show a message read it. Left unset, the message goes with the rest of the dialog, the way it always has.

Font sizes

DialogTitleFontSize, DialogMessageFontSize and DialogButtonFontSize override the theme's MahApps.Font.Size.Dialog.* resources for one dialog.

var settings = new MetroDialogSettings
               {
                   DialogTitleFontSize = 18,
                   DialogMessageFontSize = 13,
                   DialogButtonFontSize = 14
               };

To change them for every dialog in the application, override the resources instead:

<system:Double x:Key="MahApps.Font.Size.Dialog.Title">18</system:Double>

Animations

AnimateShow and AnimateHide cover both the dialog and the overlay that dims the window behind it. Turning them off makes the dialog appear and disappear in one frame, which is what you want in a test that would otherwise race the animation.

Cancellation

CancellationToken closes a message, input or login dialog from code, without the user pressing anything. The call then returns the same result it would have returned for a cancel.

Closing the window while a dialog is open

By default a MetroWindow refuses to close while one of its dialogs is up, and the close button in the title bar is greyed out. OwnerCanCloseWithDialog = true allows it.

<mah:MetroWindow ShowDialogsOverTitleBar="False">
    <mah:MetroWindow.MetroDialogOptions>
        <mah:MetroDialogSettings OwnerCanCloseWithDialog="True" />
    </mah:MetroWindow.MetroDialogOptions>
</mah:MetroWindow>

Custom resources

CustomResourceDictionary is merged into the dialog's own resources, so it can override any brush, style or template the dialog resolves dynamically — without touching the rest of the application.

var settings = new MetroDialogSettings
               {
                   CustomResourceDictionary = new ResourceDictionary
                                              {
                                                  Source = new Uri("pack://application:,,,/MyApp;component/DialogStyles.xaml")
                                              }
               };

The message dialog page shows what this looks like in practice.

Login dialogs

LoginDialogSettings derives from MetroDialogSettings and adds the username, password and remember-checkbox settings. Everything on this page applies to it as well, with the fallback caveat noted above. One thing stays true either way: the constructor sets AffirmativeButtonText to Login after copying, so that label comes from the login settings and not from the window. See Login Dialog.