How to: Add a Region

Overview

A region is a mechanism that allows developers to expose to the application Windows Presentation Foundation controls as components that encapsulate a particular visual way of displaying views. Regions can be accessed in a decoupled way by their name, and they support dynamically adding or removing views at run time.

Showing controls through regions allows you to consistently display and hide the views, independently of the visual style in which they display. This allows the appearance and behavior (look and feel) and layout of your application to evolve independently of the views hosted within it.

This topic describes how to add a region to a view or the Shell window through XAML. For information about how to access a region through code, see How to: Show a View in a Shell Region and How to: Show a View in a Scoped Region.

Prerequisites

This topic assumes that the Shell class has a region manager instance registered. If you are working on a solution created with the Composite Application Library, the Shell already contains a region manager instance. For information about how to create a solution, see How to: Create a Solution Using the Composite Application Library.

Steps

The following procedure describes how to add a region to a view or the Shell window.

To add a region to a view or the Shell window

1. Open the XAML view of your view or the Shell window.

2. Add the Composite Application Library XML namespace to the root element of the XAML file, as shown in the following highlighted markup.

   <Window x:Class="StockTraderRI.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">
   

3. Add the control you want to use as a region. 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.

4. Add an attribute named cal:RegionManager.RegionName to the control. This attribute is an attached property that indicates that a region has to be created and associated with the control when the view is being built. As the attribute value, provide a name for the region. Developers will use this name to get a reference to the region. The following code shows a region named "MainRegion" associated to an ItemsControl control.

   <ItemsControl cal:RegionManager.RegionName="MainRegion" />
   

   A recommended practice consists of using constants for region names, as shown in the following markup extracted from the UI Composition QuickStart.

   <ItemsControl cal:RegionManager.RegionName="{x:Static local:RegionNames.TabRegion}">
   

   Note

   The region will be registered with the region manager that corresponds to the scope of the view. For more information about scoped regions, see How to: Show a View in a Scoped Region.

Outcome

After adding a region, developers will be able to get a reference to it by its name and dynamically add views to it.

Next Steps

After you add a region, a typical task to perform next is to add views to it. For details about how to do this, see How to: Show a View in a Scoped Region.