Table of Contents

Class ContentDialog

Namespace
Wpf.Ui.Controls
Assembly
Wpf.Ui.dll

Dialogue displayed inside the application covering its internals, displaying some content.

public class ContentDialog : ContentControl, IAnimatable, ISupportInitialize, IFrameworkInputElement, IInputElement, IQueryAmbient, IAddChild
Inheritance
ContentDialog
Implements
Inherited Members

Examples

<ContentDialogHost x:Name="RootContentDialogHost" Grid.Row="0" />
var contentDialog = new ContentDialog(RootContentDialogHost);

contentDialog.SetCurrentValue(ContentDialog.TitleProperty, "Hello World");
contentDialog.SetCurrentValue(ContentControl.ContentProperty, "This is a message");
contentDialog.SetCurrentValue(ContentDialog.CloseButtonTextProperty, "Close this dialog");

await contentDialog.ShowAsync(cancellationToken);
var contentDialogService = new ContentDialogService();
contentDialogService.SetDialogHost(RootContentDialogHost);

await _contentDialogService.ShowSimpleDialogAsync(
    new SimpleContentDialogCreateOptions()
        {
            Title = "The cake?",
            Content = "IS A LIE!",
            PrimaryButtonText = "Save",
            SecondaryButtonText = "Don't Save",
            CloseButtonText = "Cancel"
        }
    );

Remarks

Implementation notes:

  • Focuses only on initial display behavior, not ongoing focus management
  • Works with both XAML-defined and dynamically added content
  • Does not handle UI Automation or accessibility providers

Constructors

ContentDialog()

Initializes a new instance of the ContentDialog class.

public ContentDialog()

ContentDialog(ContentPresenter?)

Initializes a new instance of the ContentDialog class.

[Obsolete("ContentDialog(ContentPresenter? is deprecated. Please use ContentDialog(ContentDialogHost? instead.", false)]
public ContentDialog(ContentPresenter? dialogHost)

Parameters

dialogHost ContentPresenter

DialogHost inside of which the dialogue will be placed. The new ContentDialog will replace the current Content.

Remarks

DEPRECATED: This constructor overload is deprecated. Use the constructor that accepts a ContentDialogHost instead for enhanced modal dialog capabilities.

ContentDialog(ContentDialogHost?)

Initializes a new instance of the ContentDialog class with the specified dialog host.

public ContentDialog(ContentDialogHost? dialogHost)

Parameters

dialogHost ContentDialogHost

The ContentDialogHost that manages the dialog's display and interaction.

Exceptions

ArgumentNullException

Thrown if dialogHost is null.

Fields

ButtonClickedEvent

Identifies the ButtonClicked routed event.

public static readonly RoutedEvent ButtonClickedEvent

Field Value

RoutedEvent

CloseButtonAppearanceProperty

Identifies the CloseButtonAppearance dependency property.

public static readonly DependencyProperty CloseButtonAppearanceProperty

Field Value

DependencyProperty

CloseButtonIconProperty

Identifies the CloseButtonIcon dependency property.

public static readonly DependencyProperty CloseButtonIconProperty

Field Value

DependencyProperty

CloseButtonTextProperty

Identifies the CloseButtonText dependency property.

public static readonly DependencyProperty CloseButtonTextProperty

Field Value

DependencyProperty

ClosedEvent

Identifies the Closed routed event.

public static readonly RoutedEvent ClosedEvent

Field Value

RoutedEvent

ClosingEvent

Identifies the Closing routed event.

public static readonly RoutedEvent ClosingEvent

Field Value

RoutedEvent

DefaultButtonProperty

Identifies the DefaultButton dependency property.

public static readonly DependencyProperty DefaultButtonProperty

Field Value

DependencyProperty

DialogHeightProperty

Identifies the DialogHeight dependency property.

public static readonly DependencyProperty DialogHeightProperty

Field Value

DependencyProperty

DialogMarginProperty

Identifies the DialogMargin dependency property.

