Introduction
The official documentation for the Eclipse Plug-in Development Environment (PDE) is in http://archive.eclipse.org/eclipse/downloads/drops/R-3.1-200506271435/org.eclipse.pde.doc.user.3.1.pdf.zip
Is also recommended to read the Platform Plug-in Developer Guide, available in http://archive.eclipse.org/eclipse/downloads/drops/R-3.1-200506271435/org.eclipse.platform.doc.isv.3.1.pdf.zip
In this text we assume the Eclipse release called "Galileo" and the Java Run-time Environment version 1.6.0_20.
In this example, let's see how to create an item in the main menu of Eclipse IDE and how to make some operations on the file opened in the editor. As you can see, after each item in this manual, there is a hyperlink with a number. Click on it to see a print screen about the item that was explained.
Working with extensions
- You need to have the edition of Eclipse for RCP/Plug-in Developers ;
- Select menu 'File > New > Project...' (1)
- A pop-up window, on which "Select a wizard" appears in the first line, is opened. Select 'Plug-in Development\Plug-in Project'. Click on 'Next' ; (2)
- In the next screen (Plug-in Project), give a name for the project (e.g. jp.shibaura.example1) and click on 'Next'; (3)
- In the next screen (Content), just click 'Next';
- In this case we will not use any Template, so, just click 'Finish'.
Now, in the editor window you can see some informations about the project and many tabs below. Select the "Extensions" tab. (4)
- In this window, click on 'Add...' button. A pop-up window opens (Extension Point Selection). Find the extension point 'org.eclipse.ui.commands'. Select and click 'Finish' (5)
- Right-click the extension and select 'New > Command' (6)
- Give an 'id' for this command, like 'jp.shibaura.example1.command.cmd1', and a name (e.g. Command 1) (7)
Before proceeding to the next, let's save the project. You will see that Eclipse creates a file called 'plugin.xml' in our project directory (7.1). This file contains the structure of all the extension-points that are being used in your plug-in and many other configurations. Eclipse provides the graphical interface for manipulating this file, so we don't need to edit the XML structure by ourselves. It is important to save the project (actually plugin.xml) after each modification or addition of extensions to allow Eclipse to reflect the change of the file plugin.xml and the references of the extensions.
- Now, let's add another extension 'org.eclipse.ui.handlers' as we did before (8).
- The Eclipse automatically creates a new handler. Click on the button 'Browse..' beside the commandId field (9).
- Select the command that we created before, 'jp.shibaura.example1.command.cmd1'.(10)
- Click on 'class' to create a new Java class.
- Give a package like 'jp.shibaura.example1.handler', a name (e.g. Handler1), and click the 'Browse...' button beside the Superclass field.(11)
- In the first field, type, find and select the class 'org.eclipse.core.commands.AbstractHandler'. (12)
- Click on 'Finish' button. By now, we will not make any implementation in this class, let's finish the extension points first.
- Now, let's add a new extension point: 'org.eclipse.ui.menus'.(13)
Right-click on this item and select 'New > menuContribution'.(14)
- The field 'locationURI' means where our menu should appear. We want that it appears in the main menu, so type: 'menu:org.eclipse.ui.main.menu'. (15)
- Now, right-click on the menuContribution and select 'New > menu'. The label will be 'Menu 1' and the id 'Menu1';
- To finish this step, right-click on the menu item and select 'New > command' (16). For the commandId field, find and select our command 'jp.shibaura.example1.command.cmd1'. (17) The Label will be 'Menu Item 1' and the id 'MenuItem1'. (18)
Now, our menu item is connected to our command, which in turn is linked to the handler, that contains the action to be executed.
Let's turn back to our class 'Handler1' and implement the action.
Implementing Handlers and actions
As our class implements the IHandler interface, we must override the method "execute":
See this image in larger size here
The line number 22 gets the current instance of the eclipse, because you can have many instances with different files and projects
IWorkbenchWindow window = HandlerUtil.getActiveWorkbenchWindowChecked(event);
The line number 23 gets the current editor, because in each instance of Eclipse, each opened file represents one editor
IEditorPart editor = window.getActivePage().getActiveEditor();
The line 25 gets the object IDocument that represents the file opened in the current editor. This interface provides a bundle of methods that can make many operations over the file, like search for strings, replace, get number of lines, length and so on. For the getDocument method implementation, please see below.
IDocument doc = getDocument(editor);
The line 26 gets the part of the file that was selected by the mouse cursor. This interface (ITextSelection) provides many methods about this selection, like line numbers where the selection starts and ends, the text selected and the position of the cursor.
ITextSelection selection = getSelection(editor);
The next line opens a pop-up window with the selection made with the mouse:
MessageDialog.openInformation(window.getShell(), "Information", selection.getText());
The next two lines we used just to put my name as author in the first line of the document:
String text = doc.get();
doc.set("Author: Sampaio, Luiz Gustavo\n" + text);
The getDocument method
This method use the interfaces IEditorInput and the IDocumentProvider to reach the interface IDocument that represents the file that we want. Pay attention to line:
if (editor instanceof TextEditor)
In case of Standard ML Files (.sml) or others "unknown extensions" for Eclipse, the editor object is a instance of TextEditor. In case of a java file (.java) this editor is a instance of other kind of class, like "javaEditor" (needing check)
The getSelection method
This method gets a instance of ISelection trough the interface ISelectionProvider. As we said about the editor object, the selection also can came from different types. Because of this, we need to test if the selection is a instance of ITextSelection interface.
Note:
When we use some interfaces (like IDocumentProvider, for example) we must add in our class a reference from the package that interface belongs, otherwise, we will get a "design-time error". To fix this problem, just put the mouse cursor over the interface and Eclipse will suggest what you should do. In our example, let's make a "import" of org.eclipse.ui.texteditor.IDocumentProvider. (21.1)
See in action!
- Now we are ready to see our plug-in running. Click on the arrow beside the button "Run" in the Eclipse toolbar and select "New Configuration" (22)
- A new instance of Eclipse will be started with our menu available. Open a .sml ou .txt file, select a piece of the code and click on 'Menu 1 > Menu item 1'. Now, see what happens! (23) (24) (25)
Any feedback can by sent to lgmsampaio@gmail.com