Google Git
Sign in
eclipse / platform / eclipse.platform.ui / refs/tags/v20020115 / . / bundles / org.eclipse.ui / doc / org_eclipse_ui_editors.html
blob: 0c58993e3f3e946b5ccf4c90728e784cfcbd582e [file] [log] [blame]
<!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.&nbsp; An editor is a visual component within a workbench
page. It is typically used to edit or browse a document or input object.&nbsp;
To open an editor, the user will typically invoke "Open" on an <tt>IFile</tt>.&nbsp;
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.&nbsp; The actual result depends on the type of
the editor.&nbsp; 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.&nbsp; 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.&nbsp; The workbench menu
and toolbar are pre-loaded with a number of common actions, such as cut,
copy, and paste.&nbsp; 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.&nbsp; These actions
only appear when the editor is active.
<p>The integration between the workbench and external editors is more tenuous.&nbsp;
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>&nbsp;&nbsp; &lt;!ELEMENT editor EMPTY></tt>
<br><tt>&nbsp;&nbsp; &lt;!ATTLIST editor</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; id&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
CDATA #REQUIRED</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
CDATA #REQUIRED</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; icon&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
CDATA #IMPLIED</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; class&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
CDATA #IMPLIED</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; command&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
CDATA #IMPLIED</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; launcher&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
CDATA #IMPLIED</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; contributorClass&nbsp;&nbsp;
CDATA #IMPLIED</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; extensions&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
CDATA #OPTIONAL</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; filenames&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
CDATA #OPTIONAL</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; default&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
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.&nbsp; This is a string containing comma separate
file extensions.&nbsp; 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.&nbsp; This is a string containing comma separate
file names.&nbsp; 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.&nbsp; 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>.&nbsp;
The <tt>contributorClass</tt> field should only be defined if the <tt>class</tt>
field is defined.&nbsp; 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>&nbsp;&nbsp; &lt;extension point="org.eclipse.ui.editors"></tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;editor</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; id="com.xyz.XMLEditor"</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; name="Fancy XYZ
XML editor"</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; icon="./icons/XMLEditor.gif"</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; extensions="xml"</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; class="com.xyz.XMLEditor"</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; contributorClass="com.xyz.XMLEditorContributor"</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; default="false"></tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/editor></tt>
<br><tt>&nbsp;&nbsp; &lt;/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.&nbsp; 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>.&nbsp;
It is common practice to subclass <tt>org.eclipse.ui.EditorPart</tt>
when defining a new editor type.&nbsp; It is also necessary to define a
<tt>contributorClass</tt> attribute.&nbsp; 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.&nbsp; For instance, there may be one or more open Java editors.&nbsp;
To avoid the creation of duplicate actions and action images the editor
concept has been split into two.&nbsp; An <tt>IEditorActionBarContributor</tt>
is responsable for the creation of actions.&nbsp; The editor is responsable
for action implementation.&nbsp; Furthermore, the contributor is shared
by each open editor.&nbsp; 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.&nbsp; These actions are shared and, when
invoked, act upon the active editor.&nbsp; The active editor is passed
to the contributor by invoking <tt>IEditorActionBarContributor#setActiveEditor</tt>.&nbsp;
The identifiers for actions and major groups within the workbench window
are defined in <tt>org.eclipse.ui.IWorkbenchActionConstants</tt>.&nbsp;
These should be used as a reference point for the addition of new actions.&nbsp;
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>