There are some situations in which you might not want events to bubble up. For example, you may wish to convert the event into something else—the Button element effectively converts a MouseDown event followed by a MouseUp event into a single Click event. It suppresses the more primitive mouse button events so that only the Click event bubbles up out of the control. (This is why the event bubbling stopped at the button in the previous example.)

Any handler can prevent further processing of a routed event by setting the Handled property of the RoutedEventArgs, as shown in Example 4-3.

void ButtonDownCanvas(object sender, RoutedEventArgs e) {
    Debug.WriteLine("ButtonDownCanvas");
    e.Handled = true;
}

If you set the Handled flag in a Preview handler, not only will the tunneling of the Preview event stop, but also the corresponding bubbling event that would normally follow will not be raised at all. This provides a way of stopping the normal handling of an event.

Although it is convenient to be able to handle events from a group of elements in a single place, your handler might need to know which element caused the event to be raised. You might think that this is the purpose of the sender parameter of your handler. In fact, the sender always refers to the object to which you attached the event handler. In the case of bubbled and tunneled events, this often isn’t the element that caused the event to be raised. In Example 4-1, the MouseDownGrid handler’s sender will always be the Grid itself, regardless of which element in the grid was clicked.

Fortunately, it’s easy to find out which element was the underlying cause of the event. The handler has a RoutedEventArgs parameter, which offers a Source property for this purpose. This is particularly useful if you need to handle events from several different sources in the same way. For example, suppose you create a window that contains a number of graphical elements, and you’d like each to change shape when clicked. Instead of attaching a MouseDown event handler to each individual shape, you could attach a single handler to the window. All the events would bubble up from any shape to this single handler, and you could use the Source property to work out which shape you need to change. (Shapes are discussed in Example 13-5. Example 4-5 uses exactly this trick.)

Normal .NET events (or, as they are often called, CLR events) offer one advantage over routed events: many .NET languages have built-in support for handling CLR events. Because of this, WPF provides wrappers for routed events, making them look just like normal CLR events.^[20] This provides the best of both worlds: you can use your favorite language’s event handling syntax while taking advantage of the extra functionality offered by routed events.

Example 4-1 and Example 4-2 arranged for the event handlers to be connected by using attributes in the markup. But we could have used the normal C# event handling syntax to attach handlers in the constructor instead. For example, you could remove the MouseDown and PreviewMouseDown attributes from the Ellipse in Example 4-1, and then modify the constructor from Example 4-2, as shown here in Example 4-4.

...
public Window1(  ) {
    InitializeComponent(  );

    myEllipse.MouseDown += MouseDownEllipse;
    myEllipse.PreviewMouseDown += PreviewMouseDownEllipse;
}
...

When you use these CLR event wrappers, WPF uses the routed event system on your behalf. The code in Example 4-5 is equivalent to that in Example 4-4.

...
public Window1(  ) {
    InitializeComponent(  );

    myEllipse.AddHandler(Ellipse.MouseDownEvent,
        new MouseButtonEventHandler(MouseDownEllipse));
    myEllipse.AddHandler(Ellipse.PreviewMouseDownEvent,
        new MouseButtonEventHandler(PreviewMouseDownEllipse));
}
...

Example 4-5 is more verbose and offers no benefit—we show it here only so that you can see what’s going on under the covers. The style shown in Example 4-4 is preferred.

The code behind is usually the best place to attach event handlers. If your user interface has unusual and creative visuals, there’s a good chance that the XAML file will effectively be owned by a graphic designer. A designer shouldn’t have to know what events a developer needs to handle, or what the handler functions are called. Ideally, the designer will give elements names in the XAML and the developer will attach handlers in the code behind.

It is possible to define an attached event. This is the routed-event equivalent of an attached property: an event defined by a different class than the one from which the event will be raised. This keeps the input system open to extension. If a new kind of input device is invented, it could define new events as attached events, enabling them to be raised from any UI element.

In fact, the WPF input system already works this way. The mouse, stylus, and keyboard events examined in this chapter are just wrappers for underlying attached events defined by the Mouse, Keyboard, and Stylus classes in the System.Windows.Input namespace. This means we could change the Grid element in Example 4-1 to use the attached events defined by the Mouse class, as shown in Example 4-6.

