Drag-and-drop operations can have different effects on the transferred data. For example, you can copy the data or you can move the data. WPF defines a DragDropEffects enumeration that you can use to specify the effect of a drag-and-drop operation. In the drag source, you can specify the effects that the source will allow in the DoDragDrop method. In the drop target, you can specify the effect that the target intends in the Effectsproperty of the DragEventArgs class. When the drop target specifies its intended effect in the DragOver event, that information is passed back to the drag source in the GiveFeedback event. The drag source uses this information to inform the user what effect the drop target intends to have on the data. When the data is dropped, the drop target specifies its actual effect in the Drop event. That information is passed back to the drag source as the return value of the DoDragDrop method. If the drop target returns an effect that is not in the drag sources list of allowedEffects, the drag-and-drop operation is cancelled without any data transfer occurring.

It is important to remember that in WPF, the DragDropEffects values are only used to provide communication between the drag source and the drop target regarding the effects of the drag-and-drop operation. The actual effect of the drag-and-drop operation depends on you to write the appropriate code in your application.

For example, the drop target might specify that the effect of dropping data on it is to move the data. However, to move the data, it must be both added to the target element and removed from the source element. The source element might indicate that it allows moving the data, but if you do not provide the code to remove the data from the source element, the end result will be that the data is copied, and not moved.

To handle drag-and-drop events for instances of an object, add handlers for the events listed in the preceding tables. To handle drag-and-drop events at the class level, override the corresponding virtual On*Event and On*PreviewEvent methods. For more information, see Class Handling of Routed Events by Control Base Classes.

An object that is a drag source is responsible for:

• Identifying when a drag occurs.

• Initiating the drag-and-drop operation.

• Identifying the data to be transferred.

• Specifying the effects that the drag-and-drop operation is allowed to have on the transferred data.

The drag source may also give feedback to the user regarding the allowed actions (move, copy, none), and can cancel the drag-and-drop operation based on additional user input, such as pressing the ESC key during the drag.

It is the responsibility of your application to determine when a drag occurs, and then initiate the drag-and-drop operation by calling the DoDragDrop method. Typically, this is when a MouseMove event occurs over the element to be dragged while a mouse button is pressed. The following example shows how to initiate a drag-and-drop operation from the MouseMove event handler of an Ellipse element to make it a drag source. The transferred data is the string representation of the ellipse’s Fill property.

private void ellipse_MouseMove(object sender, MouseEventArgs e)
{
    Ellipse ellipse = sender as Ellipse;
    if (ellipse != null && e.LeftButton == MouseButtonState.Pressed)
    {
        DragDrop.DoDragDrop( ellipse,
                             ellipse.Fill.ToString(),
                             DragDropEffects.Copy);
    }
}

Inside of the MouseMove event handler, call the DoDragDrop method to initiate the drag-and-drop operation. The DoDragDrop method takes three parameters:

• dragSource – A reference to the dependency object that is the source of the transferred data; this is typically the source of the MouseMoveevent.

• data - An object that contains the transferred data, wrapped in a DataObject.

• allowedEffects - One of the DragDropEffects enumeration values that specifies the permitted effects of the drag-and-drop operation.

Any serializable object can be passed in the data parameter. If the data is not already wrapped in a DataObject, it will automatically be wrapped in a new DataObject. To pass multiple data items, you must create the DataObject yourself, and pass it to the DoDragDrop method. For more information, see Data and Data Objects.

The allowedEffects parameter is used to specify what the drag source will allow the drop target to do with the transferred data. The common values for a drag source are Copy, Move, and All.

Note
The drop target is also able to specify what effects it intends in response to the dropped data. For example, if the drop target does not recognize the data type to be dropped, it can refuse the data by setting its allowed effects to None. It typically does this in its DragOver event handler.

A drag source can optionally handle the GiveFeedback and QueryContinueDrag events. These events have default handlers that are used unless you mark the events as handled. You will typically ignore these events unless you have a specific need to change their default behavior.

The GiveFeedback event is raised continuously while the drag source is being dragged. The default handler for this event checks whether the drag source is over a valid drop target. If it is, it checks the allowed effects of the drop target. It then gives feedback to the end user regarding the allowed drop effects. This is typically done by changing the mouse cursor to a no-drop, copy, or move cursor. You should only handle this event if you need to use custom cursors to provide feedback to the user. If you handle this event, be sure to mark it as handled so that the default handler does not override your handler.

The QueryContinueDrag event is raised continuously while the drag source is being dragged. You can handle this event to determine what action ends the drag-and-drop operation based on the state of the ESC, SHIFT, CTRL, and ALT keys, as well as the state of the mouse buttons. The default handler for this event cancels the drag-and-drop operation if the ESC key is pressed, and drops the data if the mouse button is released.

Caution
These events are raised continuously during the drag-and-drop operation. Therefore, you should avoid resource-intensive tasks in the event handlers. For example, use a cached cursor instead of creating a new cursor each time the GiveFeedback event is raised.

An object that is a drop target is responsible for:

• Specifying that it is a valid drop target.

• Responding to the drag source when it drags over the target.

• Checking that the transferred data is in a format that it can receive.

• Processing the dropped data.

To specify that an element is a drop target, you set its AllowDrop property to true. The drop target events will then be raised on the element so that you can handle them. During a drag-and-drop operation, the following sequence of events occurs on the drop target:

1. DragEnter

2. DragOver

3. DragLeave or Drop

The DragEnter event occurs when the data is dragged into the drop target's boundary. You typically handle this event to provide a preview of the effects of the drag-and-drop operation, if appropriate for your application. Do not set the DragEventArgs.Effects property in the DragEnter event, as it will be overwritten in the DragOver event.

The following example shows the DragEnter event handler for an Ellipse element. This code previews the effects of the drag-and-drop operation by saving the current Fill brush. It then uses the GetDataPresent method to check whether the DataObject being dragged over the ellipse contains string data that can be converted to a Brush. If so, the data is extracted using the GetData method. It is then converted to a Brush and applied to the ellipse. The change is reverted in the DragLeave event handler. If the data cannot be converted to a Brush, no action is performed.

private Brush _previousFill = null;
private void ellipse_DragEnter(object sender, DragEventArgs e)
{
    Ellipse ellipse = sender as Ellipse;
    if (ellipse != null)
    {
        // Save the current Fill brush so that you can revert back to this value in DragLeave.
        _previousFill = ellipse.Fill;

        // If the DataObject contains string data, extract it.
        if (e.Data.GetDataPresent(DataFormats.StringFormat))
        {
            string dataString = (string)e.Data.GetData(DataFormats.StringFormat);

            // If the string can be converted into a Brush, convert it.
            BrushConverter converter = new BrushConverter();
            if (converter.IsValid(dataString))
            {
                Brush newFill = (Brush)converter.ConvertFromString(dataString);
                ellipse.Fill = newFill;
            }
        }
    }
}

