How to: Show a View in a Scoped Region

Overview

By using regions, you can dynamically add views to a known location in the application without being tightly coupled to the containing view.

Scoped regions are regions that belong to a particular region scope. A region scope is delimited by a parent view and embraces all the child views of the parent view.

This topic describes how to create a region scope and how to add a view to a scoped region. The code shown in this topic could reside in a controller class that coordinates the activity of multiple views.

If you want to show a view in a shell region, see How to: Show a View in a Shell Region.

Prerequisites

This topic requires you to have a solution in which the Shell window has a region manager attached. If you are working on a solution based on the Composite Application Library, the Shell window already contains a region manager instance attached. For information about how to create a solution with the Composite Application Library, see How to: Create a Solution Using the Composite Application Library.

Steps

A region scope is created when you add a view to a region and you specify that the view defines a new region scope. The following procedure describes how to add a view to a region that defines a new region scope.

To add a view to a region that defines a new region scope

1. Obtain a reference to the Shell region manager instance. A region manager is a class that implements the IRegionManager interface. You can obtain the reference by using dependency injection, as shown in the following code (in this example, the code is written in a module initializer class; it is assumed that the class is instantiated using a dependency injection container).

   public class Module : IModule
   {
       private readonly IRegionManager regionManager;
   
       public Module(IRegionManager regionManager)
       {
           this.regionManager = regionManager;
       }
   
       ...
   
   }
   

2. Obtain the region where you want to place the view that will define a new region scope. To do this, use the Regions property on the Shell region manager instance, passing the region name as a parameter. The following code shows how to obtain a region named "DetailsRegion."

   IRegion detailsRegion = this.regionManager.Regions["DetailsRegion"];
   

   Note

   The region's name must match the name defined in the RegionName attribute of the region. For more information about configuring regions, see How to: Add a Region.

3. Create an instance of the view you want to show, and then add it to the region, and specify that that the view defines a new region scope. To do this, invoke the Add method on the region instance passing true for the createRegionManagerScope parameter, as shown in the following code.

   View view = new View();
   IRegionManager detailsRegionManager = detailsRegion.Add(view, null, true);
   

   Note that by setting the createRegionManagerScope parameter to true, the added view will define a new region scope; therefore, all the regions registered by the view will not be registered with the Shell window's region manager; instead, they will be registered with a new region manager associated to the view. In the preceding code, a reference to this new region manager is returned by the Add method and stored in the detailsRegionManager variable. If you want to add views to regions within the new scope, you must obtain the region references from the new region manager instance.

   Note

   The Add method adds the view to the region, but it does not ensure that the view is displayed. For example, if the underlying user interface (UI) element of the region is a TabControl control, the view will be added to the control as a new tab, but the tab will not necessarily receive focus.

4. If you want to ensure the view is displayed in the user interface, call the IRegion.Activate method passing the view object as the parameter. For example, if the underlying UI element of the region is a TabControl control, the tab that hosts the view will receive focus.

   The following code shows how the view added in the previous step is activated.

   detailsRegion.Activate(view);
   

The following procedure describes how to add a view to a scoped region.

To add a view to a scoped region

1. Obtain a reference to the scoped region. To do this, use the Regions property on the region manager instance that corresponds to the parent view that defines the region scope. The following code shows how to obtain a region named "TabRegion" from the region manager instance obtained in step 3 of the previous procedure. This region manager instance is attached to the view that defines the region scope and not to the Shell window.

   IRegion region = detailsRegionManager.Regions[“TabRegion”];
   

2. Create an instance of the view you want to show, and then add it to the region by invoking the Add method on the region, as shown in the following code.

   region.Add(new View2());
   

Outcome

After adding a view that defines a new region scope, a new region scope will be created and all the view's regions will be registered with a new region manager attached to the view.

After adding and showing a view in the scoped region, the view will appear on screen within the region.