Interface IRegionManager

Namespace: Acuit.Pinpoint.Workstation.Windows

Assembly: Acuit.Pinpoint.Workstation.Abstractions.dll

A service the manages workstation user interface regions and navigation within regions.

public interface IRegionManager

Extension Methods: RegionManagerExtensions.NavigateToViewInRegion(IRegionManager, string, Type, IReadOnlyDictionary<string, object?>?)

RegionManagerExtensions.NavigateToViewInRegion(IRegionManager, string, Type, IServiceProvider, IReadOnlyDictionary<string, object?>?)

RegionManagerExtensions.NavigateToViewInRegion<TView>(IRegionManager, string, IReadOnlyDictionary<string, object?>?)

RegionManagerExtensions.NavigateToViewInRegion<TView>(IRegionManager, string, IServiceProvider, IReadOnlyDictionary<string, object?>?)

RegionManagerExtensions.RegisterViewWithRegion(IRegionManager, string, Type)

RegionManagerExtensions.RegisterViewWithRegion(IRegionManager, string, Type, IServiceProvider)

RegionManagerExtensions.RegisterViewWithRegion<TView>(IRegionManager, string)

RegionManagerExtensions.RegisterViewWithRegion<TView>(IRegionManager, string, IServiceProvider)

Remarks

This service allows loosely-coupled components to compose user interface elements via named regions.

Participants can register named regions via container controls:

A ContentControl (or any control derived from ContentControl) can host a single view.
An ItemsControl (or any control derived from ItemsControl) can host multiple views.

There can only be one region registered for a particular name (case-sensitive).

These named regions can be used in one of two ways:

Participants can register views to appear in particular named regions.
Participants can request that a view be navigated to in a particular named region.

Any particular region can be used in either of the above two ways, but not both at the same time.

Note that the order that regions and views are registered does not matter. If a view is registered before a region, it will be added to the region when the region is registered. Also note that views registered for a region that itself is never registered will never be created or displayed, and no error will occur. However, navigating to a view in a region requires that the region already be registered.

Views, whether registered for regions or navigated to, are created on demand via view factories. Registered or navigated-to views are created immediately if the region container has already been registered, or when the region container is registered later. Views can be any non-null object that can be hosted within a ContentControl or ItemsControl. Typically, these will be WPF controls, but they can also be objects like strings that WPF will automatically convert to text blocks.

Whenever a view is removed from a region, it will be disposed if it implements IDisposable. Views are removed from regions when any of the following occurs:

The region registration is removed.
The view registration is removed.
A view is displayed in a region being used for navigation, and a different view is navigated to in the region.

CompositeDisposableBuilder can be used to safely register multiple regions at once using a method like the following:

internal sealed partial class MyView : UserControl, IDisposable
{
    private readonly CompositeDisposable _regionsRegistration;

    public MyView(IRegionManager regionManager)
    {
        InitializeComponent();
        using CompositeDisposableBuilder compositeDisposableBuilder = new();
        _regionsRegistration = compositeDisposableBuilder
            .Add(regionManager.RegisterRegion("MySingleItemRegion", _myContentControl))
            .Add(regionManager.RegisterRegion("MyMultipleItemsRegion", _myItemsControl))
            .Build();
    }

    public void Dispose() => _regionsRegistration.Dispose();
}

Methods

IsAnyViewRegistered(string)

Gets whether any views are registered for the specified region.

bool IsAnyViewRegistered(string regionName)

Parameters

regionName string: The region name.

Returns

bool: true if any views have been registered for the specified region; otherwise, false.

Exceptions

ArgumentNullException: regionName is null.

IsRegionRegistered(string)

Gets whether a specified region is registered.

bool IsRegionRegistered(string regionName)

Parameters

regionName string: The region name.

Returns

bool: true if the region is registered; otherwise, false.

Exceptions

ArgumentNullException: regionName is null.

NavigateToViewInRegion(string, Func<IServiceProvider, object>, IReadOnlyDictionary<string, object?>?)

Navigates to a view within a region.

void NavigateToViewInRegion(string regionName, Func<IServiceProvider, object> viewFactory, IReadOnlyDictionary<string, object?>? navigationParameters = null)