<Grid Mouse.PreviewMouseDown ="PreviewMouseDownGrid"
         Mouse.MouseDown ="MouseDownGrid">

This would have no effect on the behavior, because the names Example 4-1 used for these events are aliases for the attached events used in this example.

Handling attached events from code looks a little different. Normal CLR events don’t support this notion of attached events, so we can’t use the ordinary C# event syntax like we did in Example 4-4. Instead, we have to call the AddHandler method, passing in the RoutedEvent object representing the attached event (see Example 4-7).

myEllipse.AddHandler(Mouse.PreviewMouseDownEvent,
    new MouseButtonEventHandler(PreviewMouseDownEllipse));
myEllipse.AddHandler(Mouse.MouseDownEvent,
    new MouseButtonEventHandler(MouseDownEllipse));

Alternatively, we can use the helper functions provided by the Mouse class. Example 4-8 uses this to perform exactly the same job as the preceding two examples.

Mouse.AddPreviewMouseDownHandler(myEllipse, PreviewMouseDownEllipse);
Mouse.AddMouseDownHandler(myEllipse, MouseDownEllipse);

Example 4-8 is more compact than Example 4-7 because we were able to omit the explicit construction of the delegate, relying instead on C# delegate type inference. Example 4-7 cannot do this because AddHandler can attach a handler for any kind of event, so in its function signature the second parameter is of the base Delegate type. By convention, classes that define attached events usually provide corresponding helper methods like these to let you use this slightly neater style of code.

WPF always takes the shapes of your elements into account when handling mouse input. Many graphical systems just use the rectangular bounding box of elements to perform hit testing (i.e., testing to see which element the mouse input “hit”). WPF does not employ this shortcut, no matter what shapes your elements may be. For example, if you create a donut-shaped control and click on the hole in the middle, the click will be delivered to whatever was visible behind your control through the hole.

Occasionally it is useful to subvert the standard hit testing behavior. You might wish to create a donut-shaped control with a visible hole, but which doesn’t let clicks pass through it. Alternatively, you might want to create an element that is visible to the user, but transparent to the mouse. WPF lets you do both of these things.

To achieve the first trick—transparent to the eye but opaque to the mouse—you can paint an object with a transparent brush. For example, an Ellipse with its Fill set to Transparent will be invisible to the eye, but not to the mouse. Alternatively, you can use a nontransparent brush, but make the whole element transparent by setting its Opacity property to 0. If a donut-shaped control paints such an ellipse over the hole, this enables it to receive any clicks on the hole. As far as the mouse is concerned, an element is a valid mouse target as long as it is painted with some kind of brush. The mouse doesn’t even look at the level of transparency on the brush, so it treats a completely transparent brush in exactly the same way as a completely opaque brush.

WPF supports the second trick—creating a visible object that is transparent to the mouse—with the IsHitTestVisible property, which can be applied to any element. Setting this to false ensures that the element will not receive mouse input; instead, input will be delivered to whatever is under the element. For example, suppose you had written code to make some sort of graphical embellishment follow the mouse around, such as a semi-transparent ellipse to act as a halo for the pointer. Setting IsHitTestVisible to false would ensure that this visual effect had no impact on the interactive behavior.

As well as defining events, the Mouse class defines some static properties and methods that you can use to discover information about the mouse or modify its state.

The GetPosition method lets you discover the position of the mouse. As Example 4-9 shows, you must pass in a user interface element. It will return the mouse position relative to the specified element, taking into account any transformations that may be in effect.

Point positionRelativeToEllipse = Mouse.GetPosition(myEllipse);

The Capture method allows an element to capture the mouse. Mouse capture means that all mouse input events are sent to the capturing element, even if the mouse is currently outside of that element.^[21] Example 4-10 captures the mouse to an ellipse when a mouse button is pressed, enabling it to track the movement of the mouse even if it moves outside of the ellipse. In fact, it will continue to receive MouseMove events even if the mouse moves outside of the window. This is useful for drag operations, as the user will expect an item being dragged to follow the mouse for as long as the mouse button is pressed. The capture is released by passing null to the Capture method.

public Window1(  ) {
    InitializeComponent(  );

    myEllipse.MouseDown += myEllipse_MouseDown;
    myEllipse.MouseMove += myEllipse_MouseMove;
    myEllipse.MouseUp += myEllipse_MouseUp;
}

void myEllipse_MouseDown(object sender, MouseButtonEventArgs e) {
    Mouse.Capture(myEllipse);
}

void myEllipse_MouseUp(object sender, MouseButtonEventArgs e) {
    Mouse.Capture(null);
}

void myEllipse_MouseMove(object sender, MouseEventArgs e) {
    Debug.WriteLine(Mouse.GetPosition(myEllipse));
}

The Mouse class provides a Captured property that returns the element that has currently captured the mouse; it returns null if the mouse is not captured. You can also discover which element in your application, if any, the mouse is currently over, by using the static Mouse.DirectlyOver property.

Mouse provides five properties that reflect the current button state. Each returns a MouseButtonState enumeration value, which can be either Pressed or Released. Three of these properties—LeftButton, MiddleButton, and RightButton—are self-explanatory. The other two—XButton1 and XButton2—are perhaps less obvious. These are for the extra buttons provided on some mice, typically found on the side. The locations of these so-called extended buttons are not wholly consistent—one of the authors’ mice has these two buttons on the lefthand side, and another has one on each side. This explains the somewhat abstract property names.

Mouse also provides an OverrideCursor property that lets you set a mouse cursor to be shown throughout your whole application, as shown in Example 4-11. This overrides any element-specific mouse cursor settings. You could use this to temporarily show an hourglass cursor when performing some slow work.

private void StartSlowWork(  ) {
    Mouse.OverrideCursor = Cursors.AppStarting;
    ...
}

private void SlowWorkCompleted(  ) {
    Mouse.OverrideCursor = null;
}

The Keyboard class provides a static property called Modifiers. You can read this at any time to find out which modifier keys, such as the Alt, Shift, and Ctrl keys, are pressed. Example 4-12 shows how you might use this in code that needs to decide whether to copy or move an item according to whether the Ctrl key is pressed.

if (Keyboard.Modifiers & ModifierKeys.Control) != 0) {
    isCopy = true;
}

Keyboard also provides the IsKeyDown and IsKeyUp methods, which let you query the state of any individual key, as shown in Example 4-13.

bool homeKeyPressed = Keyboard.IsKeyDown(Key.Home);

You can also discover which element has the keyboard focus, using the static FocusedElement property, or set the focus into a particular element by calling the Focus method.

A command object identifies a particular command. It does not know how to handle a command—as we’ve seen, that’s the job of a command binding. Command objects are typically made available through static properties, such as ApplicationCommands.Properties.

There are several places from which you can get hold of a command object. Some controls define commands. For example, the ScrollBar control defines one for each of its actions, and makes these available in static fields, such as LineUpCommand and PageDownCommand. However, most commands are not unique to a particular control. Some correspond to application-level actions such as “new file” or “open.” Others represent actions that could be implemented by several different controls. For example, TextBox and RichTextBox can both handle clipboard operations.

WPF provides a set of classes that define standard commands. These classes are shown in Table 4-4. This means you don’t need to create your own command objects to represent the most common operations. Moreover, built-in controls understand many of these commands.

Although the standard commands cover a lot of the common features found in many applications, applications usually have functionality of their own not addressed by the standard commands. You can use the command system for application-specific actions by defining custom commands.

...
using System.Windows.Input;

namespace MyNamespace {

    public class MyAppCommands {
    public static RoutedUICommand AddToBasketCommand;

    static MyAppCommands(  ) {

        InputGestureCollection addToBasketInputs =
               new InputGestureCollection(  );
        addToBasketInputs.Add(new KeyGesture(
            Key.B, ModifierKeys.Control|ModifierKeys.Shift));
        AddToBasketCommand = new RoutedUICommand(
            "Add to Basket", "AddToBasket",
            typeof(MyAppCommands), addToBasketInputs);
        }
    }
}

<Button Command="Copy">Copy</Button>

[[xmlNamespacePrefix:]ClassName.]EventName

<Window xmlns:m="clr-namespace:MyNamespace;assembly=MyLib" ...>
    ...
    <Button Command="m:MyAppCommands.AddToBasketCommand">Add to Basket</Button>
    ...

An input binding associates a particular form of input gesture, such as a keyboard shortcut, with a command. Two input gesture types are currently supported: a MouseGesture is a particular mouse input such as a Shift-left-click, or a right-double-click; a KeyGesture, as used in Example 4-16, is a particular keyboard shortcut. Many of the built-in commands are associated with standard gestures. For example, ApplicationCommands.Copy is associated with the standard keyboard shortcut for copying (Ctrl-C in most locales).

Although a command can be associated with a set of gestures when it is created, as Example 4-17 showed, you may wish to assign additional shortcuts for the command in the context of a particular window or element. To allow this, user interface elements have an InputBindings property. This collection contains InputBinding objects that associate input gestures with commands. These augment the default gestures associated with the command. Example 4-16 illustrated this technique—it bound the Alt-Enter shortcut to the built-in Properties command.

The command source is the object that was used to invoke the command. It might be a user interface element, such as a button, hyperlink, or menu item. But it can also be an input gesture. Command sources all implement the ICommandSource interface, as shown in Example 4-20.

public interface ICommandSource {
    ICommand Command { get; }
    object CommandParameter { get; }
    IInputElement CommandTarget { get; }
}

If you set the Command property to a command object, the source will invoke this command when clicked, or in the case of an input gesture, when the user performs the relevant gesture.

The CommandParameter property allows us to pass information to a command when it is invoked. For example, we could tell our hypothetical AddToBasket command what we would like to add to the basket, as shown in Example 4-21.

<MenuItem Command="m:MyAppCommands.AddToBasketCommand"
             CommandParameter="productId4823"
             Header="Add to basket" />

The command handler can retrieve the parameter from the Parameter property of the ExecutedRoutedEventArgs, as Example 4-22 shows. (This example is a command handler for our hypothetical AddToBasketCommand. The handler would be attached with a command binding as was shown in Example 4-16.)

void AddToBasketHandler(object sender, ExecutedRoutedEventArgs e) {
    string productId = (string) e.Parameter;
    ...
}

Command parameters are slightly less useful if you plan to associate commands with keyboard shortcuts. Input bindings are command sources, so they also offer a CommandParameter property, but Example 4-23 shows the problem with this.

public Window1(  ) {
    InitializeComponent(  );

    KeyBinding kb = new KeyBinding(MyAppCommands.AddToBasketCommand, Key.B,
                            ModifierKeys.Shift|ModifierKeys.Control);
    kb.CommandParameter = "productId4299";
    this.InputBindings.Add(kb);
}

This adds an input binding, associating the Ctrl-Shift-B shortcut with our AddToBasketCommand. The CommandParameter property of the binding will be passed to the command handler just as it is when the input source is a button or menu item. But of course, it will pass the same parameter every time, which limits the utility—you might just as well hardcode the value into the command handler. So in practice, you would normally use command parameters only for commands without a keyboard shortcut.

If you were building a real application with shopping-basket functionality, it would probably make more sense to use data binding rather than command parameters. If you arrange for the control that invokes the command to have its data context set to the data you require, the command handler can retrieve the DataContext of the command target, as Example 4-24 shows.

void AddToBasketHandler(object sender, ExecutedRoutedEventArgs e) {
    FrameworkElement source = (FrameworkElement) e.Source;
    ProductInfo product = (ProductInfo) source.DataContext;
    ...
}

This technique has the benefit of working even when a keyboard shortcut is used. Chapter 6 explains data contexts.

The ICommandSource interface also offers a CommandTarget property. Although the interface defines this as a read-only property, all of the classes that implement this interface in WPF add a setter, enabling you to set the target explicitly. If you don’t set this, the command target will typically be the element with the input focus (although, as we’ll see later, there are some subtle exceptions). CommandTarget lets you ensure that a particular command source directs the command to a specific target, regardless of where the input focus may be. As an example of where you might use this, consider an application that uses a RichTextBox as part of a data template (introduced in Chapter 1)—you might use this to allow the user to add annotations to data items in a list. If you provided a set of buttons right next to the RichTextBox to invoke commands such as ToggleBold or ToggleItalic, you would want these to be applicable only to the RichTextBox they are next to. It would be confusing to the user if she clicked on one of these while the focus happened to be elsewhere in her application. By specifying a command target, you ensure that the command only ever goes where it is meant to go.