The DragOver event occurs continuously while the data is dragged over the drop target. This event is paired with the GiveFeedback event on the drag source. In the DragOver event handler, you typically use the GetDataPresent and GetData methods to check whether the transferred data is in a format that the drop target can process. You can also check whether any modifier keys are pressed, which will typically indicate whether the user intends a move or copy action. After these checks are performed, you set the DragEventArgs.Effects property to notify the drag source what effect dropping the data will have. The drag source receives this information in the GiveFeedback event args, and can set an appropriate cursor to give feedback to the user.

The following example shows the DragOver event handler for an Ellipse element. This code checks to see if the DataObject being dragged over the ellipse contains string data that can be converted to a Brush. If so, it sets the DragEventArgs.Effects property to Copy. This indicates to the drag source that the data can be copied to the ellipse. If the data cannot be converted to a Brush, the DragEventArgs.Effects property is set to None. This indicates to the drag source that the ellipse is not a valid drop target for the data.

private void ellipse_DragOver(object sender, DragEventArgs e)
{
    e.Effects = DragDropEffects.None;

    // If the DataObject contains string data, extract it.
    if (e.Data.GetDataPresent(DataFormats.StringFormat))
    {
        string dataString = (string)e.Data.GetData(DataFormats.StringFormat);

        // If the string can be converted into a Brush, allow copying.
        BrushConverter converter = new BrushConverter();
        if (converter.IsValid(dataString))
        {
            e.Effects = DragDropEffects.Copy | DragDropEffects.Move;
        }
    }
}

The DragLeave event occurs when the data is dragged out of the target's boundary without being dropped. You handle this event to undo anything that you did in the DragEnter event handler.

The following example shows the DragLeave event handler for an Ellipse element. This code undoes the preview performed in the DragEnter event handler by applying the saved Brush to the ellipse.

private void ellipse_DragLeave(object sender, DragEventArgs e)
{
    Ellipse ellipse = sender as Ellipse;
    if (ellipse != null)
    {
        ellipse.Fill = _previousFill;
    }
}

The Drop event occurs when the data is dropped over the drop target; by default, this happens when the mouse button is released. In the Dropevent handler, you use the GetData method to extract the transferred data from the DataObject and perform any data processing that your application requires. The Drop event ends the drag-and-drop operation.

The following example shows the Drop event handler for an Ellipse element. This code applies the effects of the drag-and-drop operation, and is similar to the code in the DragEnter event handler. It checks to see if the DataObject being dragged over the ellipse contains string data that can be converted to a Brush. If so, the Brush is applied to the ellipse. If the data cannot be converted to a Brush, no action is performed.

private void ellipse_Drop(object sender, DragEventArgs e)
{
    Ellipse ellipse = sender as Ellipse;
    if (ellipse != null)
    {
        // If the DataObject contains string data, extract it.
        if (e.Data.GetDataPresent(DataFormats.StringFormat))
        {
            string dataString = (string)e.Data.GetData(DataFormats.StringFormat);

            // If the string can be converted into a Brush, 
            // convert it and apply it to the ellipse.
            BrushConverter converter = new BrushConverter();
            if (converter.IsValid(dataString))
            {
                Brush newFill = (Brush)converter.ConvertFromString(dataString);
                ellipse.Fill = newFill;
            }
        }
    }
}

The DataObject class provides several overloaded constructors that facilitate populating a new DataObject instance with a single data/data format pair.

The following example code creates a new data object and uses one of the overloaded constructors DataObject(DataObject(String, Object)) to initialize the data object with a string and a specified data format. In this case, the data format is specified by a string; the DataFormats class provides a set of pre-defined type strings. Auto-conversion of the stored data is allowed by default.

string stringData = "Some string data to store...";
string dataFormat = DataFormats.UnicodeText;
DataObject dataObject = new DataObject(dataFormat, stringData);

For more examples of code that creates a data object, see How to: Create a Data Object.

A single data object is able to store data in multiple formats. Strategic use of multiple data formats within a single data object potentially makes the data object consumable by a wider variety of drop targets than if only a single data format could be represented. Note that, in general, a drag source must be agnostic about the data formats that are consumable by potential drop targets.

The following example shows how to use the SetData(String, Object) method to add data to a data object in multiple formats.

DataObject dataObject = new DataObject();
string sourceData = "Some string data to store...";

// Encode the source string into Unicode byte arrays.
byte[] unicodeText = Encoding.Unicode.GetBytes(sourceData); // UTF-16
byte[] utf8Text = Encoding.UTF8.GetBytes(sourceData);
byte[] utf32Text = Encoding.UTF32.GetBytes(sourceData);

// The DataFormats class does not provide data format fields for denoting
// UTF-32 and UTF-8, which are seldom used in practice; the following strings 
// will be used to identify these "custom" data formats.
string utf32DataFormat = "UTF-32";
string utf8DataFormat  = "UTF-8";

// Store the text in the data object, letting the data object choose
// the data format (which will be DataFormats.Text in this case).
dataObject.SetData(sourceData);
// Store the Unicode text in the data object.  Text data can be automatically
// converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object; 
// Therefore, explicitly converting the source text to Unicode is generally unnecessary, and
// is done here as an exercise only.
dataObject.SetData(DataFormats.UnicodeText, unicodeText);
// Store the UTF-8 text in the data object...
dataObject.SetData(utf8DataFormat, utf8Text);
// Store the UTF-32 text in the data object...
dataObject.SetData(utf32DataFormat, utf32Text);

Because a single data object can contain an arbitrary number of data formats, data objects include facilities for retrieving a list of available data formats.

The following example code uses the GetFormats overload to get an array of strings denoting all data formats available in a data object (both native and by auto-convert).

DataObject dataObject = new DataObject("Some string data to store...");

// Get an array of strings, each string denoting a data format
// that is available in the data object.  This overload of GetDataFormats
// returns all available data formats, native and auto-convertible.
string[] dataFormats = dataObject.GetFormats();

// Get the number of data formats present in the data object, including both
// auto-convertible and native data formats.
int numberOfDataFormats = dataFormats.Length;

// To enumerate the resulting array of data formats, and take some action when
// a particular data format is found, use a code structure similar to the following.
foreach (string dataFormat in dataFormats)
{
    if (dataFormat == DataFormats.Text)
    {
        // Take some action if/when data in the Text data format is found.
        break;
    }
    else if(dataFormat == DataFormats.StringFormat)
    {
        // Take some action if/when data in the string data format is found.
        break;
    }
}

For more examples of code that queries a data object for available data formats, see How to: List the Data Formats in a Data Object. For examples of querying a data object for the presence of a particular data format, see How to: Determine if a Data Format is Present in a Data Object.

Retrieving data from a data object in a particular format simply involves calling one of the GetData methods and specifying the desired data format. One of the GetDataPresent methods can be used to check for the presence of a particular data format. GetData returns the data in an Object; depending on the data format, this object can be cast to a type-specific container.

The following example code uses the GetDataPresent(String) overload to check if a specified data format is available (native or by auto-convert). If the specified format is available, the example retrieves the data by using the GetData(String) method.

DataObject dataObject = new DataObject("Some string data to store...");

string desiredFormat = DataFormats.UnicodeText;
byte[] data = null;

