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 image, and optional footer image

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 Visibility 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
UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithContent("Simple string-based content")
	.Show();

// Complex content
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.

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 FooterImageSource property to optionally display a 16x16 image next to the Footer content. Any ImageSource is supported.

When using the builder pattern, the WithFooterContent method is used to configure the UserPromptBuilder property and the WithFooterImage method configures the FooterImageSource property.

UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithFooterContent("Click 'Help' button for more information")
	.WithFooterImageSource(new BitmapImage(new Uri("pack://application:,,,/SampleBrowser;component/Images/Icons/Help16.png")))
	.Show();

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:

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 = UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithCheckBoxContent("_Stop showing messages like this")
	.WithIsChecked(
		getter: () => isChecked,
		setter: (value) => isChecked = value
	)
	.Show();
if (isChecked && (result == UserPromptStandardResult.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:

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 Image

An image 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 image displayed with the prompt.

The StatusImageSource property can be set to any 32x32 ImageSource.

Several common images, like those for an error or warning, are defined by the UserPromptStandardImage enumeration. Instead of populating the StatusImageSource property, set the StandardStatusImage property to one of the UserPromptStandardImage values.

When using the builder pattern, the WithStatusImage has one overload that accepts a custom ImageSource and another for a standard UserPromptStandardImage:

var result = UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithStatusImage(UserPromptStandardImage.Information)
	.Show();