DotSpatial is an open-source project that contains controls which can be used to manipulate and display geographic information. The end-user release version of DotSpatial is named MapWindow 6. We’ve made it really easy for you to customize MapWindow 6 without even downloading the source code by adding your own extensions and re-branding the application.
Downloading MapWindow 6
We’ll consider HydroDesktop, which builds upon and customizes MapWindow 6, as a case study.
Replacing or Adding Extensions
The extensibility feature in DotSpatial is heavily used in MapWindow 6. You can learn more about where to find extensions and how to write your own extensions. By default, the ClickOnce version of MapWindow includes several extensions, such as, an updater, an extension manager, an error reporter, a tree of map layers (legend), and a splash screen. All of these extensions will be composed seamlessly when the application starts. In addition, a few other UI extensions are downloaded when the application starts for the first time.
When you have located or built the extensions you want to include, you will install them into the Plugins or Application Extensions folder. You may likewise replace or remove extensions that you don’t want or need. Some extensions depend on others, so you will have to add or remove them in sets.
Also, your application must contain an implementation of IProgressHandler, IHeaderControl, and IDockManager, if it includes any extension that implements IExtension. It may contain Tools or DataProviders without this restriction. This is because Extensions are designed to work with a user interface and this base set of functionality is expected (e.g., the ability to add a menu item). Extension Manager will download a default set of UI controls if an implementation is not already provided.
HydroDesktop adds a plethora of custom built extensions, and uses its own DockManager.
Changing the Form Name
The main form title is “MapWindow 6” by default. You can replace this by modifying MapWindow.exe.config.
Notice the setting named CustomMainFormTitle in the userSettings section. Provide the value CUAHSI HydroDesktop.
<setting name="CustomMainFormTitle" serializeAs="String"> <value>CUAHSI HydroDesktop</value> </setting>
Changing the Application Icon
The application icon appears in the About extension and in the upper left hand corner of the form. It can also be customized by modifying MapWindow.exe.config. It may be easiest to drop the icon in the same folder as the executable, as I did.
<setting name="CustomAppIconPath" serializeAs="String"> <value>HydroDesktop.ico</value> </setting>
Customizing the SplashScreen Logo
If you are using the DotSpatial.Plugins.SplashScreenManager, you may customize it by providing a logo that is displayed in the splash screen. Place a PNG image in the same folder as the executable. Its dimensions shouldn’t be much larger than 426 x 120 px. Modify MapWindow.exe.config to reference the new logo and delete the old MapWindowSplashLogo.png file from the directory.
<setting name="CustomSplashImagePath" serializeAs="String"> <value>HydroDesktopSplashLogo.PNG</value> </setting>
Customizing the Executable Icon
The MapWindow.exe executable has an icon resource embedded in it. Windows displays this icon in explorer and as the default icon for any shortcuts to the executable. You can use a tool such as XN Resource Editor to replace the icon. You would generally need to check the MapWindow 6 license before doing this, but this type of modification is permitted in this open-source project (though, I’m not a lawyer).
I used the Import image Resource menu item on the context menu of XN Resource Editor and removed the old icon (Delete Resource).
Renaming the Executable
Renaming the executable is a simple two-step process: rename both the executable and the config file.
Note: After the extension is renamed, you will notice the extension manager reports that packages are placed in a different directory based on the new executable name. The path would look something like %appdata%\HydroDesktop.exe\Extensions. Packages in the %appdata%\MapWindow6.exe\Extensions folder will be ignored by this executable.