Before you write a custom control, the first question you should ask is:

Do I really need a custom control?

One of the main reasons for writing custom controls in older user interface technologies is to modify the appearance of a control, but as we’ve seen in earlier chapters, content models and templates mean this is often unnecessary. WPF offers a progressive scale of customization techniques that you should bear in mind when considering writing a custom control:

This sequence offers increasing levels of power in exchange for slightly more effort at each step. Only if 1–4 don’t meet your needs is writing some kind of custom element such as a custom control likely to be the answer.

An important indicator of whether you need to write a new control (or some other custom visual element type) is whether you plan to add new API features. Even in this case, you should consider carefully what type of custom element to write—controls are not the only kind of element. You might get more flexibility by writing a lower-level element that you can integrate into the visuals of an existing control. For example, a lot of the elements that make WPF so flexible, such as layout classes and shapes, derive from FrameworkElement, but are not in fact controls (i.e., they do not derive from the Control base class).

If you are certain that a custom element is the best way to proceed, you will need to work through a number of design steps. First, you must pick the base class—will it derive from FrameworkElement, Control, or one of the other base types provided by WPF? Then you must define the API, deciding what properties, events, and commands your class will provide. Finally, if your new element is to provide the same flexibility that built-in classes offer, you will need to pay careful attention to the interface between the element and its template.

WPF provides many classes from which you can derive when creating custom elements. Figure 18-1 shows a set of classes that are most likely to be suitable base classes, and illustrates the inheritance relationship between them. Note that this is by no means a complete inheritance diagram—it simply shows the classes you should consider as possible base classes.

Figure 18-1. Partial class hierarchy, showing candidate base classes for custom elements

Whichever base class you choose, your element will derive directly or indirectly from FrameworkElement. This offers event routing, advanced property handling, animation, data binding, layout support, styling, and logical tree integration.

Deriving directly from FrameworkElement might be appropriate for an element designed to be composed into other elements. For example, consider an element that binds to a data source and renders the data as a graph. You might be tempted to make this derive from Control. However, the raw graph drawing element would usually be used in conjunction with other elements such as TextBlock to provide labels for the graph and its axes. It might therefore make more sense to separate the graph drawing into a low-level element, which could then be incorporated into the visuals of any number of different controls.

If you are writing an element that performs custom layout logic, you should derive from Panel to be consistent with the built-in layout elements.

If you are writing an element that wraps around another element, augmenting it in some way, consider deriving from Decorator. Many built-in elements derive from Decorator. For example, there is Border, which adds a border around an element. There is also ViewBox, which automatically scales the element that it wraps to fill the available space. If you wish to provide some kind of wrapper that adds functionality around other content, consider deriving from Decorator.

The Adorner base class is designed for elements such as selection outlines and drag handles. WPF renders adorners so that they appear on top of all other elements. For example, if a selected shape in a drawing program were mostly obscured by other shapes on top of it, its selection outline would still be visible if rendered as an adorner. The Adorners section, later in this chapter, describes how to write an adorner.

Shape is the base class of elements such as Rectangle and Path. If your application makes heavy use of some shape that can be represented with a PathGeometry, you can derive your own shape class instead of having to use the Path type every time. For example, if you wanted lots of stars in your application, you could derive a Star class from Shape. When writing your own shape, you generate the appearance by overriding the DefiningGeometry property. The base Shape class’s OnRender will render the Geometry you provide, and will automatically handle the Stretch property for you by applying a transform. If you want to handle how your object changes shape when stretched—the default behavior might distort the shape in an unacceptable way—you can take complete control by overriding the OnRender method, as shown in Chapter 13.

If your element provides behavior, or supports user interactions not available from built-in components, it is appropriate to derive from Control, either directly or indirectly. For example, if you want to make an interactive graphing component, where the user can click on items in the graph to inspect them, or zoom around, you would typically write this as a control (and its template might use the lower-level graph rendering element you wrote earlier).

Control offers several derived classes, augmenting the basic control functionality. If you are writing a control that provides a space in which the user can place some content (e.g., a caption), you should derive from ContentControl—this provides your control with support for the content model. If your control supports content in both a header caption and the main area (like a tab page), consider deriving from HeaderedContentControl.

