How to use ArcGIS Explorer application conditions

Summary This topic describes the use of pre-defined application states (conditions) that can be used to determine when Buttons, DockWindows, and Galleries are enabled or disabled, avoiding redundant logic for checking application state across multiple add-ins.

About conditions in ArcGIS Explorer

The ArcGIS Explorer application defines a number of possible application states or "conditions." For example, when the user selects a Note on the Contents window, the condition, E3_NoteSelectedCondition, is true.

These conditions are used by the application Ribbon to determine which tabs or groups to display or hide, and which controls to enable or disable on the Ribbon. Using conditions allow you to avoid writing logic for enabling or disabling add-ins based on application state. Each tab, group, Button, DockWindow, and Gallery has condition attributes to indicate the conditions undere which it applies. If the condition is met, the tab or group is shown or the Button, DockWindow, or Gallery is enabled. Application conditions control the visibility of Tabs, but the enabled state of Buttons, DockWindows, and Galleries.

For example, if a Button has an E3_NoteSelectedCondition attribute set, it is enabled on the Ribbon when the E3_NoteSelectedCondition condition is true in the application.

If application conditions are insufficient for your needs, you might prefer to set the enabled state from within the OnUpdate method of your Button or Gallery; however, use conditions where possible, as this is more efficient to help maintain a more responsive application.

Using conditions in add-ins

Each Button, DockWindow, or Gallery control on the Ribbon can have a condition attribute set in the Addins.xml file. If present, this attribute is used by the Ribbon to determine when the control is enabled or disabled. This attribute is optional; if not present, the control is always enabled.

Conditions are not applicable to Extensions. There is no application programming interface (API) for querying the current conditions in the application.

Do the following steps to add a condition to your customization:

Add the "condition" attribute to the Extensible Markup Language (XML) button, dockWindow, or gallery element in the Addins.xml file. Use the installed code snippets to do this by right-clicking in the XML file and choosing Insert Snippet, then ArcGIS Explorer. See the following screen shots:
Set the value of this attribute to one of the conditions listed in the following table. You can only have one condition attribute for each button, dockWindow, or gallery element.

The Addins.xml file is case-sensitive; therefore, be careful if you manually edit any values or attribute names.

For example, in the following code example, review the "condition" attribute. The button is only enabled when a Folder is selected in the application:

[XML]


        <ExplorerAddIns
  groupCaption="Acme Tools"
  description="Acme Corporation tools for Explorer"
  name="Acme Explorer Tools"
  publisher="Acme Corp.">
  <button
    assembly="AcmeTools.dll"
    caption="Site Analysis"
    className="AcmeTools.SiteAnalysis"
    id="siteAnalysisButton"
    largeImage="default32.png"
    smallImage="default16.png"
    condition="E3_FolderSelectedCondition"/>
</ExplorerAddIns>

You can right-click in the Addins.xml file, choose Insert Code Snippet, then choose Explorer, and insert a code snippet to set a condition for your customization, instead of typing the attribute and value manually.

The following table shows the attribute value of all conditions in the ArcGIS Explorer application:

Condition	Description
E3_NoteSelectedCondition	A single note is currently selected in the application; no other items are selected.
E3_FolderSelectedCondition	A folder is currently selected in the application.
E3_LinkSelectedCondition	A link is currently selected in the application.
E3_ViewSelectedCondition	A view is currently selected in the application.
E3_FeatureLayerSelectedCondition	A feature layer (for example, a layer based on a shapefile or geodatabase feature class) is currently selected in the application.
E3_ServiceLayerSelectedCondition	A service layer (for example a Globe layer, Web Map Service [WMS] layer, or GeoRSS feed) is currently selected in the application.
E3_KMLSelectedCondition	A Keyhole Markup Language (KML) layer is currently selected in the application.
E3_KMLNodeSelectedCondition	A KML node of a KML layer is currently selected in the application.
E3_ItemsSelectedCondition	More than one MapItem of different types are currently selected in the application.
E3_SingleItemSelectedCondition	A single MapItem is currently selected in the application.
E3_RasterLayerSelectedCondition	A raster layer is currently selected in the application.
E3_ArcGISLayerSelectedCondition	An ArcGIS layer is currently selected in the application.
E3_GeoRssLayerSelectedCondition	A GeoRSS layer is currently selected in the application.
E3_ImageOverlaySelectedCondition	An Image overlay is currently selected in the application.
E3_PresentationToolsAvailableCondition	The application currently has presentation tools available on the Ribbon.
E3_HasSlidesCondition	The application currently contains presentation slides.
E3_SingleSlideSelectedCondition	A single presentation slide is currently selected in the Slides dockable window.
E3_SlidesSelectedCondition	Multiple slides are currently selected in the Slides dockable window.