Internal and External Editors

Identifier: org.eclipse.ui.editors

Description: This extension point is used to add new editors to the workbench. An editor is a visual component within a workbench page. It is typically used to edit or browse a document or input object. To open an editor, the user will typically invoke "Open" on an IFile. When this action is performed the workbench registry is consulted to determine an appropriate editor for the file type and then a new instance of the editor type is created. The actual result depends on the type of the editor. The workbench provides support for the creation of internal editors, which are tightly integrated into the workbench, and external editors, which are launched in a separate frame window. There are also various level of integration between these extremes.

In the case of an internal editor, tight integration can be achieved between the workbench window and the editor part. The workbench menu and toolbar are pre-loaded with a number of common actions, such as cut, copy, and paste. The active part, view or editor, is expected to provide the implementation for these actions. An internal editor may also define new actions which appear in the workbench window. These actions only appear when the editor is active.

The integration between the workbench and external editors is more tenuous. In this case the workbench may launch an editor but after has no way of determining the state of the external editor or collaborating with it by any means except through the file system.

Configuration Markup:

   <!ELEMENT editor EMPTY>
   <!ATTLIST editor
      id                 CDATA #REQUIRED
      name               CDATA #REQUIRED
      icon               CDATA #REQUIRED
      class              CDATA #IMPLIED
      command            CDATA #IMPLIED
      launcher           CDATA #IMPLIED
      contributorClass   CDATA #IMPLIED
      extensions         CDATA #OPTIONAL
      filenames          CDATA #OPTIONAL
      default            CDATA (true|false) "false"

id - a unique name that will be used to identify this editor.
name - a translatable name that will be used in the UI for this editor.
icon - a relative name of the icon that will be used for all resources that match the specified extensions. An icon is not required if you specify a command rather than a class or launcher. In the former case, the workbench will use the icon provided by the operating system.
extensions - an optional field containing the list of file types understood by the editor. This is a string containing comma separate file extensions. For instance, an editor which understands hypertext documents may register for "htm, html".
filenames - an optional field containing the list of file names understood by the editor. This is a string containing comma separate file names. For instance, an editor which understands specific hypertext documents may register for "ejb.htm, ejb.html".
class - a name of the class that implements org.eclipse.ui.IEditorPart. Attributes class, command and launcher are mutually exclusive. If this attribute is defined then contributorClass should also be defined.
command - a command to run in order to launch an external editor. The executable command must be located on the system path or in the plug-in's directory. Attributes class, command and launcher are mutually exclusive.
launcher - the name of a class which implements org.eclipse.ui.IEditorLauncher. A launcher will open an external editor. Attributes class, command and launcher are mutually exclusive.
contributorClass - a name of the class that implements org.eclipse.ui.IEditorActionBarContributor. The contributorClass field should only be defined if the class field is defined. This class is used to add new actions to the workbench menu and tool bar which reflect the features of the editor type.
default - if true, this editor will be used as the default editor for the type. This is only relevant in a case where more than one editor is registered for the same type. If an editor is not the default for the type, it can still be launched using "Open With" submenu for the selected resource.

Examples:

The following is an example of an internal editor extension definition:

   <extension point="org.eclipse.ui.editors">
      <editor
         id="com.xyz.XMLEditor"
         name="Fancy XYZ XML editor"
         icon="./icons/XMLEditor.gif"
         extensions="xml"
         class="com.xyz.XMLEditor"
         contributorClass="com.xyz.XMLEditorContributor"
         default="false">
      </editor>
   </extension>

API Information:

If the command attribute is used, it will be treated as an external program command line that will be executed in a platform-dependent manner.

If the launcher attribute is used the editor will also be treated as an external program. In this case the specified class must implement org.eclipse.ui.IEditorLauncher. The launcher will be instantiated and then open(IFile file) will be invoked to launch the editor.

If the class attribute is used, the workbench will assume that it is an internal editor and the specified class must implement org.eclipse.ui.IEditorPart. It is common practice to subclass org.eclipse.ui.EditorPart when defining a new editor type. It is also necessary to define a contributorClass attribute. The specified class must implement org.eclipse.ui.IEditorActionBarContributor, and is used to add new actions to the workbench menu and tool bar which reflect the features of the editor type.

Within the workbench there may be more than one open editor of a particular type. For instance, there may be one or more open Java editors. To avoid the creation of duplicate actions and action images the editor concept has been split into two. An IEditorActionBarContributor is responsible for the creation of actions. The editor is responsible for action implementation. Furthermore, the contributor is shared by each open editor. As a result of this design there is only one set of actions for one or more open editors.

The contributor will add new actions to the workbench menu and toolbar which reflect the editor type. These actions are shared and, when invoked, act upon the active editor. The active editor is passed to the contributor by invoking IEditorActionBarContributor#setActiveEditor. The identifiers for actions and major groups within the workbench window are defined in org.eclipse.ui.IWorkbenchActionConstants. These should be used as a reference point for the addition of new actions. Top level menus are created by using the following values for the path attribute:

additions - represents a group to the left of the Window menu.

Actions and menus added into these paths will only be shown while the associated editor is active. When the editor is closed, menus and actions will be removed.

Supplied Implementation: The workbench provides a "Default Text Editor". The end user product may contain other editors as part of the shipping bundle. In that case, editors will be registered as extensions using the syntax described above.