ArcGIS Explorer Blog : SDK

Tip for add-in developers: How to bundle files in an EAZ file

ArcGIS-Explorer-Team — Thu, 17 Sep 2009 20:45:00 GMT

Question: I am working on an add-in that will include several images that will be displayed as image overlays when the user views certain layers. What is the best way to include these images with my .eaz file so they can be accessed at runtime?

Answer: The correct way to bundle images, XML files, or whatever you need in your add-in is to include them in your Visual Studio add-in project using the Build Action of "Content." At runtime ArcGIS Explorer unzips the .eaz file into a temporary cache folder. In your code you can simply reference the images (or other files) as follows:

string executingAssemblyFqPath = Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().Location);

Image resource = Image.FromFile(Path.Combine(executingAssemblyFqPath,”aImage.jpg”));

ArcGIS Explorer code snippets

ArcGIS-Explorer-Team — Thu, 10 Sep 2009 23:15:00 GMT

Code snippets are a very useful feature of Visual Studio. We've added some key snippets to the ArcGIS Explorer SDK – the kinds of things that are simple but that you end up writing frequently, or that you might forget. Even some of the team members forget this stuff and have been pleased to be reminded of the snippets, so we know that you'll find these very useful.

For example, it’s easy to forget how to get hold of the application objects when coding from scratch, so we added a code snippet for every one of the static members that allow you to drill in to the ArcGIS Explorer object model. It’s also easy to forget that including the SuspendDrawing method call in a Using statement will ensure the drawing is resumed correctly; so we added a code snippet for this. These snippets are available in both Visual Basic and Visual C#, and you may have accessed them by right-clicking in the code window and choosing Insert Code Snippet, then Explorer:

BUT there is an even easier way to do this. To get a reference to the currently active View, just type “active” in the code window; you’ll see the intellisense in Visual Studio listing the activeMapDisplay keyboard shortcut to the ‘Get ActiveMapDisplay from Application’ snippet. Just hit Tab and the snippet is inserted.

If you forget what snippets are available, or want to look up a keyboard shortcut, you can use the Visual Studio Code Snippet Manager to browse the Explorer snippets including their keyboard shortcuts.

Here's a table of Visual Basic and Visual C# code snippets currently in the SDK for your convenience.

Code snippets are not just for VB and C# code though, they are also useful when you’re working declaratively with application conditions. These are pre-defined application states that can be used to determine when Buttons, DockWindows, and Galleries are enabled or disabled. For more information see the ArcGIS Explorer application conditions SDK Help topic.

You can set an application condition for a new customization when you create it using the New Item wizards which are part of the ArcGIS Explorer Tools for Visual Studio. For more information see the Visual Studio tools for ArcGIS Explorer SDK Help topic.

Open the Addins.xml file in your add-in project and for the XML element describing the add-in class. You will see an attribute named condition with a text string indicating the application condition you picked (note that if you chose the Always option in response to When should the Button be enabled, there will be no condition attribute at all in your XML).

Changing an application condition is easy to do by making use of the XML code snippets. Right click in the XML file and choose Insert Code Snippet, then Explorer. You will see a list of all the application conditions you can apply; choosing a condition snippet will add the correct text string to the XML file.

Note that the application conditions XML code snippets do not have intellisense and keyboard shortcuts - that’s something we’re working on for a future release. Let us know what you think of the snippets, and what kind of snippets you’d like to see in the future.

Getting started with the ArcGIS Explorer SDK: your first button

ArcGIS-Explorer-Team — Thu, 20 Aug 2009 18:50:00 GMT

If you want to customize ArcGIS Explorer there's a lot you can do without any programming. Application configurations provide an easy way to customize everything from the startup splash screen, functions which are available to users, and what tabs and controls are displayed. But invariably you may want to extend ArcGIS Explorer's capabilities, perhaps by tapping into an ArcGIS, or other, service. To do that you'll need to program with the SDK.

Here's a quick start to creating your first button control, which can be easily packaged, shared, and delivered as an add-in. (*.eaz file). Using templates provided with the SDK this is easy to do. Add-ins can also be part of an application configuration, and we'll cover more on that in future posts. But let's get started...

