User Prompt Content

To build a user prompt, you can create a new instance of UserPromptControl and set the appropriate properties just like any other Control. The control can be defined in XAML, but prompts often have varying content that is composed, as needed, in code.

UserPromptControl with optional content areas labeled, OK/Cancel buttons, Information status icon, and optional footer icon

Content

The UserPromptControl is comprised of the following content areas:

• Message - The primary content of the prompt, which is usually one or more sentences of text.
• Header - An optional header at the top of the prompt that might define the main instruction.
• Footer - An optional footer shown at the bottom of the prompt.
• Checkbox - An optional checkbox that allows the user to toggle an option.
• Expanded information - An optional area below the footer that shows more information to the user but is collapsed until the user expands it.

While typically set to String-based text values, each content area can support any content allowed by ContentPresenter. This allows for complex content that includes additional controls like progress bars, radio buttons, or formatted text.

Using Builder Pattern

When using the builder pattern, various With* methods are available to set the content of each area (e.g., WithContent or WithHeaderContent). Each method has three overloads:

1. With*(object? content) - Directly set any Object as content, typically a String.
2. With*(Func<object?>? object) - Define a factory method that, when invoked, will return the content for the area.
3. With*(Func<UserPromptControl, object?>? object) - Define a factory method that, when invoked, is passed the instance of UserPromptControl being configured and returns the content for the area.

The last overload is particularly useful when the content needs to reference the UserPromptControl. For example, custom content might only be visible when the prompt is expanded and would need to bind it's IsVisible property to the UserPromptControl.IsExpanded property.

Message (Primary Content)

The Content property defines the primary message of the prompt. While typically set to a String-based value, this is also the most appropriate content area to add progress bars, radio buttons, or other controls.

Any TextBlock controls used within Content will wrap text by default.

When using the builder pattern, the WithContent method is used to configure the Content property.

// Simple message
await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithContent("Simple string-based content")
	.Show();

// Complex content
await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithContent(
		new StackPanel() {
			Children = {
				new TextBlock() { Text = "Copying..." },
				new ProgressBar() { Minimum = 0, Maximum = 100, Value = 25 }
			}
		}
	)
	.Show();

Scrollbars

The default UserPromptControl template defines Content within a ScrollViewer. Use the HorizontalScrollBarVisibility and VerticalScrollBarVisibility properties to manage scroll bar visibility.

When using the builder pattern, the WithScrollBarVisibility method is used to configure both scrollbars.

Header

The Header property can be defined to prominently display content at the top of the prompt.

Any TextBlock controls used within Header will wrap text by default. Any TextElement will also have the FontSize and Foreground properties default to the HeaderFontSize and HeaderForeground property values, respectively.

When using the builder pattern, the WithHeaderContent method is used to configure the Header property.

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithHeaderContent("Export complete")
	.WithContent("Your project has been successfully exported.")
	.Show();

Footer

The Footer property can be defined to display content at the bottom of the prompt. Adding a hyperlink to a footer that links to more information is also a common practice.

Any TextBlock controls used within Footer will wrap text by default.

Use the FooterIcon property to optionally display a 16x16 icon next to the Footer content. Any object supported by Icon Presenter is supported.

When using the builder pattern, the WithFooterContent method is used to configure the UserPromptBuilder property and the WithFooterIcon method configures the FooterIcon and FooterIconTemplate properties.

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithFooterContent("Click 'Help' button for more information")
	.WithFooterIcon(GetImage("/Images/Icons/Help16.png"))
	.Show();

See the Icon Presenter topic for additional details on working with custom icon value types.

CheckBox

The CheckBoxContent property can be defined to display a CheckBox control near the bottom of the prompt. Content is typically a String-based value with full support for AccessText. This CheckBox is commonly used to allow users to indicate they no longer want to receive a particular prompt.

The IsChecked property indicates the checked state of the CheckBox control.

When using the builder pattern, the WithCheckBoxContent method is used to configure the CheckBoxContent property and the WithIsChecked method is used to configure the IsChecked property:

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithCheckBoxContent("_Stop showing messages like this")
	.WithIsChecked(true)
	.Show();

When using the builder pattern, an overload of WithIsChecked allows one delegate to be passed as the "getter" of the initial checked state, and another as the "setter" of the final checked state. This can be used to easily synchronize the checked state of the prompt with a local variable as shown below:

var isChecked = false;
var result = await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithCheckBoxContent("_Stop showing messages like this")
	.WithIsChecked(
		getter: () => isChecked,
		setter: (value) => isChecked = value
	)
	.Show();
if (isChecked && (result == MessageBoxResult.OK)) {
	// Persist user request to stop prompting
}

Expanded Information

The ExpandedInformationContent property can be defined to enable the user to toggle the display of additional content that might not be ideal to display all the time.

Any TextBlock controls used within ExpandedInformationContent will wrap text by default.

When ExpandedInformationContent is defined, a toggle control will appear at the bottom of the prompt that the user can invoke to display the additional information. Use the ExpandedInformationCollapsedHeaderText property to specify the header of the toggle when it is collapsed, and the ExpandedInformationExpandedHeaderText property to specify the header when expanded. The IsExpanded property tracks the expansion state.

When using the builder pattern, the WithExpandedInformationContent method is used to set the ExpandedInformationContent property, the WithExpandedInformationHeaderText method is used to set both the ExpandedInformationCollapsedHeaderText and ExpandedInformationExpandedHeaderText properties, and the WithIsExpanded method is used to configure the initial value of the IsExpanded property:

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithExpandedInformationHeaderText("Show more", "Show less")
	.WithExpandedInformationContent("This content will be hidden until the user clicks 'Show more'.")
	.Show();

Status Icon

An icon can be used to visually communicate the status or classification of the prompt displayed. Users can quickly differentiate an error from a warning based on the icon displayed with the prompt.

The StatusIcon property can be set to any object supported by Icon Presenter, and is typically a 32x32 IImage.

Several common icons, like those for an error or warning, are defined by the MessageBoxImage enumeration. Instead of populating the StatusIcon property, set the StandardStatusIcon property to one of the MessageBoxImage values.

When using the builder pattern, the WithStatusIcon has one overload that accepts a custom object and another for a standard MessageBoxImage:

var result = await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithStatusIcon(MessageBoxImage.Information)
	.Show();