Region

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Conceptually, a region is a mechanism that developers can use to expose Windows Presentation Foundation (WPF) controls to the application as components that encapsulate a particular visual way of displaying and laying out views. Regions can be accessed by name and support adding or removing views. This decoupling allows the appearance and behavior (look and feel) of the application to evolve independently of the views that appear within the region (for more information about views, see the Shell and View technical concept).

Regions are intended to enable a compositional pattern and are commonly used in template layouts and multiple view layouts.

Template Layout

Regions are frequently used to define a layout template for a view. Components can locate and add content to regions in the template without exact knowledge of how and where the region is visually displayed. This allows the template to change without affecting the components that are adding content to the template. This is common in the shell of an application that defines a standard layout, such as a navigation region and a main content region, as illustrated in Figure 1.

Figure 1
A shell with regions

Multiple View Layout

Regions are frequently used where multiple views need to be displayed in a list or a tab-style display. In these cases, regions serve to collect views that may be logically related and displayed in a list or a tab control.

The Stock Trader Reference Implementation (Stock Trader RI) shows the use of both the template layout and the multiple-view layout. The template view layout can be seen in the shell for the application. Figure 2 illustrates the regions defined by the Stock Trader RI shell.

Figure 2
Stock Trader RI shell regions

The regions for the shell are defined in the Shell.xaml file and use the RegionName attached property from the Composite Application Library. The following code example from the Shell.xaml file shows how the RegionManager.RegionName attached property is used to define the regions for the Stock Trader RI.

<ItemsControl x:Name="MainToolbar" cal:RegionManager.RegionName="MainToolbarRegion" ...>
  <ItemsControl.ItemsPanel>
    <ItemsPanelTemplate>
      <WrapPanel />
    </ItemsPanelTemplate>
  </ItemsControl.ItemsPanel>
</ItemsControl>
<StackPanel Grid.Row="1" Grid.RowSpan="2" Grid.Column="3">
  <Controls:TearOffItemsControl x:Name="TearOffControl"
                                cal:RegionManager.RegionName="WatchRegion"
                                ... />
  <ItemsControl Margin="0,20,0,0" cal:RegionManager.RegionName="NewsRegion" />
</StackPanel>
<TabControl x:Name="PositionBuySellTab" ... cal:RegionManager.RegionName="MainRegion" />

A multiple layout view is demonstrated in the Stock Trader RI when buying or selling a stock. The Buy & Sell tab is a list-style region that shows multiple buy/sell views as part of its list, as shown in Figure 3.

Figure 3
ListBox Region

Working with Regions

Regions are enabled in the Composite Application Library through a region manager, regions, and region adapters.

Region Manager

The RegionManager is responsible for maintaining a collection of regions and creating new regions for controls. The RegionManager finds an adapter mapped to a WPF control and associates a new region to that control. Figure 4 illustrates the relationship between the region, control, and adapter set up by the RegionManager.

Figure 4
Region, control, adapter relationship

The RegionManager also supplies the attached property that can be used for simple region creation from XAML. To use the attached property, you will need to load the Composite Application Library namespace into the XAML and then use the RegionName attached property. The following example shows using the attached property for a window with a tab control.

<Window x:Class="MyApp.Shell"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:cal="https://www.codeplex.com/CompositeWPF">
…
<TabControl x:Name="TabRegion" cal:RegionManager.RegionName="MainRegion" />
…
</Window>

The RegionManager can register regions directly without using XAML. This is useful if you want to move the control around in the visual tree and do not want the region to be cleared when the attached property value is removed. The following code shows registering a new region with the RegionManager located in a container.

IRegionManager newRegionManager = Container.Resolve<IRegionManager>();
newRegionManager.AttachNewRegion(someControl, regionName);

IRegion

A region is a class that implements the IRegion interface. The region is the container that holds content to be displayed by the control. The following code shows the IRegion interface.

public interface IRegion
    {
        IViewsCollection Views { get; }
        IViewsCollection ActiveViews { get; }
        IRegionManager Add(object view);
        IRegionManager Add(object view, string viewName);
        IRegionManager Add(object view, string viewName, bool    
                           createRegionManagerScope);
        void Remove(object view);
        void Activate(object view);
        void Deactivate(object view);
        object GetView(string viewName);
        IRegionManager RegionManager { get; set; }    
}

To add a view to a region, get the region from the region manager, and call the Add method, as shown in the following code.

IRegion region = _regionManager.Regions["MainRegion"];

var ordersPresentationModel = _container.Resolve<IOrdersPresentationModel>();
var _ordersView = ordersPresentationModel.View;
region.Add(_ordersView, "OrdersView");
region.Activate(_ordersView);

Region Adapters

Composite Application Library provides three region adapters out of the box: ContentControlRegionAdapter, SelectorRegionAdapter, and ItemsControlRegionAdapter. These adapters are meant to adapt controls derived from ContentControl, Selector, and ItemsControl, respectively. Adapters can be replaced or new ones added for new controls, by adding to the RegionAdapterMappings for the RegionManager.

In the UnityBootstrapper, the RegionAdapterMappings is supplied to the RegionManager during application initialization, as shown in the following code.

protected virtual RegionAdapterMappings ConfigureRegionAdapterMappings()
{
      RegionAdapterMappings regionAdapterMappings =
             Container.TryResolve<RegionAdapterMappings>();
       if (regionAdapterMappings != null)
       {
           regionAdapterMappings.RegisterMapping(typeof(Selector), 
                                                 new SelectorRegionAdapter());
           regionAdapterMappings.RegisterMapping(typeof(ItemsControl), 
                                                 new ItemsControlRegionAdapter());
           regionAdapterMappings.RegisterMapping(typeof(ContentControl), 
                                                 new ContentControlRegionAdapter());
       }

       return regionAdapterMappings;
}

Scoped Regions

Views defining regions with attached properties automatically inherit their parent's RegionManager. Usually, this is the global RegionManager that is registered in the shell window. If the application creates more than one instance of that view, each instance would attempt to register its region with the parent RegionManager. RegionManager allows only uniquely named regions, so the second registration produces an error. Instead, use scoped regions so that each view gets its own RegionManager and its regions will be registered with that RegionManager instead of with the parent RegionManager, as shown in Figure 5.

Figure 5
Parent and Scoped RegionManagers

To create a local RegionManager for a view, specify that a new RegionManager should be created when adding your view to a region, as illustrated in the following code example.

IRegion detailsRegion = this.regionManager.Regions["DetailsRegion"];
View view = new View();
bool createRegionManagerScope = true;
IRegionManager detailsRegionManager = detailsRegion.Add(view, null, 
                                                        createRegionManagerScope);

The Add method will return the new RegionManager that the view can retain for further access to the local scope.

More Information

For more information about regions, see the following topics:

• UI Composition QuickStart
• Region How-to topics:
  • How to: Add a Region
  • How to: Create a Custom Region Adapter
  • How to: Provide a Custom Logger
  • How to: Show a View in a Scoped Region
  • How to: Show a View in a Shell Region
• Composition patterns:
  • Patterns in the Composite Application Library (see the section titled “Composite and Composite View”)

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.