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.
Now, in the editor window you can see some informations about the project and many tabs below. Select the "Extensions" tab. (4)
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.
Right-click on this item and select 'New > menuContribution'.(14)
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.
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);
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)
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.
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)
Any feedback can by sent to firstname.lastname@example.org