Creating a custom Gallery

Summary
This walkthrough topic shows how to create a custom Gallery for ArcGIS Explorer.

Click here to get the sample associated with this walkthrough.

In this topic

Creating a project in Visual Studio

This topic shows how to create a gallery customization for ArcGIS Explorer. The easiest way to create a Gallery is to use the templates provided with this software development kit (SDK).
Do the following steps to create a custom Gallery:
  1. Start Visual Studio.
While this topic refers to and shows screen shots from Visual Studio 2008, running on Windows Vista, you can also follow the steps in Visual Studio 2010, Visual Basic or Visual C# Express, and Windows XP or Windows 7.
  1. Click File, click New, and click New Project. The New Project dialog box appears.
To complete this scenario, use C# or VB .NET. The code for both is shown; however, this topic only shows the C# dialog boxes in the screen shots, since the dialog boxes and views you interact with in VB .NET are very similar.
  1. On the New Project dialog box click the Visual C# or Visual Basic Projects node under the Project types pane, click the ArcGIS node, then click the Explorer node.
  2. Click the ArcGIS Explorer Gallery template under the Templates pane.
  3. Name the project GalleryWalkthrough, then click Browse to locate where you want to save the project. See the following screen shot:

  4. Click OK on the New Project dialog box to create the project. The New ArcGIS Explorer Gallery Project dialog box appears where you can set additional properties for your gallery.

Setting additional Gallery properties

  1. On the New ArcGIS Explorer Gallery Project (Enter Project Settings) dialog box, the Name property is automatically added. In the Description, Group Caption (displays on the Add-Ins tab), and Publisher text boxes, type an appropriate name. See the following screen shot:


  2. Click Next on the preceding dialog box. The second page (Enter Gallery Settings) of the New ArcGIS Explorer Gallery Project dialog box appears. See the following screen shot:

     
  3. Type a caption, for example, Gallery Walkthrough in the Caption text box. Type a ToolTip in the ToolTip text box, for example, Click to see items in the Gallery.
  4. Click Next. The New ArcGIS Explorer Gallery Project (Enter Gallery Item Settings) dialog box appears. Use this dialog box to set the Gallery Dimensions and Gallery Style options. See the following screen shot:


  5. Click Finish.

Adding the Add Graphic to Map functionality

Do the following steps to add the Add Graphic to Map functionality:
  1. Directly under the public class Gallery, insert the following code example:
