Plugin tutorial

An easy way of developing a plugin is by doing it inside the World Wind project. When your file is debugged you can just move the file into the Plugins directory where it should work as a plugin without modification. This tutorial shows how you could go about developing a plugin. There are many other ways, and a hard core developer could use a text editor. ;)

1. Setting up SVN
In order to write plugins you will want to have the latest version of World Wind.

Refer to Setting Up SourceForge SVN for information on how to download the World Wind source code.

2. Compiling the sources
Step number 2 is building World Wind. Refer to Compiling the sources for instructions.

3. Adding the plugin class
For this first tutorial we're just going to create a plugin that adds itself as an item in the main menu, and displays a message when you click it.
 * Open worldwind.sln in Visual Studio 2003. You will debug your plugin in this project
 * Find your "Class View" window in Visual Studio (View->Class View).
 * Right click on WorldWind project
 * Select Add->Add class
 * Type a class name for your plugin, like "Tutorial1", and preferably a new namespace name, like "AnonDeveloper.Plugin".
 * Click the "Base class" tab on the left.
 * Select "WorldWind.PluginEngine" from the Namespace dropdown, and "Plugin" from the Base Class dropdown.
 * Now click finish.
 * Go back to your class browser and expand the hierarchy until you see the methods on "Plugin", the base class.




 * Now right click on "Load" and "Unload" methods and select "Add->Override". These methods are the ones World Wind will call to load our plugin and later unload it.
 * In your editor window you should now see something like the following.

If you don't see it, double click "Tutorial1" or the name of your class in the tree to open it in the editor.

4. Writing plugin code
Since we don't use constructor in this sample, you can delete it.

public Tutorial1 { }

We willl now add a menu item and simple functionality to that menu item.

Add: System.Windows.Forms.MenuItem menuItem; to the top of your class.

Then add the following lines to your Load method:

// Add our plugin to the World Wind Tools menu menuItem = new System.Windows.Forms.MenuItem; menuItem.Text = "Tutorial1 test"; menuItem.Click += new System.EventHandler(menuItem_Click); ParentApplication.ToolsMenu.MenuItems.Add(menuItem);

This will add the menu item to World Wind's main menu and make sure menuItem_Click is called when the user selects our menu item.

Then add the following lines to the Unload method:

// Remove menu item ParentApplication.ToolsMenu.MenuItems.Remove(menuItem); This will clean up should the user decide to unload our plugin.

Finally we will add functionality to the menu item. For now we are just going to display a message box.

Add the method menuItem_Click like this:

void menuItem_Click(object sender, EventArgs e) { System.Windows.Forms.MessageBox.Show("Tutorial1 works."); }

The end result should look something like the following:

// // NAME: Tutorial1 // DESCRIPTION: My first plugin // DEVELOPER: My name // WEBSITE: http://www.mywebsite.com // using System; namespace AnonDeveloper.Plugin {  ///    /// Tutorial1 ///   public class Tutorial1 : WorldWind.PluginEngine.Plugin {    System.Windows.Forms.MenuItem menuItem; public override void Load {      // Add our plugin to the World Wind Tools menu menuItem = new System.Windows.Forms.MenuItem; menuItem.Text = "Tutorial1 test"; menuItem.Click += new System.EventHandler(menuItem_Click); ParentApplication.ToolsMenu.MenuItems.Add(menuItem); base.Load; }    public override void Unload {      // Clean up, remove menu item ParentApplication.ToolsMenu.MenuItems.Remove(menuItem); base.Unload ; }    void menuItem_Click(object sender, EventArgs e)     { // Fired when user clicks our main menu item. System.Windows.Forms.MessageBox.Show("Tutorial1 works."); }  } }

The comment header will be used by the Plugin Manager to give the user information about your plugin without actually having to compile it first. The header is optional, but recommended. While you are debugging your plugin inside WW this information will not show up (since it has been precompiled before launching WW).

5. Debugging our plugin
When you have fixed any compile errors, press Run and watch World Wind load. World Wind will when compiled in Debug mode automatically load up any objects deriving from the "Plugin" base class.

But our plugin is new and thus not automatically loaded.




 * From the Main menu select Plugins->Load/Unload.
 * If you haven't yet enabled the plugin system World Wind will ask whether it's ok. Choose yes.
 * You should now be able to find Tutorial1 or the name you chose for your plugin in the list.
 * Click it, and press the Load button.
 * If you expect to be loading your new plugin many times it will usually be a good idea to check the Startup check box to avoid having to manually perform the load step each time you restart World Wind.
 * If everything worked and your plugin was successfully initialized you will see a green lamp to the left of your plugin.
 * Close the plugin manager.
 * Drop down the Tools menu in World Wind, you should find your menu item there, it's name will be Tutorial test if you didn't change it.
 * Click it

If a message pops up on screen, hooray, you just wrote your first World Wind plugin.

5.1 Slightly more advanced Debugging
If you need to start up a debugger and see what is going on in your plugin you can use System.Diagnostics.Debugger.Launch or System.Diagnostics.Debugger.Break to trigger a breakpoint if a debugger is already attached (ie. you are running it from VS.NET)

6. Using our plugin in World Wind 1.3.2
To use our plugin in the official release of 1.3.2 we have to copy Tutorial1.cs from WorldWind\WorldWind to Program Files\NASA\World Wind 1.3\Plugins.

Then repeat the steps in section 5 to load Tutorial1.cs in plugin manager.

7. Alternate development method
If you are coding in a different language than C# or don't want to modify the World Wind project there is an alternate way to debug your code.


 * Create a new library (.dll) project in your favorite language
 * Add a reference to WorldWind.exe. If you are using Visual Studio.net it might tell you it can't do this, but it's a lie.  I suggest adding a reference to worldwindow.dll, and then open your project file in your favorite editor and change it to worldwind.exe.  There is as far as I know no difference between .dll and .exe assemblies so why they decide to make vs.net behave this way is a big mystery to me.
 * Go to your project properties pages and adjust the Output path of your project to "Plugins/something" under the directory you have WorldWind.exe in.
 * Develop your plugin as usual by deriving from Plugin
 * Build and then run WorldWind.exe, WorldWind should find and display your dll plugin in the Plugin->Load/Unload dialog.
 * After loading your plugin, attach your debugger and you should be able to debug your code.