ArcGIS Pro 3.1 API Reference Guide
ArcGIS.Desktop.Framework Namespace / State Class
Members

In This Topic
    State Class
    In This Topic
    Syntax
    public sealed class State 
    Public NotInheritable Class State 
    Remarks

    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.

    Plugin Type Framework Provided Activation
    Ribbon Tab Tab is shown or hidden based on the associated condition. When the Tab first appears, other objects which appear on the tab may load if they are visible.
    DockPane DockPanes can initially be shown based on the associated condition. The DockPane object itself will not be loaded or created until the condition is initially met. DockPanes are not automatically hidden when their condition no longer matches.
    Controls (Buttons, Tools, Etc.) Control Plugins are enabled and disabled based on their associated condition. The Control Plugin object itself will not be loaded or created until the condition is initially met, and thereafter, OnUpdate will not be called unless the supplied context is currently satisfied. Note that the loadOnClick attribute is checked after the Condition, so loadOnClick controls will still appear disabled if their Condition hasn’t yet been satisfied..
    Property Page A property sheet contains a collection of property pages. The sheet will not show pages that specify a condition that is not met.

    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:

    Implicit State Details
    Active Pane The ID of the active Pane is designated as an implicit state and activated when the pane is active.
    Active Tab The ID of the active Tab is designated as an implicit state and activated when the tab is active.
    Active Tool The ID of the active Tool is designated as an implicit state and activated when the tool is active.
    Module Loaded When a module is loaded, its ID is designated as an implicit state and activated. When unloaded, its ID is deactivated.

    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).

    Inheritance Hierarchy

    System.Object
       ArcGIS.Desktop.Framework.State

    Requirements

    Target Platforms: Windows 11, Windows 10

    ArcGIS Pro version: 3.0 or higher.
    See Also