Plugin tutorial

From World Wind Wiki

Revision as of 17:54, 18 May 2005 by 82.33.118.207 (Talk)
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, Guide for World Wind developers for a tutorial on how to set up CVS so you can retrieve the latest version.

TODO: Replace with anonymous CVS instructions?

After you have have CVS configured, get latest from nasa-exp/worldwind.

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 go ahead and double click on "Tutorial1" or the name of your class in the tree.

4. Writing plugin code

  • You can go ahead and delete the constructor if you like (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);
m_Application.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
m_Application.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);
      m_Application.ToolsMenu.MenuItems.Add(menuItem);      
      
      base.Load();
    }
  
    public override void Unload()
    {
      // Clean up, remove menu item
      m_Application.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.

External links

Personal tools