How to: Create a Custom Region Adapter

Overview

To expose a UI control as a region, a region adapter is used. Region adapters are responsible for creating a region and associating it to the control. By doing this, developers can manage the UI control's contents in a consistent way through the IRegion interface. Each region adapter adapts a particular type of UI control. The Composite Application Library provides three region adapters out-of-the-box:

• ContentControlRegionAdapter. This adapter adapts controls of type System.Windows.Controls.ContentControl and derived classes.
• SelectorRegionAdapter. This adapter adapts controls derived from the class System.Windows.Controls.Primitives.Selector, such as the System.Windows.Controls.TabControl control.
• ItemsControlRegionAdapter. This adapter adapts controls of type System.Windows.Controls.ItemsControl and derived classes.

There are some scenarios in which none of the preceding region adapters suit the developer needs. In those cases, custom region adapters can be created to adapt controls not supported by the Composite Application Library out-of-the-box.

The purpose of this topic is to explain how to create custom region adapters.

Prerequisites

This topic assumes that you already have a solution based on the Composite Application Library. For information about how to do this, see How to: Create a Solution Using the Composite Application Library.

Steps

Region adapters implement the Microsoft.Practices.Composite.Regions.IRegionAdapter interface. This interface defines a single method named **Initialize **that takes the object to adapt and returns a new region associated with the adapted control. The interface definition is shown in the following code.

public interface IRegionAdapter
{
    IRegion Initialize(object regionTarget);
}

To create a region adapter, you implement the IRegionAdapter interface. The following procedure describes how to implement the IRegionAdapter interface.

To create a custom region adapter

1. Add a new class to your solution.

2. Add the following using statements at the top of the class file. You will use them to refer to region elements in the Composite Application Library.

   using Microsoft.Practices.Composite.Wpf.Regions;
   using Microsoft.Practices.Composite.Regions;
   

3. Change your class signature to inherit from the RegionAdapterBase<T> base class, where T is the type of the UI control to adapt. This base class implements the IRegionAdapter interface and provides common behavior and template methods you must override in your derived class. The following code example shows the definition of the ContentControlRegionAdapter class. Note that the type parameter of the base class is ContentControl. This means the region adapts controls of this type.

   public class ContentControlRegionAdapter : RegionAdapterBase<ContentControl>
   {
   }
   

4. Implement the CreateRegion template method. This is an abstract method defined in the **RegionAdapterBase **class; it should return a region instance (an object that implements the IRegion interface) to be associated with the adapted control. The Composite Application Library provides the following region implementations out-of-the-box:

   • Region. This region allows multiple active views. This is the region used for controls derived from the Selector class.
   • SingleActiveRegion. This region allows a maximum of one active view at a time. This is the region used for ContentControl controls.
   • AllActiveRegion. This region keeps all the views in it as active. Deactivation of views is not allowed. This is the region used for ItemsControl controls.

   The following code shows the CreateRegion method implementation included in the ContentControlRegionAdapter class. Because **ContentControl **controls can contain a single piece of content at a time, a SingleActiveRegion region is utilized.

   protected override IRegion CreateRegion()
   {
       return new SingleActiveRegion();
   }
   

5. Override the abstract Adapt method. This template method has to adapt the control to the region created in the previous step. The Adapt method takes two parameters: the region with which the adapted control has to be associated and the control to adapt. The method's signature is shown in the following code.

   protected abstract void Adapt(IRegion region, T regionTarget);
   

   An example implementation of the Adapt method taken from the ContentControlRegionAdapter region adapter is shown in the following code.

   protected override void Adapt(IRegion region, ContentControl regionTarget)
   {
       if (regionTarget.Content != null || (BindingOperations.GetBinding(regionTarget, ContentControl.ContentProperty) != null))
           throw new InvalidOperationException(Resources.ContentControlHasContentException);
   
       region.ActiveViews.CollectionChanged += delegate
       {
           regionTarget.Content = region.ActiveViews.FirstOrDefault();
       };
   }
   

   Note that in the preceding code, the content of the adapted control is set to the first active view of the region whenever the collection of active views of the region changes.

6. Optionally, override the AttachBehaviors method. This method is used to attach special logic to customize the region behavior. If you do not override the AttachBehaviors method, a **CollectionActiveAwareBehavior **behavior is used by default. This behavior manages the active state of each view.

Region adapter mappings are used by the region manager service to associate the correct region adapters for XAML-defined regions. The following procedure describes how to create a region adapter mapping to map the custom region adapter created in the previous procedure with the UI control type the region adapter adapts.

To register the custom region adapter mapping

1. In your application's bootstrapper class file, add the following using statement at the top of the file. You will use it to refer to region elements in the Composite Application Library.

   using Microsoft.Practices.Composite.Wpf.Regions;
   

2. Override the ConfigureRegionAdapterMappings method to add your own custom region adapter mappings. To do this, perform the following steps:

   1. Invoke the base implementation of the ConfigureRegionAdapterMappings method to obtain the region adapter mappings registered by default by the UnityBootstrapper class. Region mappings are represented by an instance of the RegionAdapterMappings class.
   2. Register your custom mapping by invoking the RegisterMapping method on the region mappings instance. This method accepts the following parameters: the type of the control to adapt and an instance of the corresponding region adapter.
   3. Return the region mappings.

   The following code example shows how to add a mapping for a control of type ControlToAdapt and a region adapter named CustomRegionAdapter.

   protected override RegionAdapterMappings ConfigureRegionAdapterMappings()
   {
       RegionAdapterMappings mappings = base.ConfigureRegionAdapterMappings();
       mappings.RegisterMapping(typeof(ControlToAdapt), new CustomRegionAdapter());
   return mappings;
   }
   

Outcome

You will have a new custom region adapter created and a mapping registered.