For a command to be of any use, something must respond when it is invoked. Some controls automatically handle certain commands—the TextBox and RichTextBox handle the copy and paste commands for us, for example. But what if we want to provide our own logic to handle a particular command?

Command handling is slightly more involved than simply attaching a CLR event handler to a UI element. The classes in Table 4-4 define 144 commands, so if FrameworkElement defined CLR events for each distinct command, that would require 288 events once you include previews. Besides being unwieldy, this wouldn’t even be a complete solution—many applications define their own custom commands as well as using standard ones.

The obvious alternative would be for the command object itself to raise events. However, each command is a singleton—there is only one ApplicationCommands.Copy object, for example. If you were able to add a handler to a command object directly, that handler would run anytime the command was invoked anywhere in your application. What if you want to handle the command only if it is executed in a particular window or within a particular element?

The CommandBinding class solves these problems. A CommandBinding object associates a specific command object with a handler function in the scope of a particular user interface element. This CommandBinding class offers PreviewExecuted and Executed events, which are raised as the command tunnels and bubbles through the UI.

Command bindings are held in the CommandBindings collection property defined by UIElement. Example 4-25 shows how to handle the ApplicationCommands.New command in the code behind for a window.

public partial class Window1 : Window {
    public Window1(  ) {
        InitializeComponent(  );

        CommandBinding cmdBindingNew = new CommandBinding(ApplicationCommands.New);
        cmdBindingNew.Executed += NewCommandHandler;
        CommandBindings.Add(cmdBindingNew);
    }

    void NewCommandHandler(object sender, ExecutedRoutedEventArgs e) {
        if (unsavedChanges) {
            MessageBoxResult result = MessageBox.Show(this,
                "Save changes to existing document?", "New",
                MessageBoxButton.YesNoCancel);

            if (result == MessageBoxResult.Cancel) {
                return;
            }
            if (result == MessageBoxResult.Yes) {
                SaveChanges(  );
            }
        }

        // Reset text box contents
        inputBox.Clear(  );
    }
    ...
}

public Window1(  ) {
    InitializeComponent(  );

    CommandBinding redoCommandBinding =
        new CommandBinding(ApplicationCommands.Redo);
    redoCommandBinding.CanExecute += RedoCommandCanExecute;
    CommandBindings.Add(redoCommandBinding);
}

void RedoCommandCanExecute(object sender, CanExecuteRoutedEventArgs e) {
    e.CanExecute = myCustomUndoManager.CanRedo;
}

Command routing

All of the built-in command objects use a class called RoutedUICommand, and you will normally use this if you define application-specific commands.^[22] RoutedUICommand provides the mechanism for finding the right command binding when the command is invoked. This often needs to be determined by context. Consider Example 4-27.

Example 4-27. Multiple command targets

<Grid>
  <Grid.RowDefinitions>
    <RowDefinition Height="Auto" />
    <RowDefinition />
    <RowDefinition />
  </Grid.RowDefinitions>

  <Menu Grid.Row="0">
    <MenuItem Header="_Edit">
      <MenuItem Header="Cu_t"   Command="ApplicationCommands.Cut" />
      <MenuItem Header="_Copy"  Command="ApplicationCommands.Copy" />
      <MenuItem Header="_Paste" Command="ApplicationCommands.Paste" />
    </MenuItem>
  </Menu>

  <TextBox Grid.Row="1" AcceptsReturn="True" />
  <ListBox Grid.Row="2">
    <TextBlock Text="One" />
    <TextBlock Text="Two" />
  </ListBox>
</Grid>

If the focus is in the text box when the Copy command is invoked, the text box handles the command itself as you would expect, copying the currently selected text to the clipboard. But not all controls have an obvious default Copy behavior. If the command were invoked while the focus was in the listbox, you would need to supply application-specific code in order for the command to do anything. RoutedUICommand supports this by providing a mechanism for identifying the command’s target and locating the correct handler.

The target of the RoutedUICommand is determined by the way in which the command was invoked. Typically, the target will be whichever element currently has the focus, unless the command source’s CommandTarget has been set. Figure 4-4 shows the controls and menu from Example 4-27. As you can see from the selection highlight, the TextBox at the top had the focus when the menu was opened, so you would expect it to be the target of the commands. This is indeed what happens, but it’s not quite as straightforward as you might expect.

