The Menu Control

Most applications include menus and toolbars of some kind. Both are a means to the same end: to provide easy navigation of the application's content. Toolbars generally contain a subset of the same entries that the menus provide and can be thought of as shortcuts to the menu items.

Visual Studio ships with both a Menu and a Toolbar control. The example here shows the use of the Menu control but using the Toolbar is very similar.

By default, the menu item appears as a horizontal bar from which you can drop down lists of items. The control is an Items control, so it is possible to change the default items contained in the content; however, you would normally use MenuItems in some form, as shown in the following example. Each MenuItem can contain other menu items, and you can build complex menus by nesting MenuItems within each other, but you should try to keep the menu structure as simple as possible.

You can control how the MenuItem displays using a number of properties (see Table 15.1).

Routed Commands with Menus

Routed commands were briefly discussed in Chapter 14, but now you are going to see them in action for the first time. Recall that these commands are akin to events in that they execute code when a user performs an action, and they can return a state indicating whether they can be executed at any given time.

There are at least three reasons why you would want to use routed commands instead of events:

1. The action that will cause an event to occur can be triggered from multiple locations in your application.
2. The UI element should be accessible only under certain conditions, such as a Save button being disabled if there's nothing to save.
3. You want to disconnect the code that handles the event from the code-behind file.

If any of these scenarios matches yours, consider using routed commands. In the case of the game, some of the items in the menu should also potentially be available from a toolbar. In addition, the Save action should be available only when a game is in progress and it should potentially be available from both a menu and the toolbar.

Styles

WPF controls have a property called Style (inherited from FrameworkElement) that can be set to an instance of the Style class. The Style class is quite complex and is capable of advanced styling functionality, but at its heart it is essentially a set of Setter objects. Each Setter object is responsible for setting the value of a property according to its Property property (the name of the property to set) and its Value property (the value to set the property to). You can either fully qualify the name you use in Property to the control type (for example, Button.Foreground), or you can set the TargetType property of the Style object (for example, Button), so that it is capable of resolving property names.

The following code shows how to use a Style object to set the Foreground property of a Button control:

<Button>
  Click me!
  <Button.Style>
    <Style TargetType="Button">
      <Setter Property="Foreground">
        <Setter.Value>
          <SolidColorBrush Color="Purple"/>
        </Setter.Value>
      </Setter>
    </Style>
  </Button.Style>
</Button>

Obviously, in this case it would be far easier simply to set the Foreground property of the button in the usual way. Styles become much more useful when you turn them into resources, because resources can be reused. You will learn how to do this in the “WPF User Controls” section later in the chapter.

Templates

Controls are constructed using templates, which you can customize. A template consists of a hierarchy of controls used to build the display of a control, which may include a content presenter for controls such as buttons that display content.

The template of a control is stored in its Template property, which is an instance of the ControlTemplate class. The ControlTemplate class includes a TargetType property that you can set to the type of control for which you are defining a template, and it can contain a single control. This control can be a container such as Grid, so this doesn't exactly limit what you can do.

Typically, you set the template for a class by using a style. This simply involves providing controls to use for the Template property in the following way:

<Button>
  Click me!
  <Button.Style>
    <Style TargetType="Button">
      <Setter Property="Template">
        <Setter.Value>
          <ControlTemplate TargetType="Button">
            …
          </ControlTemplate>
        </Setter.Value>
      </Setter>
    </Style>
  </Button.Style>
</Button>

Some controls may require more than one template. For example, CheckBox controls use one template for a check box (CheckBox.Template) and one template to output text next to the check box (CheckBox.ContentTemplate).

Templates that require content presenters can include a ContentPresenter control at the location where you want to output content. Some controls — especially those that output collections of items — use alternative techniques, which aren't covered in this chapter.

Again, replacing templates is most useful when combined with resources. However, as control styling is a very common technique, it is worth looking at how to do it in a Try It Out.

Value Converters

You may have wondered at some of the assignments that you have used in the examples so far: How, for example, can you assign the string value “true” to a Boolean property? You have learned that C# is type-safe and the compiler should not allow that kind of thing to happen! Happily, the reality is that it doesn't. XAML and WPF make extensive use of something called value converters, which can convert from one type to another behind the scenes.

WPF ships with converters for just about all the standard scenarios you can think of, so you can always convert from int to string or bool and integer. But what happens when you want to convert something that is not included? Then you have to implement the converter yourself.

Let's look at one example that is very common: the inversed bool converter. Imagine that you have a check box on a dialog box. Depending on whether it's checked, another part of the dialog box will be disabled or enabled. Quite often, the answer must be reversed for this to make sense. Take a look at the Options dialog box, for example. It has a check box with the question, “Play against computer?” Selecting this option should disable the ComboBox and TextBoxes on the dialog box. The value of IsChecked would be true, so binding that to IsEnabled of the other two controls will not work. Enter the InversedBoolConverter. This converter will simply inverse the bool value.