If you need to present multiple child items, first consider whether the combination of ListBox, data binding, templates, and styles will meet your requirements. Data binding and styling enable WPF’s list controls such as ListBox and TreeView to handle a wide range of scenarios for which their Win32 and Windows Forms forebears are unsuited. If you need extra functionality not provided by the built-in list controls, you should consider deriving your custom element type from either Selector or its base class, ItemsControl. ItemsControl provides the basic support for controls containing lists of items, including optional data binding functionality. Selector augments this with the ability to track a currently selected item or set of items.

Once you have picked a base class, you will need to devise an API for your control. WPF elements usually expose the majority of their functionality through properties, events, and commands, because these get extensive support from the framework and are easily used from XAML. WPF can provide automatic support for routing of events and commands, and its dependency property system provides support for many framework features such as data binding, styling, triggers, and animation. You can, of course, write methods as well, and for certain kinds of functionality, methods are the best approach. (For example, the ListBox has a ScrollIntoView method that ensures that a particular item is visible. This is a useful thing to be able to do from code.) But, you should prefer properties, events, and commands where they are a reasonable fit.

public class MyCustomControl : ContentControl {

    public static readonly DependencyProperty StripeBrushProperty;

    static MyCustomControl(  ) {
        PropertyMetadata stripeBrushMetadata =
            new PropertyMetadata(Brushes.Green); // default value
        StripeBrushProperty = DependencyProperty.Register("StripeBrush",
            typeof(Brush), typeof(MyCustomControl), stripeBrushMetadata);
    }

    public Brush StripeBrush {
        get { return (Brush) GetValue(StripeBrushProperty); }
        set { SetValue(StripeBrushProperty, value); }
    }
}

myControl.SetValue(MyCustomControl.StripeBrushProperty, Brushes.Red);

<local:MyCustomControl StripeBrush="Blue" />

public class ElementWithAttachedProp : Panel {

    public static readonly DependencyProperty IsSkewedProperty;

    static ElementWithAttachedProp (  ) {
        PropertyMetadata isSkewedMetadata = new PropertyMetadata(false);
        IsSkewedProperty = DependencyProperty.RegisterAttached
("IsSkewed",
            typeof(bool), typeof(ElementWithAttachedProp), isSkewedMetadata);
    }
    public static bool GetIsSkewed(DependencyObject target) {
        return (bool) target.GetValue(IsSkewedProperty);
    }

    public static void SetIsSkewed(DependencyObject target, bool value) {
        target.SetValue(IsSkewedProperty, value);
    }
    ...
}

<Button local:ElementWithAttachedProp.IsSkewed="True"/>

<Button>
    <Button.Background>
        <SolidColorBrush Color="Blue" />
    </Button.Background>
    <Grid.Row>1</Grid.Row>
    <local:ElementWithAttachedProp.IsSkewed>
        True
    </local:ElementWithAttachedProp.IsSkewed>
 </Button>

...
static ElementWithAttachedProp (  ) {
    PropertyChangedCallback isSkewedChanged =
        new PropertyChangedCallback(OnIsSkewedChanged);
    PropertyMetadata isSkewedMetadata =
        new PropertyMetadata(false, isSkewedChanged);
    IsSkewedProperty = DependencyProperty.RegisterAttached("IsSkewed",
        typeof(bool), typeof(ElementWithAttachedProp), isSkewedMetadata);
}
...
static void OnIsSkewedChanged(DependencyObject target,
                            DependencyPropertyChangedEventArgs e) {
    Debug.WriteLine("IsSkewed just changed: " + e.NewValue);
}
...

partial class MyWindow : Window {
    ...
    protected override void OnPropertyChanged(
            DependencyPropertyChangedEventArgs e) {

        base.OnPropertyChanged(e);
        if (e.Property == UIElement.IsMouseOverProperty) {
            this.Background = this.IsMouseOver ? Brushes.Red : Brushes.Blue;
        }
    }
}

