bundles/org.eclipse.platform.doc.isv/guide/workbench_basicext_editors.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
 <HEAD>

 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

 <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
 <TITLE>org.eclipse.ui.editors</TITLE>

 <link rel="stylesheet" type="text/css" HREF="../book.css">
 </HEAD>
 <BODY BGCOLOR="#ffffff">
 <H3>
 org.eclipse.ui.editors</H3>

 <P >
 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
 (<a href="../reference/api/org/eclipse/ui/IEditorInput.html"><b>IEditorInput</b></a>). 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. </P>
 <P >
 Only one editor can be open for any particular editor input in a workbench page. For example, if the user is editing
 <b> readme.txt</b> 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).&nbsp;
 Unlike views, however, the same editor type, such as a text editor, may be open
 many times
 within one workbench page for different inputs.</P>
 <P >
 The workbench extension point <b><a href="../reference/extension-points/org_eclipse_ui_editors.html">org.eclipse.ui.editors</a></b>
 is used by plug-ins to add editors to the workbench. Plug-ins that contribute an editor must register the editor
 extension in their <b>plugin.xml </b> file, along with configuration information
 for the editor. Some
 of the editor information, such as the implementation <b> class</b> and the
 <b> name</b> and the <b>icon</b>  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
 <b> contributorClass</b>, which is a class that adds actions to workbench menus and tool bars when the editor is active.</P>
 <P >
 The interface for editors is defined in <b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>, but plug-ins
 can choose to extend the
 <b><a href="../reference/api/org/eclipse/ui/part/EditorPart.html"> EditorPart</a></b> class rather than implement an
 <b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>
 from scratch.</P>
 <blockquote><i>
 Note:&nbsp; 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
 <b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>.</i></blockquote>
 <P >
 The readme tool provides a custom editor primarily for the purpose of contributing its own content outliner page to the
 workbench outline view.&nbsp;&nbsp;</P>
 <P >
  The configuration for the editor extension is defined as follows.</P>
 <pre>
 &lt;extension
     point = &quot;org.eclipse.ui.editors&quot;&gt;
 	&lt;editor
   	   id = &quot;org.eclipse.ui.examples.readmetool.ReadmeEditor&quot;
   	   name=&quot;%Editors.ReadmeEditor&quot;
       	   icon=&quot;icons/obj16/editor.png&quot;
       	   class=&quot;org.eclipse.ui.examples.readmetool.ReadmeEditor&quot;
 	   extensions=&quot;readme&quot;
            contributorClass=&quot;org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor&quot;&gt;
 	&lt;/editor&gt;
 &lt;/extension&gt;</pre>
 <P >
 We see the familiar configuration markup for <b>id</b>,
 <b>name</b>,
 <b>icon</b>, and <b>class</b>.&nbsp;&nbsp; The <b>extensions</b> attribute
 describes the file types that the editor understands.&nbsp; (You could also
 specify <b>filenames</b> if you need to be more specific.)&nbsp; The <b>class</b>
 implements the editor, and the <b>contributorClass</b> 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 <a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>.
 Let's look at the contributor that's used for actions in more
 detail.</P>

 <H4>
 Editor action contributors</H4>
 <P >
 The contributor class adds editor-related actions to the workbench menu and toolbar. It must implement the
 <b><a href="../reference/api/org/eclipse/ui/IEditorActionBarContributor.html"> IEditorActionBarContributor</a></b> 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.&nbsp;</P>
 <P >
 In <b>ReadmeEditorActionBarContributor</b>, we contribute three actions,
 &quot;Editor Action1,&quot; &quot;Editor Action2,&quot; and &quot;Editor Action3.&quot;&nbsp;&nbsp;
 These are set up in the constructor.</P>
 <pre>
    public ReadmeEditorActionBarContributor() {
       	...
 	action1 = new EditorAction(MessageUtil.getString(&quot;Editor_Action1&quot;));
 	action1.setToolTipText(MessageUtil.getString(&quot;Readme_Editor_Action1&quot;));
 	action1.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_DISABLE);
 	action1.setImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_ENABLE);
 	...
 	action2 = new RetargetAction(IReadmeConstants.RETARGET2, MessageUtil.getString(&quot;Editor_Action2&quot;));
 	action2.setToolTipText(MessageUtil.getString(&quot;Readme_Editor_Action2&quot;));
 	action2.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_DISABLE);
 	action2.setImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_ENABLE);
 	...
 	action3 = new LabelRetargetAction(IReadmeConstants.LABELRETARGET3, MessageUtil.getString(&quot;Editor_Action3&quot;));
 	action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
 	action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
 	...
    }
 </pre>
 <P >
 The names and icons for the actions are set up in the code rather than in the <b>plugin.xml</b>.&nbsp;
 (We'll ignore the differences in the action classes for now until we look at <a href="wrkAdv_retarget_contribute.htm">retargetable
 actions</a>.)&nbsp;&nbsp;</P>
 <P >Note how similar the action information is to the
 <b> viewActions</b> information we saw in the markup
 for the view action.&nbsp; The actions are set up in code since we have to
 manage the sharing of the actions among different instances of the same editor.&nbsp;
 When the actions are created in the constructor, they are independent of any
 particular instance of the editor.</P>
 <P >
  When an editor becomes active and it has actions that need to be installed in the workbench menus and tool bar, the <b>setActiveEditor
 </b>message is sent to the contributor.&nbsp; The contributor connects the editor actions to a specific editor.&nbsp;&nbsp;</P>
 <pre>
    public void setActiveEditor(IEditorPart editor) {
       ...
       action1.setActiveEditor(editor);
       ...
    }
 </pre>
 <P >
 As you can see, the actions show up in the workbench menu and tool bar when a readme editor is active. </P>

 <img src="images/editormenu.png" alt="Readme entry in workbench menu bar with three editor actions" border="0" >


 <p><img src="images/editortoolbar.png" alt="Workbench toolbar with three readme actions" border="0" ></p>
 <P >
 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
 <a HREF="workbench_menupaths.htm" CLASS="XRef">Menu and toolbar paths</a>.</P>


 <H4>
 Editors and content outliners
 </h4>
 <P >
 The readme editor itself, <b>ReadmeEditor</b>, is not very complicated. It extends the
 <b><a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"> TextEditor</a></b> 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.</P>
 <p><img src="images/readmeoutliner.png" alt="" border="0"></p>
 <P >
 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.&nbsp; See <a href="editors_workbench_outliner.htm">Content
 outliners</a> for more detail. </P>


 <P >
 We'll look at the implementation of text editors in <a href="editors_jface.htm">Text
 editors and platform text</a>. </P>


 </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
	<HEAD>

	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
	<TITLE>org.eclipse.ui.editors</TITLE>

	<link rel="stylesheet" type="text/css" HREF="../book.css">
	</HEAD>
	<BODY BGCOLOR="#ffffff">
	<H3>
	org.eclipse.ui.editors</H3>

	<P >
	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
	(<a href="../reference/api/org/eclipse/ui/IEditorInput.html"><b>IEditorInput</b></a>). 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. </P>
	<P >
	Only one editor can be open for any particular editor input in a workbench page. For example, if the user is editing
	<b> readme.txt</b> 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.</P>
	<P >
	The workbench extension point <b><a href="../reference/extension-points/org_eclipse_ui_editors.html">org.eclipse.ui.editors</a></b>
	is used by plug-ins to add editors to the workbench. Plug-ins that contribute an editor must register the editor
	extension in their <b>plugin.xml </b> file, along with configuration information
	for the editor. Some
	of the editor information, such as the implementation <b> class</b> and the
	<b> name</b> and the <b>icon</b> 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
	<b> contributorClass</b>, which is a class that adds actions to workbench menus and tool bars when the editor is active.</P>
	<P >
	The interface for editors is defined in <b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>, but plug-ins
	can choose to extend the
	<b><a href="../reference/api/org/eclipse/ui/part/EditorPart.html"> EditorPart</a></b> class rather than implement an
	<b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>
	from scratch.</P>
	<blockquote><i>
	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
	<b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>.</i></blockquote>
	<P >
	The readme tool provides a custom editor primarily for the purpose of contributing its own content outliner page to the
	workbench outline view.  </P>
	<P >
	The configuration for the editor extension is defined as follows.</P>
	<pre>
	<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></pre>
	<P >
	We see the familiar configuration markup for <b>id</b>,
	<b>name</b>,
	<b>icon</b>, and <b>class</b>.   The <b>extensions</b> attribute
	describes the file types that the editor understands.  (You could also
	specify <b>filenames</b> if you need to be more specific.)  The <b>class</b>
	implements the editor, and the <b>contributorClass</b> 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 <a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>.
	Let's look at the contributor that's used for actions in more
	detail.</P>

	<H4>
	Editor action contributors</H4>
	<P >
	The contributor class adds editor-related actions to the workbench menu and toolbar. It must implement the
	<b><a href="../reference/api/org/eclipse/ui/IEditorActionBarContributor.html"> IEditorActionBarContributor</a></b> 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. </P>
	<P >
	In <b>ReadmeEditorActionBarContributor</b>, we contribute three actions,
	"Editor Action1," "Editor Action2," and "Editor Action3."
	These are set up in the constructor.</P>
	<pre>
	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);
	...
	}
	</pre>
	<P >
	The names and icons for the actions are set up in the code rather than in the <b>plugin.xml</b>.
	(We'll ignore the differences in the action classes for now until we look at <a href="wrkAdv_retarget_contribute.htm">retargetable
	actions</a>.)  </P>
	<P >Note how similar the action information is to the
	<b> viewActions</b> 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.</P>
	<P >
	When an editor becomes active and it has actions that need to be installed in the workbench menus and tool bar, the <b>setActiveEditor
	</b>message is sent to the contributor.  The contributor connects the editor actions to a specific editor.  </P>
	<pre>
	public void setActiveEditor(IEditorPart editor) {
	...
	action1.setActiveEditor(editor);
	...
	}
	</pre>
	<P >
	As you can see, the actions show up in the workbench menu and tool bar when a readme editor is active. </P>

	<img src="images/editormenu.png" alt="Readme entry in workbench menu bar with three editor actions" border="0" >



	<p><img src="images/editortoolbar.png" alt="Workbench toolbar with three readme actions" border="0" ></p>
	<P >
	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
	<a HREF="workbench_menupaths.htm" CLASS="XRef">Menu and toolbar paths</a>.</P>



	<H4>
	Editors and content outliners
	</h4>
	<P >
	The readme editor itself, <b>ReadmeEditor</b>, is not very complicated. It extends the
	<b><a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"> TextEditor</a></b> 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.</P>
	<p><img src="images/readmeoutliner.png" alt="" border="0"></p>
	<P >
	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 <a href="editors_workbench_outliner.htm">Content
	outliners</a> for more detail. </P>


	<P >
	We'll look at the implementation of text editors in <a href="editors_jface.htm">Text
	editors and platform text</a>. </P>





	</BODY>
	</HTML>