<!doctype html public "-//w3c//dtd html 4.0//en"> | |
<html> | |
<head> | |
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
<title>Eclipse Workbench Extension Point: Editors</title> | |
</head> | |
<body link="#0000FF" vlink="#800080"> | |
<center> | |
<h1> | |
Internal and External Editors</h1></center> | |
<b><i>Identifier: </i></b>org.eclipse.ui.editors | |
<p><b><i>Description</i>: </b>This extension point is used to add new editors | |
to the workench. 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 <tt>IFile</tt>. | |
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. | |
<p>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. | |
<p>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. | |
<p><b><i>Configuration Markup:</i></b> | |
<p><tt> <!ELEMENT editor EMPTY></tt> | |
<br><tt> <!ATTLIST editor</tt> | |
<br><tt> id | |
CDATA #REQUIRED</tt> | |
<br><tt> name | |
CDATA #REQUIRED</tt> | |
<br><tt> icon | |
CDATA #IMPLIED</tt> | |
<br><tt> class | |
CDATA #IMPLIED</tt> | |
<br><tt> command | |
CDATA #IMPLIED</tt> | |
<br><tt> launcher | |
CDATA #IMPLIED</tt> | |
<br><tt> contributorClass | |
CDATA #IMPLIED</tt> | |
<br><tt> extensions | |
CDATA #OPTIONAL</tt> | |
<br><tt> filenames | |
CDATA #OPTIONAL</tt> | |
<br><tt> default | |
CDATA (true|false) "false"</tt> | |
<ul> | |
<li> | |
<b>id</b> - a unique name that will be used to identify this editor</li> | |
<li> | |
<b>name</b> - a translatable name that will be used in the UI for this | |
editor</li> | |
<li> | |
<b>icon</b> - 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.</li> | |
<li> | |
<b>extensions</b> - 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".</li> | |
<li> | |
<b>filenames</b> - 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".</li> | |
<li> | |
<b>class</b> - a name of the class that implements <tt>org.eclipse.ui.IEditorPart</tt>. | |
Attributes <tt>class,</tt> <tt>command</tt> and <tt>launcher</tt> are mutually | |
exclusive. If this attribute is defined then <tt>contributorClass</tt> | |
should also be defined.</li> | |
<li> | |
<b>command</b> - a command to run in order to launch an external editor. | |
The executatble command must be located on the system path or in the plugins | |
directory. Attributes <tt>class,</tt> <tt>command</tt> and <tt>launcher</tt> | |
are mutually exclusive.</li> | |
<li> | |
<b>launcher</b> - the name of a class which implements <tt>org.eclipse.ui.IEditorLauncher</tt>. | |
A launcher will open an external editor. Attributes <tt>class,</tt> <tt>command</tt> | |
and <tt>launcher</tt> are mutually exclusive.</li> | |
<li> | |
<b>contributorClass</b> - a name of the class that implements <tt>org.eclipse.ui.IEditorActionBarContributor</tt>. | |
The <tt>contributorClass</tt> field should only be defined if the <tt>class</tt> | |
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.</li> | |
<li> | |
<b>default</b> - 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.</li> | |
</ul> | |
<b><i>Examples:</i></b> | |
<p>The following is an example of an internal editor extension definition: | |
<p><tt> <extension point="org.eclipse.ui.editors"></tt> | |
<br><tt> <editor</tt> | |
<br><tt> id="com.xyz.XMLEditor"</tt> | |
<br><tt> name="Fancy XYZ | |
XML editor"</tt> | |
<br><tt> icon="./icons/XMLEditor.gif"</tt> | |
<br><tt> extensions="xml"</tt> | |
<br><tt> class="com.xyz.XMLEditor"</tt> | |
<br><tt> contributorClass="com.xyz.XMLEditorContributor"</tt> | |
<br><tt> default="false"></tt> | |
<br><tt> </editor></tt> | |
<br><tt> </extension></tt> | |
<p><b><i>API Information:</i></b> | |
<p>If the <tt>command</tt> attribute is used, it will be treated as an | |
external program command line that will be executed in a platform-dependent | |
manner. | |
<p>If the <tt>launcher</tt> attribute is used the editor will also be treated | |
as an external program. In this case the specified class must implement | |
<tt>org.eclipse.ui.IEditorLauncher</tt>. | |
The launcher will be instantiated and then <tt>open(IFile file)</tt> will | |
be invoked to launch the editor. | |
<p>If the <tt>class</tt> attribute is used, the workbench will assume that | |
it is an internal editor and the specified class must implement <tt>org.eclipse.ui.IEditorPart</tt>. | |
It is common practice to subclass <tt>org.eclipse.ui.EditorPart</tt> | |
when defining a new editor type. It is also necessary to define a | |
<tt>contributorClass</tt> attribute. The specified class must implement | |
<tt>org.eclipse.ui.IEditorActionBarContributor</tt>, and is used to | |
add new actions to the workbench menu and tool bar which reflect the features | |
of the editor type. | |
<p>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 <tt>IEditorActionBarContributor</tt> | |
is responsable for the creation of actions. The editor is responsable | |
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. | |
<p>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 <tt>IEditorActionBarContributor#setActiveEditor</tt>. | |
The identifiers for actions and major groups within the workbench window | |
are defined in <tt>org.eclipse.ui.IWorkbenchActionConstants</tt>. | |
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 <tt>path</tt> | |
attribute: | |
<ul> | |
<li> | |
<tt>additions</tt> - represents a group to the left of the Window menu.</li> | |
</ul> | |
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. | |
<p><b><i>Supplied Implementation: </i></b>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. | |
<p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corp. 2000, 2001. All Rights Reserved." BORDER=0 height=12 width=195></a> | |
</body> | |
</html> |