Plugin tutorial

From World Wind Wiki

Revision as of 09:29, 4 June 2005 by Mashiharu (Talk | contribs)
Jump to: navigation, search

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 do it in notepad. ;)

Contents

1. Setting up CVS

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

Refer to Setting Up SourceForge CVS 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.

Image:Tutorial_override.png

  • 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.

Image:Tutorial_src1.png

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
{
  /// <summary>
  /// Tutorial1
  /// </summary>
  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.

Image:Tutorial_pluginman.png

  • From the Main menu select Tools->Plugin Manager.
  • 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.

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 notepad 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.

External links

Personal tools