// Use the GetDataPresent method to check for the presence of a desired data format.
// This particular overload of GetDataPresent looks for both native and auto-convertible 
// data formats.
if (dataObject.GetDataPresent(desiredFormat))
{
    // If the desired data format is present, use one of the GetData methods to retrieve the
    // data from the data object.
    data = dataObject.GetData(desiredFormat) as byte[];
}

For more examples of code that retrieves data from a data object, see How to: Retrieve Data in a Particular Data Format.

Data cannot be directly removed from a data object. To effectively remove data from a data object, follow these steps:

1. Create a new data object that will contain only the data you want to retain.

2. "Copy" the desired data from the old data object to the new data object. To copy the data, use one of the GetData methods to retrieve an Object that contains the raw data, and then use one of the SetData methods to add the data to the new data object.

3. Replace the old data object with the new one.

Note
The SetData methods only add data to a data object; they do not replace data, even if the data and data format are exactly the same as a previous call. Calling SetData twice for the same data and data format will result in the data/data format being present twice in the data object.

1. Create a new WPF Application project in Visual Basic or Visual C# named DragDropExample. For more information, see How to: Create a New WPF Application Project.

2. Open MainWindow.xaml.

3. Add the following markup between the opening and closing Grid tags.

   This markup creates the user interface for the test application.

   XAML

   <Grid.ColumnDefinitions>
       <ColumnDefinition />
       <ColumnDefinition />
   </Grid.ColumnDefinitions>
   <StackPanel Grid.Column="0"
               Background="Beige">
       <TextBox Width="Auto" Margin="2"
                Text="green"/>
   </StackPanel>
   <StackPanel Grid.Column="1"
               Background="Bisque">
   </StackPanel>
   

1. On the Project menu, select Add User Control.

2. In the Add New Item dialog box, change the name to Circle.xaml, and click Add.

   Circle.xaml and its code-behind is added to the project.

3. Open Circle.xaml.

   This file will contain the user interface elements of the user control.

4. Add the following markup to the root Grid to create a simple user control that has a blue circle as its UI.

   XAML

   <Ellipse x:Name="circleUI" 
            Height="100" Width="100"
            Fill="Blue" />
   

5. Open Circle.xaml.cs or Circle.xaml.vb.

6. In C#, add the following code after the default constructor to create a copy constructor. In Visual Basic, add the following code to create both a default constructor and a copy constructor.

   In order to allow the user control to be copied, you add a copy constructor method in the code-behind file. In the simplified Circle user control, you will only copy the Fill and the size of the of the user control.

   C#

   VB

   public Circle(Circle c)
   {
       InitializeComponent();
       this.circleUI.Height = c.circleUI.Height;
       this.circleUI.Width = c.circleUI.Height;
       this.circleUI.Fill = c.circleUI.Fill;
   }
   

1. Open MainWindow.xaml.

2. Add the following XAML to the opening Window tag to create an XML namespace reference to the current application.

   xmlns:local="clr-namespace:DragDropExample"
   

3. In the first StackPanel, add the following XAML to create two instances of the Circle user control in the first panel.

   XAML

   <local:Circle Margin="2" />
   <local:Circle Margin="2" />
   

   The full XAML for the panel looks like the following.

   XAML

   <StackPanel Grid.Column="0"
               Background="Beige">
       <TextBox Width="Auto" Margin="2"
                Text="green"/>
       <local:Circle Margin="2" />
       <local:Circle Margin="2" />
   </StackPanel>
   <StackPanel Grid.Column="1"
               Background="Bisque">
   </StackPanel>
   

1. Open Circle.xaml.cs or Circle.xaml.vb.

2. Add the following OnMouseMove override to provide class handling for the MouseMove event.

   C#

   VB

   protected override void OnMouseMove(MouseEventArgs e)
   {
       base.OnMouseMove(e);
       if (e.LeftButton == MouseButtonState.Pressed)
       {
           // Package the data.
           DataObject data = new DataObject();
           data.SetData(DataFormats.StringFormat, circleUI.Fill.ToString());
           data.SetData("Double", circleUI.Height);
           data.SetData("Object", this);
   
           // Inititate the drag-and-drop operation.
           DragDrop.DoDragDrop(this, data, DragDropEffects.Copy | DragDropEffects.Move);
       }
   }
   

   This OnMouseMove override performs the following tasks:

   • Checks whether the left mouse button is pressed while the mouse is moving.

   • Packages the Circle data into a DataObject. In this case, the Circle control packages three data items; a string representation of its Fill color, a double representation of its height, and a copy of itself.

   • Calls the static DragDrop.DoDragDrop method to initiate the drag-and-drop operation. You pass the following three parameters to the DoDragDrop method:

     • dragSource – A reference to this control.

     • data – The DataObject created in the previous code.

     • allowedEffects – The allowed drag-and-drop operations, which are Copy or Move.

3. Press F5 to build and run the application.

4. Click one of the Circle controls and drag it over the panels, the other Circle, and the TextBox. When dragging over the TextBox, the cursor changes to indicate a move.

5. While dragging a Circle over the TextBox, press the CTRL key. Notice how the cursor changes to indicate a copy.

6. Drag and drop a Circle onto the TextBox. The string representation of the Circle’s fill color is appended to the TextBox.

   

By default, the cursor will change during a drag-and-drop operation to indicate what effect dropping the data will have. You can customize the feedback given to the user by handling the GiveFeedback event and setting a different cursor.

1. Open Circle.xaml.cs or Circle.xaml.vb.

2. Add the following OnGiveFeedback override to provide class handling for the GiveFeedback event.

   C#

   VB

   protected override void OnGiveFeedback(GiveFeedbackEventArgs e)
   {
       base.OnGiveFeedback(e);
       // These Effects values are set in the drop target's
       // DragOver event handler.
       if (e.Effects.HasFlag(DragDropEffects.Copy))
       {
           Mouse.SetCursor(Cursors.Cross);
       }
       else if (e.Effects.HasFlag(DragDropEffects.Move))
       {
           Mouse.SetCursor(Cursors.Pen);
       }
       else
       {
           Mouse.SetCursor(Cursors.No);
       }
       e.Handled = true;
   }
   

   This OnGiveFeedback override performs the following tasks:

   • Checks the Effects values that are set in the drop target's DragOver event handler.

   • Sets a custom cursor based on the Effects value. The cursor is intended to give visual feedback to the user about what effect dropping the data will have.

3. Press F5 to build and run the application.

4. Drag one of the Circle controls over the panels, the other Circle, and the TextBox. Notice that the cursors are now the custom cursors that you specified in the OnGiveFeedback override.

   

5. Select the text green from the TextBox.

6. Drag the green text to a Circle control. Notice that the default cursors are shown to indicate the effects of the drag-and-drop operation. The feedback cursor is always set by the drag source.

1. Open Circle.xaml.

2. In the opening UserControl tag, add the AllowDrop property and set it to true.

   XAML

   <UserControl x:Class="DragDropWalkthrough.Circle"
                xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
                xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 
                mc:Ignorable="d" 
                d:DesignHeight="300" d:DesignWidth="300"
                AllowDrop="True">
   

