Display and Results

Once the User Prompt Content and User Prompt Buttons have been defined, it is time to show the prompt and collect feedback from the user.

Showing a User Prompt Dialog

The builder pattern is recommended for showing user prompts, but is not required. The UserPromptWindow.ShowDialog method can be used to display any UserPromptControl in a modal dialog that will automatically close and return a UserPromptStandardResult when the user responds.

The following code demonstrates showing a UserPromptControl as a modal dialog using UserPromptWindow and evaluating the result:

var userPromptControl = new UserPromptControl() {
	Content = "This file has been modified. Do you want to save your changes before closing?",
	StandardButtons = UserPromptStandardButtons.YesNo,
};
var result = UserPromptWindow.ShowDialog(userPromptControl, "Save Changes?");
if (result == UserPromptStandardResult.Yes) {
	// Insert code to save changes here
}

When using the builder pattern, the Show method is used to display a prompt based on the configuration and return the result as shown in the sample blow:

var result = UserPromptBuilder.Configure()
	.WithContent("This file has been modified. Do you want to save your changes before closing?")
	.WithStandardButtons(UserPromptStandardButtons.YesNo)
	.Show();
if (result == UserPromptStandardResult.Yes) {
	// Insert code to save changes here
}

Title

All Window instances should have a title, so the UserPromptWindow.ShowDialog method optionally accepts an argument that will be used as the title of the UserPromptWindow when displayed.

When using the builder pattern, the WithTitle method is used to set the title associated with the user prompt:

UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithTitle("Actipro WPF Controls")
	.Show();

Inferred and Fallback Titles

When a title is undefined or null, the UserPromptControl.StandardStatusImage property is used to infer a contextually appropriate title. For example, the title is set to "Warning" when the status image is UserPromptStandardImage.Warning .

If a title cannot be inferred, the static UserPromptBuilder.FallbackTitle value will be used.

If a title is still undefined, the TitleAttribute metadata of the entry assembly will be used.

Close Caption Button

A UserPromptWindow will only display a Close caption button in the title bar if a response can be associated with closing the window. The CloseResult property is used to define the result associated with closing the window instead of invoking an available button. When set to UserPromptStandardResult.None, the Close caption button will not be displayed.

When CloseResult is set to null and the StandardButtons property is used to define the available buttons, an appropriate UserPromptStandardResult will be assigned to CloseResult based on the current value of StandardButtons.

For example, using UserPromptStandardButtons.YesNoCancel will automatically assign UserPromptStandardButtons.Cancel as the CloseResult. Explicitly set the CloseResult to UserPromptStandardResult.None to prevent the Close caption button from automatically displaying.

When using the builder pattern, the WithCloseResult method is used to set the close result:

UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithCloseResult(UserPromptStandardResult.Ignore)
	.Show();

Configuring and Evaluating Results

The UserPromptControl.Result property is used to read or write the user's response to a prompt and is typically only used when working with custom buttons.

The UserPromptWindow.ShowDialog method returns the UserPromptControl.Result. If the UserPromptWindow is closed without invoking one of the available buttons, the value of UserPromptControl.CloseResult is returned instead.

The UserPromptControl.Responding event is raised when the UserPromptControl.Result property is changed. UserPromptWindow listens to this event to know when to close the dialog.

When using the builder pattern, the Show method returns the same result as UserPromptWindow.ShowDialog.

Default Button

Typically, the first available button will be the default button that receives initial focus. There are two ways to change this behavior to explicitly indicate which button should be the default: UserPromptControl.DefaultResult and Button.IsDefault.

When standard buttons are configured using the StandardButtons property, the default button is defined by setting the DefaultResult property to the UserPromptStandardResult that corresponds to the standard button.

When custom buttons are configured using the ButtonItems property, the first Button control whose IsDefault property is set to true will be configured as the default.

When using the builder pattern, the button builder's UseAsDefaultResult method is used to configure Button.IsDefault as true.

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithButton(_ => _
		.WithResult(MessageBoxResult.Yes)
		.UseAsDefaultResult()
	)
	.Show();

Responding Event

The UserPromptControl.Responding event is raised when the UserPromptControl.Result property is changed. UserPromptWindow listens to this event to know when to close the dialog.

When using the builder pattern, the OnResponding method is used to define a callback that will receive the UserPromptBuilder and UserPromptResponseEventArgs of the event. The following demonstrates how the callback can be used to cancel a response:

UserPromptBuilder.Configure()
	// ... other configuration options here
	.OnResponding((builder, args) => {
		if ((builder?.Instance is UserPromptControl userPromptControl) && (userPromptControl.IsChecked)) {
			// Cancel the response
			ThemedMessageBox.Show($"Cancelling response of '{args.Response}'", "Result Canceled");
			args.Cancel = true;
		}
	})
	.Show();

Owner

When the user prompt is shown as a modal dialog, it must have an owner Window. Some of the UserPromptWindow.ShowDialog overloads allow an owner to be specified. If one is not specified, a default owner Window will be determined by the currently active Window.

When using the builder pattern, the WithOwner method is used to assign a non-default owner. Since the builder pattern supports displaying dialogs or overlays, the owner is specified as a TopLevel (which, on desktop applications, is typically a Window).

Startup Location

By default, a UserPromptWindow.WindowStartupLocation is set to CenterScreen, but this can be changed.

The UserPromptWindow.ShowDialog method accepts a callback that can be used to configure the UserPromptWindow before it is displayed. The following sample demonstrates changing the startup location to CenterOwner:

var userPromptControl = new UserPromptControl() { ... };
Window owner = null; // Use default

UserPromptWindow.ShowDialog(
	userPromptControl,
	"Window Title",
	owner,
	window => {
		window.WindowStartupLocation = WindowStartupLocation.CenterOwner;
	});

See the "Customize UserPromptWindow" section of the Customizing Appearance topic for more examples of how to set properties like WindowStartupLocation on the UserPromptWindow.

When using the builder pattern, the WithWindowStartupLocation method is used to specify a desired startup location.

UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithWindowStartupLocation(WindowStartupLocation.CenterOwner)
	.Show();

Auto-Sizing

Auto-sizing is a feature only available when using the builder pattern. By default, this feature is only enabled when a String is used as the Content of the prompt, but the WithAutoSize method can be used to explicitly enable the functionality for non-String content as well.

Auto-sizing involves a series of calculations that attempt to generate the ideal width of the prompt. The goal is to start at a given width and then ensure the prompt does not exceed a relative height. If the prompt is too tall, the width is increased in logical steps until the height is within a desired range.

The minimum width, accessible by AutoSizeMinimumWidth, is assigned using one of the available arguments passed to the WithAutoSize method.

When UserPromptBuilder.WindowStartupLocation is null (the default), the auto-size logic will first attempt to size the prompt to a width and height that do not exceed the bounds of the owner. This is important to allow WindowStartupLocation.CenterOwner to be used without some parts of the prompt potentially displayed off screen. Otherwise, if it is not displayed as an overlay, the prompt will be sized within the working area of the screen so that WindowStartupLocation.CenterScreen can be used to fully display the prompt.

Playing a SystemSound

When a native MessageBox is displayed, an associated System.Media.SystemSound may be played based on the value of MessageBoxImage used. Set UserPromptControl.SystemSound to any SystemSound and it will be played when the UserPromptWindow is shown.

When SystemSound is set to null and the StandardStatusImage property is used to define the status image, an appropriate SystemSound will be automatically assigned based on the image as shown in the following table: