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.

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

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. See Login Dialog.