The OnDrop method is called when the AllowDrop property is set to true and data from the drag source is dropped on the Circle user control. In this method, you will process the data that was dropped and apply the data to the Circle.

1. Open Circle.xaml.cs or Circle.xaml.vb.

2. Add the following OnDrop override to provide class handling for the Drop event.

   C#

   VB

   protected override void OnDrop(DragEventArgs e)
   {
       base.OnDrop(e);
   
       // If the DataObject contains string data, extract it.
       if (e.Data.GetDataPresent(DataFormats.StringFormat))
       {
           string dataString = (string)e.Data.GetData(DataFormats.StringFormat);
   
           // If the string can be converted into a Brush, 
           // convert it and apply it to the ellipse.
           BrushConverter converter = new BrushConverter();
           if (converter.IsValid(dataString))
           {
               Brush newFill = (Brush)converter.ConvertFromString(dataString);
               circleUI.Fill = newFill;
   
               // Set Effects to notify the drag source what effect
               // the drag-and-drop operation had.
               // (Copy if CTRL is pressed; otherwise, move.)
               if (e.KeyStates.HasFlag(DragDropKeyStates.ControlKey))
               {
                   e.Effects = DragDropEffects.Copy;
               }
               else
               {
                   e.Effects = DragDropEffects.Move;
               }
           }
       }
       e.Handled = true;
   }
   

   This OnDrop override performs the following tasks:

   • Uses the GetDataPresent method to check if the dragged data contains a string object.

   • Uses the GetData method to extract the string data if it is present.

   • Uses a BrushConverter to try to convert the string to a Brush.

   • If the conversion is successful, applies the brush to the Fill of the Ellipse that provides the UI of the Circle control.

   • Marks the Drop event as handled. You should mark the drop event as handled so that other elements that receive this event know that the Circle user control handled it.

3. Press F5 to build and run the application.

4. Select the text green in the TextBox.

5. Drag the text to a Circle control and drop it. The Circle changes from blue to green.

   

6. Type the text green in the TextBox.

7. Select the text gre in the TextBox.

8. Drag it to a Circle control and drop it. Notice that the cursor changes to indicate that the drop is allowed, but the color of the Circle does not change because gre is not a valid color.

9. Drag from the green Circle control and drop on the blue Circle control. The Circle changes from blue to green. Notice that which cursor is shown depends on whether the TextBox or the Circle is the drag source.

Setting the AllowDrop property to true and processing the dropped data is all that is required to enable an element to be a drop target. However, to provide a better user experience, you should also handle the DragEnter, DragLeave, and DragOver events. In these events, you can perform checks and provide additional feedback to the user before the data is dropped.

When data is dragged over the Circle user control, the control should notify the drag source whether it can process the data that is being dragged. If the control does not know how to process the data, it should refuse the drop. To do this, you will handle the DragOver event and set the Effectsproperty.

1. Open Circle.xaml.cs or Circle.xaml.vb.

2. Add the following OnDragOver override to provide class handling for the DragOver event.

   C#

   VB

   protected override void OnDragOver(DragEventArgs e)
   {
       base.OnDragOver(e);
       e.Effects = DragDropEffects.None;
   
       // If the DataObject contains string data, extract it.
       if (e.Data.GetDataPresent(DataFormats.StringFormat))
       {
           string dataString = (string)e.Data.GetData(DataFormats.StringFormat);
   
           // If the string can be converted into a Brush, allow copying or moving.
           BrushConverter converter = new BrushConverter();
           if (converter.IsValid(dataString))
           {
               // Set Effects to notify the drag source what effect
               // the drag-and-drop operation will have. These values are 
               // used by the drag source's GiveFeedback event handler.
               // (Copy if CTRL is pressed; otherwise, move.)
               if (e.KeyStates.HasFlag(DragDropKeyStates.ControlKey))
               {
                   e.Effects = DragDropEffects.Copy;
               }
               else
               {
                   e.Effects = DragDropEffects.Move;
               }
           }
       }
       e.Handled = true;
   }
   

   This OnDragOver override performs the following tasks:

   • Sets the Effects property to None.

   • Performs the same checks that are performed in the OnDrop method to determine whether the Circle user control can process the dragged data.

   • If the user control can process the data, sets the Effects property to Copy or Move.

3. Press F5 to build and run the application.

4. Select the text gre in the TextBox.

5. Drag the text to a Circle control. Notice that the cursor now changes to indicate that the drop is not allowed because gre is not a valid color.

You can further enhance the user experience by applying a preview of the drop operation. For the Circle user control, you will override the OnDragEnter and OnDragLeave methods. When the data is dragged over the control, the current background Fill is saved in a placeholder variable. The string is then converted to a brush and applied to the Ellipse that provides the Circle's UI. If the data is dragged out of the Circle without being dropped, the original Fill value is re-applied to the Circle.

1. Open Circle.xaml.cs or Circle.xaml.vb.

