org.eclipse.ui.editors
An editor is a workbench part that allows a user to edit an object (often a
file). Editors operate in a manner similar to file system editing tools, except that they are tightly integrated into the platform workbench UI. An editor is always associated with an input object
(
IEditorInput). You can think of the input object as
the document or file that is being edited. Changes made in an editor are not
committed until the user saves them.
Only one editor can be open for any particular editor input in a workbench page. For example, if the user is editing
readme.txt in the workbench, opening it again
in the same perspective will activate the same editor. (You can open another
editor on the same file from a different workbench window or perspective).
Unlike views, however, the same editor type, such as a text editor, may be open
many times
within one workbench page for different inputs.
The workbench extension point
org.eclipse.ui.editors
is used by plug-ins to add editors to the workbench. Plug-ins that contribute an editor must register the editor
extension in their plugin.xml file, along with configuration information
for the editor. Some
of the editor information, such as the implementation class and the
name and the icon to be used in the workbench menus and
labels, is similar to the view information. In addition, editor extensions specify the file extensions or file name patterns of the file types that the editor understands. Editors can also define a
contributorClass, which is a class that adds actions to workbench menus and tool bars when the editor is active.
The interface for editors is defined in
IEditorPart
, but plug-ins
can choose to extend the
EditorPart
class rather than implement an
IEditorPart
from scratch.
Note: An editor extension can also be configured to launch an external program
or to call pre-existing java code. In this discussion, we are focusing on those editors that are actually tightly integrated with the workbench and
are implemented using
IEditorPart
.
The readme tool provides a custom editor primarily for the purpose of contributing its own content outliner page to the
workbench outline view.
The configuration for the editor extension is defined as follows.
<extension
point = "org.eclipse.ui.editors">
<editor
id = "org.eclipse.ui.examples.readmetool.ReadmeEditor"
name="%Editors.ReadmeEditor"
icon="icons/obj16/editor.png"
class="org.eclipse.ui.examples.readmetool.ReadmeEditor"
extensions="readme"
contributorClass="org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor">
</editor>
</extension>
We see the familiar configuration markup for id,
name,
icon, and class. The extensions attribute
describes the file types that the editor understands. (You could also
specify filenames if you need to be more specific.) The class
implements the editor, and the contributorClass is responsible for
providing editor-related actions. The contributor is not normally used to
contribute commands or handlers to the workbench menu or toolbar, that's done
via
org.eclipse.ui.menus.
Let's look at the contributor that's used for actions in more
detail.
Editor action contributors
The contributor class adds editor-related actions to the workbench menu and toolbar. It must implement the
IEditorActionBarContributor
interface. The contributor is
separate from the editor itself since any given workbench page can have multiple editors of the same type.
A single contributor is shared by all the editors of a specific type, rather than
having each instance of an editor create actions and images.
In ReadmeEditorActionBarContributor, we contribute three actions,
"Editor Action1," "Editor Action2," and "Editor Action3."
These are set up in the constructor.
public ReadmeEditorActionBarContributor() {
...
action1 = new EditorAction(MessageUtil.getString("Editor_Action1"));
action1.setToolTipText(MessageUtil.getString("Readme_Editor_Action1"));
action1.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_DISABLE);
action1.setImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_ENABLE);
...
action2 = new RetargetAction(IReadmeConstants.RETARGET2, MessageUtil.getString("Editor_Action2"));
action2.setToolTipText(MessageUtil.getString("Readme_Editor_Action2"));
action2.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_DISABLE);
action2.setImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_ENABLE);
...
action3 = new LabelRetargetAction(IReadmeConstants.LABELRETARGET3, MessageUtil.getString("Editor_Action3"));
action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
...
}
The names and icons for the actions are set up in the code rather than in the plugin.xml.
(We'll ignore the differences in the action classes for now until we look at
retargetableactions.)
Note how similar the action information is to the
viewActions information we saw in the markup
for the view action. The actions are set up in code since we have to
manage the sharing of the actions among different instances of the same editor.
When the actions are created in the constructor, they are independent of any
particular instance of the editor.
When an editor becomes active and it has actions that need to be installed in the workbench menus and tool bar, the setActiveEditor
message is sent to the contributor. The contributor connects the editor actions to a specific editor.
public void setActiveEditor(IEditorPart editor) {
...
action1.setActiveEditor(editor);
...
}
As you can see, the actions show up in the workbench menu and tool bar when a readme editor is active.
These menu and tool bar items are only shown when the editor is active. The location for the menu and tool bar items can be specified as described in
Menu and toolbar paths.
Editors and content outliners
The readme editor itself, ReadmeEditor, is not very complicated. It extends the
TextEditor
class so that it can contribute a customized content outliner page
to the outline view when a readme file is being edited. It does not change any behavior inside the text editor.
Editors often have corresponding content outliners that provide a structured
view of the editor's contents and assist the user in navigating through the
contents of the editor. See
Contentoutliners for more detail.
We'll look at the implementation of text editors in
Texteditors and platform text.