public static readonly DependencyProperty DialogMarginProperty

Field Value

DependencyProperty

DialogMaxHeightProperty

Identifies the DialogMaxHeight dependency property.

public static readonly DependencyProperty DialogMaxHeightProperty

Field Value

DependencyProperty

DialogMaxWidthProperty

Identifies the DialogMaxWidth dependency property.

public static readonly DependencyProperty DialogMaxWidthProperty

Field Value

DependencyProperty

DialogWidthProperty

Identifies the DialogWidth dependency property.

public static readonly DependencyProperty DialogWidthProperty

Field Value

DependencyProperty

IsFooterVisibleProperty

Identifies the IsFooterVisible dependency property.

public static readonly DependencyProperty IsFooterVisibleProperty

Field Value

DependencyProperty

IsLegacyHostProperty

Identifies the IsLegacyHost dependency property.

public static readonly DependencyProperty IsLegacyHostProperty

Field Value

DependencyProperty

IsPrimaryButtonEnabledProperty

Identifies the IsPrimaryButtonEnabled dependency property.

public static readonly DependencyProperty IsPrimaryButtonEnabledProperty

Field Value

DependencyProperty

IsSecondaryButtonEnabledProperty

Identifies the IsSecondaryButtonEnabled dependency property.

public static readonly DependencyProperty IsSecondaryButtonEnabledProperty

Field Value

DependencyProperty

OpenedEvent

Identifies the Opened routed event.

public static readonly RoutedEvent OpenedEvent

Field Value

RoutedEvent

PrimaryButtonAppearanceProperty

Identifies the PrimaryButtonAppearance dependency property.

public static readonly DependencyProperty PrimaryButtonAppearanceProperty

Field Value

DependencyProperty

PrimaryButtonIconProperty

Identifies the PrimaryButtonIcon dependency property.

public static readonly DependencyProperty PrimaryButtonIconProperty

Field Value

DependencyProperty

PrimaryButtonTextProperty

Identifies the PrimaryButtonText dependency property.

public static readonly DependencyProperty PrimaryButtonTextProperty

Field Value

DependencyProperty

SecondaryButtonAppearanceProperty

Identifies the SecondaryButtonAppearance dependency property.

public static readonly DependencyProperty SecondaryButtonAppearanceProperty

Field Value

DependencyProperty

SecondaryButtonIconProperty

Identifies the SecondaryButtonIcon dependency property.

public static readonly DependencyProperty SecondaryButtonIconProperty

Field Value

DependencyProperty

SecondaryButtonTextProperty

Identifies the SecondaryButtonText dependency property.

public static readonly DependencyProperty SecondaryButtonTextProperty

Field Value

DependencyProperty

TemplateButtonCommandProperty

Identifies the TemplateButtonCommand dependency property.

public static readonly DependencyProperty TemplateButtonCommandProperty

Field Value

DependencyProperty

TitleProperty

Identifies the Title dependency property.

public static readonly DependencyProperty TitleProperty

Field Value

DependencyProperty

TitleTemplateProperty

Identifies the TitleTemplate dependency property.

public static readonly DependencyProperty TitleTemplateProperty

Field Value

DependencyProperty

Properties

CloseButtonAppearance

Gets or sets the ControlAppearance to apply to the close button.

public ControlAppearance CloseButtonAppearance { get; set; }

Property Value

ControlAppearance

CloseButtonIcon

Gets or sets the SymbolRegular on the close button.

public IconElement? CloseButtonIcon { get; set; }

Property Value

IconElement

CloseButtonText

Gets or sets the text to display on the close button.

public string CloseButtonText { get; set; }

Property Value

string

ContentPresenter 

[Obsolete("ContentPresenter is deprecated. Please use DialogHost instead.")]
public ContentPresenter? ContentPresenter { get; set; }

Property Value

ContentPresenter

DefaultButton

Gets or sets a value that indicates which button on the dialog is the default action.

public ContentDialogButton DefaultButton { get; set; }

Property Value

ContentDialogButton