First, you need to download the ArcGIS Explorer SDK, a separate download from the core application. Begin by starting Visual Studio and create a new project.

Within the SDK you have both project and item templates. In this case we are going to make use of the project template for a new button add-in. From the new project window in Visual Studio browse the template options in the language of your choice (either VB.Net or C#) and look under ArcGIS Explorer for the project templates. Choose the ArcGIS Explorer button option form the list on the right, then fill in the information about what to call the project and what folder to place it in. Here we've called the new project "myFirstButton."

After specifying the project name (or taking the default) and setting the folder, click the OK button. There are various additional parameters you can set for your project and the button you’re about to create. The templates include a wizard to guide you through this process. On the first page of the wizard are all the settings for the project including a description and the name of the group to place the button in.

When you've completed your project settings (or accepted the default), click on the Next button to move on to the button settings. On the button settings page you are setting the parameters specific to the button we are going to create. Projects can have one then one Add-In within them, so you need to set parameters for each individual Add-In (button in this case). The button settings include the Caption that will be displayed in ArcGIS Explorer, the Image to use with it, and the Availability setting.

We are going to leave the Availability at the default setting of Always, but this is a key setting as it allows you to specify what conditions are necessary for your button to be active. For instance, you may write a button to perform a custom operation on a Feature Layer and therefore would only want the button to be available when a Feature Layer was selected in the Contents window.

After completing your button settings, select the Finish button and the project will be created. As well as creating the project with a new class for your button and the supporting images specified, the template will lay down the references to the required ArcGIS Explorer libraries and create an XML file containing all the parameters to be used by the application for group names, etc. (i.e., everything you specified in the project and button settings). The template will also set a debug path to the install directory for ArcGIS Explorer, so you can test your add-in right away.

Now that we have a project with our button class, all we need to do is write a little code. Double click on the AddGraphic.cs class in the Solution Explorer to open it. You’ll notice that all the API namespaces have been referenced by the button template, so we can begin coding. For a button, all we need to do is put some code in the OnClick event, so add the following:

Using C#:

MapDisplay mapDisp = Application.ActiveMapDisplay;
Graphic newGraphic = new Graphic(mapDisp.Target);
newGraphic.Symbol = Symbol.Marker.Sphere.Red;
newGraphic.Symbol.Size = 500;
mapDisp.Graphics.Add(newGraphic);

Using VB:

Dim mapDisp As MapDisplay = Application.ActiveMapDisplay
Dim newGraphic As Graphic = New Graphic(mapDisp.Target)
newGraphic.Symbol = Symbol.Marker.Sphere.Red
newGraphic.Symbol.Size = 500;
mapDisp.Graphics.Add(newGraphic)

The code will get the active map display, create a new graphic based on the target location for our view in 3D, add a symbol to that graphic (a red sphere), exaggerate the size of the symbol so we can see it at a global scale, then add the graphic to the collection for the display. There’s no need to explicitly call a refresh or anything else to repaint the display.

That's all there is to it, and we're ready to go. Just click on the Debug button in Visual Studio to start the application. As mentioned earlier, the path to the ArcGIS Explorer application (based on the install directory) is set by the project template, so it will start when you begin debugging.

When you create an add-in, by default they will appear on a new tab in ArcGIS Explorer called "Add-Ins." When you deploy add-ins to your end users you would normally want to place the customizations in a more appropriate place using application configurations (look for more info on this in a later blog).

Our add-in is on the Add-Ins tab in the SDK test group, based on what was specified in our project settings. When we click on it a red sphere is added to the middle (target) of our globe.

So that's your first button, stay tuned for more...

Custom Task Lifecycles

ArcGIS-Explorer-Team — Sun, 27 Jan 2008 17:06:00 GMT

(by Rob Dunfey, ArcGIS Explorer SDK Development Team)

Custom tasks have many different functions, but for all their differences they have much in common. For example, all custom tasks have a task lifecycle, and as a custom task developer it is important you are aware of what this means, and what it means to your task users.

As a task moves through its lifecycle, its status changes. At any given time a custom task has a status equal to one of six values, as listed in the esriE2TaskStatus enumeration illustrated below.

The current status of a task is displayed in the ArcGIS Explorer results panel when a custom task is pending execution, executing, or has been stopped. A custom task has default messages associated with each status value in the esriE2TaskStatus enumeration.

As a custom task developer you have full control over these messages, and are encouraged to set the message associated with a task status to give appropriate user feedback. For example, the default status message when a task is executing is 'MyCustomTaskName - executing' as illustrated below:

Using TaskContext.SetStatusMessage we can change the message associated with the Task executing status:

Having set the status message with the above code, the following is displayed when the task executes:

This message provides more feedback to the user, and is another facet of creating a well-implemented task.

For a comprehensive introduction to the lifecycle of a custom task, view the ArcGIS Explorer TaskContext Lifecycle Diagram which can be found at the ESRI Developer Network (EDN) site as well as in the Explorer SDK Help when you install it.

This is just one of several design patterns you can adopt when developing custom tasks to give your task a familiar look and feel. More tips and tricks can be found in the new ArcGIS Explorer Custom Task Style Guide.

Explorer and OpenGL in Action

ArcGIS-Explorer-Team — Thu, 23 Aug 2007 19:12:00 GMT

In an earlier post we talked about some of the new SDK features in the latest release (Build 410). In that post we mentioned the addition of OpenGL support and included a screenshot showing wind vectors implemented using OpenGL in Explorer. Here's a link to a YouTube movie showing that in action.

New Explorer SDK Enhancements (Build 410)

ArcGIS-Explorer-Team — Tue, 21 Aug 2007 01:32:00 GMT

(submitted by Rob Dunfey, ArcGIS Explorer SDK Development Team)

The latest release of ArcGIS Explorer includes a host of enhancements to the API, creating new opportunities for custom task developers. The custom task framework genuinely differentiates ArcGIS Explorer from other virtual globes, allowing users to plug in custom functionality directly into the main application.

The most notable of the API enhancements are changes to the View3D class. This class controls the main viewing window in ArcGIS Explorer (the window which displays the globe). New methods and events on the View3D class now allow developers to render OpenGL graphics on top of the view. In the example below, we've drawn wind vectors using OpenGL.

If you step back and think about this, it really is a quite powerful feature. What you choose to draw to the globe is now only limited by your imagination. A new developer sample in the SDK illustrates how you can use these new methods and events to draw grid lines and symbols on top of the globe, but perhaps you will choose to render a Second Life avatar? More usefully, you may want to display a unique watermark on top of the globe when viewing a particular layer, or incorporate the output from other specialist modelling software.

Other changes to the View3D class include a new property that enables your custom task to alter the vertical exaggeration of the globe surface, and a FlyPolyline method that will allow you to fly along a polyline. This is similar to the functionality available in the application when you right-click a result from the Get Driving Directions task.

We’ve also added methods and properties to the View and Layer classes to give developers greater control over the caching of layers. Now when you add layers to ArcGIS Explorer with a custom task, you can use the new CacheType layer property to determine how ArcGIS Explorer caches the layer, just like when you add layers via the ArcGIS Explorer user interface.

In addition, the new RemoveLayerCache method on the View class allows your custom task to delete a layer cache. Using these new members in combination as a developer, you have far greater control of layer caching, and can ensure layers representing dynamic data sources remain current.

New methods and properties have also been added to the API to help developers work with results. For example, the new AutoZoom property on the TaskContext will automatically zoom the observer to the location of any new results that are passed to the task context. Using this, and adding just a single line of code should make for more user friendly custom tasks.

The new SetZoomPerspective on the Result class lets the custom task developer define the location from which a particular result should be viewed when zoomed to in the application. Again, this should make for more user friendly custom tasks.

We’ve also fixed a bug with the LocalLayer class so that it can be used to represent kml files stored on a web server. Previously it didn’t recognize the http prefix which meant this wasn’t possible. Perhaps you want to build a custom task that searches the web for KML files and displays the KML files it finds in ArcGIS Explorer? With this fix, now you can.

And finally, a number of constructor overloads have been added to the API which should make for less lines of code.