partial class Window1 : Window {

   public Window1(  ) {
        InitializeComponent(  );

        // myButton refers to a <Button> in the XAML (not shown)
        PropertyDescriptor buttonIsPressedProp =
            TypeDescriptor.GetProperties(myButton)["IsPressed"];

        buttonIsPressedProp.AddValueChanged(myButton, OnButtonIsPressedChanged);
    }

    void OnButtonIsPressedChanged(object sender, EventArgs e) {
        this.Background = myButton.IsPressed ? Brushes.Red : Brushes.Blue;
    }
}

PropertyDescriptor buttonIsPressedProp =
    DependencyPropertyDescriptor.FromProperty(Button.IsPressedProperty,
                                              typeof(Button));

public class Star : FrameworkElement {
    public static readonly DependencyProperty PointsProperty;

    public int Points {
        get { return (int) GetValue(PointsProperty); }
        set { SetValue(PointsProperty, value); }
    }

    static Star(  ) {
        FrameworkPropertyMetadata pointsMetadata =
            new FrameworkPropertyMetadata(5, // default value
                   FrameworkPropertyMetadataOptions.AffectsRender);

        PointsProperty = DependencyProperty.Register("Points",
            typeof(int), typeof(Star), pointsMetadata);
    }
    ...
}

public class ClockControl : ContentControl {

    public static RoutedEvent AlarmEvent;
    public static RoutedEvent PreviewAlarmEvent;

    static ClockControl(  ) {
        AlarmEvent = EventManager.RegisterRoutedEvent(
            "Alarm", RoutingStrategy.Bubble,
            typeof(RoutedEventHandler), typeof(ClockControl));
        PreviewAlarmEvent = EventManager.RegisterRoutedEvent(
            "PreviewAlarm", RoutingStrategy.Tunnel,
            typeof(RoutedEventHandler), typeof(ClockControl));
    }

    public event RoutedEventHandler Alarm {
        add { AddHandler(AlarmEvent, value); }
        remove { RemoveHandler(AlarmEvent, value); }
    }
    public event RoutedEventHandler PreviewAlarm {
        add { AddHandler(PreviewAlarmEvent, value); }
        remove { RemoveHandler(PreviewAlarmEvent, value); }
    }

    protected virtual void OnAlarm(  ) {
        RoutedEventArgs args = new RoutedEventArgs(PreviewAlarmEvent);
        RaiseEvent(args);
        if (!args.Handled) {
            args = new RoutedEventArgs(AlarmEvent);
            RaiseEvent(args);
        }
    }
    ...
}

RoutedEventHandler handler = MyAlarmHandlerMethod;
myButton.AddHandler(ClockControl.AlarmEvent, handler);

RoutedEventArgs re = new RoutedEventArgs(ClockControl.AlarmEvent);
myButton.RaiseEvent(re);

public class ClockControl : Control {
    public static RoutedUICommand SnoozeCommand;

    static ClockControl(  ) {
        InputGestureCollection boomInputs = new InputGestureCollection(  );
        boomInputs.Add(new KeyGesture(Key.F,
                                     ModifierKeys.Control|ModifierKeys.Shift));
        SnoozeCommand = new RoutedUICommand("Snooze", "Snooze",
                                     typeof(ClockControl), boomInputs);
    }
    ...
}

<Button Command="local:ClockControl.SnoozeCommand">Click me</Button>

public class MyCustomControl : ContentControl {

    static MyCustomControl(  ) {
        CommandBinding copyCommandBinding = new CommandBinding(
            ApplicationCommands.Copy,
            HandleCopyCommand);
        CommandManager.RegisterClassCommandBinding(typeof(MyCustomControl),
        copyCommandBinding);
    }

    static void HandleCopyCommand(object target,
                                        ExecutedRoutedEventArgs e) {
        MyCustomControl myControl = (MyCustomControl) target;
        ...
    }
}

