bundles/org.eclipse.platform.doc.isv/guide/wrkAdv_retarget_contribute_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>
 Retargetable editor actions
 </TITLE>

 <link rel="stylesheet" type="text/css" HREF="../book.css">
 </HEAD>
 <BODY BGCOLOR="#ffffff">
 <h4>Retargetable editor actions</h4>
 <p>Recall that the <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
 tool</a> defines its own editor which contributes actions
 to the workbench menu bar using its <b>ReadmeEditorActionBarContributor</b>.&nbsp;&nbsp;</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;
            <b>contributorClass=&quot;org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor</b>&quot;&gt;
 	&lt;/editor&gt;
 &lt;/extension&gt;</pre>
 <p>Let's look closer at what happens in the contributor class.</p>
 <pre>public ReadmeEditorActionBarContributor() {
 	...
 	action2 = new <b>RetargetAction</b>(<b>IReadmeConstants.RETARGET2</b>, 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 <b>LabelRetargetAction</b>(<b>IReadmeConstants.LABELRETARGET3</b>, MessageUtil.getString(&quot;Editor_Action3&quot;));
 	action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
 	action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
 	...&nbsp;&nbsp;
 	<b>handler2</b> = new EditorAction(MessageUtil.getString(&quot;Editor_Action2&quot;));
 	...
 	<b>handler3</b> = new EditorAction(MessageUtil.getString(&quot;Editor_Action3&quot;));
 	...</pre>
 <p>When the contributor is created, it creates two retargetable actions (one
 that allows label update and one that does not).&nbsp; Creation of the actions
 uses the same technique that the workbench uses.&nbsp; It also creates two
 handlers that will be used for the actions when the editor is the active
 part.&nbsp;&nbsp;</p>
 <p>But where are the handlers for the actions registered?&nbsp; Setting the
 global handlers is done a little differently when your editor defines the
 retargeted actions.&nbsp; Why?&nbsp; Because your contributor is in charge of
 tracking the active view and hooking different handlers as different views or
 the editor itself becomes active.&nbsp; (The workbench does this for you when
 you set a handler for one of its global actions).&nbsp; Here's how the <b>ReadmeEditorActionBarContributor</b>
 sets things up:</p>
 <pre>public void init(IActionBars bars, IWorkbenchPage page) {
 	super.init(bars, page);
 	bars.setGlobalActionHandler(IReadmeConstants.RETARGET2, handler2);
 	bars.setGlobalActionHandler(IReadmeConstants.LABELRETARGET3, handler3);
 	...</pre>
 <p>First, the contributor registers its handlers for the retargeted
 actions.&nbsp; This ensures that the contributor's actions will be run when the
 editor itself is active.&nbsp; The next step is to register each <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
 </b>as a part listener on the page.</p>
 <pre>	...
 	// Hook retarget actions as page listeners
 	page.addPartListener(action2);
 	page.addPartListener(action3);
 	IWorkbenchPart activePart = page.getActivePart();
 	if (activePart != null) {
 		action2.partActivated(activePart);
 		action3.partActivated(activePart);
 	}
 }</pre>
 <p>Adding each <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
 </b>as a part listener means that it will be notified when the active part
 changes.&nbsp; The action can get the correct global handler from the newly
 activated part.&nbsp; (See the implementation of <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
 </b>for all the details.)&nbsp;&nbsp; Note that to start, the action is seeded
 with the currently active part. </p>
 <p>When the editor contributor is disposed, it should unhook the retargetable
 actions as page listeners.</p>
 <pre>public void dispose() {
 	// Remove retarget actions as page listeners
 	getPage().removePartListener(action2);
 	getPage().removePartListener(action3);
 }</pre>
 <p>Finally, recall that action bar contributors are shared among instances of
 the same editor class.&nbsp; For this reason, the handlers must be notified when
 the active editor changes so that they can connect to the proper editor
 instance.</p>
 <pre>public void setActiveEditor(IEditorPart editor) {
 	...
 	handler2.setActiveEditor(editor);
 	handler3.setActiveEditor(editor);
 	...
 }</pre>
 <p>That completes the setup on the editor side.&nbsp; When the editor is open
 and active, the handlers (and their labels) as defined by the <b>ReadmeEditorActionBarContributor
 </b>will appear in the workbench menu bar.</p>
 <p><img src="images/editorretargets.png" alt="Readme menu with three editor actions in workbench menu bar" border="0"></p>
 <p>Now that the editor's contributions are in place, what does a view do to register a handler?&nbsp; The code on the client side
 is similar to registering a handler for a workbench action, except that the
 action id is the one defined by the plug-in's editor.&nbsp; The <b>ReadmeContentOutlinePage</b>
 registers a handler for these actions.</p>
 <pre>public void createControl(Composite parent) {
 	super.createControl(parent);
 	...
 	getSite().getActionBars().<b>setGlobalActionHandler(
 		IReadmeConstants.RETARGET2, </b>
 		new OutlineAction(MessageUtil.getString(&quot;Outline_Action2&quot;)));

 	OutlineAction action = new OutlineAction(MessageUtil.getString(&quot;Outline_Action3&quot;));
 	<b>action.setToolTipText(MessageUtil.getString(&quot;Readme_Outline_Action3&quot;)); </b>
 	getSite().getActionBars().<b>setGlobalActionHandler(
 		IReadmeConstants.LABELRETARGET3, </b>
 		action);
 	...</pre>
 <p>Note that the outliner sets tool tip text and a label on the second action,
 since it allows relabeling.&nbsp; When the readme outliner view is made active,
 its handlers (and their labels) will now appear in the workbench menu bar.</p>
 <p><img src="images/editoroutlineretargets.png" alt="Readme menu with one renamed editor action" border="0"></p>
 <p>Note that the relabeled action shows the new label.</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>
	Retargetable editor actions
	</TITLE>

	<link rel="stylesheet" type="text/css" HREF="../book.css">
	</HEAD>
	<BODY BGCOLOR="#ffffff">
	<h4>Retargetable editor actions</h4>
	<p>Recall that the <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
	tool</a> defines its own editor which contributes actions
	to the workbench menu bar using its <b>ReadmeEditorActionBarContributor</b>.  </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"
	<b>contributorClass="org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor</b>">
	</editor>
	</extension></pre>
	<p>Let's look closer at what happens in the contributor class.</p>
	<pre>public ReadmeEditorActionBarContributor() {
	...
	action2 = new <b>RetargetAction</b>(<b>IReadmeConstants.RETARGET2</b>, 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 <b>LabelRetargetAction</b>(<b>IReadmeConstants.LABELRETARGET3</b>, MessageUtil.getString("Editor_Action3"));
	action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
	action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
	...
	<b>handler2</b> = new EditorAction(MessageUtil.getString("Editor_Action2"));
	...
	<b>handler3</b> = new EditorAction(MessageUtil.getString("Editor_Action3"));
	...</pre>
	<p>When the contributor is created, it creates two retargetable actions (one
	that allows label update and one that does not).  Creation of the actions
	uses the same technique that the workbench uses.  It also creates two
	handlers that will be used for the actions when the editor is the active
	part.  </p>
	<p>But where are the handlers for the actions registered?  Setting the
	global handlers is done a little differently when your editor defines the
	retargeted actions.  Why?  Because your contributor is in charge of
	tracking the active view and hooking different handlers as different views or
	the editor itself becomes active.  (The workbench does this for you when
	you set a handler for one of its global actions).  Here's how the <b>ReadmeEditorActionBarContributor</b>
	sets things up:</p>
	<pre>public void init(IActionBars bars, IWorkbenchPage page) {
	super.init(bars, page);
	bars.setGlobalActionHandler(IReadmeConstants.RETARGET2, handler2);
	bars.setGlobalActionHandler(IReadmeConstants.LABELRETARGET3, handler3);
	...</pre>
	<p>First, the contributor registers its handlers for the retargeted
	actions.  This ensures that the contributor's actions will be run when the
	editor itself is active.  The next step is to register each <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
	</b>as a part listener on the page.</p>
	<pre> ...
	// Hook retarget actions as page listeners
	page.addPartListener(action2);
	page.addPartListener(action3);
	IWorkbenchPart activePart = page.getActivePart();
	if (activePart != null) {
	action2.partActivated(activePart);
	action3.partActivated(activePart);
	}
	}</pre>
	<p>Adding each <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
	</b>as a part listener means that it will be notified when the active part
	changes.  The action can get the correct global handler from the newly
	activated part.  (See the implementation of <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
	</b>for all the details.)   Note that to start, the action is seeded
	with the currently active part. </p>
	<p>When the editor contributor is disposed, it should unhook the retargetable
	actions as page listeners.</p>
	<pre>public void dispose() {
	// Remove retarget actions as page listeners
	getPage().removePartListener(action2);
	getPage().removePartListener(action3);
	}</pre>
	<p>Finally, recall that action bar contributors are shared among instances of
	the same editor class.  For this reason, the handlers must be notified when
	the active editor changes so that they can connect to the proper editor
	instance.</p>
	<pre>public void setActiveEditor(IEditorPart editor) {
	...
	handler2.setActiveEditor(editor);
	handler3.setActiveEditor(editor);
	...
	}</pre>
	<p>That completes the setup on the editor side.  When the editor is open
	and active, the handlers (and their labels) as defined by the <b>ReadmeEditorActionBarContributor
	</b>will appear in the workbench menu bar.</p>
	<p><img src="images/editorretargets.png" alt="Readme menu with three editor actions in workbench menu bar" border="0"></p>
	<p>Now that the editor's contributions are in place, what does a view do to register a handler?  The code on the client side
	is similar to registering a handler for a workbench action, except that the
	action id is the one defined by the plug-in's editor.  The <b>ReadmeContentOutlinePage</b>
	registers a handler for these actions.</p>
	<pre>public void createControl(Composite parent) {
	super.createControl(parent);
	...
	getSite().getActionBars().<b>setGlobalActionHandler(
	IReadmeConstants.RETARGET2, </b>
	new OutlineAction(MessageUtil.getString("Outline_Action2")));

	OutlineAction action = new OutlineAction(MessageUtil.getString("Outline_Action3"));
	<b>action.setToolTipText(MessageUtil.getString("Readme_Outline_Action3")); </b>
	getSite().getActionBars().<b>setGlobalActionHandler(
	IReadmeConstants.LABELRETARGET3, </b>
	action);
	...</pre>
	<p>Note that the outliner sets tool tip text and a label on the second action,
	since it allows relabeling.  When the readme outliner view is made active,
	its handlers (and their labels) will now appear in the workbench menu bar.</p>
	<p><img src="images/editoroutlineretargets.png" alt="Readme menu with one renamed editor action" border="0"></p>
	<p>Note that the relabeled action shows the new label.</p>



	</BODY>
	</HTML>