Define the Scope of Controllers and Actions

This topic describes how to set conditions for activating Controllers and their Actions.

Specify the Scope of Controllers

If you have implemented a Controller that executes code in the Controller.Activated event handler or in the OnActivated and OnViewControlsCreated methods, you might have to define the conditions when this code is executed. For instance, you may need to define that a Controller customizing a grid editor should be active for List Views only. To do this, change the Controller.Active property's value directly or using one of Controller's properties listed later in this topic.

The Controller.Active property also affects the visibility of all Actions declared in this Controller (if a Controller is inactive, all its Actions are also inactive). To hide a single Action, you can use the ActionBase class's properties (see Change the Scope of Actions).

The following members help you specify the required conditions for Controller activation:

Member Description
Controller.Active Provides access to a collection of reason/value pairs used to activate or deactivate a Controller or determine its active state. The Controller is active when all items in this collection have the true value. You can add an item with a value representing a conditional expression, so the Controller is deactivated when this expression returns false.
ViewController.TargetObjectType Specifies the type of objects a View should represent to activate a View Controller.
ViewController.TargetViewId Specifies the ID of the View for which a View Controller is intended.
ViewController.TargetViewType Specifies the type of the View for which a View Controller is intended.
ViewController.TargetViewNesting Specifies whether the View for which a View Controller is intended must be root, nested or any.
WindowController.TargetWindowType Specifies the kind of the Window for which a Window Controller is intended.

You can inherit your Controller from ViewController<ViewType> or ObjectViewController<ViewType, ObjectType> and use the generic parameters to control for what views and types a View Controller should be activated. The example below demonstrates how to activate a Controller only for the Person class’s Detail View.

public class ViewController1 : ObjectViewController<DetailView, Person> {
    protected override void OnActivated() {
        base.OnActivated();
        Person person = this.ViewCurrentObject;
        DetailView detailView = this.View;
        // ....
    }
}

Note that the ObjectViewController`2.ViewCurrentObject and ObjectViewController`2.View properties types are changed based on types passed as generic parameters. This may be useful when you want to avoid casting the View Controller's View to ListView or DetailView. Note that the Visual Studio Designer does not work for Controllers inherited from generic types.

Change the Scope of Actions

When implementing an Action, you may want it to be displayed in a particular form. For instance, a CancelAppointment Action should be displayed for Views representing Appointment object(s) only. There are two approaches to deactivating an Action: deactivating its Controller and deactivating the Action itself.

Deactivate an Action's Controller

In most cases, you can turn off (deactivate) a Controller in which an Action is declared to hide this Action. If you deactivate a Controller, all its Actions will be invisible. Refer to the Specify the Scope of Controllers section to learn how to do this.

Deactivate an Action Itself

It is also possible to define the target Views and Windows for each Action individually. To do this, use the following properties:

Member Description
ActionBase.Active Provides access to a collection of key/value pairs used to determine or change the Action's active state. The resulting state determines the Action's visibility.
ActionBase.Enabled Provides access to a collection of key/value pairs used to determine an Action's enabled/disabled state. A Disabled Action is visible in the UI, but it is grayed out and cannot be executed.
ActionBase.TargetObjectsCriteria Specifies a criteria for enabling an Action.
ActionBase.TargetObjectsCriteriaMode Specifies whether all the currently selected objects must meet the TargetObjectsCriteria criteria to enable an Action.
ActionBase.TargetObjectType Specifies the type of the object(s) that the current View should represent to activate an Action.
ActionBase.TargetViewId Specifies the ID of the View for which an Action is intended.
ActionBase.TargetViewNesting Specifies whether the View for which an Action is intended must be root, nested or any.
ActionBase.TargetViewType Specifies the type of the View for which an Action is intended.
ActionBase.SelectionDependencyType Specifies a context for enabling an Action.

These properties control whether an Action is visible in certain Views and Windows. Refer to the ActionBase.Active topic to learn other ways to control visibility state (for example, hide an Action depending on a business object's property value).

See Also