The final design consideration for any custom element is how it will connect with its visuals. If the element derives directly from FrameworkElement, it might be appropriate for it to generate its own visuals. (Chapter 13 described how to create a graphical appearance.) In particular, if you are creating an element whose purpose is to provide a particular form of visualization—such as an element that renders a three-dimensional graph—the element should take complete control of how this is managed. However, if you are writing a control, you would not normally hard-wire the graphics into the control.

Remember that a control’s job is to provide behavior. The visuals are provided by the control template. A control may provide a default set of visuals, but it should allow these to be replaced in order to offer the same flexibility as the built-in controls. (Chapter 9 described how to replace a control’s visuals with a template.) A control that conforms to this approach, where the visuals are separated from the control, is often described as lookless, because the control has no intrinsic appearance or “look.” All of the controls built into WPF are lookless.

Of course, it is not possible for the control to be entirely independent of its visuals. As we saw in Chapter 9, there is an implied contract between a control and its template. The control allows its appearance to be customized by replacing the template, but the template should in turn provide certain features on behalf of the control. Chapter 9 described the various styles of contract; some controls use a mixture of these styles. The following sections describe how to support these contract types in a custom control.

<ControlTemplate TargetType="{x:Type local:MyCustomControl}">
  <Grid>
    <Line Stroke="{TemplateBinding StripeBrush}" StrokeThickness="1"
                X1="0" Y1="0" X2="100" Y2="100" />
  </Grid>
</ControlTemplate>

<ControlTemplate TargetType="{x:Type loc:ControlWithNamedParts}">
  <Grid Width="80" Height="100">
    <Ellipse Fill="Black" Stroke="Gray" StrokeThickness="3" Margin="0,20,0,0" />
    <ContentControl x:Name="PART_Body"
                    Foreground="White" HorizontalAlignment="Center"
                    VerticalAlignment="Center" Margin="0,15,0,0" />
    <Line x:Name="PART_Fuse"
          Stroke="Blue" StrokeThickness="3" X1="55" Y1="40" X2="75" Y2="5" />
  </Grid>
</ControlTemplate>

[TemplatePart(Name="PART_Body", Type=typeof(ContentControl))]
[TemplatePart(Name="PART_Fuse", Type=typeof(FrameworkElement))]
public class ControlWithNamedParts : Control {
    ContentControl body;
    FrameworkElement fuse;

    public override void OnApplyTemplate(  )  {
        base.OnApplyTemplate(  );

        body = Template.FindName("PART_Body", this) as ContentControl;
        fuse = Template.FindName("PART_Fuse", this) as FrameworkElement;
    }
    ...
}

[TemplatePart(Name="PART_Target", Type=typeof(FrameworkElement))]
public class MyControl : Control {
    private FrameworkElement targetPart;

    public override void OnApplyTemplate(  ) {
        base.OnApplyTemplate(  );

        FrameworkElement oldTargetPart = targetPart;
        targetPart = Template.FindName("PART_Target", this) as FrameworkElement;
        if (!object.ReferenceEquals(oldTargetPart, targetPart)) {
            if (oldTargetPart != null) {
                oldTargetPart.MouseEnter -=
                    new MouseEventHandler(targetPart_MouseEnter);
                oldTargetPart.MouseLeave -=
                    new MouseEventHandler(targetPart_MouseLeave);
            }

            if (targetPart != null) {
                targetPart.MouseEnter +=
                    new MouseEventHandler(targetPart_MouseEnter);
                targetPart.MouseLeave +=
                    new MouseEventHandler(targetPart_MouseLeave);
            }
        }
    }

    void targetPart_MouseLeave(object sender, MouseEventArgs e) {
        ...
    }
    void targetPart_MouseEnter(object sender, MouseEventArgs e) {
        ...
    }
   ...
}

<ControlTemplate TargetType="{x:Type local:MyContentControl}">
  <Grid>
    <Rectangle Fill="White" />
    <ContentPresenter />
  </Grid>
</ControlTemplate>

<ControlTemplate TargetType="{x:Type local:MyHeaderedContentControl}">
  <Grid>
    <Grid.RowDefinitions>
      <RowDefinition />
      <RowDefinition />
    </Grid.RowDefinitions>

    <ContentPresenter Grid.Row="0" Content="{TemplateBinding Content}" />
    <ContentPresenter Grid.Row="1" Content="{TemplateBinding Header}" />
  </Grid>