[C#] 
string _imgPath = Environment.GetEnvironmentVariable("ArcGIS_E3SDK") + 
    "\\..\\Styles\\SymbolImages\\Points of Interest\\Information.png";
[VB.NET] 
Dim _strImage As String = Environment.GetEnvironmentVariable("ArcGIS_E3SDK") + "\\..\\Styles\\SymbolImages\\Points of Interest\\Information.png";
  1. For C#, locate the Gallery() method in the Gallery.cs class and for VB .NET, locate the New() method.
  2. Insert the following code example:
[C#] 
Image btnImage = Image.FromFile(_imgPath);
GalleryItem myGalleryItem = new GalleryItem("MyGalleryItem", btnImage, 
    "Click on the map to add graphic");
this.Items.Add(myGalleryItem);
[VB.NET] 
Dim btnImage As Image = Image.FromFile(strImage)
Dim myGalleryItem As GalleryItem = New GalleryItem("MyGalleryItem", btnImage, "Click on the map to add graphic")
Me.Items.Add(myGalleryItem)
  1. Locate the OnClick() method in the Gallery.cs class.
  2. Insert the following code example:
[C#] 
MapDisplay md = Application.ActiveMapDisplay;
//Track the Point on the map of the mouse click.
ESRI.ArcGISExplorer.Geometry.Point trackPoint = md.TrackPoint();
//Turn the Point in to a Graphic.
Graphic pointGraphic = new Graphic(trackPoint);
//Set the Graphic's symbol to the same as the Gallery Image (access the Symbol through Marker).
pointGraphic.Symbol = Symbol.Marker.PointsOfInterest.Information;
//Add the Graphic to the Map Display. 
md.Graphics.Add(pointGraphic);
[VB.NET] 
Dim md As MapDisplay = Application.ActiveMapDisplay
'Track the Point on the map of the mouse click.
Dim trackPoint As ESRI.ArcGISExplorer.Geometry.Point = md.TrackPoint()
'Turn the Point in to a Graphic.
Dim pointGraphic As Graphic = New Graphic(trackPoint)
'Set the Graphic's symbol to the same as the Gallery Image (access the Symbol through Marker).
pointGraphic.Symbol = Symbol.Marker.PointsOfInterest.Information
'Add the graphic to the map.
md.Graphics.Add(pointGraphic)
  • The complete Gallery class resembles the following code example:
[C#] 
using System;
using System.Drawing;
using ESRI.ArcGISExplorer;
using ESRI.ArcGISExplorer.Application;
using ESRI.ArcGISExplorer.Mapping;
using ESRI.ArcGISExplorer.Geometry;
using ESRI.ArcGISExplorer.Data;
using ESRI.ArcGISExplorer.Threading;
using System.IO;
namespace GalleryWalkthroughCS
{
    public class Gallery: ESRI.ArcGISExplorer.Application.Gallery
    {
        //Use the ArcGIS_E3SDK environment variable, which points to the install 
        //location of the ArcGIS Explorer developer kit, that is, \Program Files\Explorer\DeveloperKit.
        string _imgPath = Environment.GetEnvironmentVariable("ArcGIS_E3SDK") + 
            "\\..\\Styles\\SymbolImages\\Points of Interest\\Information.png";

        public Gallery()
        {
            //Set the Gallery button Image and properties.
            Image btnImage = Image.FromFile(_imgPath);
            Gallery.GalleryItem myGalleryItem = new Gallery.GalleryItem(
                "MyGalleryItem", btnImage, "Click on the map to add graphic");
            this.Items.Add(myGalleryItem);
        }
        public override void OnClick(GalleryItem item)
        {
            MapDisplay md = Application.ActiveMapDisplay;
            //Track the Point on the map of the mouse click.
            ESRI.ArcGISExplorer.Geometry.Point trackPoint = md.TrackPoint();
            //Turn the Point in to a Graphic.
            Graphic pointGraphic = new Graphic(trackPoint);
            //Set the Graphic's symbol to the same as the Gallery Image (access the Symbol through Marker).
            pointGraphic.Symbol = Symbol.Marker.PointsOfInterest.Information;
            //Add the Graphic to the Map Display. 
            md.Graphics.Add(pointGraphic);
        }
    }
}
[VB.NET] 
Imports System
Imports System.Drawing
Imports ESRI.ArcGISExplorer
Imports ESRI.ArcGISExplorer.Application
Imports ESRI.ArcGISExplorer.Mapping
Imports ESRI.ArcGISExplorer.Data
Imports ESRI.ArcGISExplorer.Threading

Public Class Gallery
    Inherits ESRI.ArcGISExplorer.Application.Gallery
    
    'Use the ArcGIS_E3SDK environment variable, which points to the install
    'location of the ArcGIS Explorer developer kit, that is, \Program Files\Explorer\DeveloperKit.
    Dim _strImage As String = Environment.GetEnvironmentVariable("ArcGIS_E3SDK") + "\\..\\Styles\\SymbolImages\\Points of Interest\\Information.png"
    
    Public Sub New()
        Dim btnImage As Image = Image.FromFile(_strImage)
        Dim myGalleryItem As Gallery.GalleryItem = New Gallery.GalleryItem("MyGalleryItem", btnImage, "Click on the map to add graphic")
        Me.Items.Add(myGalleryItem)
    End Sub
    
    Public Overrides Sub OnClick(ByVal Item As GalleryItem)
    Dim md As MapDisplay = Application.ActiveMapDisplay
    'Track the Point on the map of the mouse click.
    Dim trackPoint As ESRI.ArcGISExplorer.Geometry.Point = md.TrackPoint()
    'Turn the Point in to a Graphic.
    Dim pointGraphic As Graphic = New Graphic(trackPoint)
    'Set the Graphic's symbol to the same as the Gallery Image (access the Symbol through Marker).
    pointGraphic.Symbol = Symbol.Marker.PointsOfInterest.Information
    'Add the graphic to the map.
    md.Graphics.Add(pointGraphic)
End Sub

End Class

Compiling the project

Do the following steps to build your project:
  1. Save your project.
  2. Click the Build menu and click Build Solution.
  3. If your project built correctly, a report states the build succeeded in the Output window at the bottom of the Visual Studio .NET integrated development environment (IDE).
You can also check the results of the build operation by reviewing the subdirectories of your project. By default, you will build a debug version of your project. The dynamic-link library (DLL) that results from the build operation will be stored in the Bin\Debug subdirectory of your project. This directory also contains debug information (.pdb) and a type library (.tlb) file, produced by the Assembly Registration tool.
 
The obj subdirectory of the project directory contains temporary files used by the compiler and Visual Studio.
  1. If you successfully followed this walkthrough, your build will succeed. Close Visual Studio now that your gallery has been created. If your build operation did not succeed, click View and click Task List to view the errors, correct the errors as indicated, then close Visual Studio when you have a successful build.
If you double-click the task, the line of code causing the error is automatically selected.
On a successful build, the necessary files are automatically placed in the following locations:
  • For Windows Vista and Windows 7—C:\Users\<username>\AppData\Roaming\ESRI\ArcGIS Explorer\Addins.
  • For Windows XP—C:\Documents and Settings\<username>\Application Data\ESRI\ArcGIS Explorer\AddIns.

Using the add-in in ArcGIS Explorer

Do the following steps to use the gallery in ArcGIS Explorer:
  1. Start ArcGIS Explorer and zoom to a location, such as a city or neighborhood.
  2. Click the Add-Ins tab to view your gallery.
  3. Click the gallery, then click the gallery item to add a graphic to the map.

Debugging the add-in

Running the add-in in debug mode allows you to step through the code when it is executed. This is helpful when you encounter bugs in custom add-ins. If you followed the steps in this topic, you should not have to debug the add-in you have created in this walkthrough. However, for more information about debugging add-ins, see How to debug add-ins in Visual Studio.


See Also:

Sample: Gallery Walkthrough
How to debug add-ins in Visual Studio