• View
• Edit
• History
• Print

How to Write an Eclipse Plug-in for IDE

Introduction

What is a plug-in?

All functionality in Eclipse is provided by plug-ins, built to the OSGi specification. You can see these plug-ins in Help|About -> Plug-in Details (below), or if you look into the ide/plugins subdirectory of your OMNeT++ installation. Eclipse "Features" are basically collections of plug-ins.

Plug-ins can contribute new items to menus, content menus, toolbars; the File|New and Export/Import dialogs, they can add new editors and views, new launch types, new perspectives, etc., and can basically extend the IDE in any conceivable way.

Motivation

Why should you care about plug-ins? Well, if you are about to write a GUI for some simulation-related task, you could as well implement it as an Eclipse plug-in that integrates seemlessly into the IDE. For example, a GUI that generates networks (NED files and/or associated config files) might be implemented as wizard accessible via the File|New... menu item in Eclipse.

An additional advantage of writing the code as a plug-in is that you can access functionality already provided by Eclipse or the OMNeT++ IDE. For example, you can query or manipulate NED definitions as objects, without the need to parse NED. Or, if you use annotated UML diagrams to define your model or part of it (Eclipse offers several UML editors), you can write a plug-in that generates the OMNeT++ simulation model from UML.

Is it hard?

Not harder than writing your GUI program from scratch.

The functionality that can be accessed from within the IDE is incredibly rich, but the good news is you don't have to know everything at once. Java knowledge is obviously required though. The IDE offers wizards that generate the initial code for the most frequent types of extensions to get you started. The documentation is also good, and there are a lot of resources on the web about Eclipse programming. When it's about GUI, SWT (the Eclipse widget library) isn't that different from Swing or other object-oriented GUI toolkits you might know.

Prerequisites

To develop plug-ins, you need to have PDE (Plug-in Development Environment) installed; see HowToInstallPDE. It is a good idea turn on Project|Build Automatically. (It is turned off in the OMNeT++ IDE by default, because it is not very convenient when working with C++ projects; however, with Java it is extremely useful.)

Creating your first plug-in

Creating the plug-in project

To create the plug-in project, select File|New|Project... from the menu, choose Plug-in Project, and click Next. Note: one plug-in is one project, but one plug-in may contain as much code and may make as many contributions to the IDE as you want.

The next page (not depicted) will ask for the project name; enter org.example.test. Leave other settings unchanged, and click Next.

The next page asks for the plug-in ID, name, and provider. The ID is usually the same as the project name. The plug-in name and provider will appear in the About->Plug-in Details dialog (see top) when your plug-in is installed. Click Next to go to the next page.

The Templates page allows you to add some functionality to the generated project. Choose "Hello World Command" (or any other), and click Next. There'll be one extra page to customize the generated Java class name its package, and the "Hello World" string, and you're done.

After finishing the wizard, this is how the new project should look like in Project Explorer:

Note that in addition to the Java files, there're two special files in the project: META-INF/MANIFEST.MF and plugin.xml. The former contains the plugin-in ID, name, provider, the list of plug-ins it depends on, the Java packages it exports (makes accessible) for other plug-ins, and various other information. plugin.xml describes in XML what contributions this plug-in makes to the IDE. Both files are edited together in the Plug-in Manifest Editor, which is opened by default when the project is created. If you close it, you can reopen it by clicking either META-INF/MANIFEST.MF or plugin.xml.

Running

You can run your plug-in right away: click either "Launch an Eclipse Application" or "Launch an Eclipse Application in Debug Mode" in the bottom-right part of the plug-in manifest editor. As a side effect, this will also create a launch configuration which you can examine, edit or re-launch in the Run (Debug) Configurations... dialog, the same place you also use when launching simulations.

What actually happens is that the whole IDE gets launched in another instance, with your plug-in in addition to the normal ones. You can check in the About->Plug-in Details dialog that it's actually there. The contribution is the blue Eclipse icon on the toolbar, which you can click to bring up a message box saying "Hello World". It also appears in the menu.

A closer look

The Extensions page of the plug-in manifest editor is where the contributions can be seen and edited. In this case it declares a command "sampleCommand" which gets contributed to the menu and the toolbar, and also has a key binding. The command is associated with the SampleCommand class whose execute() methods will be invoked when the command is chosen by the user.

Note the Add button. It can be used to create other extensions, and it offers more than a few wizards too, that generate Java code as well as the extension XML.

What next?

There are several resources where you can go on reading from here:

• Platform Plug-in Developers Guide. This is available in the Eclipse help system, and contains a very good overview of every topic you might need.
• There are several tutorials on the web, for example at http://www.eclipse.org/articles/Article-PDE-does-plugins/PDE-intro.html, at http://www.ibm.com/developerworks/opensource/library/os-ecplug/, or http://www.onjava.com/pub/a/onjava/2005/02/09/eclipse.html. Google is your friend.
• Javadoc comments in the source of Platform classes. The API classes are extremely well commented. You can also browse the code (hit F3 on a class name) or see inheritance hierarchy (F4).
• While you're learning SWT (the widget toolkit) and JFace (higher-level wrapper over SWT), the Eclipse Visual Editor (VE; a GUI builder) can be quite useful; you can also install it via Help|Software Updates|Find and Install...
• If you are serious: There are countless books on the topic. One I can recommend is "Official Eclipse 3.0 FAQs" by John Arthorne and Chris Laffra -- it is concise and to the point.

If you get stuck, you can write to the Eclipse or the OMNeT++ mailing lists.