</ControlTemplate>

public class ControlWithPlaceholder : Control {
    public static readonly DependencyProperty IsMyPlaceholderProperty;

    static ControlWithPlaceholder(  ) {

        PropertyMetadata isMyPlaceholderMetadata = new PropertyMetadata(false,
            new PropertyChangedCallback(OnIsMyPlaceholderChanged));

        IsMyPlaceholderProperty = DependencyProperty.RegisterAttached(
            "IsMyPlaceholder", typeof(bool),
            typeof(ControlWithPlaceholder), isMyPlaceholderMetadata);
    }

    public static bool GetIsMyPlaceholder(DependencyObject target) {
        return (bool) target.GetValue(IsMyPlaceholderProperty);
    }
    public static void SetIsMyPlaceholder(DependencyObject target, bool value) {
        target.SetValue(IsMyPlaceholderProperty, value);
    }
...

    ...
    static void OnIsMyPlaceholderChanged(DependencyObject target,
                                    DependencyPropertyChangedEventArgs e) {

        FrameworkElement targetElement = target as FrameworkElement;
        if (targetElement != null && GetIsMyPlaceholder(targetElement)) {
            ControlWithPlaceholder containingControl =
                targetElement.TemplatedParent as ControlWithPlaceholder;
            if (containingControl != null) {
                containingControl.placeholder = targetElement;
            }
        }
    }

    FrameworkElement placeholder;

    ...
}

<ControlTemplate TargetType="{x:Type local:ControlWithPlaceholder}">
  <Grid local:ControlWithPlaceholder.IsMyPlaceholder="True" />
</ControlTemplate>

Although the ability to provide a custom look for a control is useful, developers should be able to use a control without having to supply custom visuals. The control should just work when used in its most straightforward way, which means that it should supply a default set of visuals. This is normally done by providing a style that sets default property values, including a default control template.

Logically speaking, these default styles live in the system resource scope. As we saw in Chapter 12, this scope contains system-defined resources such as system colors, and default styles for built-in controls. If you write a custom control, you can add your own resources to this scope by adding a themesgeneric.xaml file to your project. See Chapter 12 for more information on custom system-scope resources.

For each custom control, you should define a system-scope style with a TargetType specifying your control. This style must set the Template property with a ControlTemplate defining the default visuals for your control, such as the one shown in Example 18-26. See Chapter 8 and Chapter 9 for more information on how to define a style that supplies a template.

<!-- themes/generic.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="clr-namespace:CustomControlLib">
  <Style TargetType="{x:Type local:MyCustomControl}"
>
    <Setter Property="Template">
      <Setter.Value>
        <ControlTemplate TargetType="{x:Type local:MyCustomControl}">
          <Border Background="{TemplateBinding Background}"
                  BorderBrush="{TemplateBinding BorderBrush}"
                  BorderThickness="{TemplateBinding BorderThickness}">
            <ContentPresenter />
          </Border>
        </ControlTemplate>
      </Setter.Value>
    </Setter>
  </Style>
</ResourceDictionary>

To make sure your control picks up this default theme, you need to let the dependency property system know that the style is there. If you don’t, the control will just pick up the default style for its base class. Example 18-27 shows how to ensure that the correct style is used.

public class MyCustomControl : ContentControl {
    static MyCustomControl(  ) {
        ...
        DefaultStyleKeyProperty.OverrideMetadata(typeof(MyCustomControl),
            new FrameworkPropertyMetadata(typeof(MyCustomControl)));
    }
    ...
}

Note that the Visual Studio extensions for .NET 3.0 generate this code for you when you add a new custom control to a WPF project.

User controls offer a way of building custom controls that works rather differently than everything we’ve looked at so far. These are intended to offer a similar model to user controls in other UI frameworks such as Windows Forms and ASP.NET. In those technologies, user controls are built with the visual designer in the same way as a window or page would be created, using the same event handling and code-behind mechanisms.

