How to: Show a View in a Scoped Region

Article
08/04/2010

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 in this topic could reside in a controller class that coordinates the activity of multiple views.

Note

This topic assumes you are familiar with regions. For more information about regions, see the UI Composition technical concept.

If you want to show a view in a shell region, see How to: Show a View in a Region Using View Discovery UI Composition and How to: Show a View in a Region Using View Injection UI Composition.

Note

The information in this topic is valid if you are using the view injection approach for UI composition. For more information about when to use view injection versus view discovery, see the UI Composition technical concept.

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.

For information about how to add a region, see How to: Add a Region.

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

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;
    }

    ...

}
```
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.
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 in 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.
If you want to make sure the view is displayed in the UI, 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

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”];
```
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 you add a view that defines a new region scope, a new region scope is created and all the view's regions are registered with a new region manager attached to the view.

After you add and show a view in the scoped region, the view appears on screen in the region.

More Information

For information related to regions and views, 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