DialogHeight

Gets or sets the height of the ContentDialog.

public double DialogHeight { get; set; }

Property Value

double

DialogHost

Gets or sets DialogHost inside of which the dialogue will be placed.

[Obsolete("DialogHost is deprecated. Please use DialogHostEx instead.")]
public ContentPresenter? DialogHost { get; set; }

Property Value

ContentPresenter

Exceptions

InvalidOperationException

Thrown if trying to set DialogHost when DialogHostEx is already set, or if trying to change DialogHost while the dialog is being shown.

DialogHostEx

Gets or sets DialogHostEx inside of which the dialogue will be placed.

public ContentDialogHost? DialogHostEx { get; set; }

Property Value

ContentDialogHost

Exceptions

InvalidOperationException

Thrown if trying to set DialogHostEx when DialogHost is already set, or if trying to change DialogHostEx while the dialog is being shown.

DialogMargin

Gets or sets the margin of the ContentDialog.

public Thickness DialogMargin { get; set; }

Property Value

Thickness

DialogMaxHeight

Gets or sets the max height of the ContentDialog.

public double DialogMaxHeight { get; set; }

Property Value

double

DialogMaxWidth

Gets or sets the max width of the ContentDialog.

public double DialogMaxWidth { get; set; }

Property Value

double

DialogWidth

Gets or sets the width of the ContentDialog.

public double DialogWidth { get; set; }

Property Value

double

IsFooterVisible

Gets or sets a value indicating whether the footer buttons are visible.

public bool IsFooterVisible { get; set; }

Property Value

bool

IsLegacyHost

Gets a value indicating whether the dialog is shown in the legacy ContentPresenter host.

public bool IsLegacyHost { get; }

Property Value

bool

IsPrimaryButtonEnabled

Gets or sets a value indicating whether the ContentDialog primary button is enabled.

public bool IsPrimaryButtonEnabled { get; set; }

Property Value

bool

IsSecondaryButtonEnabled

Gets or sets a value indicating whether the ContentDialog secondary button is enabled.

public bool IsSecondaryButtonEnabled { get; set; }

Property Value

bool

PrimaryButtonAppearance

Gets or sets the ControlAppearance to apply to the primary button.

public ControlAppearance PrimaryButtonAppearance { get; set; }

Property Value

ControlAppearance

PrimaryButtonIcon

Gets or sets the SymbolRegular on the secondary button.

public IconElement? PrimaryButtonIcon { get; set; }

Property Value

IconElement

PrimaryButtonText

Gets or sets the text to display on the primary button.

public string PrimaryButtonText { get; set; }

Property Value

string

SecondaryButtonAppearance

Gets or sets the ControlAppearance to apply to the secondary button.

public ControlAppearance SecondaryButtonAppearance { get; set; }

Property Value

ControlAppearance

SecondaryButtonIcon

Gets or sets the SymbolRegular on the primary button.

public IconElement? SecondaryButtonIcon { get; set; }

Property Value

IconElement

SecondaryButtonText

Gets or sets the text to be displayed on the secondary button.

public string SecondaryButtonText { get; set; }

Property Value

string

Tcs 

protected TaskCompletionSource<ContentDialogResult>? Tcs { get; set; }

Property Value

TaskCompletionSource<ContentDialogResult>

TemplateButtonCommand

Gets command triggered after clicking the button in the template.

public IRelayCommand TemplateButtonCommand { get; }

Property Value

IRelayCommand

Title

Gets or sets the title of the ContentDialog.

public object? Title { get; set; }

Property Value

object

TitleTemplate

Gets or sets the title template of the ContentDialog.

public DataTemplate? TitleTemplate { get; set; }

Property Value

DataTemplate

Methods

Hide(ContentDialogResult)

Hides the dialog with result

public virtual void Hide(ContentDialogResult result = ContentDialogResult.None)

Parameters

result ContentDialogResult

IsFocusInsideDialog()

Returns true when the keyboard focus is currently within the dialog's visual/logical tree.

