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, CheckBoxes, ComboBoxes, 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, CheckBox, ComboBox, DockWindow, and Gallery has condition attributes to indicate the conditions under which it applies. If the condition is met, the tab or group is shown or the Button, CheckBox, ComboBox, DockWindow, or Gallery is enabled. Application conditions control the visibility of Tabs, but the enabled state of Buttons, CheckBoxes, ComboBoxes, 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.

A number of new conditions were introduced at Explorer 1500, relating to single items being selected. These are indicated in the table of conditions below.

Using conditions in add-ins

Each Button, CheckBox, ComboBox, 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.

When creating a new add-in control, you can select a condition in the New Project or New Item wizards in Visual Studio.

Do the following to add a condition to an existing customization:

Add the "condition" attribute to the Extensible Markup Language (XML) button, check box, combo box, 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, check box, combo box, dockWindow, or gallery element.

The Addins.xml file is case-sensitive; therefore, be careful if you manually edit any values or attribute names. The add-in verification tasks integrated into Visual Studio will notify you of any errors.

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	One or more notes are currently selected in the application; no other items are selected.
E3_SingleNoteSelectedCondition	A single note is currently selected in the application. This condition is supported from version 1500.
E3_FolderSelectedCondition	One or more folders are currently selected in the application.
E3_SingleFolderSelectedCondition	A single folder is currently selected in the application. This condition is supported from version 1500.
E3_LinkSelectedCondition	One or more links are currently selected in the application.
E3_SingleLinkSelectedCondition	A single link is currently selected in the application. This condition is supported from version 1500.
E3_ViewSelectedCondition	One or more views are currently selected in the application.
E3_SingleViewSelectedCondition	A single view is currently selected in the application. This condition is supported from version 1500.
E3_FeatureLayerSelectedCondition	One or more feature layers (for example, a layer based on a shapefile or geodatabase feature class) are currently selected in the application.
E3_SingleFeatureLayerSelectedCondition	A single feature layer is currently selected in the application. This condition is supported from version 1500.
E3_ServiceLayerSelectedCondition	One or more service layers (for example a Globe layer, Web Map Service [WMS] layer, or GeoRSS feed) are currently selected in the application.
E3_SingleServiceLayerSelectedCondition	A single service layer is currently selected in the application. This condition is supported from version 1500.
E3_KMLSelectedCondition	One or more Keyhole Markup Language (KML) layers are currently selected in the application.
E3_SingleKMLSelectedCondition	A single KML layer is currently selected in the application. This condition is supported from version 1500.
E3_KMLNodeSelectedCondition	One or more KML nodes of a KML layer are currently selected in the application.
E3_SingleKMLNodeSelectedCondition	A single KML node of a KML layer is currently selected in the application. This condition is supported from version 1500.
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	One or more raster layers are currently selected in the application.
E3_SingleRasterLayerSelectedCondition	A single raster layer is currently selected in the application. This condition is supported from version 1500.
E3_ArcGISLayerSelectedCondition	One or more ArcGIS layers (layer file or layer package) are currently selected in the application.
E3_SingleArcGISLayerSelectedCondition	A single ArcGIS layer is currently selected in the application. This condition is supported from version 1500.
E3_GeoRssLayerSelectedCondition	One or more GeoRSS layers are currently selected in the application.
E3_SingleGeoRssLayerSelectedCondition	A single GeoRSS layer is currently selected in the application. This condition is supported from version 1500.
E3_ImageOverlaySelectedCondition	One or more image overlays are currently selected in the application.
E3_SingleImageOverlaySelectedCondition	A single image overlay is currently selected in the application. This condition is supported from version 1500.
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.