How to Load DotSpatial Extensions Into My Toolbar

Introduction

DotSpatial is an open-source project that contains controls which can be used to manipulate and display geographic information. As DotSpatial is extensible, developers may find they want to load extensions create by others. This article describes the requirements for loading extensions that interact with the user interface.

Downloading DotSpatial and Creating a Project

This article is based on the DotSpatial 1.0 Release located on the downloads tab at http://dotspatial.codeplex.com

If you are not familiar with creating a simple DotSpatial-based application, please consider the introductory article and basic extension loading. For practical purposes, we assume you are coming to this article after having completed the previous ones.

Extension Interfaces

In order to provide extension developers (those writing a class that inherits from Extension or IExtension) with a simpler experience, we guarantee that they will have access to a Docking Manager, Header Control, and Status Control. This means they can create docking panels, ribbon buttons or menu items, and progress messages.

We don’t want these developers to worry about checking first to see if a header control or progress bar is available, so we categorically require that the application developer implement IDockManager, IHeaderControl, and IStatusControl. If you’re feeling like implementing these is going to be too much work, you might also ask “should I create an extension or an application?” You don’t need to implement these interfaces to support ITool or IDataProvider based extensions.

We’ve provided a few implementations which are available in the feed, such as DotSpatial.Plugins.Ribbon, which implements IHeaderControl and IStatusControl and DotSpatial.Plugins.DockManager, which implements IDockManager.

These can be consumed as nuget packages, or you can download them as zip files. Locate the zip url as the tag that begins with

content type="application/zip"

The aforementioned assemblies presently have the requirement that your main form export a Shell (see DemoMap), so that they understand to what form they should attach themselves.

Implementing IHeaderControl

Let’s examine the DemoMap project for a sample implementation of IHeaderControl.

[Export(typeof(IHeaderControl))]
public class SimpleHeaderControl : MenuBarHeaderControl, IPartImportsSatisfiedNotification
{
    private ToolStripContainer toolStripContainer1;

    [Import("Shell", typeof(ContainerControl))]
    private ContainerControl Shell { get; set; }

    ///

    /// Called when a part's imports have been satisfied and it is safe to use. (Shell will have a value)
    ///

public void OnImportsSatisfied() { this.toolStripContainer1 = new ToolStripContainer(); this.toolStripContainer1.ContentPanel.SuspendLayout(); this.toolStripContainer1.SuspendLayout(); this.toolStripContainer1.Dock = DockStyle.Fill; this.toolStripContainer1.Name = “toolStripContainer1”; // place all of the controls that were on the form originally inside of our content panel. while (Shell.Controls.Count > 0) { foreach (Control control in Shell.Controls) { this.toolStripContainer1.ContentPanel.Controls.Add(control); } } Shell.Controls.Add(this.toolStripContainer1); this.toolStripContainer1.ContentPanel.ResumeLayout(false); this.toolStripContainer1.ResumeLayout(false); this.toolStripContainer1.PerformLayout(); Initialize(toolStripContainer1); } }

Note the attribute decorating the SimpleHeaderControl class.

[Export(typeof(IHeaderControl))]

This attribute declares that this is the header control that we are exporting. We can only export one header control, one status control, and  one dock manager; otherwise when extensions are loaded, it is not clear which one should be used.

SimpleHeaderControl provides a menu and toolbar implementation and is derived from DotSpatial.Controls.Header.MenuBarHeaderControl which does the bulk of the work and requires only a ToolStripContainer where it can place menu items and toolbar buttons.

In the listed code you can see we nest any controls that were on the shell form inside of the content panel so that the menu and toolbar are docked outside (above) them.

If you are not able to derive from MenuBarHeaderControl, you will need to provide similar functionality but should be able to derive from HeaderControl, which keeps track of which items are added by what extension and implements the RemoveAll() method.

Points of Interest

You can test your implementation, by loading the DotSpatial.Plugins.MenuBar assembly.

The DemoMap.exe contains code that meets the requirements for loading extensions. Instead of creating a separate sample in this article, please reference that code.

DotSpatial 1.7 requires and extra line of code to display the default buttons in the header control. InstantiateSnippet

new DotSpatial.Controls.DefaultMenuBars(appManager1).Initialize(appManager1.HeaderControl);

Finding and Installing the WebMap Extension

Introduction

DotSpatial is an open-source project that contains controls which can be used to manipulate and display geographic information. MapWindow 6 is a thin wrapper around DotSpatial. This article explains how to locate, download, and use the WebMap extension. Some extensions are included by default with DotSpatial builds while others can be found in the Extension Manager.

Downloading DotSpatial

This article is based on DotSpatial 1.0 Release — Minimal located on the downloads tab at http://dotspatial.codeplex.com

Using the Extension Manager

Launch the Extension Manager (from the File menu).

The Extension Manager will probably be greatly improved at some point and include a search feature. Presently, there is a short list of extensions we can view on the Online tab. Select the DotSpatial.Plugins.WebMap extension and click Install.

The application status bar informs us that the extension is downloading. Once the installation completes, we can see it appear on the Installed Extensions tab. You will also note the addition of two drop down controls on the toolstrip:

If you want to see the files that were created on disk, click Show Extensions Folder. This will open explorer to a location similar to %appdata%\DemoMap.exe\Extensions\Packages

Using WebMap

Select the Bing Street Map from the first drop down and click the zoom tool.

As we zoom in, the extension displays a properly resized basemap from the nearest available zoom level. Feel free to contribute code that creates an option to snap to zoom levels!

How to Create an Extension for DotSpatial Desktop Mapping GIS

Introduction

DotSpatial is an open-source project that contains controls which can be used to manipulate and display geographic information. This article explains how to create a DotSpatial extension by using the online template. Though this template is for C#, you can do something similar in other .Net languages.

Downloading Visual Studio

There are several free IDEs available, namely SharpDevelop, MonoDevelop, and Visual Studio Express. None of these presently support the template, however, so you’ll need Visual Studio Professional or better. Notably, Visual C# 2010 Express should support this template if NuGet becomes available.

Creating a New Project

Start Visual Studio 2010 and open the New Project dialog (File, New, Project…). Click the Online Template Tab and search for DotSpatial.

Select the DotSpatial Plugin Template from the list of results, name your project and click OK.

After accepting any applicable license agreement, the template will download and install and your project will be created.

Once you have initially downloaded and installed the template, you can create new projects using this template without going online and searching. It will be listed along with your other installed templates. Also, if we update the template, you may be prompted by Visual Studio to update your copy of it.

Customizing the extension

The advantage of creating an extension is that it can be published to the public extension feed or opened in any supported application, such as MapWindow 6.

Let’s modify our extension so that it shows the number of layers presently open.

The code corresponding to the extension is in MyPlugin1.cs. Open this file and change “My Button Caption” to “Show Layer Count”.

Replace the comment in the ButtonClick event handler method with code so that a progress message is displayed when the menu item is clicked:

public void ButtonClick(object sender, EventArgs e)
{
    string message = String.Format("Number of Layers: {0}",
        App.Map.Layers.Count);
    App.ProgressHandler.Progress(null, 0, message);
}

Building and running

The template contains a number of NuGet packages and a sample executable so that you can build and run your project without any further ado! (Debug, Start Debugging) The plugin will be copied to the appropriate directory and you will be presented with a sample legend, toolbox, and map configuration.

Feel free to drop a layer onto the map or click the menu item that was created.