object Convert(object value, Type targetType,
    object parameter, CultureInfo culture);
object ConvertBack(object value, Type targetType,
    object parameter, CultureInfo culture);

Triggers

Events in WPF can include all manner of things, including button clicks, application startup and shutdown events, and so on. There are, in fact, several types of triggers in WPF, all of which inherit from a base TriggerBase class. One such trigger is the EventTrigger class, which contains a collection of actions, each of which is an object that derives from the base TriggerAction class. These actions are executed when the trigger is activated.

Not a lot of classes inherit from TriggerAction in WPF, but you can, of course, define your own. You can use EventTrigger to trigger animations using the BeginStoryboard action, manipulate storyboards using ControllableStoryboardAction, and trigger sound effects with SoundPlayerAction. As this latter trigger is mostly used in animations, you'll look at it in the next section.

Every control has a Triggers property that you can use to define triggers directly on that control. You can also define triggers further up the hierarchy — for example, on a Window object as shown earlier. The type of trigger you will use most often when you are styling controls is Trigger (although you will still use EventTrigger to trigger control animations). The Trigger class is used to set properties in response to changes to other properties, and is particularly useful when used in Style objects.

Trigger objects are configured as follows:

• To define what property a Trigger object monitors, you use the Trigger.Property property.
• To define when the Trigger object activates, you set the Trigger.Value property.
• To define the actions taken by a Trigger, you set the Trigger.Setters property to a collection of Setter objects.

The Setter objects referred to here are exactly the same objects that you saw in the “Styles” section earlier.

For example, the following trigger examines the value of a property called MyBooleanValue, and when that property is true it sets the value of the Opacity property to 0.5:

<Trigger Property="MyBooleanValue" Value="true">
  <Setter Property="Opacity" Value="0.5"/>
</Trigger>

On its own, this code doesn't tell you very much, as it is not associated with any control or style. The following code is much more explanatory; it shows a Trigger as you would use it in a Style object:

<Style TargetType="Button">
  <Style.Triggers>
    <Trigger Property="IsMouseOver" Value="true">
      <Setter Property="Foreground" Value="Yellow"/>
    </Trigger>
  </Style.Triggers>
</Style>

This code changes the Foreground property of a Button control to Yellow when the Button.IsMouseOver property is true. IsMouseOver is one of several extremely useful properties that you can use as a shortcut to find out information about controls and control state. As its name suggests, it is true if the mouse is over the control. This enables you to code for mouse rollovers. Other properties like this include IsFocused, to determine whether a control has focus; IsHitTestVisible, which indicates whether it is possible to click on a control (that is, it is not obscured by controls further up the stacking order); and IsPressed, which indicates whether a button is pressed. The last of these only applies to buttons that inherit from ButtonBase, whereas the others are available on all controls.

You can also achieve a great deal by using the ControlTemplate.Triggers property, which enables you to create templates for controls that include triggers. This is how the default Button template is able to respond to mouse rollovers, clicks, and focus changes with its template. This is also what you must modify to implement this functionality for yourself.

Animations

Animations are created by using storyboards. The absolute best way to define animations is, without a doubt, to use a designer such as Expression Blend. However, you can also define them by editing XAML code directly, and by implication from code-behind (as XAML is simply a way to build a WPF object model).

A storyboard is defined using a Storyboard object, which contains one or more timelines. You can define timelines by using key frames or by using one of several simpler objects that encapsulate entire animations. Complex storyboards may even contain nested storyboards.

A Storyboard is contained in a resource dictionary, so you must identify it with an x:Key property.

Within the timeline of a storyboard, you can animate properties of any element in your application that is of type double, Point, or Color. This covers most of the things that you may want to change, so it's quite flexible. There are some things that you can't do, such as replace one brush with another, but there are ways to achieve pretty much any effect you can imagine given these three types.

Each of these three types has two associated timeline controls that you can use as children of Storyboard. These six controls are DoubleAnimation, DoubleAnimationUsingKeyFrames, PointAnimation, PointAnimationUsingKeyFrames, ColorAnimation, and ColorAnimationUsingKeyFrames. Every timeline control can be associated with a specific property of a specific control by using the attached properties Storyboard.TargetName and Storyboard.TargetProperty. For example, you would set these properties to MyRectangle and Width if you wanted to animate the Width property of a Rectangle control with a Name property of MyRectangle. You would use either DoubleAnimation or DoubleAnimationUsingKeyFrames to animate this property. You will see examples of using storyboards as this chapter progresses.

Next, you'll look at the simple, animation timelines without key frames, and then move on to look at the timelines that use key frames.

<Storyboard x:Key="RectangleExpander">
<DoubleAnimation Storyboard.TargetName="MyRectangle"
  Storyboard.TargetProperty="Width" Duration="00:00:05"
  From="100" To="200"/>
</Storyboard>

