How to: Add a Region

  • Article

Overview

A region is a mechanism that allows developers to expose to the application Windows Presentation Foundation (WPF) 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.

By showing controls through regions, you can consistently display and hide the views, independently of the visual style in which they display. By doing this, the appearance and layout of your application can 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 Region Using View Injection UI Composition and How to: Show a View in a Scoped Region.

Note

For more information about regions, see the UI Composition technical concept.

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 markups for WPF and Silverlight:

    • For WPF views, add the following namespace.

      xmlns:cal="https://www.codeplex.com/CompositeWPF"

    • For Silverlight views, add the following namespace.

      xmlns:Regions="clr-namespace:Microsoft.Practices.Composite.Presentation.Regions;assembly=Microsoft.Practices.Composite.Presentation"

    After this step, the resulting XAML of a WPF view should look similar to the following example 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:

    • 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 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. For the attribute value, provide a name for the region. Developers will use this name to get a reference to the region. Make sure you are using the appropriate namespace for this attached property:

    • The following code shows a region named "MainRegion" associated to an ItemsControl control in WPF.

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

    • The following code shows how to associate a region named "MainRegion" to an ItemsControl control in Silverlight.

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

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

    Note

    You cannot use constants in XAML if you are developing a Silverlight view.

    <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 you add a region, you can get a reference to it by its name and then 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, seeHow to: Show a View in a Scoped Region.

More Information

For information related to regions, see the following topics:

For a complete list of How-to topics included with the Composite Application Guidance, see Development Activities.

Home page on MSDN | Community site