Builder Pattern

The UserPromptBuilder class is used to configure and show a UserPromptControl. While a UserPromptControl can be instantiated and configured just like any other Control, the UserPromptBuilder can simplify the process.

Basic Usage

The basic flow for UserPromptBuilder is as follows:

1. Create a new UserPromptBuilder.
2. Use With* methods to configure properties to be applied to the UserPromptControl when it is built.
3. Show the prompt.

UserPromptBuilder utilizes a fluent API, which means each method returns the class instance so additional methods can be called on the same instance. This is also referred to as method-chaining.

Create Builder

To get started, call UserPromptBuilder.Configure. This method will create and return a new instance of UserPromptBuilder to be configured.

Configure Properties

The UserPromptBuilder instance has multiple methods that can be called to specify which property values will be populated on the UserPromptControl it creates. The naming convention for most methods is With<PropertyName> where <PropertyName> is the name of the UserPromptControl property to be configured. For example, set the DefaultResult property by calling the WithDefaultResult method.

Use method-chaining to apply all desired configuration options.

Global Configuration

There are two methods available to register callbacks that are always invoked to configure each new instance of UserPromptBuilder.

All User Prompts

The UserPromptBuilder.RegisterGlobalConfigureCallback method is used to register a callback that is invoked immediately after creating a new instance of UserPromptBuilder. Use this method to define an application-wide configuration that will be applied to all user prompts without having to configure each builder instance individually.

The following example demonstrates how a global callback can be registered to use the theme-solid accent style classes on the default button (if any) for every prompt:

UserPromptBuilder.RegisterGlobalConfigureCallback(_ => _
	.WithDefaultButtonClasses("theme-solid accent")
);

MessageBox Only

The MessageBox.RegisterGlobalBuilderConfigureCallback method is used to register a callback specifically for the builder used by MessageBox, and this callback is invoked after the previously mentioned global callback for all user prompts. Use this method to specifically define application-wide configurations for the prompts displayed by MessageBox.

The following example demonstrates how a global callback can be registered that alters the default behavior by displaying a message box title in the header of the prompt:

MessageBox.RegisterGlobalBuilderConfigureCallback(_ => _
	.AfterBuild(builder => {
		// Configure UserPromptControl.Header with the Title
		builder.Instance!.Header = builder.Title;

		// Clear the Title configuration to avoid it appearing elsewhere
		builder.WithTitle(null);
	})
);

Show Prompt

Finally, call the Show method. This will create the UserPromptControl, apply the desired configuration, display the prompt, and await a response from the user.

Example

The following code sample demonstrates how UserPromptBuilder could be used to display a prompt to the user with response buttons of Yes or No.

var result = await UserPromptBuilder.Configure()
	.WithHeaderContent("Overwrite existing file?")
	.WithContent("The specified file already exists. Do you want to overwrite the file?")
	.WithStandardButtons(MessageBoxButtons.YesNo)
	.WithStatusImage(MessageBoxImage.Question)
	.Show();

The fluent API allows the entire configuration to be defined as a single statement.

See the User Prompt Content and User Prompt Buttons topics for more details and examples.

Builder Lifecycle and Callbacks

Nothing happens with UserPromptBuilder until the Show method is called. At that point, the following sequence of events will occur:

• Create a UserPromptControl and assign to the Instance property.
• Invoke all AfterInitialize callbacks.
• Assign properties on UserPromptControl. After this point, the Instance property is fully initialized any changes to builder properties that affect the configuration of the UserPromptControl will not be applied.
• Invoke all AfterBuild callbacks.
• Use the RequestedDisplayMode to determine how the prompt will be displayed and assign the ActualDisplayMode property to the mode that is used.
• Invoke all BeforeShow callbacks.
• When displayed as a Dialog...
  • Configure UserPromptWindow to host the UserPromptControl.
  • Invoke all AfterInitializeWindow callbacks.
  • Show the UserPromptWindow as a dialog and await a response.
• When displayed as an Overlay...
  • Configure an overlay to host the UserPromptControl.
  • Show the overlay and await a response.
• Invoke all OnResponding callbacks when a response is indicated.
• Invoke all AfterShow callbacks with the indicated result.
• Return the result.

Callbacks are available at different stages of the build process to support extensibility.

Instance Property

The UserPromptBuilder.Instance is populated with the instance of UserPromptControl that is being built. This property will be null until the Show method is called. All callbacks can safely read this property to interact with the UserPromptControl being built except the global configuration callbacks.

Tag Property

The UserPromptBuilder.Tag property can be used to store an arbitrary object value on the builder, and this can be used to store data that is accessibile from multiple callback methods. Use the UserPromptBuilder.WithTag method to assign values to this property.

AfterInitialize Callback

This callback is invoked immediately after an instance of UserPromptControl is created and can be used to initialize the control or further customize the builder before the builder configuration settings are applied.

var result = await UserPromptBuilder.Configure()
	// ... other configuration options here
	.AfterInitialize(builder => {
		// Define logic here
	})
	.Show();

AfterBuild Callback

This callback is invoked after all builder configuration settings have been applied and can be used to finalize the UserPromptControl before it is shown.

var result = await UserPromptBuilder.Configure()
	// ... other configuration options here
	.AfterBuild(builder => {
		// Define logic here
	})
	.Show();

BeforeShow Callback

This callback is invoked before attempting to show the prompt. At this point, the RequestedDisplayMode has been evaluated and the ActualDisplayMode is assigned. This callback could be used to further customize the UserPromptControl based on how it will be displayed.

AfterInitializeWindow Callback (Dialogs Only)

When displayed as a Dialog, this callback is invoked to finalize the UserPromptWindow that will host the UserPromptControl as a modal dialog. The callback is invoked after the window is initially configured.

var result = await UserPromptBuilder.Configure()
	// ... other configuration options here
	.AfterInitializeWindow(window => {
		// Define logic here
	})
	.Show();

OnResponding Callback

This callback is invoked when the user indicates a response and can be used to confirm and/or cancel the response using the UserPromptResponseEventArgs that are passed.

var result = await UserPromptBuilder.Configure()
	// ... other configuration options here
	.OnResponding((builder, args) => {
		// Define logic here
	})
	.Show();

AfterShow Callback

This callback is invoked after the prompt is closed and passes the MessageBoxResult.

var result = await UserPromptBuilder.Configure()
	// ... other configuration options here
	.AfterShow((builder, result) => {
		// Define logic here
	})
	.Show();