Figure 4-4. Command targets and focus

RoutedUICommand tries to locate a handler using a tunneling and bubbling system similar to the one used by the event system. However, command routing has an additional feature not present in normal event routing: if bubbling fails to find a handler, RoutedUICommand may try to retarget the command. This is designed for the scenario where commands are invoked by user interface elements such as menu or toolbar items because these present an interesting challenge.

Example 4-27 is an example of this very scenario. It has a subtle potential problem. While the menu is open, it steals the input focus away from the TextBox. It’s unlikely that the menu item itself is the intended target for a command—it’s merely the means of invoking the command. Users will expect the Copy menu item to copy whatever was selected in the TextBox, rather than copying the contents of the menu item. The menu deals with this by relinquishing the focus when the command is executed. This causes the focus to return to the TextBox, and so the command target is the one we expect. However, there’s a problem regarding disabled commands.

A command target can choose whether the commands it supports are enabled. A TextBox enables copying only if there is some selected text. It enables pasting only if the item on the clipboard is text, or can be converted to text. Menus gray out disabled commands, as Figure 4-4 shows. To do this, a menu item must locate the command target. The problem is that the menu is in possession of the keyboard focus at the point at which it needs to discover whether the command is enabled; the appropriate command target is therefore not the focused item in this case.

The RoutedUICommand class relies on focus scopes to handle this situation. If a RoutedUICommand fails to find a command binding, it checks to see whether the initial target was in a nested focus scope. If it was, WPF finds the parent focus scope, which will typically be the window. It then retargets the command, choosing the element in the parent scope that has the logical focus (i.e., the last element to have the focus before the menu grabbed it). This causes a second tunneling and bubbling phase to occur. The upshot is that the command’s target is whichever element had the focus before the menu was opened, or the toolbar button clicked.

If you are using menus or toolbars, you don’t need to do anything to make this work, because Menu and ToolBar elements both introduce nested focus scopes automatically. However, if you want to invoke commands from other elements, such as buttons, you’ll need to define the focus scope explicitly. Consider Example 4-28.

Example 4-28. Without focus scope

<StackPanel>
  <Button Command="ApplicationCommands.Copy"  Content="_Copy" />
  <Button Command="ApplicationCommands.Paste" Content="_Paste" />
  <TextBox />
</StackPanel>

This associates two buttons with commands supported by a TextBox. And yet, as Figure 4-5 shows, the buttons remain disabled even when the TextBox should be able to process at least one of the commands.

Figure 4-5. Commands disabled due to missing focus scope

We can fix this by introducing a focus scope around the buttons, as Example 4-29 shows.

Example 4-29. Focus scope

<StackPanel>
     <StackPanel FocusManager.IsFocusScope="True">
     <Button Command="ApplicationCommands.Copy"  Content="Copy" />
     <Button Command="ApplicationCommands.Paste" Content="Paste" />
     </StackPanel>
  <TextBox />
</StackPanel>

Now when the buttons attempt to locate a handler in order to choose whether they are enabled, the presence of the focus scope will cause the command routing to look for the element with the focus. If the TextBox has the logical focus, it will become the command target. As Figure 4-6 shows, this causes the buttons to reflect the availability of the commands correctly, and it means they invoke the command on the correct target when clicked.

Figure 4-6. Command enabled thanks to focus scope

We don’t have to use focus scopes to solve the problem in this particular example. You can use the more explicit, though slightly cumbersome, approach shown in Example 4-30.

Example 4-30. Explicit command targets

<StackPanel>
  <Button Command="Copy" Content="Copy"
             CommandTarget="{Binding ElementName=targetControl}" />
  <Button Command="Paste" Content="Paste"
             CommandTarget="{Binding ElementName=targetControl}" />
  <TextBox x:Name="targetControl" />
</StackPanel>

Here, each button specifies its command target explicitly. This makes it absolutely clear what the target will be. However, it is more verbose, so the automatic command routing is often more convenient. And even if the thought of manually specifying the command target for every item in a menu doesn’t strike you as unbearable, command routing has the added benefit of working well when there are multiple potential command targets (e.g., multiple text boxes on a form) and you want the command to go to whichever one last had the focus.