2. In the Circle class, declare a private Brush variable named _previousFill and initialize it to null.

   C#

   VB

   public partial class Circle : UserControl
   {
       private Brush _previousFill = null;
   

3. Add the following OnDragEnter override to provide class handling for the DragEnter event.

   C#

   VB

   protected override void OnDragEnter(DragEventArgs e)
   {
       base.OnDragEnter(e);
       // Save the current Fill brush so that you can revert back to this value in DragLeave.
       _previousFill = circleUI.Fill;
   
       // If the DataObject contains string data, extract it.
       if (e.Data.GetDataPresent(DataFormats.StringFormat))
       {
           string dataString = (string)e.Data.GetData(DataFormats.StringFormat);
   
           // If the string can be converted into a Brush, convert it.
           BrushConverter converter = new BrushConverter();
           if (converter.IsValid(dataString))
           {
               Brush newFill = (Brush)converter.ConvertFromString(dataString.ToString());
               circleUI.Fill = newFill;
           }
       }
   }
   

   This OnDragEnter override performs the following tasks:

   • Saves the Fill property of the Ellipse in the _previousFill variable.

   • Performs the same checks that are performed in the OnDrop method to determine whether the data can be converted to a Brush.

   • If the data is converted to a valid Brush, applies it to the Fill of the Ellipse.

4. Add the following OnDragLeave override to provide class handling for the DragLeave event.

   C#

   VB

   protected override void OnDragLeave(DragEventArgs e)
   {
       base.OnDragLeave(e);
       // Undo the preview that was applied in OnDragEnter.
       circleUI.Fill = _previousFill;
   }
   

   This OnDragLeave override performs the following tasks:

   • Applies the Brush saved in the _previousFill variable to the Fill of the Ellipse that provides the UI of the Circle user control.

5. Press F5 to build and run the application.

6. Select the text green in the TextBox.

7. Drag the text over a Circle control without dropping it. The Circle changes from blue to green. 

   

8. Drag the text away from the Circle control. The Circle changes from green back to blue.

1. Open MainWindow.xaml.

2. As shown in the following XAML, in each of the StackPanel controls, add handlers for the DragOver and Drop events. Name the DragOverevent handler, panel_DragOver, and name the Drop event handler, panel_Drop.

   XAML

   <StackPanel Grid.Column="0"
               Background="Beige"
               AllowDrop="True"
               DragOver="panel_DragOver"
               Drop="panel_Drop">
       <TextBox Width="Auto" Margin="2"
                Text="green"/>
       <local:Circle Margin="2" />
       <local:Circle Margin="2" />
   </StackPanel>
   <StackPanel Grid.Column="1"
               Background="Bisque"
               AllowDrop="True"
               DragOver="panel_DragOver"
               Drop="panel_Drop">
   </StackPanel>
   

3. Open MainWindows.xaml.cs or MainWindow.xaml.vb.

4. Add the following code for the DragOver event handler.

   C#

   VB

   private void panel_DragOver(object sender, DragEventArgs e)
   {
       if (e.Data.GetDataPresent("Object"))
       {
           // These Effects values are used in the drag source's
           // GiveFeedback event handler to determine which cursor to display.
           if (e.KeyStates == DragDropKeyStates.ControlKey)
           {
               e.Effects = DragDropEffects.Copy;
           }
           else
           {
               e.Effects = DragDropEffects.Move;
           }
       }
   }
   

   This DragOver event handler performs the following tasks:

   • Checks that the dragged data contains the "Object" data that was packaged in the DataObject by the Circle user control and passed in the call to DoDragDrop.

   • If the "Object" data is present, checks whether the CTRL key is pressed.

   • If the CTRL key is pressed, sets the Effects property to Copy. Otherwise, set the Effects property to Move.

5. Add the following code for the Drop event handler.

   C#

   VB

   private void panel_Drop(object sender, DragEventArgs e)
   {
       // If an element in the panel has already handled the drop,
       // the panel should not also handle it.
       if (e.Handled == false)
       {
           Panel _panel = (Panel)sender;
           UIElement _element = (UIElement)e.Data.GetData("Object");
   
           if (_panel != null && _element != null)
           {
               // Get the panel that the element currently belongs to,
               // then remove it from that panel and add it the Children of
               // the panel that its been dropped on.
               Panel _parent = (Panel)VisualTreeHelper.GetParent(_element);
   
               if (_parent != null)
               {
                   if (e.KeyStates == DragDropKeyStates.ControlKey &&
                       e.AllowedEffects.HasFlag(DragDropEffects.Copy))
                   {
                       Circle _circle = new Circle((Circle)_element);
                       _panel.Children.Add(_circle);
                       // set the value to return to the DoDragDrop call
                       e.Effects = DragDropEffects.Copy;
                   }
                   else if (e.AllowedEffects.HasFlag(DragDropEffects.Move))
                   {
                       _parent.Children.Remove(_element);
                       _panel.Children.Add(_element);
                       // set the value to return to the DoDragDrop call
                       e.Effects = DragDropEffects.Move;
                   }
               }
           }
       }
   }
   

   This Drop event handler performs the following tasks:

   • Checks whether the Drop event has already been handled. For instance, if a Circle is dropped on another Circle which handles the Drop event, you do not want the panel that contains the Circle to also handle it.

   • If the Drop event is not handled, checks whether the CTRL key is pressed.

   • If the CTRL key is pressed when the Drop happens, makes a copy of the Circle control and add it to the Children collection of the StackPanel.

   • If the CTRL key is not pressed, moves the Circle from the Children collection of its parent panel to the Children collection of the panel that it was dropped on.

   • Sets the Effects property to notify the DoDragDrop method whether a move or copy operation was performed.

6. Press F5 to build and run the application.

7. Select the text green from the TextBox.

8. Drag the text over a Circle control and drop it.

9. Drag a Circle control from the left panel to the right panel and drop it. The Circle is removed from the Children collection of the left panel and added to the Children collection of the right panel.

10. Drag a Circle control from the panel it is in to the other panel and drop it while pressing the CTRL key. The Circle is copied and the copy is added to the Children collection of the receiving panel.

    

The following example code creates a new data object and uses one of the overloaded constructors (DataObject(Object)) to initialize the data object with a string. In this case, an appropriate data format is determined automatically according to the stored data's type, and auto-converting of the stored data is allowed by default.

The following example code is a condensed version of the code shown above.

The following example code creates a new data object and uses one of the overloaded constructors (DataObject(String, Object)) to initialize the data object with a string and a specified data format. In this case the data format is specified by a string; the DataFormats class provides a set of pre-defined type strings. Auto-converting of the stored data is allowed by default.

The following example code is a condensed version of the code shown above.

The following example code creates a new data object and uses one of the overloaded constructors (DataObject) to initialize the data object with a string and a specified data format. In this case the data format is specified by a Type parameter. Auto-converting of the stored data is allowed by default.

The following example code is a condensed version of the code shown above.

The following example code creates a new data object and uses one of the overloaded constructors (DataObject(String, Object, Boolean)) to initialize the data object with a string and a specified data format. In this case the data format is specified by a string; the DataFormats class provides a set of pre-defined type strings. This particular constructor overload enables the caller to specify whether auto-converting is allowed.

The following example code is a condensed version of the code shown above.

The following example code uses the GetDataPresent(String) overload to query for the presence of a particular data format by descriptor string.

The following example code uses the GetDataPresent(Type) overload to query for the presence of a particular data format by type.

The following example code uses the GetDataPresent(String, Boolean) overload to query for data by descriptor string, and specifying how to treat auto-convertible data formats.

The following example code uses the GetFormats overload to get an array of strings denoting all data formats available in a data object (both native and auto-convertible).

The following example code uses the GetFormats overload to get an array of strings denoting only data formats available in a data object (auto-convertible data formats are filtered).

The following example code uses the GetDataPresent(String) overload to first check if a specified data format is available (natively or by auto-convert); if the specified format is available, the example retrieves the data by using the GetData(String) method.

The following example code uses the GetDataPresent(String, Boolean) overload to first check if a specified data format is available natively (auto-convertible data formats are filtered); if the specified format is available, the example retrieves the data by using the GetData(String) method.

In addition to the input API on the base element classes, the Keyboard class and Mouse classes provide additional API for working with keyboard and mouse input.

Examples of input API on the Keyboard class are the Modifiers property, which returns the ModifierKeys currently pressed, and the IsKeyDown method, which determines whether a specified key is pressed.

The following example uses the GetKeyStates method to determine if a Key is in the down state.

// Uses the Keyboard.GetKeyStates to determine if a key is down.
// A bitwise AND operation is used in the comparison. 
// e is an instance of KeyEventArgs.
if ((Keyboard.GetKeyStates(Key.Return) & KeyStates.Down) > 0)
{
    btnNone.Background = Brushes.Red;
}

Examples of input API on the Mouse class are MiddleButton, which obtains the state of the middle mouse button, and DirectlyOver, which gets the element the mouse pointer is currently over.

The following example determines whether the LeftButton on the mouse is in the Pressed state.

if (Mouse.LeftButton == MouseButtonState.Pressed)
{
    UpdateSampleResults("Left Button Pressed");
}

The Mouse and Keyboard classes are covered in more detail throughout this overview.

WPF has integrated support for the Stylus. The Stylus is a pen input made popular by the Tablet PC. WPF applications can treat the stylus as a mouse by using the mouse API, but WPF also exposes a stylus device abstraction that use a model similar to the keyboard and mouse. All stylus-related APIs contain the word "Stylus".

Because the stylus can act as a mouse, applications that support only mouse input can still obtain some level of stylus support automatically. When the stylus is used in such a manner, the application is given the opportunity to handle the appropriate stylus event and then handles the corresponding mouse event. In addition, higher-level services such as ink input are also available through the stylus device abstraction. For more information about ink as input, see Getting Started with Ink.

The following example listens for a left arrow key press. A StackPanel is created that has a Button. An event handler to listen for the left arrow key press is attached to the Button instance.

The first section of the example creates the StackPanel and the Button and attaches the event handler for the KeyDown.

<StackPanel>
  <Button Background="AliceBlue"
          KeyDown="OnButtonKeyDown"
          Content="Button1"/>
</StackPanel>

// Create the UI elements.
StackPanel keyboardStackPanel = new StackPanel();
Button keyboardButton1 = new Button();

// Set properties on Buttons.
keyboardButton1.Background = Brushes.AliceBlue;
keyboardButton1.Content = "Button 1";

// Attach Buttons to StackPanel.
keyboardStackPanel.Children.Add(keyboardButton1);

// Attach event handler.
keyboardButton1.KeyDown += new KeyEventHandler(OnButtonKeyDown);

The second section is written in code and defines the event handler. When the left arrow key is pressed and the Button has keyboard focus, the handler runs and the Background color of the Button is changed. If the key is pressed, but it is not the left arrow key, the Background color of the Button is changed back to its starting color.

private void OnButtonKeyDown(object sender, KeyEventArgs e)
{
    Button source = e.Source as Button;
    if (source != null)
    {
        if (e.Key == Key.Left)
        {
            source.Background = Brushes.LemonChiffon;
        }
        else
        {
            source.Background = Brushes.AliceBlue;
        }
    }
}

In the following example, the Background color of a Button is changed when the mouse pointer enters the Button. The Background color is restored when the mouse leaves the Button.

The first section of the example creates the StackPanel and the Button control and attaches the event handlers for the MouseEnter and MouseLeave events to the Button.

<StackPanel>
  <Button Background="AliceBlue"
          MouseEnter="OnMouseExampleMouseEnter"
          MouseLeave="OnMosueExampleMouseLeave">Button

  </Button>
</StackPanel>

// Create the UI elements.
StackPanel mouseMoveStackPanel = new StackPanel();
Button mouseMoveButton = new Button();

// Set properties on Button.
mouseMoveButton.Background = Brushes.AliceBlue;
mouseMoveButton.Content = "Button";

// Attach Buttons to StackPanel.
mouseMoveStackPanel.Children.Add(mouseMoveButton);

// Attach event handler.
mouseMoveButton.MouseEnter += new MouseEventHandler(OnMouseExampleMouseEnter);
mouseMoveButton.MouseLeave += new MouseEventHandler(OnMosueExampleMouseLeave);

The second section of the example is written in code and defines the event handlers. When the mouse enters the Button, the Background color of the Button is changed to SlateGray. When the mouse leaves the Button, the Background color of the Button is changed back to AliceBlue.

private void OnMouseExampleMouseEnter(object sender, MouseEventArgs e)
{
    // Cast the source of the event to a Button.
    Button source = e.Source as Button;

    // If source is a Button.
    if (source != null)
    {
        source.Background = Brushes.SlateGray;
    }
}

private void OnMosueExampleMouseLeave(object sender, MouseEventArgs e)
{
    // Cast the source of the event to a Button.
    Button source = e.Source as Button;

    // If source is a Button.
    if (source != null)
    {
        source.Background = Brushes.AliceBlue;
    }
}

You need the following components to develop an application that responds to touch.

• Microsoft Visual Studio 2010.

• Windows 7.

• A device, such as a touchscreen, that supports Windows Touch.

The following terms are used when touch is discussed.

• Touch is a type of user input that is recognized by Windows 7. Usually, touch is initiated by putting fingers on a touch-sensitive screen. Note that devices such as a touchpad that is common on laptop computers do not support touch if the device merely converts the finger's position and movement as mouse input.

• Multitouch is touch that occurs from more than one point simultaneously. Windows 7 and WPF supports multitouch. Whenever touch is discussed in the documentation for WPF, the concepts apply to multitouch.

• A manipulation occurs when touch is interpreted as a physical action that is applied to an object. In WPF, manipulation events interpret input as a translation, expansion, or rotation manipulation.

• A touch device represents a device that produces touch input, such as a single finger on a touchscreen.

The following controls can be scrolled by dragging a finger across the control if it has content that is scrolled out of view.

• ComboBox

• ContextMenu

• DataGrid

• ListBox

• ListView

• MenuItem

• TextBox

• ToolBar

• TreeView

The ScrollViewer defines the ScrollViewer.PanningMode attached property that enables you to specify whether touch panning is enabled horizontally, vertically, both, or neither. The ScrollViewer.PanningDeceleration property specifies how quickly the scrolling slows down when the user lifts the finger from the touchscreen. The ScrollViewer.PanningRatio attached property specifies the ratio of scrolling offset to translate manipulation offset.

The base classes, UIElement, UIElement3D, and ContentElement, define events that you can subscribe to so your application will respond to touch. Touch events are useful when your application interprets touch as something other than manipulating an object. For example, an application that enables a user to draw with one or more fingers would subscribe to touch events.

All three classes define the following events, which behave similarly, regardless of the defining class.

• TouchDown

• TouchMove

• TouchUp

• TouchEnter

• TouchLeave

• PreviewTouchDown

• PreviewTouchMove

• PreviewTouchUp

• GotTouchCapture

• LostTouchCapture

Like keyboard and mouse events, the touch events are routed events. The events that begin with Preview are tunneling events and the events that begin with Touch are bubbling events. For more information about routed events, see Routed Events Overview. When you handle these events, you can get the position of the input, relative to any element, by calling the GetTouchPoint or GetIntermediateTouchPoints method.

To understand the interaction among the touch events, consider the scenario where a user puts one finger on an element, moves the finger in the element, and then lifts the finger from the element. The following illustration shows the execution of the bubbling events (the tunneling events are omitted for simplicity).

Touch events

The following list describes the sequence of the events in the preceding illustration.

1. The TouchEnter event occurs one time when the user puts a finger on the element.

2. The TouchDown event occurs one time.

3. The TouchMove event occurs multiple times as the user moves the finger within the element.

4. The TouchUp event occurs one time when the user lifts the finger from the element.

5. The TouchLeave event occurs one time.

When more than two fingers are used, the events occur for each finger.

For cases where an application enables a user to manipulate an object, the UIElement class defines manipulation events. Unlike the touch events that simply report the position of touch, the manipulation events report how the input can be interpreted. There are three types of manipulations, translation, expansion, and rotation. The following list describes how to invoke the three types of manipulations.

• Put a finger on an object and move the finger across the touchscreen to invoke a translation manipulation. This usually moves the object.

• Put two fingers on an object and move the fingers closer together or farther apart from one another to invoke an expansion manipulation. This usually resizes the object.

• Put two fingers on an object and rotate the fingers around each other to invoke a rotation manipulation. This usually rotates the object.

More than one type of manipulation can occur simultaneously.

When you cause objects to respond to manipulations, you can have the object appear to have inertia. This can make your objects simulate the physical world. For example, when you push a book across a table, if you push hard enough the book will continue to move after you release it. WPF enables you to simulate this behavior by raising manipulation events after the user's fingers releases the object.

For information about how to create an application that enables the user to move, resize, and rotate an object, see Walkthrough: Creating Your First Touch Application.

The UIElement defines the following manipulation events.

• ManipulationStarting

• ManipulationStarted

• ManipulationDelta

• ManipulationInertiaStarting

• ManipulationCompleted

• ManipulationBoundaryFeedback

By default, a UIElement does not receive these manipulation events. To receive manipulation events on a UIElement, set UIElement.IsManipulationEnabled to true.

A UIElement can always receive touch events. When the IsManipulationEnabled property is set to true, a UIElement can receive both touch and manipulation events. If the TouchDown event is not handled (that is, the Handled property is false), the manipulation logic captures the touch to the element and generates the manipulation events. If the Handled property is set to true in the TouchDown event, the manipulation logic does not generate manipulation events. The following illustration shows the relationship between touch events and manipulation events.

Touch and manipulation events

The following list describes the relationship between the touch and manipulation events that is shown in the preceding illustration.

• When the first touch device generates a TouchDown event on a UIElement, the manipulation logic calls the CaptureTouch method, which generates the GotTouchCapture event.

• When the GotTouchCapture occurs, the manipulation logic calls the Manipulation.AddManipulator method, which generates the ManipulationStarting event.

• When the TouchMove events occur, the manipulation logic generates the ManipulationDelta events that occur before the ManipulationInertiaStarting event.

• When the last touch device on the element raises the TouchUp event, the manipulation logic generates the ManipulationInertiaStartingevent.

Keyboard focus refers to the element that is receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In WPF, the element that has keyboard focus will have IsKeyboardFocused set to true. The static Keyboard method FocusedElement returns the element that currently has keyboard focus.

Keyboard focus can be obtained by tabbing to an element or by clicking the mouse on certain elements, such as a TextBox. Keyboard focus can also be obtained programmatically by using the Focus method on the Keyboard class. Focus attempts to give the specified element keyboard focus. The element returned by Focus is the element that currently has keyboard focus.

In order for an element to obtain keyboard focus the Focusable property and the IsVisible properties must be set to true. Some classes, such as Panel, have Focusable set to false by default; therefore, you may have to set this property to true if you want that element to be able to obtain focus.

The following example uses Focus to set keyboard focus on a Button. The recommended place to set initial focus in an application is in the Loadedevent handler.

private void OnLoaded(object sender, RoutedEventArgs e)
{
    // Sets keyboard focus on the first Button in the sample.
    Keyboard.Focus(firstButton);
}

For more information about keyboard focus, see Focus Overview.

Logical focus refers to the FocusManager.FocusedElement in a focus scope. There can be multiple elements that have logical focus in an application, but there may only be one element that has logical focus in a particular focus scope.

A focus scope is a container element that keeps track of the FocusedElement within its scope. When focus leaves a focus scope, the focused element will lose keyboard focus but will retain logical focus. When focus returns to the focus scope, the focused element will obtain keyboard focus. This allows for keyboard focus to be changed between multiple focus scopes but insures that the focused element within the focus scope remains the focused element when focus returns.

An element can be turned into a focus scope in Extensible Application Markup Language (XAML) by setting the FocusManager attached property IsFocusScope to true, or in code by setting the attached property by using the SetIsFocusScope method.

The following example makes a StackPanel into a focus scope by setting the IsFocusScope attached property.

<StackPanel Name="focusScope1" 
            FocusManager.IsFocusScope="True"
            Height="200" Width="200">
  <Button Name="button1" Height="50" Width="50"/>
  <Button Name="button2" Height="50" Width="50"/>
</StackPanel>

StackPanel focuseScope2 = new StackPanel();
FocusManager.SetIsFocusScope(focuseScope2, true);

Classes in WPF which are focus scopes by default are Window, Menu, ToolBar, and ContextMenu.

An element that has keyboard focus will also have logical focus for the focus scope it belongs to; therefore, setting focus on an element with the Focus method on the Keyboard class or the base element classes will attempt to give the element keyboard focus and logical focus.

To determine the focused element in a focus scope, use GetFocusedElement. To change the focused element for a focus scope, use SetFocusedElement.

For more information about logical focus, see Focus Overview.

Commands in WPF are created by implementing the ICommand interface. ICommand exposes two methods, Execute, and CanExecute, and an event, CanExecuteChanged. Execute performs the actions that are associated with the command. CanExecute determines whether the command can execute on the current command target. 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 ICommand is the RoutedCommand class and is the focus of this overview.

The main sources of input in WPF are the mouse, the keyboard, ink, and routed commands. The more device-oriented inputs use a RoutedEvent to notify objects in an application page that an input event has occurred. A RoutedCommand is no different. The Execute and CanExecute methods of a 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 CommandBinding. The 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.

The Execute method on a RoutedCommand raises the PreviewExecuted and the Executed events on the command target. The CanExecute method on a RoutedCommand raises the CanExecute and PreviewCanExecute events on the command target. These events tunnel and bubble through the element tree until they encounter an object which has a CommandBinding for that particular command.

WPF supplies a set of common routed commands spread across several classes: MediaCommands, ApplicationCommands, NavigationCommands, ComponentCommands, and EditingCommands. These classes consist only of the 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 command source is the object which invokes the command. Examples of command sources are MenuItem, Button, and KeyGesture.

Command sources in WPF generally implement the ICommandSource interface.

ICommandSource exposes three properties: Command, CommandTarget, and CommandParameter:

• Command is the command to execute when the command source is invoked.

• CommandTarget is the object on which to execute the command. It is worth noting that in WPF the CommandTarget property on ICommandSource is only applicable when the ICommand is a RoutedCommand. If the CommandTarget is set on an ICommandSource and the corresponding command is not a RoutedCommand, the command target is ignored. If the CommandTarget is not set, the element with keyboard focus will be the command target.

• CommandParameter is a user-defined data type used to pass information to the handlers implementing the command.

The WPF classes that implement ICommandSource are ButtonBase, MenuItem, Hyperlink, and InputBinding. ButtonBase, MenuItem, and Hyperlinkinvoke a command when they are clicked, and an InputBinding invokes a command when the InputGesture associated with it is performed.

The following example shows how to use a MenuItem in a ContextMenu as a command source for the Properties command.

<StackPanel>
  <StackPanel.ContextMenu>
    <ContextMenu>
      <MenuItem Command="ApplicationCommands.Properties" />
    </ContextMenu>
  </StackPanel.ContextMenu>
</StackPanel>

StackPanel cmdSourcePanel = new StackPanel();
ContextMenu cmdSourceContextMenu = new ContextMenu();
MenuItem cmdSourceMenuItem = new MenuItem();

// Add ContextMenu to the StackPanel.
cmdSourcePanel.ContextMenu = cmdSourceContextMenu;
cmdSourcePanel.ContextMenu.Items.Add(cmdSourceMenuItem);

// Associate Command with MenuItem.
cmdSourceMenuItem.Command = ApplicationCommands.Properties;

Typically, a command source will listen to the 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 RoutedCommand by using the CanExecute method. The command source can then disable itself if the command cannot execute. An example of this is a MenuItemgraying itself out when a command cannot execute.

An InputGesture can be used as a command source. Two types of input gestures in WPF are the KeyGesture and MouseGesture. You can think of a KeyGesture as a keyboard shortcut, such as CTRL+C. A KeyGesture is comprised of a Key and a set of ModifierKeys. A MouseGesture is comprised of a MouseAction and an optional set of ModifierKeys.

In order for an 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 InputBinding.

The following example shows how to create a KeyBinding between a KeyGesture and a RoutedCommand.

<Window.InputBindings>
  <KeyBinding Key="B"
              Modifiers="Control" 
              Command="ApplicationCommands.Open" />
</Window.InputBindings>

KeyGesture OpenKeyGesture = new KeyGesture(
    Key.B,
    ModifierKeys.Control);

KeyBinding OpenCmdKeybinding = new KeyBinding(
    ApplicationCommands.Open,
    OpenKeyGesture);

this.InputBindings.Add(OpenCmdKeybinding);

Another way to associate an InputGesture to a RoutedCommand is to add the InputGesture to the InputGestureCollection on the RoutedCommand.

The following example shows how to add a KeyGesture to the InputGestureCollection of a RoutedCommand.

KeyGesture OpenCmdKeyGesture = new KeyGesture(
    Key.B,
    ModifierKeys.Control);

ApplicationCommands.Open.InputGestures.Add(OpenCmdKeyGesture);

A CommandBinding associates a command with the event handlers that implement the command.

The CommandBinding class contains a Command property, and PreviewExecuted, Executed, PreviewCanExecute, and CanExecute events.

Command is the command that the CommandBinding is being associated with. The event handlers which are attached to the PreviewExecuted and Executed events implement the command logic. The event handlers attached to the PreviewCanExecute and CanExecute events determine if the command can execute on the current command target.

The following example shows how to create a CommandBinding on the root Window of an application. The CommandBinding associates the Opencommand with Executed and CanExecute handlers.

<Window.CommandBindings>
  <CommandBinding Command="ApplicationCommands.Open"
                  Executed="OpenCmdExecuted"
                  CanExecute="OpenCmdCanExecute"/>
</Window.CommandBindings>

// Creating CommandBinding and attaching an Executed and CanExecute handler
CommandBinding OpenCmdBinding = new CommandBinding(
    ApplicationCommands.Open,
    OpenCmdExecuted,
    OpenCmdCanExecute);

this.CommandBindings.Add(OpenCmdBinding);

Next, the ExecutedRoutedEventHandler and a CanExecuteRoutedEventHandler are created. The ExecutedRoutedEventHandler opens a MessageBoxthat displays a string saying the command has been executed. The CanExecuteRoutedEventHandler sets the CanExecute property to true.

void OpenCmdExecuted(object target, ExecutedRoutedEventArgs e)
{
    String command, targetobj;
    command = ((RoutedCommand)e.Command).Name;
    targetobj = ((FrameworkElement)target).Name;
    MessageBox.Show("The " + command +  " command has been invoked on target object " + targetobj);
}

void OpenCmdCanExecute(object sender, CanExecuteRoutedEventArgs e)
{
    e.CanExecute = true;
}

A CommandBinding is attached to a specific object, such as the root Window of the application or a control. The object that the CommandBindingis attached to defines the scope of the binding. For example, a CommandBinding attached to an ancestor of the command target can be reached by the Executed event, but a CommandBinding attached to a descendant of the command target cannot be reached. This is a direct consequence of the way a RoutedEvent tunnels and bubbles from the object that raises the event.

In some situations the CommandBinding is attached to the command target itself, such as with the TextBox class and the Cut, Copy, and Pastecommands. Quite often though, it is more convenient to attach the CommandBinding to an ancestor of the command target, such as the main Window or the Application object, especially if the same CommandBinding can be used for multiple command targets. These are design decisions you will want to consider when you are creating your commanding infrastructure.

The command target is the element on which the command is executed. With regards to a RoutedCommand, the command target is the element at which routing of the Executed and CanExecute starts. As noted previously, in WPF the CommandTarget property on ICommandSource is only applicable when the ICommand is a RoutedCommand. If the CommandTarget is set on an ICommandSource and the corresponding command is not a 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 MenuItem invokes the Paste command in an application that has a TextBox control and a PasswordBox control, the target can be either the TextBox or PasswordBox depending on which control has keyboard focus.

The following example shows how to explicitly set the command target in markup and in code behind.

<StackPanel>
  <Menu>
    <MenuItem Command="ApplicationCommands.Paste"
              CommandTarget="{Binding ElementName=mainTextBox}" />
  </Menu>
  <TextBox Name="mainTextBox"/>
</StackPanel>

// Creating the UI objects
StackPanel mainStackPanel = new StackPanel();
TextBox pasteTextBox = new TextBox();
Menu stackPanelMenu = new Menu();
MenuItem pasteMenuItem = new MenuItem();

// Adding objects to the panel and the menu
stackPanelMenu.Items.Add(pasteMenuItem);
mainStackPanel.Children.Add(stackPanelMenu);
mainStackPanel.Children.Add(pasteTextBox);

// Setting the command to the Paste command
pasteMenuItem.Command = ApplicationCommands.Paste;

// Setting the command target to the TextBox
pasteMenuItem.CommandTarget = pasteTextBox;

The CommandManager serves a number of command related functions. It provides a set of static methods for adding and removing PreviewExecuted, Executed, PreviewCanExecute, and CanExecute event handlers to and from a specific element. It provides a means to register CommandBinding and InputBinding objects onto a specific class. The CommandManager also provides a means, through the RequerySuggestedevent, to notify a command when it should raise the CanExecuteChanged event.

The InvalidateRequerySuggested method forces the CommandManager to raise the RequerySuggested event. This is useful for conditions that should disable/enable a command but are not conditions that the CommandManager is aware of.

If you are specifically interested in keyboard focus, the IsKeyboardFocused dependency property can be used for a property Trigger. A property trigger in either a style or template is a more appropriate technique for defining a keyboard focus behavior that is very specifically for a single control, and which might not visually match the keyboard focus behavior for other controls.

Another similar dependency property is IsKeyboardFocusWithin, which might be appropriate to use if you want to visually call out that keyboard focus is somewhere within compositing or within the functional area of the control. For example, you might place an IsKeyboardFocusWithintrigger such that a panel that groups several controls appears differently, even though keyboard focus might more precisely be on an individual element within that panel.

You can also use the events GotKeyboardFocus and LostKeyboardFocus (as well as their Preview equivalents). You can use these events as the basis for an EventSetter, or you can write handlers for the events in code-behind.