Using Commands

All interactive controls in this product are designed to work well with MVVM patterns and the WPF command model.

Controls will execute their command when a primary action occurs on the control, and use the ICommand.CanExecute result to determine if the control is enabled. Commands can be used to support live preview for gallery items as well.

Control Command Support

Many controls implement ICommandSource, meaning that they have Command, CommandParameter, and CommandTarget properties. The ICommand that is assigned to a control can be any command, including those defined in the WPF framework in the System.Windows.Input namespace, those created by Actipro in the ActiproSoftware.Windows.Input namespace, or any other third-party commands.

Summary Table

This table summarizes the command support across some of the interactive controls in this product:

See the individual topics for details on each control's command infrastructure.

Command Interfaces

Two command-related interfaces are fundamental for command support by controls.

ICommand

The ICommand interface provides the foundation of any command and includes support for executing a command and determining whether a command can execute.

Controls will execute the command when their primary action occurs, such as a button being clicked. Controls will also use the ICommand.CanExecute result to determine if the control should be enabled.

Actipro provides couple useful implementations of the ICommand interface that are described below.

IPreviewableCommand (Live Preview Support)

The IPreviewableCommand interface inherits ICommand and adds support for starting and then later canceling a live preview. A live preview can temporarily display the result of a command being executed without actually committing it. This is often used with gallery controls in cases where hovering over a gallery item like a color temporarily displays the applied color.

These are the important methods on the IPreviewableCommand interface and are called similarly to ICommand methods, where a command parameter is passed:

The caller of these methods should always cancel a previous preview prior to starting a new preview.

Actipro provides couple useful implementations of the IPreviewableCommand interface that are described below.

Framework Command Types

The WPF framework has a couple built-in types that implement ICommand.

RoutedCommand

RoutedCommand defines a command that is routed through the element tree. The Execute and CanExecute methods on a RoutedCommand do not contain the application logic for the command as is the case with a typical ICommand, but rather, these methods raise events that traverse the element tree looking for an object with a CommandBinding. The event handlers attached to the CommandBinding contain the command logic.

Screen tips and menu items are able to locate any KeyBinding that is on the RoutedCommand and can display its keyboard shortcut if no other input gesture text is specified.

RoutedUICommand

RoutedUICommand inherits RoutedCommand and has the same general design, but with the additional benefit that it contains a Text property too.

Delegate Command Types

Delegate commands are often preferred to routed commands in more complex apps, and those that use MVVM. Delegate commands are passed a delegate for execute, can-execute, etc. logic.

Actipro includes a couple implementations of delegate commands in the Shared Library.

DelegateCommand<T>

The DelegateCommand<T> class implements a basic delegate command that supports execute and can-execute logic. The generic type parameter for the class indicates the Type of command parameter that is passed. Use Object if any or an unknown type of command parameter can be passed.

The following example shows how a DelegateCommand<T> can be created to insert a symbol into a document in response to a gallery item click.

var insertSymbolCommand = new DelegateCommand<SymbolBarGalleryItemViewModel>(
	executeAction: p => currentDocument?.Insert(p.Symbol),
	canExecuteFunc: p => currentDocument != null,
);

PreviewableDelegateCommand<T>

The PreviewableDelegateCommand<T> class inherits DelegateCommand<T> and augments it by implementing the IPreviewableCommand interface for live preview support. It adds delegates for starting and canceling live preview.

The following example shows how a PreviewableDelegateCommand<T> can be created to apply a text style to the selected text in a document and also support live preview.

var setTextStyleCommand = new PreviewableDelegateCommand<TextStyleBarGalleryItemViewModel>(
	executeAction: p => {
		currentDocument?.ApplyTextStyle(p);
	},
	canExecuteFunc: p => currentDocument != null,
	previewAction: p => {
		currentDocument?.StartPreviewMode();
		currentDocument?.ApplyTextStyle(p);
	},
	cancelPreviewAction: p => {
		currentDocument?.CancelPreviewMode();
	}
);

Composite Command Types

Composite commands are those that consist of one or more child commands working together as a single command. This is useful for scenarios where there may be transient view models or more than one view model that is active at a time. In those scenarios, and where each view model has a command, it's most effective to have the main window view model contain composite commands and have the child view models register their related commands with the appropriate composite command. This way the main window view model only knows about a general command functionality provided and doesn't have to iterate through the child view models itself when trying to execute their commands.

Actipro includes a couple implementations of composite commands in the Shared Library.

CompositeCommand

The CompositeCommand class implements a composite command that supports zero to many registered child commands.

A child command can be registered via the CompositeCommand.RegisterCommand or TryRegisterCommand methods. The former will throw an exception if the child command being registered is already registered. A child command can later be unregistered via the UnregisterCommand method.

The CompositeCommand.Execute method will iterate each registered child command and will call their own Execute methods.

The CompositeCommand.CanExecute method will iterate registered child commands, however its behavior is influenced by the RequireAllCommandsCanExecute property setting. If that property is true, all registered child commands will be checked to ensure that they all can execute. If that property is false, the logic will only ensure that at least one registered child command can execute.

PreviewableCompositeCommand

The PreviewableCompositeCommand class inherits CompositeCommand and augments it by implementing the IPreviewableCommand interface for live preview support.

The PreviewableCompositeCommand.Preview method will iterate all registered child commands that implement IPreviewableCommand, and will call their Preview methods.

The PreviewableCompositeCommand.CancelPreview method will iterate all registered child commands that implement IPreviewableCommand, and will call their CancelPreview methods.