Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Plug-in Developer Guide
Previous Page Home Next Page

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.

Readme entry in workbench menu bar with three editor actions

Workbench toolbar with three readme actions

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.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire