The framework incorporates a mechanism for triggering the activation of customizations based on user defined conditions. Unlike classic events or callbacks, the binding between condition and customizations is provided statically (declaratively) using DAML. This mechanism provides a simplified and declarative means for expressing when various GUI elements such as ribbon tabs, dock panes, buttons and tools should and shouldn’t be visible or enabled within the application. Using conditions also ensures that code modules and their associated resources are loaded and consumed only when they are relevant, a feature that is critical to scalability, efficiency, and fast application startup. The use of Conditions and State also simplifies coding by greatly reducing the need for complex and largely redundant event wiring associated with more traditional models.

States are named Boolean values which symbolize a particular aspect of the application’s overall status; for example, whether a particular view is active, or whether a particular type of feature is selected. States are declared using ordinary character strings; to avoid name collisions, they are typically named using the Plugin naming convention

Conditions are DAML expressions composed of one or more states, such as (A or B), where both A and B are states. Conditions themselves are named so that they can be referenced by those DAML elements which permit the use of conditions; for instance, a custom ribbon tab can be caused to show up on the ribbon only when a map view is active, and hide when any other type of view is active

DECLARING STATES AND CONDITIONS:

States and Conditions are declared using DAML elements as follows:

A simple condition (consisting of only one state):

            <conditions>
              <insertCondition id="aSimpleCondition"> 
               <state id="someState"/> 
              </insertCondition>
            </conditions>
            

A more complex condition:

            <conditions>
              <insertCondition id="aMoreComplexCondition"> 
                <and>
                  <state id="someState"/> 
                  <or/>
                    <state id="someOtherState"/>
                    <state id="yetAnotherState"/>
                  </or/>
                <and>
              </insertCondition>
            </conditions>
            

The above condition evaluates to (someState AND (someOtherState OR yetAnotherState)).

Conditions are defined at the root level in the DAML file—outside the scope of any extension block—since they are simply expressions (without an active aspect), and do not need to be associated with any controlling extension; conditions should be considered global in scope. The Boolean operators And, Or, and Not can be combined recursively to form complex conditional expressions if necessary, but conditions themselves cannot be used (recursively) in place of states within another Condition block.

Conditions are associated with a particular Plugin using the Condition attribute:

The specified custom dockpane appears only when active view is a map view.

The specified custom dockpane appears only when active view is a map view.

             <dockpane id="myDockPane" condition="esri_mapping_MapView"/>
            

STATE ACTIVATION

The framework defines a fixed set of activation behaviors which can be triggered using conditions. States are maintained in state tables, where state is said to be activated if the state exists in the table, and deactivated otherwise. While the application runs, the state tables within the framework are periodically monitored for changes. When a change is detected, the tables are matched against any conditions currently defined, and the appropriate activation (or deactivation) is triggered in response.

IMPLICIT AND EXPLICIT STATE

States can be either implicit or explicit. Implicit states are those which are intrinsically defined and controlled by the framework itself; these states are activated and deactivated automatically.

The framework currently defines the following implicit states:

Explicit states are set manually using developer supplied code; the meanings of these states are usually defined by the developer and used to identify more specific types of context such as custom modes; i.e.: "I’m editing", or a custom status: "a raster layer is selected in the TOC."

Explicit state changes are made by calling Activate or Deactivate on the State object.

             // Called when a raster layer is selected.
             State.Activate("esri_core_RasterLayerSelected");  
            
             // Called when editing mode is exited.
             State.Deactivate("esri_core_EditingModeExited");  
             

LOCALITY OF STATE

State tables are maintained at two levels within the framework: Application level state, and Pane level state. Applications built with the framework are primarily pane centric applications, and as such the framework is designed to support several independent activities, each potentially associated with different pane instances. Each pane may have state which is relevant only to that instance and should not be altered if the user simply switches to another pane; e.g. the current selection or current tool. For this reason, each pane instance maintains its own state table accessible via the Pane class:

             // Deactivate a state associated with a particular view.
             Pane.State.Deactivate("esri_mapping_FeatureSelected");
             

Application level state contains global state relevant to the application as a whole such as which view is currently active, or whether a particular extension is currently loaded. Application level state is accessed via the Application class:

             // Activate a state associated the application as a whole.
             Application.State.Activate("esri_mapping_DigitizerEnabled");  
             

During condition matching, the framework will always consider the state associated with application level, as well as the state associated with the currently active pane; thus a condition will be satisfied if its expression evaluates positively on the combination of these two tables. It is important to activate or deactivate state at the appropriate level (depending on the type of state).

System.Object
   ArcGIS.Desktop.Framework.State

Target Platforms: Windows 11, Windows 10

Reference

State Members
ArcGIS.Desktop.Framework Namespace