mirror of
https://github.com/Stone-Red-Code/docs-desktop.git
synced 2026-09-06 07:56:06 +02:00
Replace various WPF include files with content (#1335)
* net-current-v30plus-md.md * net-current-v40plus-md.md * tla2sharptla-ui-md.md * tla2sharptla-uiautomation-md.md * tla2sharptla-winclient-md.md * tla2sharptla-xaml-md.md * tlasharptla-ui-md.md * tlasharptla-uiautomation-md.md * tlasharptla-winclient-md.md * tlasharptla-xaml-md.md * fix warnings
This commit is contained in:
Andy (Steve) De George
@@ -18,9 +18,9 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
---
|
||||
# Commanding Overview
|
||||
|
||||
<a name="introduction"></a> 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.
|
||||
<a name="introduction"></a> Commanding is an input mechanism in Windows Presentation Foundation (WPF) 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 overview defines what commands are in WPF, which classes are part of the commanding model, and how to use and create commands in your applications.
|
||||
|
||||
This topic contains the following sections:
|
||||
|
||||
@@ -48,7 +48,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
## 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 <xref:System.Windows.Input.RoutedCommand> 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 <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command is one of the predefined commands in the <xref:System.Windows.Input.ApplicationCommands> class. The <xref:System.Windows.Controls.TextBox> control has built in logic for handling the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command. And the <xref:System.Windows.Controls.MenuItem> class has native support for invoking commands.
|
||||
The simplest way to use a command in WPF is to use a predefined <xref:System.Windows.Input.RoutedCommand> 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 <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command is one of the predefined commands in the <xref:System.Windows.Input.ApplicationCommands> class. The <xref:System.Windows.Controls.TextBox> control has built in logic for handling the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command. And the <xref:System.Windows.Controls.MenuItem> class has native support for invoking commands.
|
||||
|
||||
The following example shows how to set up a <xref:System.Windows.Controls.MenuItem> so that when it is clicked it will invoke the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command on a <xref:System.Windows.Controls.TextBox>, assuming the <xref:System.Windows.Controls.TextBox> has keyboard focus.
|
||||
|
||||
@@ -61,7 +61,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
## 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 routed command model in WPF 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.
|
||||
|
||||
@@ -77,13 +77,13 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
### Commands
|
||||
|
||||
Commands in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are created by implementing the <xref:System.Windows.Input.ICommand> interface. <xref:System.Windows.Input.ICommand> exposes two methods, <xref:System.Windows.Input.ICommand.Execute%2A>, and <xref:System.Windows.Input.ICommand.CanExecute%2A>, and an event, <xref:System.Windows.Input.ICommand.CanExecuteChanged>. <xref:System.Windows.Input.ICommand.Execute%2A> performs the actions that are associated with the command. <xref:System.Windows.Input.ICommand.CanExecute%2A> determines whether the command can execute on the current command target. <xref:System.Windows.Input.ICommand.CanExecuteChanged> 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 <xref:System.Windows.Input.ICommand> is the <xref:System.Windows.Input.RoutedCommand> class and is the focus of this overview.
|
||||
Commands in WPF are created by implementing the <xref:System.Windows.Input.ICommand> interface. <xref:System.Windows.Input.ICommand> exposes two methods, <xref:System.Windows.Input.ICommand.Execute%2A>, and <xref:System.Windows.Input.ICommand.CanExecute%2A>, and an event, <xref:System.Windows.Input.ICommand.CanExecuteChanged>. <xref:System.Windows.Input.ICommand.Execute%2A> performs the actions that are associated with the command. <xref:System.Windows.Input.ICommand.CanExecute%2A> determines whether the command can execute on the current command target. <xref:System.Windows.Input.ICommand.CanExecuteChanged> 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 WPF implementation of <xref:System.Windows.Input.ICommand> is the <xref:System.Windows.Input.RoutedCommand> 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 <xref:System.Windows.RoutedEvent> to notify objects in an application page that an input event has occurred. A <xref:System.Windows.Input.RoutedCommand> is no different. The <xref:System.Windows.Input.RoutedCommand.Execute%2A> and <xref:System.Windows.Input.RoutedCommand.CanExecute%2A> methods of a <xref:System.Windows.Input.RoutedCommand> 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 <xref:System.Windows.Input.CommandBinding>. The <xref:System.Windows.Input.CommandBinding> 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 main sources of input in WPF are the mouse, the keyboard, ink, and routed commands. The more device-oriented inputs use a <xref:System.Windows.RoutedEvent> to notify objects in an application page that an input event has occurred. A <xref:System.Windows.Input.RoutedCommand> is no different. The <xref:System.Windows.Input.RoutedCommand.Execute%2A> and <xref:System.Windows.Input.RoutedCommand.CanExecute%2A> methods of a <xref:System.Windows.Input.RoutedCommand> 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 <xref:System.Windows.Input.CommandBinding>. The <xref:System.Windows.Input.CommandBinding> contains the handlers for these events and it is the handlers that perform the command. For more information on event routing in WPF, see [Routed Events Overview](routed-events-overview.md).
|
||||
|
||||
The <xref:System.Windows.Input.RoutedCommand.Execute%2A> method on a <xref:System.Windows.Input.RoutedCommand> raises the <xref:System.Windows.Input.CommandManager.PreviewExecuted> and the <xref:System.Windows.Input.CommandManager.Executed> events on the command target. The <xref:System.Windows.Input.RoutedCommand.CanExecute%2A> method on a <xref:System.Windows.Input.RoutedCommand> raises the <xref:System.Windows.Input.CommandManager.CanExecute> and <xref:System.Windows.Input.CommandManager.PreviewCanExecute> events on the command target. These events tunnel and bubble through the element tree until they encounter an object which has a <xref:System.Windows.Input.CommandBinding> for that particular command.
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supplies a set of common routed commands spread across several classes: <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.ComponentCommands>, and <xref:System.Windows.Documents.EditingCommands>. These classes consist only of the <xref:System.Windows.Input.RoutedCommand> 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.
|
||||
WPF supplies a set of common routed commands spread across several classes: <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.ComponentCommands>, and <xref:System.Windows.Documents.EditingCommands>. These classes consist only of the <xref:System.Windows.Input.RoutedCommand> 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.
|
||||
|
||||
<a name="Command_Sources"></a>
|
||||
|
||||
@@ -91,17 +91,17 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
A command source is the object which invokes the command. Examples of command sources are <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Controls.Button>, and <xref:System.Windows.Input.KeyGesture>.
|
||||
|
||||
Command sources in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] generally implement the <xref:System.Windows.Input.ICommandSource> interface.
|
||||
Command sources in WPF generally implement the <xref:System.Windows.Input.ICommandSource> interface.
|
||||
|
||||
<xref:System.Windows.Input.ICommandSource> exposes three properties: <xref:System.Windows.Input.ICommandSource.Command%2A>, <xref:System.Windows.Input.ICommandSource.CommandTarget%2A>, and <xref:System.Windows.Input.ICommandSource.CommandParameter%2A>:
|
||||
|
||||
- <xref:System.Windows.Input.ICommandSource.Command%2A> is the command to execute when the command source is invoked.
|
||||
|
||||
- <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> 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 <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> property on <xref:System.Windows.Input.ICommandSource> is only applicable when the <xref:System.Windows.Input.ICommand> is a <xref:System.Windows.Input.RoutedCommand>. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is set on an <xref:System.Windows.Input.ICommandSource> and the corresponding command is not a <xref:System.Windows.Input.RoutedCommand>, the command target is ignored. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is not set, the element with keyboard focus will be the command target.
|
||||
- <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is the object on which to execute the command. It is worth noting that in WPF the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> property on <xref:System.Windows.Input.ICommandSource> is only applicable when the <xref:System.Windows.Input.ICommand> is a <xref:System.Windows.Input.RoutedCommand>. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is set on an <xref:System.Windows.Input.ICommandSource> and the corresponding command is not a <xref:System.Windows.Input.RoutedCommand>, the command target is ignored. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is not set, the element with keyboard focus will be the command target.
|
||||
|
||||
- <xref:System.Windows.Input.ICommandSource.CommandParameter%2A> 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 <xref:System.Windows.Input.ICommandSource> are <xref:System.Windows.Controls.Primitives.ButtonBase>, <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Documents.Hyperlink>, and <xref:System.Windows.Input.InputBinding>. <xref:System.Windows.Controls.Primitives.ButtonBase>, <xref:System.Windows.Controls.MenuItem>, and <xref:System.Windows.Documents.Hyperlink> invoke a command when they are clicked, and an <xref:System.Windows.Input.InputBinding> invokes a command when the <xref:System.Windows.Input.InputGesture> associated with it is performed.
|
||||
The WPF classes that implement <xref:System.Windows.Input.ICommandSource> are <xref:System.Windows.Controls.Primitives.ButtonBase>, <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Documents.Hyperlink>, and <xref:System.Windows.Input.InputBinding>. <xref:System.Windows.Controls.Primitives.ButtonBase>, <xref:System.Windows.Controls.MenuItem>, and <xref:System.Windows.Documents.Hyperlink> invoke a command when they are clicked, and an <xref:System.Windows.Input.InputBinding> invokes a command when the <xref:System.Windows.Input.InputGesture> associated with it is performed.
|
||||
|
||||
The following example shows how to use a <xref:System.Windows.Controls.MenuItem> in a <xref:System.Windows.Controls.ContextMenu> as a command source for the <xref:System.Windows.Input.ApplicationCommands.Properties%2A> command.
|
||||
|
||||
@@ -112,7 +112,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
Typically, a command source will listen to the <xref:System.Windows.Input.RoutedCommand.CanExecuteChanged> 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 <xref:System.Windows.Input.RoutedCommand> by using the <xref:System.Windows.Input.RoutedCommand.CanExecute%2A> method. The command source can then disable itself if the command cannot execute. An example of this is a <xref:System.Windows.Controls.MenuItem> graying itself out when a command cannot execute.
|
||||
|
||||
An <xref:System.Windows.Input.InputGesture> can be used as a command source. Two types of input gestures in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are the <xref:System.Windows.Input.KeyGesture> and <xref:System.Windows.Input.MouseGesture>. You can think of a <xref:System.Windows.Input.KeyGesture> as a keyboard shortcut, such as CTRL+C. A <xref:System.Windows.Input.KeyGesture> is comprised of a <xref:System.Windows.Input.Key> and a set of <xref:System.Windows.Input.ModifierKeys>. A <xref:System.Windows.Input.MouseGesture> is comprised of a <xref:System.Windows.Input.MouseAction> and an optional set of <xref:System.Windows.Input.ModifierKeys>.
|
||||
An <xref:System.Windows.Input.InputGesture> can be used as a command source. Two types of input gestures in WPF are the <xref:System.Windows.Input.KeyGesture> and <xref:System.Windows.Input.MouseGesture>. You can think of a <xref:System.Windows.Input.KeyGesture> as a keyboard shortcut, such as CTRL+C. A <xref:System.Windows.Input.KeyGesture> is comprised of a <xref:System.Windows.Input.Key> and a set of <xref:System.Windows.Input.ModifierKeys>. A <xref:System.Windows.Input.MouseGesture> is comprised of a <xref:System.Windows.Input.MouseAction> and an optional set of <xref:System.Windows.Input.ModifierKeys>.
|
||||
|
||||
In order for an <xref:System.Windows.Input.InputGesture> 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 <xref:System.Windows.Input.InputBinding>.
|
||||
|
||||
@@ -163,7 +163,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
### Command Target
|
||||
|
||||
The command target is the element on which the command is executed. With regards to a <xref:System.Windows.Input.RoutedCommand>, the command target is the element at which routing of the <xref:System.Windows.Input.CommandManager.Executed> and <xref:System.Windows.Input.CommandManager.CanExecute> starts. As noted previously, in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> property on <xref:System.Windows.Input.ICommandSource> is only applicable when the <xref:System.Windows.Input.ICommand> is a <xref:System.Windows.Input.RoutedCommand>. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is set on an <xref:System.Windows.Input.ICommandSource> and the corresponding command is not a <xref:System.Windows.Input.RoutedCommand>, the command target is ignored.
|
||||
The command target is the element on which the command is executed. With regards to a <xref:System.Windows.Input.RoutedCommand>, the command target is the element at which routing of the <xref:System.Windows.Input.CommandManager.Executed> and <xref:System.Windows.Input.CommandManager.CanExecute> starts. As noted previously, in WPF the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> property on <xref:System.Windows.Input.ICommandSource> is only applicable when the <xref:System.Windows.Input.ICommand> is a <xref:System.Windows.Input.RoutedCommand>. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is set on an <xref:System.Windows.Input.ICommandSource> and the corresponding command is not a <xref:System.Windows.Input.RoutedCommand>, 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 <xref:System.Windows.Controls.MenuItem> invokes the **Paste** command in an application that has a <xref:System.Windows.Controls.TextBox> control and a <xref:System.Windows.Controls.PasswordBox> control, the target can be either the <xref:System.Windows.Controls.TextBox> or <xref:System.Windows.Controls.PasswordBox> depending on which control has keyboard focus.
|
||||
|
||||
@@ -186,11 +186,11 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
## 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: <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Documents.EditingCommands>, and the <xref:System.Windows.Input.ComponentCommands>. These classes provide commands such as <xref:System.Windows.Input.ApplicationCommands.Cut%2A>, <xref:System.Windows.Input.NavigationCommands.BrowseBack%2A> and <xref:System.Windows.Input.NavigationCommands.BrowseForward%2A>, <xref:System.Windows.Input.MediaCommands.Play%2A>, <xref:System.Windows.Input.MediaCommands.Stop%2A>, and <xref:System.Windows.Input.MediaCommands.Pause%2A>.
|
||||
WPF provides a set of predefined commands. The command library consists of the following classes: <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Documents.EditingCommands>, and the <xref:System.Windows.Input.ComponentCommands>. These classes provide commands such as <xref:System.Windows.Input.ApplicationCommands.Cut%2A>, <xref:System.Windows.Input.NavigationCommands.BrowseBack%2A> and <xref:System.Windows.Input.NavigationCommands.BrowseForward%2A>, <xref:System.Windows.Input.MediaCommands.Play%2A>, <xref:System.Windows.Input.MediaCommands.Stop%2A>, and <xref:System.Windows.Input.MediaCommands.Pause%2A>.
|
||||
|
||||
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 <xref:System.Windows.Input.ICommand>, 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).
|
||||
When you reference commands in the various command libraries using WPF WPF XAML processor references at load time).
|
||||
|
||||
<a name="creating_commands"></a>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user