Application

Additional assembly information: Contents, Object Model Diagram

The Application namespace contains classes that enable you to integrate your customizations with ArcGIS Explorer. The Application namespace contains six abstract classes, from which each type of Add-In can be derived and "application" classes that enable you to provide application specific functionality. The Application namespace is the starting point for ArcGIS Explorer customization, from which you can access the mapping namespace.

See the following sections for more information about this namespace:

Abstract Add-In classes
Application classes

Abstract Add-In classes

An ArcGIS Explorer customization must inherit from one of the six following abstract classes that form the basis of each type of ArcGIS Explorer Add-In. The starting point for an ArcGIS Explorer customization is a project template, installed with the ArcGIS Explorer software development kit (SDK). When you select a project template appropriate for the type of Add-In you intend to develop, a class is automatically generated that inherits from the appropriate abstract class. There are six classes that represent each type of ArcGIS Explorer Add-In, the manner in which you work with each of these classes is discussed as follows.

Button

The Button abstract class is the base class for developing a button. When compiled, the button shows on the ArcGIS Explorer Ribbon. A button's OnClick method can be overridden, which allows you to control the code that executes when the button is clicked. See the following code example:

[C#]


            public class Button: ESRI.ArcGISExplorer.Application.Button
{
    public override void OnClick()
    {
        System.Windows.Forms.MessageBox.Show("You have just clicked a button");
    }
}

[VB.NET]


            Public Class Button
    Inherits ESRI.ArcGISExplorer.Application.Button
    Public Overrides Sub OnClick()
    System.Windows.Forms.MessageBox.Show("You have just clicked a button")
End Sub

End Class

When developing a button, you can also override the OnUpdate method, which is called frequently during the application's life span. This method can be used to check for specific conditions that determine the appropriate enabled state of your button. The button's enabled state can be set with an appropriate boolean value for the Enabled property.

CheckBox

The CheckBox abstract class is the base class for developing a check box. When compiled, the check box shows on the ArcGIS Explorer Ribbon. A check box's OnClick method can be overridden, which allows you to control the code that executes when clicked. See the following code example:

[C#]


            public class CheckBox: ESRI.ArcGISExplorer.Application.CheckBox
{
    public override void OnClick()
    {
        System.Windows.Forms.MessageBox.Show("You have just checked the box");
    }
}

[VB.NET]


            Public Class CheckBox
    Inherits ESRI.ArcGISExplorer.Application.CheckBox
    Public Overrides Sub OnClick()
    System.Windows.Forms.MessageBox.Show("You have just checked the box")
End Sub

End Class

ComboBox

The ComboBox abstract class is the base class for developing a combo box. When compiled, the combo box shows on the ArcGIS Explorer Ribbon. A combobox's OnSelectionChange method can be overridden, which allows you to control the code that executes when an item in the drop down list is selected. See the following code example:

[C#]


            public class ComboBox: ESRI.ArcGISExplorer.Application.ComboBox
{
    public override void OnSelectionChange(ComboItem item)
    {

        //Insert code here
    }
}

[VB.NET]


            Public Class ComboBox
    Inherits ESRI.ArcGISExplorer.Application.ComboBox
    Public Overrides Sub OnSelectionChange()
    'Insert code here
End Sub

End Class

DockWindow

The DockWindow abstract class is the base class for developing a dockable window. When compiled, a dockable window shows in the application and behaves like other built-in dockable windows, for example, the Find window. The DockWindow class exposes OnActivate and OnDeactive methods, both of which can be overridden, allowing you to control the behavior of your dockable window as it gains and loses focus as the user interacts with other parts of the application. See the following code example:

[C#]


            public partial class DockWindow: ESRI.ArcGISExplorer.Application.DockWindow
{
    public DockWindow()
    {
        InitializeComponent();
    }
    public override void OnActivate()
    {
        base.OnActivate();
        MessageBox.Show("Your Dockable Window has focus");
    }
    public override void OnDeactivate()
    {
        base.OnDeactivate();
        MessageBox.Show("Your Dockable Window has lost focus");
    }
}

[VB.NET]


            Public Partial Class DockWindow
Inherits ESRI.ArcGISExplorer.Application.DockWindow

Public Sub New()
    InitializeComponent()
End Sub

Public Overrides Sub OnActivate()
MyBase.OnActivate()
MessageBox.Show("Your Dockable Window has focus")
End Sub

Public Overrides Sub OnDeactivate()
MyBase.OnDeactivate()
MessageBox.Show("Your Dockable Window has lost focus")
End Sub

End Class

A caption and image can be specified for a DockWindow, which is used to show a button that appears on the ArcGIS Explorer Ribbon; this button is used to show and activate the DockWindow.

Gallery

The Gallery abstract class is the base class for developing a gallery. When compiled, a gallery appears on the Ribbon and shows a series of choices, one of which can be selected by clicking. The gallery Items property can be set to an instance of a GalleryItemCollection. The GalleryItemCollection determines the number of choices (Gallery Items) the user is given when interacting with the gallery hosted on the Ribbon. Items can be added to a GalleryItemCollection via the InsertItem method. Populate the gallery Items property inside the Gallery constructor. See the following code example:

[C#]


            public Gallery()
{
    // Create images to use in gallery.
    Image imgGreenFlag = Image.FromFile(@
                                        "C:\Program Files\Explorer\Styles\SymbolImages\Flag\GreenFlag.png");
    Image imgRedFlag = Image.FromFile(@
                                      "C:\Program Files\Explorer\Styles\SymbolImages\Flag\RedFlag.png");
    // Create gallery items.
    GalleryItem giGreen = new GalleryItem("Green", imgGreenFlag);
    GalleryItem giRed = new GalleryItem("Red", imgRedFlag);
    // Add items to collection.
    this.Items.Add(giGreen);
    this.Items.Add(giRed);
}

[VB.NET]


            Public Sub New()
    ' Create images to use in gallery.
    Dim imgGreenFlag As Image = Image.FromFile("C:\Program Files\Explorer\Styles\SymbolImages\Flag\GreenFlag.png")
    Dim imgRedFlag As Image = Image.FromFile("C:\Program Files\Explorer\Styles\SymbolImages\Flag\RedFlag.png")
    ' Create gallery items.
    Dim giGreen As GalleryItem = New GalleryItem("Green", imgGreenFlag)
    Dim giRed As GalleryItem = New GalleryItem("Red", imgRedFlag)
    ' Add items to collection.
    Me.Items.Add(giGreen)
    Me.Items.Add(giRed)
End Sub

The Gallery OnClick method can be overridden, which allows the code to execute when a gallery item is selected. The selected gallery item is passed as a parameter to the OnClick method. See the following code example:

[C#]


            public override void OnClick(GalleryItem item)
{
    // Code when an item is clicked.
    switch (item.Caption)
    {
        case "Red":
            System.Windows.Forms.MessageBox.Show("You picked Red");
            break;
        case "Green":
            System.Windows.Forms.MessageBox.Show("You picked Green");
            break;
        default:
            break;
    }
}

[VB.NET]


            Public Overrides Sub OnClick(ByVal Item As GalleryItem)
' Code when an item is clicked.
Select Case Item.Caption
    Case "Red"
        System.Windows.Forms.MessageBox.Show("You picked Red")
    Case "Green"
        System.Windows.Forms.MessageBox.Show("You picked Green")
    Case Else
End Select
End Sub

Extension

The Extension abstract class is the base class for developing an extension. An extension does not rely on user interaction, but instead, can be used to run code in response to the application starting up or shutting down. The OnStartUp and OnShutdown methods can be overridden, allowing you to execute code when the application starts up and shuts down, respectively. Initializing a Timer on application startup allows you to continue to run code in the timer's interval event handler for the duration of the application's life span. See the following code example:

[C#]


            // Create a timer that fires every 10 seconds.
System.Timers.Timer _t = new System.Timers.Timer(10000);

public override void OnStartup()
{
    // Start the timer.
    _t.Start();
    _t.Elapsed += new System.Timers.ElapsedEventHandler(_t_Elapsed);
}

void _t_Elapsed(object sender, System.Timers.ElapsedEventArgs e)
{
    // Do something every 10 seconds.
    System.Windows.Forms.MessageBox.Show(
        "This message box is displayed every 10 seconds");
}

public override void OnShutdown()
{
    // Stop the timer.
    _t.Stop();
}

[VB.NET]


            ' Create a timer that fires every 10 seconds.
Private _t As System.Timers.Timer = New System.Timers.Timer(10000)
Public Overrides Sub OnStartup()
' Start the timer.
_t.Start()
AddHandler _t.Elapsed, AddressOf _t_Elapsed
End Sub


Private Sub _t_Elapsed(ByVal sender As Object, ByVal e As System.Timers.ElapsedEventArgs)
    ' Do something every 10 seconds.
    System.Windows.Forms.MessageBox.Show("This message box is displayed every 10 seconds")
End Sub

Public Overrides Sub OnShutdown()
' Stop the timer.
_t.Stop()
End Sub

Application classes

In addition to the six abstract classes previously discussed, the application namespace includes other classes that enable you to develop customizations with application specific functionality. The Application class is the entry point to working with other parts of the ArcGIS Explorer object model. The Application class ActiveMapDisplay property returns an instance of the MapDisplay class, which resides in the Mapping namespace and represents the active map display. See the following code example:

[C#]


            ESRI.ArcGISExplorer.Mapping.MapDisplay amd =
    ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay;

[VB.NET]


            Dim amd As ESRI.ArcGISExplorer.Mapping.MapDisplay = ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay

The Application.SelectedItems property returns a SelectedItemsCollection object which contains any MapItems which are currently selected in the contents window. Conversely the SelectedItemsCollection.Select method can be used to programmatically select items in the contents window. See the following code example:

[C#]


            //Get the currently selected MapItems
SelectedItemsCollection selectedItems = Application.SelectedItems;
//Print the names of the currently selected items
foreach (MapItem item in selectedItems)
{
    System.Diagnostics.Debug.Print(item.Name);
}

//Find a layer in the contents window
ServiceLayer demogServiceLayer = Application.ActiveMapDisplay.Map.FindByName(
    "demographics map service")as ServiceLayer;
//check that the layer has been found
if (demogServiceLayer != null)
{
    //Clear the existing selection
    if (selectedItems.Count > 0)
        selectedItems.Clear();
    //Select the demographics map service layer
    selectedItems.Select(demogServiceLayer);
}

[VB.NET]


            'Get the currently selected MapItems
Dim selectedItems As SelectedItemsCollection = Application.SelectedItems
'Print the names of the currently selected items
For Each Item As MapItem In selectedItems
    System.Diagnostics.Debug.Print(Item.Name)
Next
'Find a layer in the contents window
Dim demogServiceLayer As ServiceLayer = TryCast(Application.ActiveMapDisplay.Map.FindByName("demographics map service"), ServiceLayer)
'check that the layer has been found
If demogServiceLayer IsNot Nothing Then
    'Clear the existing selection
    If (selectedItems.Count > 0) Then
        selectedItems.Clear()
    End If
    'Select the demographics map service layer
    selectedItems.Select(demogServiceLayer)
End If

The Application class also exposes useful events you will want to consider using when developing customizations for ArcGIS Explorer. For example, the MapItemChanged event can be used to detect when a MapItem has changed. You might want to use this event to listen for when the symbol associated with a note is changed or a layer is added to the application.

The following code example shows how the MapItemChanged event can be used as part of an Extension Add-In to show the map layer count; it shows a message box with the number of layers on the map, when layers are added, then removed from the map:

[C#]


            class Extension: ESRI.ArcGISExplorer.Application.Extension
{
    public override void OnStartup()
    {
        Application.MapItemChanged += new EventHandler < MapItemEventArgs > 
            (Application_MapItemChanged);
    }
    public void Application_MapItemChanged(object sender, MapItemEventArgs e)
    {
        MapDisplay md = Application.ActiveMapDisplay;
        int LayerCount = md.Map.GetMapItems < Layer > ().Count;
        switch (e.Status)
        {
            case MapItemChangeStatus.Added:
                System.Windows.Forms.MessageBox.Show("There are now " +
                    LayerCount.ToString() + " layers");
                break;
            case MapItemChangeStatus.Removed:
                System.Windows.Forms.MessageBox.Show("There are now " +
                    LayerCount.ToString() + " layers");
                break;
            default:
                break;
        }
    }
    public override void OnShutdown(){}
}

[VB.NET]


            Class Extension
    Inherits ESRI.ArcGISExplorer.Application.Extension
    Public Overrides Sub OnStartup()
    AddHandler Application.MapItemChanged, AddressOf Application_MapItemChanged
End Sub


Public Sub Application_MapItemChanged(ByVal sender As Object, ByVal e As MapItemEventArgs)
    Dim md As MapDisplay = Application.ActiveMapDisplay
    Dim LayerCount As Integer = md.Map.GetMapItems(Of Layer)().Count
    Select Case e.Status
        Case MapItemChangeStatus.Added
            System.Windows.Forms.MessageBox.Show("There are now " & LayerCount.ToString() & " layers")
        Case MapItemChangeStatus.Removed
            System.Windows.Forms.MessageBox.Show("There are now " & LayerCount.ToString() & " layers")
        Case Else
    End Select
End Sub

Public Overrides Sub OnShutdown()
End Sub

End Class

The class also contains a number of useful application management methods and properties:

The ColorScheme property and the ColorSchemeChanged event allow you to manage the applications color scheme.
The IsUsingApplicationConfiguration and ApplicationConfigurationPath properties provide information on the currently running application configuration.
There are several methods to manage map documents within the application, namely the LoadDocument, SaveDocument and NewDocument methods.
The GetBasemaps method returns a collection of all the basemaps currently available to the user.

The ProgressHelper class allows you to show a progress dialog box while you wait for an event to occur. The progress dialog box that shows when the Show method is called, is similar to the progress dialog boxes native to the application. Several update methods on the ProgressHelper class allow you to develop a rich user experience. The following code uses the ProgressHelper class to display a dialog and uses the UpdateMessage method to update the message displayed within it so that the user is kept informed about the number of features that have been processed.

[C#]


            //Open a geodatabase feature class
Table roadsTable = Table.OpenShapefile(@"C:\Data\Roads.shp");
//The using statement means that the ProgressHelper object will be disposed even if an exception is thrown
using(ProgressHelper pgh = new ProgressHelper("A progress dialog", 
      "Exporting road vertices", "Please Wait..."))
{
    //show the progress window
    pgh.Show();
    //iterate over all the rows
    foreach (Row road in roadsTable.GetRows())
    {
        //Update the message shown in the ProgressHelper as each road is exported
        pgh.UpdateMessage(string.Format("Exporting road with ID = {0}",
                          road.ObjectID.ToString()));
        //Get the geoemtry of each road
        Polyline roadLine = road.Geometry as Polyline;
        //Iterate over all the vertices making up the road
        for (int i = 0; i < roadLine.PointCount(); i++)
        {
            ESRI.ArcGISExplorer.Geometry.Point vertex = roadLine.GetPoint(i);
            //Do something with the vertices like export to text file....
        }
    }
    pgh.Close();
}

[VB.NET]


            'Open a geodatabase feature class
Dim roadsTable As Table = Table.OpenShapefile("C:\Data\Roads.shp")
'The using statement means that the ProgressHelper object will be disposed even if an exception is thrown
Using pgh As ProgressHelper = New ProgressHelper("A progress dialog", "Exporting road vertices", "Please Wait...")
'show the progress window
pgh.Show()
'iterate over all the rows
For Each road As Row In roadsTable.GetRows()
    'Update the message shown in the ProgressHelper as each road is exported
    pgh.UpdateMessage(String.Format("Exporting road with ID = {0}", road.ObjectID.ToString()))
    'Get the geoemtry of each road
    Dim roadLine As Polyline = DirectCast(road.Geometry, Polyline)
    'Iterate over all the vertices making up the road
    For i As Integer = 0 To roadLine.PointCount() - 1
        Dim vertex As ESRI.ArcGISExplorer.Geometry.Point = roadLine.GetPoint(i)
        'Do something with the vertices like export to text file....
    Next
Next
pgh.Close()
End Using

The Presentation and PresentationOptions classes allow you to create and control ArcGIS Explorer presentations programmatically.