How to: Show a View in a Shell 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.

Overview

By using regions, you can dynamically add views to a known location in the application without being tightly coupled to the containing view. This topic describes how to place a view in a region defined in the shell. The code shown could reside in the module initialization or 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 Region technical concept.

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

Prerequisites

To use Shell regions, you must have a solution in which the Shell class has a region manager registered. If you are working on a solution built using the Composite Application Library, the Shell likely contains a region manager instance. 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

To show a view in a region

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 your view. To do this, use the Regions property on the region manager instance, passing the region name as a parameter. The following code shows how to obtain a region named "MainRegion."

   IRegion mainRegion = this.regionManager.Regions["MainRegion"];
   

   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. To do this, invoke the Add method on the region instance, as shown in the following example code.

   View view = new View();
   mainRegion.Add(view);
   

   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, invoke the Activate method on the region, 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.

   mainRegion.Activate(view);
   

In some cases, you may want to add a view to a region and associate a name to it. By associating a name to a view, you can retrieve the view later from the region to perform actions with it, such as removing the view from the region, showing it, or editing it. Views that have an associated name are referred to as named views.

To add a named view to a region

• Invoke the method Add on the region, passing as parameters the view instance and the view name, as shown in the following code.

  mainRegion.Add(new View(), "View 1");
  

To retrieve the view instance by its name

• Invoke the GetView method on the region, passing the view's name as the parameter, as shown in the following code.

  View view = mainRegion.GetView("View 1") as View;
  

Note

If a view with the specified name is not found in the region, the default region implementation included in the Composite Application Library returns a null value. Therefore, you can use the GetView method to test if a view exists in a region.

Outcome

After adding and showing the view to the region, the view will appear on screen within the 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.