<Storyboard x:Key="EllipseMover">
  <PointAnimationUsingKeyFrames Storyboard.TargetName="MyEllipse"
    Storyboard.TargetProperty="Center" RepeatBehavior="Forever">
    <LinearPointKeyFrame KeyTime="00:00:00" Value="50,50"/>
    <LinearPointKeyFrame KeyTime="00:00:01" Value="100,50"/>
    <LinearPointKeyFrame KeyTime="00:00:02" Value="100,100"/>
    <LinearPointKeyFrame KeyTime="00:00:03" Value="50,100"/>
    <LinearPointKeyFrame KeyTime="00:00:04" Value="50,50"/>
  </PointAnimationUsingKeyFrames>
</Storyboard>

Implementing Dependency Properties

You can add dependency properties to any class that inherits from System.Windows.DependencyObject. This class is in the inheritance hierarchy for many classes in WPF, including all the controls and UserControl.

To implement a dependency property to a class, you add a public, static member to your class definition of type System.Windows.DependencyProperty. The name of this member is up to you, but best practice is to follow the naming convention <PropertyName>Property:

public static DependencyProperty MyStringProperty;

It might seem odd that this property is defined as static, as you end up with a property that can be uniquely defined for each instance of your class. The WPF property framework keeps track of things for you, so you don't have to worry about this for the moment.

The member you add must be configured by using the static DependencyProperty.Register() method:

public static DependencyProperty MyStringProperty =
   DependencyProperty.Register(…);

This method takes between three and five parameters, as shown in the Table 15.4 (these are shown in order, with the first three parameters being the mandatory ones).

There are oth methods that you can use to register dependency properties, such as RegisterAttached(), which you can use to implement an attached property. You won't look at these other methods in this chapter, but it's worth reading up on them.

For example, you could register the MyStringProperty dependency property using three parameters as follows:

public class MyClass : DependencyObject
{
   public static DependencyProperty MyStringProperty = DependencyProperty.Register(
      "MyString",
      typeof(string),
      typeof(MyClass));
}

You can also include a .NET property that can be used to access dependency properties directly (although this isn't mandatory, as you will see shortly). However, because dependency properties are defined as static members, you cannot use the same syntax you would use with ordinary properties. To access the value of a dependency property, you have to use methods that are inherited from DependencyObject, as follows:

    public string MyString
    {
        get { return (string)GetValue(MyStringProperty); }
        set { SetValue(MyStringProperty, value); }
    }

Here, the GetValue() and SetValue() methods get and set, respectively, the value of the MyStringProperty, dependency property for the current instance. These two methods are public, so client code can use them directly to manipulate dependency property values. This is why adding a .NET property to access a dependency property is not mandatory.

If you want to set metadata for a property, then you must use an object that derives from PropertyMetadata, such as FrameworkPropertyMetadata, and pass this instance as the fourth parameter to Register(). There are 11 overloads of the FrameworkPropertyMetadata constructor, and they take one or more of the parameters shown in Table 15.5.

A simple example of using FrameworkPropertyMetadata is to use it to set the default value of a property:

   public static DependencyProperty MyStringProperty =
         DependencyProperty.Register(
         "MyString",
         typeof(string),
         typeof(MyClass),
         new FrameworkPropertyMetadata("Default value"));

You have so far learned about three callback methods that you can specify, for property change notification, property coercion, and property value validation. These callbacks, like the dependency property itself, must all be implemented as public, static methods. Each callback has a specific return type and parameter list that you must use on your callback method.

Now it is time to get back on track and continue with the game client for Karli Cards. In the following Try It Out, you create a user control that can represent a playing card in the application.

Refactoring the Domain Model

As stated, the domain model is the code that describes the objects of the game. At the moment, you have these classes in the CardLib project that describe objects of the game:

• Card
• Deck
• Rank
• Suit

In addition to these classes, the game needs a Player and a ComputerPlayer class, so you are going to add those. You also need to modify the Card and Deck classes a bit to make them work better in a Windows application.

There is a lot of work to do, so let's get started.

The View Models

The purpose of a view model is to hold the state of the view that displays it. In the case of the Karli Cards, this means that you already have a view model class: the GameOptions class. This class holds the state of the Options and StartGame windows. At the moment, you can't get the selected players from the options, so you have to add that ability. The view model of the Game Client window is missing, so that is the next task to do.

The view model for the execution of the game must reflect all the parts of the game as it is running. The parts of the game are:

• The deck from which the current player draw a card
• A card that can be taken by the current player instead of drawing a card
• A current player
• A number of participating players

The view model should also be able to notify observers of changes, and that means implementing INotifyPropertyChanged again.

In addition to these abilities, the view model should also provide a way of starting a new game. You will do this by creating a new routed command for the menu. The command is created in the view model, but is called from the view.

Completing the Game

You now have a complete game that you can't play because nothing is being displayed in the game client. For the game to run, you need two additional user controls that will be positioned on the game client using a dock panel.

The two user controls are called CardsInHand, which displays a player's hand, and GameDecks, which displays the main deck and the available card.