Parameters

regionName string: The region name.
viewFactory Func<IServiceProvider, object>: A factory method used to create the view given the host service provider, augmented with a NavigationContext.
navigationParameters IReadOnlyDictionary<string, object>: Optional navigation parameters.

Remarks

When the view is created due to being navigate to, a NavigationContext will be provided to the view factory.

See the remarks for IRegionManager for details about view lifetimes and view disposal.

Exceptions

ArgumentNullException: regionName is null.
ArgumentNullException: viewFactory is null.
InvalidOperationException: A container for region name regionName has not been registered.
InvalidOperationException: The region cannot be used for navigation because one or more views are registered for it.
InvalidOperationException: The view factory returned null.

RegisterRegion(string, ContentControl)

Registers a region, specifying the container control that can contain a single view. If a view has already been registered for the region, it will be created and added to the container.

IDisposable RegisterRegion(string regionName, ContentControl container)

Parameters

regionName string: The region name.
container ContentControl: The container control for the region's view.

Returns

IDisposable: An IDisposable that can be used to remove the region registration.

Remarks

See the remarks for IRegionManager for an example of registering multiple regions at once.

Exceptions

ArgumentNullException: regionName is null.
ArgumentNullException: container is null.
InvalidOperationException: A container for the region named regionName has already been registered.
InvalidOperationException: The container allows only a single view, but multiple views have been registered for the region.
InvalidOperationException: The view factory for the view registered for this region returned null.

RegisterRegion(string, ItemsControl)

Registers a region, specifying the container control that can contain multiple views. If any views has already been registered for the region, they will be created and added to the container.

IDisposable RegisterRegion(string regionName, ItemsControl container)

Parameters

regionName string: The region name.
container ItemsControl: The container control for the region's views.

Returns

IDisposable: An IDisposable that can be used to remove the region registration.

Remarks

See the remarks for IRegionManager for an example of registering multiple regions at once.

Exceptions

ArgumentNullException: regionName is null.
ArgumentNullException: container is null.
InvalidOperationException: A container for region name regionName has already been registered.
InvalidOperationException: The view factory for a view registered for this region returned null.

RegisterViewWithRegion(string, Func<IServiceProvider, object>, string?)

Registers a view with a region.

IDisposable RegisterViewWithRegion(string regionName, Func<IServiceProvider, object> viewFactory, string? sortHint = null)

Parameters

regionName string: The region name.
viewFactory Func<IServiceProvider, object>: A factory method used to create the view given the host service provider.
sortHint string: An optional sort hint for the view in the region.

Returns

IDisposable: An IDisposable that can be used to remove the view registration.

Remarks

See the remarks for IRegionManager for details about view lifetimes and view disposal.

Exceptions

ArgumentNullException: regionName is null.
ArgumentNullException: viewFactory is null.
InvalidOperationException: Views cannot be registered for the region because it is being used for navigation.
InvalidOperationException: The container registered for the region allows only a single view, but multiple views have been registered for the region.
InvalidOperationException: The view factory returned null.

Events

RegionRegistered

Raised when a region is registered.

event EventHandler<RegionEventArgs>? RegionRegistered

Event Type

EventHandler<RegionEventArgs>

ViewRegistered

Raised when a view is registered to a region.

event EventHandler<RegionEventArgs>? ViewRegistered

Event Type

EventHandler<RegionEventArgs>

Table of Contents

Interface IRegionManager

Remarks

Methods

IsAnyViewRegistered(string)

Parameters

Returns

Exceptions

IsRegionRegistered(string)

Parameters

Returns

Exceptions

NavigateToViewInRegion(string, Func<IServiceProvider, object>, IReadOnlyDictionary<string, object?>?)

Parameters

Remarks

Exceptions

RegisterRegion(string, ContentControl)

Parameters

Returns

Remarks

Exceptions

RegisterRegion(string, ItemsControl)

Parameters

Returns

Remarks

Exceptions

RegisterViewWithRegion(string, Func<IServiceProvider, object>, string?)

Parameters

Returns

Remarks

Exceptions

Events

RegionRegistered

Event Type

ViewRegistered

Event Type