In this conclusion to a four-part series on important concepts in Windows Presentation Foundation, you'll learn about attached events and commands. This article is excerpted from chapter three of the book Windows Presentation Foundation Unleashed, written by Adam Nathan (Sam's Publishing; ISBN: 0672328917).
The tunneling and bubbling of a routed event is natural when every element in the tree exposes that event. But WPF supports tunneling and bubbling of routed events through elements that don’t even define that event! This is possible thanks to the notion of attached events.
Attached events operate much like attached properties (and their use with tunneling or bubbling is very similar to using attached properties with property value inheritance). Listing 3.9 changes the About dialog again by handing the bubbling SelectionChanged event raised by its ListBox and the bubbling Click event raised by both of its Buttons directly on the root Window. Because Window doesn’t define its own SelectionChanged or Click events, the event attribute names must be prefixed with the class name defining these events. Listing 3.10 contains the corresponding code-behind file that implements the two event handlers. Both event handlers simply show a MessageBox with information about what just happened.
LISTING 3.9 The About Dialog with Two Attached Event Handlers on the Root Window
using System.Windows; using System.Windows.Controls;
public partial class AboutDialog : Window { public AboutDialog() { InitializeComponent(); }
void ListBox_SelectionChanged(object sender, SelectionChangedEventArgs e) { if (e.AddedItems.Count > 0) MessageBox.Show("You just selected " + e.AddedItems[0]); } void Button_Click(object sender, RoutedEventArgs e) { if (e.AddedItems.Count > 0) MessageBox.Show("You just clicked " + e.Source); } }
Every routed event can be used as an attached event. The attached event syntax used in Listing 3.9 is valid because the XAML compiler sees the SelectionChanged .NET event defined on ListBox and the Click .NET event defined on Button. At run-time, however, AddHandler is directly called to attach these two events to the Window. Therefore, the two event attributes are equivalent to placing the following code inside the Window’s constructor:
public AboutDialog() { InitializeComponent(); this.AddHandler(ListBox.SelectionChangedEvent, new SelectionChangedEventHandler(ListBox_SelectionChanged)); this.AddHandler(Button.ClickEvent, new RoutedEventHandler(Button_Click)); }
DIGGING DEEPER
Consolidating Routed Event Handlers
Because of the rich information passed to routed events, you could handle every event that tunnels or bubbles with one top-level "megahandler" if you really wanted to! This handler could examine the RoutedEvent object to determine which event got raised, cast the RoutedEventArgs parameter to an appropriate subclass (such as KeyEventArgs, MouseButtonEventArgs, and so on) and go from there.
For example, Listing 3.9 could be changed to assign both ListBox.SelectionChanged and Button.Click to the same GenericHandler method, defined as follows:
void GenericHandler(object sender, RoutedEventArgs e) { if (e.RoutedEvent == Button.ClickEvent) { MessageBox.Show("You just clicked " + e.Source); } else if (e.RoutedEvent == ListBox.SelectionChangedEvent) { SelectionChangedEventArgs sce = (SelectionChangedEventArgs)e; if (sce.AddedItems.Count > 0) MessageBox.Show("You just selected " + sce.AddedItems[0]); } }
This is also made possible by the delegate contravariance feature added in version 2.0 of the .NET Framework, enabling a delegate to be used with a method whose signature uses a base class of an expected parameter (e.g. RoutedEventArgs instead of SelectionChangedEventArgs). GenericHandler simply casts the RoutedEventArgs parameter when necessary to get the extra information specific to the SelectionChanged event.
WPF provides built-in support for commands, a more abstract and loosely-coupled version of events. Whereas events are tied to details about specific user actions (such as a Button being clicked or a ListBoxItem being selected), commands represent actions independent from their user interface exposure. Canonical examples of commands are Cut, Copy, and Paste. Applications often expose these actions through many mechanisms simultaneously: MenuItems in a Menu, MenuItems on a ContextMenu, Buttons on a ToolBar, keyboard shortcuts, and so on.
You could handle the multiple exposures of commands such as Cut, Copy, and Paste with events fairly well. For example, you could define a generic event handler for each of the three actions and then attach each handler to the appropriate events on the relevant elements (the Click event on a Button, the KeyDown event on the main Window, and so on). In addition, you’d probably want to enable and disable the appropriate controls whenever the corresponding actions are invalid (for example, disabling any user interface for Paste when there is nothing on the clipboard). This two-way communication gets a bit more cumbersome, especially if you don’t want to hard-code a list of controls that need updating.
Fortunately, WPF’s support for commands is designed to make such scenarios very easy. The support reduces the amount of code you need to write (and in some cases eliminating all procedural code), and it gives you more flexibility to change your user interface without breaking the back-end logic. Commands are not a new invention of WPF; older technologies such as Microsoft Foundation Classes (MFC) have a similar mechanism. Of course, even if you’re familiar with MFC, commands in WPF have their own unique traits to learn about.
Much of the power of commands comes from the following three features:
WPF defines a number of built-in commands.
Commands have automatic support for input gestures (such as keyboard shortcuts).
Some of WPF’s controls have built-in behavior tied to various commands.
A command is any object implementing the ICommand interface (from System.Windows.Input), which defines three simple members:
Execute—The method that executes the command-specific logic
CanExecute—A method returning true if the command is enabled or false if it is disabled
CanExecuteChanged—An event that is raised whenever the value of CanExecute changes
If you want to create Cut, Copy, and Paste commands, you could define and implement three classes implementing ICommand, find a place to store them (perhaps as static fields of your main Window), call Execute from relevant event handlers (when CanExecute returns true), and handle the CanExecuteChanged event to toggle the IsEnabled property on the relevant pieces of user interface. This doesn’t sound much better than simply using events, however.
Fortunately, controls such as Button, CheckBox, and MenuItem have logic to interact with any command on your behalf. They expose a simple Command property (of type ICommand). When set, these controls automatically call the command’s Execute method (when CanExecute returns true) whenever their Click event is raised. In addition, they automatically keep their value for IsEnabled synchronized with the value of CanExecute by leveraging the CanExecuteChanged event. By supporting all this via a simple property assignment, all of this logic is available from XAML.
Even more fortunately, WPF defines a bunch of commands already, so you don’t have to implement ICommand objects for Cut, Copy, and Paste and worry about where to store them. WPF’s built-in commands are exposed as static properties of five different classes:
Each of these properties does not return a unique type implementing ICommand. Instead, they are all instances of RoutedUICommand, a class that not only implements ICommand, but supports bubbling just like a routed event.
The About dialog has a “Help” Button that currently does nothing, so let’s demonstrate how these built-in commands work by attaching some logic with the Help command defined in ApplicationCommands. Assuming the Button is named helpButton, you can associate it with the Help command in C# as follows:
helpButton.Command = ApplicationCommands.Help;
All RoutedUICommand objects define a Text property containing a name for the command that’s appropriate to show in a user interface. (This property is the only difference between RoutedUICommand and its base RoutedCommand class.) For example, the Help command’s Text property is (unsurprisingly) set to the string Help. The hard-coded Content on this Button could therefore be replaced as follows:
The Text string defined by all RoutedUICommands is automatically localized into every language supported by WPF! This means that a Button whose Content is assigned to ApplicationCommands. Help.Text automatically displays “Ayuda” rather than “Help” when the thread’s current UI culture represents Spanish rather than English. Even in a context where you want to expose images rather than text (perhaps on a ToolBar), you can still leverage this localized string elsewhere, such as in a ToolTip.
Of course, you’re still responsible for localizing any of your own strings that get displayed in your user interface. Leveraging Text on commands can simply cut down on the number of terms you need to translate.
If you were to run the About dialog with this change, you would see that the Button is now permanently disabled. That’s because the built-in commands can’t possibly know when they should be enabled or disabled, or even what action to take when they are executed. They delegate this logic to consumers of the commands.
To plug in custom logic, you need to add a CommandBinding to the element that will execute the command or any parent element (thanks to the bubbling behavior of routed commands). All classes deriving from UIElement (and ContentElement) contain a CommandBindings collection that can hold one or more CommandBinding objects. Therefore, you can add a CommandBinding for Help to the About dialog’s root Window as follows in its code-behind file:
This assumes that methods called HelpExecuted and HelpCanExecute have been defined. These methods will be called back at appropriate times in order to plug in an implementation for the Help command’s CanExecute and Execute methods.
Listings 3.11 and 3.12 change the About dialog one last time, binding the Help Button to the Help command entirely in XAML (although the two handlers must be defined in the code-behind file).
LISTING 3.11 The About Dialog Supporting the Help Command
Window’s CommandBinding can be set in XAML because it defines a default constructor and enables its data to be set with properties. Button’s Content can even be set to the chosen command’s Text property in XAML thanks to a popular data binding technique discussed in Chapter 9. In addition, notice that a type converter simplifies specifying the Help command in XAML. A CommandConverter class knows about all the built-in commands, so the Command property can be set to Help in both places rather than the more verbose {x:Static ApplicationCommands.Help}. (Custom commands don’t get the same special treatment.) In the code-behind file, HelpCanExecute keeps the command enabled at all times, and HelpExecuted launches a web browser with an appropriate help URL.
Using the Help command in such a simple dialog may seem like overkill when a simple event handler for Click would do, but the command has provided an extra benefit (other than localized text): automatic binding to a keyboard shortcut.
Applications typically invoke their version of help when the user presses the F1 key. Sure enough, if you press F1 while displaying the dialog defined in Listing 3.10, the Help command is automatically launched, as if you clicked the Help Button! That’s because commands such as Help define a default input gesture that executes the command. You can bind your own input gestures to a command by adding KeyBinding and/or MouseBinding objects to the relevant element’s InputBindings collection. For example, to assign F2 as a keyboard shortcut that executes Help, you could add the following statement to AboutDialog’s constructor:
this.InputBindings.Add( new KeyBinding(ApplicationCommands.Help, new KeyGesture(Key.F2)));
This would make both F1 and F2 execute Help, however. You could additionally suppress the default F1 behavior by binding F1 to a special NotACommand command as follows:
this.InputBindings.Add( new KeyBinding(ApplicationCommands.NotACommand, new KeyGesture(Key.F1)));
Both of these statements could alternatively be represented in XAML as follows:
It can seem almost magical when you encounter it, but some controls in WPF contain their own command bindings. The simplest example of this is the TextBox control, which has its own built-in bindings for the Cut, Copy, and Paste commands that interact with the clipboard, as well as Undo and Redo commands. This not only means that TextBox responds to the standard Ctrl+X, Ctrl+C, Ctrl+V, Ctrl+Z, and Ctrl+Y keyboard shortcuts, but that it’s easy for additional elements to participate in these actions.
The following standalone XAML demonstrates the power of these built-in command bindings:
You can paste this content into XamlPad or save it as a .xaml file to view in Internet Explorer, because no procedural code is necessary. Each of the five Buttons is associated with one of the commands and sets its Content to the string returned by each command’s Text property. The only new thing here is the setting of each Button’s CommandTarget property to the instance of the TextBox (again using data binding functionality discussed in Chapter 9). This causes the command to be executed from the TextBox rather than the Button, which is necessary in order for it to react to the commands.
This XAML produces the result in Figure 3.8. The first two Buttons are automatically disabled when no text in the TextBox is selected, and automatically enabled when there is a selection. Similarly, the Paste Button is automatically enabled whenever there is text content on the clipboard, or disabled other wise.
Figure 3.8.The five Buttons work as expected without any procedural code, thanks to TextBox’s built-in bindings.
Button and TextBox have no direct knowledge of each other, yet though commands they can achieve rich interaction. This is why WPF’s long list of built-in commands is so important. The more that third-party controls standardize on WPF’s built-in commands, the more seamless (and declarative) interaction can be achieved among controls that have no direct knowledge of each other.
WPF’s classes have a very deep inheritance hierarchy, so it can be hard to get your head wrapped around the significance of various classes and their relationships. The inside cover of this book contains a map of these classes to help you put them in perspective as you encounter new ones. It is incomplete due to space constraints, but the major classes are covered.
A handful of classes are fundamental to the inner-workings of WPF, and deserve a quick explanation before we get any further in the book. Some of these have been mentioned in passing already. Figure 3.9 shows these important classes and their relationships without all the extra clutter from the inside cover.
These ten classes have the following significance:
Object—The base class for all .NET classes.
DispatcherObject—The base class for any object that wishes to be accessed only on the thread that created it. Most WPF classes derive from DispatcherObject, and are therefore inherently thread-unsafe. The Dispatcher part of the name refers to WPF’s version of a Win32-like message loop, discussed further in Chapter 7, “Structuring and Deploying an Application.”
DependencyObject—The base class for any object that can support dependency properties. DependencyObject defines the GetValue and SetValue methods that are central to the operation of dependency properties.
Figure 3.9.The core classes in the WPF Presentation Framework.
Freezable—The base class for objects that can be “frozen” into a read-only state for performance reasons. Freezables, once frozen, can even be safely shared among multiple threads, unlike all other DispatcherObjects. Frozen objects can never be unfrozen, but you can clone them to create unfrozen copies.
Visual—The base class for all objects that have their own visual representation. Visuals are discussed in depth in Chapter 11.
UIElement—The base class for all visual objects with support for routed events, command binding, layout, and focus.
ContentElement—A base class similar to UIElement, but for pieces of content that don’t have rendering behavior on their own. Instead, ContentElements are hosted in a Visual-derived class to be rendered on the screen.
FrameworkElement—The base class that adds support for styles, data binding, resources, and a few common mechanisms for Windows-based controls such as tooltips and context menus.
FrameworkContentElement—The analog to FrameworkElement for content. Chapter 14 examines the FrameworkContentElements in WPF.
Control—The base class for familiar controls such as Button, ListBox, and StatusBar. Control adds many properties to its FrameworkElement base class, such as Foreground, Background, and FontSize. Controls also support templates that enable you to completely replace their visual tree, discussed in Chapter 10. The next chapter examines WPF’s Controls in depth.
Throughout the book, the simple term element is used to refer to an object that derives from UIElement or FrameworkElement, and sometimes ContentElement or FrameworkContentElement. The distinction between UIElement versus FrameworkElement or ContentElement versus FrameworkContentElement is not important because WPF doesn’t ship any other public subclasses of UIElement and ContentElement.
Conclusion
In this chapter and the preceding two chapters, you’ve learned about all the major ways that WPF builds on top of the foundation of the .NET Framework. The WPF team could have exposed its features via typical .NET APIs similar to Windows Forms and still have an interesting technology. Instead, the team added several fundamental concepts that enable a wide range of features to be exposed in a way that can provide great productivity for developers and designers.
Indeed, when you focus on these core concepts (as this chapter has done), you can see that the landscape isn’t quite as simple as it used to be: There are multiple types of properties, multiple types of events, multiple trees, and multiple ways of achieving the same results (such as writing declarative versus procedural code)! Hopefully you can now appreciate some of the value of these new mechanisms. Throughout the rest of the book, these concepts generally fade into the background as we focus on accomplishing specific development tasks.
Because of the (primitive) examples used in this chapter, you should now have a feel for some of WPF’s controls and how WPF user interfaces are arranged. The next three chapters build on this by formally introducing you to WPF’s controls and layout mechanisms.
/ 5 
Visual Basic for Beginners