UserControl is a very simple class that derives from ContentControl and adds very little. It defines no new public members, and merely makes minor changes to some default behaviors: it prevents the control from acting as a target for focus and tab navigation (we typically want the elements inside the user control to act as focus targets, not the containing user control itself). The main purpose of UserControl is to signal intent: by deriving from UserControl, you are indicating to the development environment how you would like to build and edit the control. It also offers a clue to developers using your control that it is unlikely to be lookless—user controls use the same tightly coupled relationship between markup and code behind as a window or page, so they do not usually support customization through templates.

Example 18-28 shows the XAML and code behind for a very simple user control.

<!-- CustomElement.xaml -->
<UserControl x:Class="CustomElement"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <Grid>
    <Button Click="OnButtonClick" Content="_Click me" />
  </Grid>
</UserControl>

// CustomElement.xaml.cs
public partial class CustomElement : UserControl
 {
    public CustomElement(  ){
        InitializeComponent(  );
    }

    void OnButtonClick(object sender, RoutedEventArgs e) {
        MessageBox.Show("Clicked");
    }
}

Having written a user control, you use it in the same way as any other custom element. Example 18-29 shows how you might use the control defined in Example 18-28.

<Window ...
    xmlns:local="clr-namespace:MyNamespace">
  <Grid>
    <local:CustomElement />
  </Grid>
</Window>

One of the reasons UserControl is so simple is that we don’t technically need it—features intrinsic to user controls in other UI frameworks are supported throughout all of WPF, so you can build custom elements using markup with code behind without deriving from UserControl. XAML is quite happy to use any root element type, so you can derive from any base class you like. Example 18-30 shows a pair of markup and code-behind files for a custom element that derives directly from Grid. This behaves in much the same way as the user control defined in Example 18-28.

<!-- CustomElement.xaml -->
<Grid x:Class="CustomElement"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

  <Button Click="OnButtonClick" Content="_Click me" />

</Grid>

// CustomElement.xaml.cs
public partial class CustomElement : Grid {
    public CustomElement(  ){
        InitializeComponent(  );
    }

    void OnButtonClick(object sender, RoutedEventArgs e) {
        MessageBox.Show("Clicked");
    }
}

As you can see, we add elements and attach event handlers to this code in the same way as with a user control. The current preview .NET 3.0 extensions for Visual Studio 2005 will even let you edit the design of such an element interactively—it doesn’t care that it’s not a user control.

Today, there is very little difference between these two ways of creating custom elements. This illustrates that the UserControl class doesn’t offer any unique functionality. It exists mainly to signal explicitly that you are using the markup and code-behind idiom. And this is A Good Thing—the minimal functionality doesn’t mean that class is useless. If another developer is using your element, she might be misled if it derives directly from Grid—she could reasonably think that it is intended as a custom layout element. But if it derives from UserControl, that provides a clear indication of its nature.

An adorner is a special-purpose custom element whose purpose is to add visual features to a UI element. An adorner appears at the same position as the element it adorns, but it will be at top of the Z order—it appears above all nonadorner elements in the window. Adorners are typically used in interactive editing scenarios to display selection outlines or handles. Figure 18-2 shows a typical example from Microsoft Expression Blend.

Figure 18-2. Adorners in action

Figure 18-2 shows two rounded rectangles. The one with the white fill is on top of the gray one, partially obscuring it. The gray one underneath has been selected, causing various handles, shapes, and labels to light up. For example, there’s a rectangle showing the bounding box, with small, square resize handles at each corner, and there’s an outline version of the shape itself. Notice that the white rectangle has obscured none of these features. Even though the gray rectangle is beneath the white rectangle, all of the handles appear on top, making it easy to edit the shape even though it is mostly obscured. These handles and other features appear on top because they use WPF’s adorner system.

Adorners are able to appear on top because WPF creates a special AdornerLayer element at the top of the Z order. There is nothing magic about this—you could achieve the same effect without using the adorner infrastructure simply by creating a suitably placed panel to host your adorners. However, it would require a considerable amount of work to ensure that the elements on this panel appeared in the correct position. This is what makes the adorner system attractive—it ensures that the objects in the adorner layer are always in the same position as the elements they adorn, despite being in completely different parts of the UI tree.

