Home > Patterns > The Sticky Component Framework

The Sticky Component Framework


What is a Sticky Component? A Sticky Component is a component that can be attached to any FrameworkElement or FrameworkContentElement in order to enhance its functionality, without the need to subclass the element or to write code behind for it. Because of this, Sticky Components can be used very effectively to encapsulate specialized behaviours in a reusable way, and to enhance either the View or the ViewModel of an MVVM application without changing its code.

Sticky Component Interaction Patterns

In order to enhance the functionality of an element, the Sticky Component needs to interact with the element. There are several possible ways to connect the two:

  • Through registering event handlers: The Sticky Component can subscribe to events of the element it is attached to, and trigger its own functionality through these events.
  • Through registering CommandBindings: The Sticky Component can add its own CommandBindings to the element’s CommandBindings collection, thus enabling the element to handle the specified command.
  • Through registering InputBindings: the Sticky Component can enable an element to invoke commands by adding InputBindings to its InputBindings collection.
  • Through data binding: the Sticky Component can bind its own properties to the properties of the element. These bindings could in principle have the element as target or as source. But since many properties in the WPF framework are readonly, it is less error prone to always make the Sticky Component the binding target by convention.
  • Through binding to the element’s DataContext: a special class of Sticky Component, the Sticky ViewModel, doesn’t enhance the View, but the ViewModel, by binding to its properties and adding functionality that isn’t present in the ViewModel without the need to change it.

Some of these patterns require references between the Sticky ViewModel and the element it is attached to (its “base”). References are dangerous. They may cause memory leaks and unintended behaviour, e.g. if events are handled even if the view that established the event subscription is already out of scope. Therefore, the core of the Sticky Component Framework is concerned with managing the lifetime of a Sticky Component and its interaction patterns so that all these references are cleaned up when appropriate.

Sticky Component Lifetime

The life cycle of a Sticky Component looks like follows:

  • It is defined and configured in the Resources of the application, a window, or an individual element.
  • It is referenced in an attached property on the base element it is attached to. This is the time when the Sticky Component is actually instantiated.
  • It attaches itself to the base. This can happen either immediately or delayed, depending on whether the base must be in initialized or loaded state before the component can attach to it.

The end of the component’s relationship to the base could come in two ways:

  • Either the attached property which connects the component to the base is reset,
  • or the base itself is unloaded.

In both cases, all references between the Sticky Component and its base should be removed, leaving either object ready for garbage collection. If the component still exists after it has been detached from its base (e.g. because it is kept as a shared instance in a ResourceDictionary), it could be attached again to a different base, or even the same, if that still is available.

This lifetime pattern is expressed in the following interface definition:

Public Enum AttachMode As Integer
    Immediate = 0
    OnInitialized = 1
    OnLoaded = 2
End Enum

Public Interface IStickyComponent

    Sub OnAttach(ByVal base As Object, ByVal e As EventArgs)

    Sub OnDetach(ByVal base As Object, ByVal e As EventArgs)

    ReadOnly Property Mode() As AttachMode

End Interface

OnAttach will be called whenever the Sticky Component will be attached to a base, OnDetach will be called when it is detached. Both methods have EventHandler signatures, so that they can be invoked by the Initialized, Loaded or Unloaded events, respectively. The Mode property defines when the component should attach itself to the element. If possible, the component should attach itself immediately. However, if it needs to modify existing bindings, it will have to do that during the Initialized event, and if it needs to access properties that are data bound, like e.g. the DataContext of the base, it might have to wait until the Loaded event. Since these requirements depend on what the component does, it would be expected that a class that implements IStickyComponent would return a constant value here.

The StickyComponentManager

The StickyComponentManager is a static class that encapsulates the different ways to establish and remove interaction connections between a Sticky Component and its base. It offers overloaded Attach and Detach procedures in pairs with corresponding parameters. So, one would attach an event to a base using the Attach(base,event,handler) overload, and remove it again using the Detach(base, event,handler) overload. There are overloads for all cases discussed here; some of these overloads offer additional services; e.g. there are overloads for attaching event handlers which automatically remove the event handler after it has fired once (using the One Shot Event pattern), or if another specified event occurs before the event that the handler is supposed to handle.

In your Sticky Component, you would set up the connection to the base by calling the appropriate Attach methods of the StickyComponentManager in your OnAttach implementation, and remove the connection by calling the corresponding Detach methods in the OnDetach implementation.

The most important overloads of these methods are the ones that attach / detach Sticky Components. There is a special implementation of a DependencyPropertyChangedHandler that you can use with your attached properties that attach Sticky Components which calls these overloads:

Public Shared Sub OnStickyComponentChanged(ByVal d As DependencyObject, ByVal e As DependencyPropertyChangedEventArgs)
    Dim c As IStickyComponent
    If e.OldValue IsNot e.NewValue Then
        c = TryCast(e.OldValue, IStickyComponent)
        If c IsNot Nothing Then
            StickyComponentManager.Detach(d, c)
        End If
        c = TryCast(e.NewValue, IStickyComponent)
        If c IsNot Nothing Then
            StickyComponentManager.Attach(d, c)
        End If
    End If
End Sub

This will ensure that the lifetime of the sticky component is managed according to the life cycle described above.

In addition to the Attach and Detach methods, the StickyComponentManager contains several utility methods which hide the difference between FrameworkElement and FrameworkContentElement when attaching Sticky Components. So, elements derived from both of these classes could be the base for Sticky Components; on other elements, the Attach / Detach methods would simply do nothing.

Using Sticky Components

In XAML, you would normally declare and configure a Sticky Component in a Resources section, like this:

    <ex:TestStickyPatterns x:Key="UseEvents"
        Name="UseEvents" UseCommand="False"/>
</Page.Resources>

This would define a Sticky Component of class TestStickyPatterns and configure it by setting its Name and UseCommand properties.

You would then use it on a base element like this:

    <Button x:Name="TestEventPatternsButton"
          ex:TestStickyPatterns.Component="{StaticResource UseEvents}">
    Test Event Patterns</Button>

 

If you need the Sticky Component more than once on your page, consider setting the x:Shared attribute to false on its declaration. Thus you make sure that each time the component is used, you start with a fresh instance. Otherwise it could happen that the component is attached to multiple elements on your page at the same time, with unwelcome results.

Implementing Sticky Components

The TestStickyPatterns.Component attached property would be defined like this:

Public Shared ReadOnly ComponentProperty As DependencyProperty = _
    DependencyProperty.RegisterAttached("Component", _
    GetType(IStickyComponent), GetType(StickyTestComponent), _
    New PropertyMetadata(AddressOf StickyComponentManager.OnStickyComponentChanged))
Public Shared Function GetComponent(ByVal d As DependencyObject) As IStickyComponent
    Return d.GetValue(ComponentProperty)
End Function
Public Shared Sub SetComponent(ByVal d As DependencyObject, _
                               ByVal value As IStickyComponent)
    d.SetValue(ComponentProperty, value)
End Sub

Notice that the property metadata refers to the shared (static in C#) method StickyComponentManager.OnStickyComponentChanged in order to enable lifecycle management for the component.

Its OnAttach and OnDetach implementations look as follows:

Public Sub OnAttach(ByVal sender As Object, ByVal e As EventArgs) Implements IStickyComponent.OnAttach
    MyBase.OnAttach(sender, e)
    If _UseCommand Then
        StickyComponentManager.Attach(sender, MyCommand, AddressOf OnExecuted, Nothing)
        StickyComponentManager.Attach(sender, New KeyGesture(Key.Space, ModifierKeys.Control), MyCommand)
    Else
        StickyComponentManager.Attach(sender, ButtonBase.ClickEvent, AddressOf OnClick)
        StickyComponentManager.Attach(sender, ButtonBase.ClickEvent, AddressOf OnClickOneShot, True)
        StickyComponentManager.Attach(sender, ButtonBase.ClickEvent, AddressOf OnClickCancel, FocusManager.LostFocusEvent)
    End If
End Sub

Public Sub OnDetach(ByVal sender As Object, ByVal e As EventArgs) Implements IStickyComponent.OnDetach
    MyBase.OnDetach(sender, e)
    If _UseCommand Then
        StickyComponentManager.Detach(sender, New KeyGesture(Key.Space, ModifierKeys.Control))
        StickyComponentManager.Detach(sender, MyCommand)
    Else
        StickyComponentManager.Detach(sender, ButtonBase.ClickEvent, AddressOf OnClick)
        StickyComponentManager.Detach(sender, ButtonBase.ClickEvent, AddressOf OnClickOneShot)
        StickyComponentManager.Detach(sender, ButtonBase.ClickEvent, AddressOf OnClickCancel)
    End If
End Sub

 

Grouping Sticky Components

Since the idea in using Sticky Components is that their behaviour is very narrow and specialized, so that they are suitable for many different contexts, there is a need to be able to group Sticky Components and attach a whole group at once to the same base element. The Sticky Component Framework contains a generic collection to help with that: StickyComponentCollection(Of T as IStickyComponent). This collection attaches and detaches its items at the right times, provides change notification, and if you implement the INamedStickyComponent interface on the collection’s items, you even can refer to the components inside the collection using string indexers in XAML. Here is an example of the use of this collection:

<Page.Resources>
    <ex:StickyTestComponentSet x:Key="test2">
        <ex:StickyTestComponent Name="Page Immediate"/>
        <ex:StickyTestComponent Name="Page OnInitialized" AttachMode="OnInitialized"/>
        <ex:StickyTestComponent Name="Page OnLoaded" AttachMode="OnLoaded"/>
    </ex:StickyTestComponentSet>

 

StickyTestComponentSet is defined by inheriting a concrete type instance of the generic collection:

Public Class StickyTestComponentSet
    Inherits StickyComponentCollection(Of StickyTestComponent)
    Implements IStickyComponent, IList

 

Notice that for some reason the Visual Studio XAML designer (Cider) will only let you add direct content to the class if you specify “Implements IList” again, even though this interface is already implemented by the base class.

The StickyComponent Example

On the Downloads page you will find the source code for the framework and an example project called StickyComponentExample. This project mainly focuses on demonstrating the different interaction techniques between StickyComponents, their usage patterns, and their life cycle. In order to trace the life cycle, a lot of debug output is written to Debug.Print, so you should run the project in the Visual Studio Debugger and follow the output in the Immediate window.

Coming Soon…

There is one special case of a Sticky Component: the Sticky ViewModel. It deserves special attention, and even though the example is already in the example solution, I’d like to cover it in a separate post.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: