--- title: "Commanding Overview" description: Learn about commanding, an input mechanism in Windows Presentation Foundation which provides input handling at a more semantic level than device input. ms.date: "03/30/2017" dev_langs: - "csharp" - "vb" helpviewer_keywords: - "interfaces [WPF], ICommandSource" - "command library [WPF]" - "commands [WPF], definition of" - "CommandBindings [WPF]" - "ICommandSource interfaces [WPF]" - "commanding [WPF]" - "CommandManager [WPF]" ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 --- # Commanding Overview Commanding is an input mechanism in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] which provides input handling at a more semantic level than device input. Examples of commands are the **Copy**, **Cut**, and **Paste** operations found on many applications. This overview defines what commands are in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], which classes are part of the commanding model, and how to use and create commands in your applications. This topic contains the following sections: - [What Are Commands?](#commands_at_10000_feet) - [Simple Command Example in WPF](#simple_command) - [Four Main Concepts in WPF Commanding](#Four_main_Concepts) - [Command Library](#Command_Library) - [Creating Custom Commands](#creating_commands) ## What Are Commands? Commands have several purposes. The first purpose is to separate the semantics and the object that invokes a command from the logic that executes the command. This allows for multiple and disparate sources to invoke the same command logic, and it allows the command logic to be customized for different targets. For example, the editing operations **Copy**, **Cut**, and **Paste**, which are found in many applications, can be invoked by using different user actions if they are implemented by using commands. An application might allow a user to cut selected objects or text by either clicking a button, choosing an item in a menu, or using a key combination, such as CTRL+X. By using commands, you can bind each type of user action to the same logic. Another purpose of commands is to indicate whether an action is available. To continue the example of cutting an object or text, the action only makes sense when something is selected. If a user tries to cut an object or text without having anything selected, nothing would happen. To indicate this to the user, many applications disable buttons and menu items so that the user knows whether it is possible to perform an action. A command can indicate whether an action is possible by implementing the method. A button can subscribe to the event and be disabled if returns `false` or be enabled if returns `true`. The semantics of a command can be consistent across applications and classes, but the logic of the action is specific to the particular object acted upon. The key combination CTRL+X invokes the **Cut** command in text classes, image classes, and Web browsers, but the actual logic for performing the **Cut** operation is defined by the application that performs the cut. A enables clients to implement the logic. A text object may cut the selected text into the clipboard, while an image object may cut the selected image. When an application handles the event, it has access to the target of the command and can take appropriate action depending on the target's type. ## Simple Command Example in WPF The simplest way to use a command in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is to use a predefined from one of the command library classes; use a control that has native support for handling the command; and use a control that has native support for invoking a command. The command is one of the predefined commands in the class. The control has built in logic for handling the command. And the class has native support for invoking commands. The following example shows how to set up a so that when it is clicked it will invoke the command on a , assuming the has keyboard focus. [!code-xaml[CommandingOverviewSnippets#CommandingOverviewSimpleCommand](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml#commandingoverviewsimplecommand)] [!code-csharp[CommandingOverviewSnippets#CommandingOverviewCommandTargetCodeBehind](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml.cs#commandingoverviewcommandtargetcodebehind)] [!code-vb[CommandingOverviewSnippets#CommandingOverviewCommandTargetCodeBehind](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandingOverviewSnippets/visualbasic/window1.xaml.vb#commandingoverviewcommandtargetcodebehind)] ## Four Main Concepts in WPF Commanding The routed command model in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can be broken up into four main concepts: the command, the command source, the command target, and the command binding: - The *command* is the action to be executed. - The *command source* is the object which invokes the command. - The *command target* is the object that the command is being executed on. - The *command binding* is the object which maps the command logic to the command. In the previous example, the command is the command, the is the command source, the is the command target, and the command binding is supplied by the control. It is worth noting that it is not always the case that the is supplied by the control that is the command target class. Quite often the must be created by the application developer, or the might be attached to an ancestor of the command target. ### Commands Commands in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are created by implementing the interface. exposes two methods, , and , and an event, . performs the actions that are associated with the command. determines whether the command can execute on the current command target. is raised if the command manager that centralizes the commanding operations detects a change in the command source that might invalidate a command that has been raised but not yet executed by the command binding. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of is the class and is the focus of this overview. The main sources of input in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are the mouse, the keyboard, ink, and routed commands. The more device-oriented inputs use a to notify objects in an application page that an input event has occurred. A is no different. The and methods of a do not contain the application logic for the command, but rather they raise routed events that tunnel and bubble through the element tree until they encounter an object with a . The contains the handlers for these events and it is the handlers that perform the command. For more information on event routing in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [Routed Events Overview](routed-events-overview.md). The method on a raises the and the events on the command target. The method on a raises the and events on the command target. These events tunnel and bubble through the element tree until they encounter an object which has a for that particular command. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supplies a set of common routed commands spread across several classes: , , , , and . These classes consist only of the objects and not the implementation logic of the command. The implementation logic is the responsibility of the object on which the command is being executed on. ### Command Sources A command source is the object which invokes the command. Examples of command sources are , , and . Command sources in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] generally implement the interface. exposes three properties: , , and : - is the command to execute when the command source is invoked. - is the object on which to execute the command. It is worth noting that in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] the property on is only applicable when the is a . If the is set on an and the corresponding command is not a , the command target is ignored. If the is not set, the element with keyboard focus will be the command target. - is a user-defined data type used to pass information to the handlers implementing the command. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes that implement are , , , and . , , and invoke a command when they are clicked, and an invokes a command when the associated with it is performed. The following example shows how to use a in a as a command source for the command. [!code-xaml[CommandingOverviewSnippets#CommandingOverviewCmdSourceXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml#commandingoverviewcmdsourcexaml)] [!code-csharp[CommandingOverviewSnippets#CommandingOverviewCmdSource](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml.cs#commandingoverviewcmdsource)] [!code-vb[CommandingOverviewSnippets#CommandingOverviewCmdSource](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandingOverviewSnippets/visualbasic/window1.xaml.vb#commandingoverviewcmdsource)] Typically, a command source will listen to the event. This event informs the command source that the ability of the command to execute on the current command target may have changed. The command source can query the current status of the by using the method. The command source can then disable itself if the command cannot execute. An example of this is a graying itself out when a command cannot execute. An can be used as a command source. Two types of input gestures in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are the and . You can think of a as a keyboard shortcut, such as CTRL+C. A is comprised of a and a set of . A is comprised of a and an optional set of . In order for an to act as a command source, it must be associated with a command. There are a few ways to accomplish this. One way is to use an . The following example shows how to create a between a and a . [!code-xaml[CommandingOverviewSnippets#CommandingOverviewXAMLKeyBinding](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml#commandingoverviewxamlkeybinding)] [!code-csharp[CommandingOverviewSnippets#CommandingOverviewKeyBinding](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml.cs#commandingoverviewkeybinding)] [!code-vb[CommandingOverviewSnippets#CommandingOverviewKeyBinding](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandingOverviewSnippets/visualbasic/window1.xaml.vb#commandingoverviewkeybinding)] Another way to associate an to a is to add the to the on the . The following example shows how to add a to the of a . [!code-csharp[CommandingOverviewSnippets#CommandingOverviewKeyGestureOnCmd](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml.cs#commandingoverviewkeygestureoncmd)] [!code-vb[CommandingOverviewSnippets#CommandingOverviewKeyGestureOnCmd](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandingOverviewSnippets/visualbasic/window1.xaml.vb#commandingoverviewkeygestureoncmd)] ### CommandBinding A associates a command with the event handlers that implement the command. The class contains a property, and , , , and events. is the command that the is being associated with. The event handlers which are attached to the and events implement the command logic. The event handlers attached to the and events determine if the command can execute on the current command target. The following example shows how to create a on the root of an application. The associates the command with and handlers. [!code-xaml[commandwithhandler#CommandHandlerCommandBinding](~/samples/snippets/csharp/VS_Snippets_Wpf/commandWithHandler/CSharp/Window1.xaml#commandhandlercommandbinding)] [!code-csharp[CommandHandlerProcedural#CommandHandlerBindingInit](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandHandlerProcedural/CSharp/Window1.xaml.cs#commandhandlerbindinginit)] [!code-vb[CommandHandlerProcedural#CommandHandlerBindingInit](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandHandlerProcedural/visualbasic/window1.xaml.vb#commandhandlerbindinginit)] Next, the and a are created. The opens a that displays a string saying the command has been executed. The sets the property to `true`. [!code-csharp[commandwithhandler#CommandHandlerExecutedHandler](~/samples/snippets/csharp/VS_Snippets_Wpf/commandWithHandler/CSharp/Window1.xaml.cs#commandhandlerexecutedhandler)] [!code-vb[commandwithhandler#CommandHandlerExecutedHandler](~/samples/snippets/visualbasic/VS_Snippets_Wpf/commandWithHandler/VisualBasic/Window1.xaml.vb#commandhandlerexecutedhandler)] [!code-csharp[commandwithhandler#CommandHandlerCanExecuteHandler](~/samples/snippets/csharp/VS_Snippets_Wpf/commandWithHandler/CSharp/Window1.xaml.cs#commandhandlercanexecutehandler)] [!code-vb[commandwithhandler#CommandHandlerCanExecuteHandler](~/samples/snippets/visualbasic/VS_Snippets_Wpf/commandWithHandler/VisualBasic/Window1.xaml.vb#commandhandlercanexecutehandler)] A is attached to a specific object, such as the root of the application or a control. The object that the is attached to defines the scope of the binding. For example, a attached to an ancestor of the command target can be reached by the event, but a attached to a descendant of the command target cannot be reached. This is a direct consequence of the way a tunnels and bubbles from the object that raises the event. In some situations the is attached to the command target itself, such as with the class and the , , and commands. Quite often though, it is more convenient to attach the to an ancestor of the command target, such as the main or the Application object, especially if the same can be used for multiple command targets. These are design decisions you will want to consider when you are creating your commanding infrastructure. ### Command Target The command target is the element on which the command is executed. With regards to a , the command target is the element at which routing of the and starts. As noted previously, in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] the property on is only applicable when the is a . If the is set on an and the corresponding command is not a , the command target is ignored. The command source can explicitly set the command target. If the command target is not defined, the element with keyboard focus will be used as the command target. One of the benefits of using the element with keyboard focus as the command target is that it allows the application developer to use the same command source to invoke a command on multiple targets without having to keep track of the command target. For example, if a invokes the **Paste** command in an application that has a control and a control, the target can be either the or depending on which control has keyboard focus. The following example shows how to explicitly set the command target in markup and in code behind. [!code-xaml[CommandingOverviewSnippets#CommandingOverviewXAMLCommandTarget](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml#commandingoverviewxamlcommandtarget)] [!code-csharp[CommandingOverviewSnippets#CommandingOverviewCommandTargetCodeBehind](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml.cs#commandingoverviewcommandtargetcodebehind)] [!code-vb[CommandingOverviewSnippets#CommandingOverviewCommandTargetCodeBehind](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandingOverviewSnippets/visualbasic/window1.xaml.vb#commandingoverviewcommandtargetcodebehind)] ### The CommandManager The serves a number of command related functions. It provides a set of static methods for adding and removing , , , and event handlers to and from a specific element. It provides a means to register and objects onto a specific class. The also provides a means, through the event, to notify a command when it should raise the event. The method forces the to raise the event. This is useful for conditions that should disable/enable a command but are not conditions that the is aware of. ## Command Library [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a set of predefined commands. The command library consists of the following classes: , , , , and the . These classes provide commands such as , and , , , and . Many of these commands include a set of default input bindings. For example, if you specify that your application handles the copy command, you automatically get the keyboard binding "CTRL+C" You also get bindings for other input devices, such as Tablet PC pen gestures and speech information. When you reference commands in the various command libraries using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can usually omit the class name of the library class that exposes the static command property. Generally, the command names are unambiguous as strings, and the owning types exist to provide a logical grouping of commands but are not necessary for disambiguation. For instance, you can specify `Command="Cut"` rather than the more verbose `Command="ApplicationCommands.Cut"`. This is a convenience mechanism that is built in to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor for commands (more precisely, it is a type converter behavior of , which the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor references at load time). ## Creating Custom Commands If the commands in the command library classes do not meet your needs, then you can create your own commands. There are two ways to create a custom command. The first is to start from the ground up and implement the interface. The other way, and the more common approach, is to create a or a . For an example of creating a custom , see [Create a Custom RoutedCommand Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Input%20and%20Commands/CustomRoutedCommand). ## See also - - - - - [Input Overview](input-overview.md) - [Routed Events Overview](routed-events-overview.md) - [Implement ICommandSource](how-to-implement-icommandsource.md) - [How to: Add a Command to a MenuItem](https://docs.microsoft.com/previous-versions/dotnet/netframework-3.5/ms741839(v=vs.90)) - [Create a Custom RoutedCommand Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Input%20and%20Commands/CustomRoutedCommand)