public bool IsFocusInsideDialog()

Returns

bool

Exceptions

InvalidOperationException

Thrown when the method is called from a non-UI thread.

MeasureOverride(Size)

Called to remeasure a control.

protected override Size MeasureOverride(Size availableSize)

Parameters

availableSize Size

Returns

Size

The size of the control, up to the maximum specified by constraint.

OnButtonClick(ContentDialogButton)

Invoked when a ContentDialogButton is clicked.

protected virtual void OnButtonClick(ContentDialogButton button)

Parameters

button ContentDialogButton

The button that was clicked.

OnClosed(ContentDialogResult)

Occurs after ContentPresenter.Content = null

protected virtual void OnClosed(ContentDialogResult result)

Parameters

result ContentDialogResult

OnCreateAutomationPeer()

Returns class-specific AutomationPeer implementations for the Windows Presentation Foundation (WPF) infrastructure.

protected override AutomationPeer OnCreateAutomationPeer()

Returns

AutomationPeer

The type-specific AutomationPeer implementation.

OnLoaded()

Occurs after Loaded event

protected virtual void OnLoaded()

OnPreviewLostKeyboardFocus(KeyboardFocusChangedEventArgs)

Completely prevents focus from escaping the ContentDialog. When a focus escape is detected, the focus is forcibly pulled back into the dialog.

protected override void OnPreviewLostKeyboardFocus(KeyboardFocusChangedEventArgs e)

Parameters

e KeyboardFocusChangedEventArgs

OnUnloaded()

Occurs after Unloaded event

protected virtual void OnUnloaded()

SetInitialFocus()

Sets the initial keyboard focus when the dialog is first displayed.

protected virtual void SetInitialFocus()

Remarks

Priority strategy:

  1. Content-first: focus the first focusable element within the user-provided Content (the first focusable <xref href="System.Windows.Controls.Control" data-throw-if-not-resolved="false"></xref>).
  2. Built-in default button: if a built-in template button (Primary, Close, or Secondary) is marked as default and is safely focusable, focus it (see Wpf.Ui.Controls.ContentDialog.FocusBuiltInButton()).
  3. Template fallback: find any System.Windows.Controls.Button in the template with IsDefault == true and focus it.
  4. Fallback: if none of the above are available, make the ContentDialog itself focusable and set focus to it.

ShowAsync(CancellationToken)

Shows the dialog

[SuppressMessage("WpfAnalyzers.DependencyProperty", "WPF0041:Set mutable dependency properties using SetCurrentValue", Justification = "SetCurrentValue(ContentProperty, ...) will not work")]
public Task<ContentDialogResult> ShowAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<ContentDialogResult>

Events

ButtonClicked

Occurs after the ContentDialogButton has been tapped.

public event TypedEventHandler<ContentDialog, ContentDialogButtonClickEventArgs> ButtonClicked

Event Type

TypedEventHandler<ContentDialog, ContentDialogButtonClickEventArgs>

Closed

Occurs after the dialog is closed.

public event TypedEventHandler<ContentDialog, ContentDialogClosedEventArgs> Closed

Event Type

TypedEventHandler<ContentDialog, ContentDialogClosedEventArgs>

Closing

Occurs after the dialog starts to close, but before it is closed and before the Closed event occurs.

public event TypedEventHandler<ContentDialog, ContentDialogClosingEventArgs> Closing

Event Type

TypedEventHandler<ContentDialog, ContentDialogClosingEventArgs>

Remarks

This event allows cancellation of the close operation by setting Cancel to true.

Important: The Closing event is only raised for explicit close operations initiated via the Hide(ContentDialogResult) method. It is not raised when the dialog is passively removed from the visual tree, such as when:

  • Another dialog replaces this one
  • The host control or window is disposed

Opened

Occurs after the dialog is opened.

public event TypedEventHandler<ContentDialog, RoutedEventArgs> Opened

Event Type

TypedEventHandler<ContentDialog, RoutedEventArgs>
Edit this page