The AdornerLayer can contain multiple elements, so you might expect it to be a panel. However, it derives directly from FrameworkElement, not Panel, for a couple of reasons. First, it can only contain elements that derive from Adorner, whereas panels can contain any UI elements. Second, AdornerLayer has no layout logic of its own—adorners are positioned on the adorner layer according to the location of the elements they adorn. This means that adorners do not participate in layout in the normal way.

No public classes are derived from the Adorner abstract base class, so you are obliged to derive your own. And, because the Adorner class does not provide a way to define the appearance through properties, you can’t simply use XAML. A common approach for writing adorners is to use visual layer programming, which we described in Chapter 13. Example 18-31 shows an example of this approach.

class BoxingAdorner : Adorner {
    public BoxingAdorner(UIElement adornedElement)
        : base(adornedElement) { }

    protected override void OnRender(DrawingContext drawingContext) {
        drawingContext.DrawRectangle(null, new Pen(Brushes.Blue, 2),
            new Rect(0, 0, 100, 40));
    }
}

This adorner will render a blue box 100 device-independent pixels wide and 40 high. Notice that the constructor takes as its parameter the element to be adorned. All adorners must do this because the Adorner base class has no default constructors—you must provide it with a reference to the element being adorned. Example 18-32 shows the XAML and code behind for a window that uses this adorner.

<Window ... >
  <Grid>
    <TextBlock x:Name="targetElement" Margin="40,40,0,0" Text="Test" />
  </Grid>
</Window>

// Code behind
partial class Window1 : Window {

    public Window1(  ) {
        InitializeComponent(  );

        this.Loaded += new RoutedEventHandler(Window1_Loaded);
    }

    void Window1_Loaded(object sender, RoutedEventArgs e) {
        AdornerLayer al = AdornerLayer.GetAdornerLayer(targetElement);
        BoxingAdorner myAdorner = new BoxingAdorner(targetElement);
        al.Add(myAdorner);
    }
}

The work is done in the Loaded event handler, because the adorner layer is not available until then. In the event handler, we ask WPF for the AdornerLayer to use for the target element, we create an instance of our adorner class, and then we add that to the adorner layer. Figure 18-3 shows the results: a box around the text block.

Figure 18-3. TextBlock with adorner

Note that the adorner is significantly larger than the content of the TextBlock. Adorners are often larger than the element they adorn. The resize box in Figure 18-2 is a typical example. You can draw your adorner outside the adorned element’s area by passing in suitable coordinates when drawing—modifying Example 18-31 to pass negative x and y values would move the top left of the adorner above and to the left of the text block. Alternatively, you can override the GetDesiredTransform method, returning the transform you would like to have applied to your adorner. (We discussed transforms in Chapter 13.) Either way, the adorner can fill the whole adorner layer if it wants.

Example 18-32 had to do its work in the Loaded event handler because the adorner layer wasn’t ready sooner. This raises the question: where does the adorner layer come from? The answer is the AdornerDecorator class.

<Window ... >
  <Grid>
    <Grid.ColumnDefinitions>
      <ColumnDefinition />
      <ColumnDefinition />
    </Grid.ColumnDefinitions>


    <AdornerDecorator Grid.Column="1">
      <TextBlock x:Name="targetElement" Margin="40,40,0,0" Text="Test" />
    </AdornerDecorator>
  </Grid>
</Window>

You should write a custom element only if the underlying behavior you require is not offered by any of the built-in types, and you cannot build it by composing existing elements. Even if you do write a custom type, it will not necessarily be a control. When you write a custom element of any kind, you will use the dependency property system to provide properties that support data binding and animation. You will use the routed event infrastructure to expose events. If your element defines a particular interactive behavior, it should be a control. If you want to write a “lookless” control that allows its visuals to be replaced just like the built-in controls, you must consider how your control and template will interact with one another. You will also most likely want to supply a default style with a template that provides a default set of visuals.