User Prompt Buttons

A user typically responds to a prompt by invoking a button that corresponds to the desired response. There are two ways to define buttons for a prompt:

1. Use a pre-defined set of one or more standard buttons.
2. Explicitly define each button.

By default, an OK button will be displayed if no other button configuration is assigned.

Standard Buttons

Most prompts can be built using one or more of the commonly used buttons defined by the MessageBoxButtons enumeration. These flags can easily be combined to display a fixed set of buttons to the user and are assigned to the StandardButtons property.

When using the builder pattern, the WithStandardButtons method is used to configure the StandardButtons property.

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithContent("Error processing file. How do you want to proceed?")
	.WithStandardButtons(MessageBoxButtons.YesNo)
	.Show();

Explicit Button Definitions

While the StandardButtons can be used for most prompts, some scenarios may require explicitly defining the individual buttons. Examples include:

• Adding a button that is not available as one of the MessageBoxButtons values.
• Customizing the content of a button (e.g., changing the label or adding an icon).
• Assigning a custom command to the button.

Collections of explicitly defined buttons are assigned to the UserPromptControl.ButtonItems property (which can be set to any IEnumerable). Each available object will be displayed as a Button by the UserPromptButtonItemsControl.

When using the builder pattern, the WithButton method is used to configure individual buttons that will be added to the ButtonItems property. The simplest overload to WithButton accepts a MessageBoxResult that associates a response with the button. The overload also has optional arguments to define an ICommand or label.

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithButton(MessageBoxResult.Cancel)
	.WithButton(MessageBoxResult.Ignore, label: "Continue")
	.Show();

Button Builder

For more advanced button definitions, a special UserPromptButtonBuilder is utilized to build each button. Similar to the UserPromptBuilder, the button builder is used to create and configure a Button control that is suitable for use on a user prompt.

The following example demonstrates using the button builder to create a button with a custom label and an alternate theme using Avalonia Classes:

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithButton(_ => _
		.WithResult(MessageBoxResult.Ignore)
		.WithContent("Continue")
		.WithClasses("theme-solid")
	)
	.Show();

Help Button

A special Help button can be included in StandardButtons. Invoking the Help button will execute the command designated by the HelpCommand property. An additional HelpCommandParameter can also be populated that will be passed to the HelpCommand when invoked.

When using the builder pattern, the WithHelpCommand method is used to automatically configure an additional Help button and can be used with standard buttons or explicitly defined buttons This method allows the HelpCommand to be directly assigned, or a callback Action can be defined instead. The following shows how to configure a Help button using a callback that will invoke a custom method for displaying help:

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithHelpCommand(() => OpenHelp())
	.Show();

ButtonResult Attached Property

The UserPromptControl.ButtonResult attached property is used to associate a Button with a specific MessageBoxResult . Any Button without an explicitly defined Button.Command will be automatically assigned a special ICommand that, when invoked, will read the UserPromptControl.ButtonResult attached property of the Button and assign that value to UserPromptControl.Result.

The UserPromptControl.ButtonResult attached property is also used to identify which Button corresponds to UserPromptControl.DefaultResult and will receive keyboard focus when shown in a UserPromptWindow.

When using the builder pattern, the button builder's WithResult method is used to define the result.

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

Standard Button Result

Each individual value for MessageBoxButtons has a corresponding value in MessageBoxResult. For example, the MessageBoxButtons.OK button corresponds to the MessageBoxResult.OK result. When using the UserPromptControl.StandardButtons property to define buttons, the UserPromptControl.ButtonResult attached property is automatically populated with the corresponding MessageBoxResult. Invoking one of the buttons will assign the value to UserPromptControl.Result.

Custom Button Result

When populating UserPromptControl.ButtonItems with custom Button instances, each button can optionally be associated with a specific MessageBoxResult using the UserPromptControl.ButtonResult attached property. Any Button without an explicitly defined Button.Command will be automatically assigned a special ICommand that, when invoked, will read the UserPromptControl.ButtonResult attached property of the Button and assign that value to UserPromptControl.Result.

The following code demonstrates how to assign a MessageBoxResult to a custom button when building a UserPromptControl:

await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithButton(_ => _
		.WithResult(MessageBoxResult.CustomButton)
		.WithContent("Custom")
	)
	.Show();

If multiple custom buttons are required, a value can be added to CustomButton to distinguish one custom button from another as shown below:

var result = await UserPromptBuilder.Configure()
	// ... other configuration options here
	.WithButton(_ => _
		.WithResult(MessageBoxResult.CustomButton + 1)
		.WithContent("Custom 1")
	)
	.WithButton(_ => _
		.WithResult(MessageBoxResult.CustomButton + 2)
		.WithContent("Custom 2")
	)
	.Show();

if (result == (MessageBoxResult.CustomButton + 1)) {
	// Custom 1 was selected
}
else if (result == (MessageBoxResult.CustomButton + 2)) {
	// Custom 2 was selected
}