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

 <link rel="stylesheet" type="text/css" HREF="../book.css">
 </HEAD>
 <BODY BGCOLOR="#ffffff">
 <H2>Registering editor actions</H2>
 <p>The text editor framework provides many utility classes that aid in presenting
 and updating text and source code.&nbsp; Now we will turn our attention to the workbench in
 which the editor is but one part.&nbsp; How does the editor interact with other
 workbench features such as context menus, menu bars, and tool bars?</p>

 <h3>Editor menu bar actions</h3>

 <p>To understand how editors register themselves with the workbench and provide
 actions for the workbench menu bar, see the section discussing <a href="workbench_basicext_editors.htm">org.eclipse.ui.editors</a>.&nbsp;
 We won't rehash that information here.&nbsp;&nbsp;We'll just take a quick look
 at the markup where the Java example editor registers its editor.</p>

 <pre>&lt;extension
       point=&quot;org.eclipse.ui.editors&quot;&gt;
    &lt;editor
          name=&quot;%javaEditorName&quot;
          icon=&quot;icons/obj16/java.png&quot;
          extensions=&quot;jav&quot;
          <b>contributorClass=&quot;org.eclipse.ui.examples.javaeditor.JavaActionContributor&quot;</b>
          class=&quot;org.eclipse.ui.examples.javaeditor.JavaEditor&quot;
          id=&quot;org.eclipse.ui.JavaEditor&quot;&gt;
    &lt;/editor&gt;
 &lt;/extension&gt;</pre>

 <p>Workbench menu bar actions are contributed by the <b>JavaActionContributor</b>.&nbsp;
   It implements actions that are placed in the workbench <b>Edit</b> menu and
   the workbench tool bar.</p>

 <pre>public JavaActionContributor() {
 	super();
 	fContentAssistProposal= <b>new RetargetTextEditorAction</b>(JavaEditorMessages.getResourceBundle(), &quot;ContentAssistProposal.&quot;); //$NON-NLS-1$
 	...
 	fContentAssistTip= new RetargetTextEditorAction(JavaEditorMessages.getResourceBundle(), &quot;ContentAssistTip.&quot;); //$NON-NLS-1$
 	...
 	fTogglePresentation= new PresentationAction();
 }</pre>
 <p>The first two actions are defined as retargetable text editor actions. The
   principle is similar to the <a href="wrkAdv_retarget.htm">retargetable actions</a>
   provided by the workbench. Retargetable text editor actions represent menu entries
   which the action contributor dynamically binds to corresponding actions provided
   by the active editor. When the active editor changes, the action to which a
   retargetable text editor action is bound changes as well. The following snippet
   shows that the editor action contributor finds the corresponding action by asking
   the editor for an action of a given id:</p>
 <pre>protected final IAction getAction(ITextEditor editor, String actionId) {<br>	return (editor == null ? null : editor.getAction(actionId));<br>}

 public void setActiveEditor(IEditorPart part) {<br>	super.setActiveEditor(part);<br>	ITextEditor editor= null;<br>	if (part instanceof ITextEditor)<br>		editor= (ITextEditor) part;<br>	fContentAssistProposal.setAction(getAction(editor, &quot;ContentAssistProposal&quot;));<br>	fContentAssistTip.setAction(getAction(editor, &quot;ContentAssistTip&quot;));<br>	fTogglePresentation.setEditor(editor);<br>	fTogglePresentation.update();<br>}</pre>
 <p>The id must be the same under which the action is registered with the editor
   as given here for the <b>JavaTextEditor</b>. (See also next section.):<br>
 </p>
 <pre>protected void createActions() {
 	super.createActions();

 	IAction a= new TextOperationAction(JavaEditorMessages.getResourceBundle(), &quot;ContentAssistProposal.&quot;, this, ISourceViewer.CONTENTASSIST_PROPOSALS); //$NON-NLS-1$
 	<b>a.setActionDefinitionId(ITextEditorActionDefinitionIds.CONTENT_ASSIST_PROPOSALS);</b>
 	setAction(&quot;ContentAssistProposal&quot;, a);

 	a= new TextOperationAction(JavaEditorMessages.getResourceBundle(), &quot;ContentAssistTip.&quot;, this, ISourceViewer.CONTENTASSIST_CONTEXT_INFORMATION);  //$NON-NLS-1$
 	a.setActionDefinitionId(ITextEditorActionDefinitionIds.CONTENT_ASSIST_CONTEXT_INFORMATION);
 	setAction(&quot;ContentAssistTip&quot;, a);
 }</pre>

 <p>The third action in the contributor is a concrete action added to the workbench
   tool bar.&nbsp; It toggles the state of the editor between showing the highlighted
   range (as dictated by the Java example's content outliner) and showing the entire
   file.&nbsp; This action only appears in the tool bar.</p>

 <h3>Editor context menus</h3>

 The editor context menus are created and managed in the <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>
  and <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a><b>
  </b>framework.
 <p>The method <b>createActions</b> is used to register actions with the editor.&nbsp;
   This includes actions appropriate for the editor context menus or any actions
   contributed in extension definitions.&nbsp; In the Java example editor, only
   the actions that get bound to the retargetable actions are created.&nbsp; However,
   the Java example editor also inherits the actions created by <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a>
   and its superclasses.&nbsp; These actions can be used in the editor context
   menus.</p>
 <p>The <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a>
 method <b>editorContextMenuAboutToShow</b> is used in the framework to allow
 editors to add actions to the context menu for the editing area.&nbsp; You can
 use a menu path to decide exactly where your action should appear.&nbsp; Valid
 menu paths inside the editor context menu are defined in the implementation of
 this method in <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>.</p>
 <p>There are several ways to add an action to this menu.&nbsp; The first way is
   by adding an action using only the id under which it is registered with the
   editor.&nbsp; For example, the <b>JavaTextEditor</b> adds its actions for content
   assistance to the menu when this method is called.&nbsp; Actions will not appear
   in the menu when no action is registered under the used id.</p>
 <pre>public void editorContextMenuAboutToShow(MenuManager menu) {
 	super.editorContextMenuAboutToShow(menu);
 	addAction(menu, &quot;ContentAssistProposal&quot;);
 	addAction(menu, &quot;ContentAssistTip&quot;);
 }</pre>
 <p>The superclass <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a>
   adds actions a second way - by specifying a menu group in the context menu
   for placing the action.&nbsp; In this case the actions (<b>Shift Left</b>, <b>Shift
   Right</b>) do appear in the context menu in the group defined by <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>.</p>
 <pre>protected void editorContextMenuAboutToShow(IMenuManager menu) {
 	super.editorContextMenuAboutToShow(menu);
 	addAction(menu, ITextEditorActionConstants.GROUP_EDIT, ITextEditorActionConstants.SHIFT_RIGHT);
 	addAction(menu, ITextEditorActionConstants.GROUP_EDIT, ITextEditorActionConstants.SHIFT_LEFT);
 }</pre>
 <p><img src="images/javaeditorcontextmenu.png" alt="Editor context menu" border="0"> </p>
 <p>The method <b>rulerContextMenuAboutToShow</b>  is used in the same way before
 the ruler's context menu is shown.&nbsp; The implementation of this method in <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>
 defines the groups in which items can be added to the menu. </p>
 <h3>Menu ids </h3>
 <p>The editor context and ruler context menus can be assigned ids so that other
 plug-ins can contribute to these menus in their extensions.&nbsp; The scheme for
 establishing menu ids is more flexible since the original version of the
 platform.&nbsp; However, the framework can run in a compatibility mode in order
 to remain compatible with plug-ins developed for the original version.&nbsp; You
 can use <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setCompatibilityMode()"><b>AbstractTextEditor.setCompatibilityMode()</b></a>
 to control this behavior.&nbsp; The default setting is true. </p>

 <h4>1.0 compatible menu ids </h4>
 <p>When the compatibility mode is true, the ids of the editor and ruler context
   menus can be set using <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>
   protocol.&nbsp; The methods <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setEditorContextMenuId(java.lang.String)"><b>setEditorContextMenuId</b></a>
   and <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setRulerContextMenuId(java.lang.String)"><b>setRulerContextMenuId</b></a>
   can be used for this purpose.&nbsp; Resetting the ids can be useful if you want
   to prevent inheriting menus that were contributed to superclass menus.&nbsp;
   For example, the <b>JavaTextEditor</b> in the example resets its context menu
   ids to be Java specific in order to prevent inheriting any generic text contributions
   from other plug-ins. </p>
 <pre>protected void initializeEditor() {
 	super.initializeEditor();
 	JavaEditorEnvironment.connect(this);
 	setSourceViewerConfiguration(new JavaSourceViewerConfiguration());
 	<b>setEditorContextMenuId(&quot;#JavaEditorContext&quot;);
 	setRulerContextMenuId(&quot;#JavaRulerContext&quot;); </b>
 }</pre>
 <p>If no id is set anywhere in the
   concrete hierarchy, the default ids defined by <b><a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html">AbstractTextEditor</a></b>
   will be used. </p>
 <h4>1.0 non-compatible menu ids </h4>
 <p>The editor context menu id is always <code>&lt;editor id&gt;.EditorContext</code>,
   where <code>&lt;editor id&gt;</code> is the id of the editor . The id of an
   editor is defined in the xml declaration of the editor. The ruler context menu
   id is always <code>&lt;editor id&gt;.RulerContext</code>.</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>
	Registering editor actions
	</TITLE>

	<link rel="stylesheet" type="text/css" HREF="../book.css">
	</HEAD>
	<BODY BGCOLOR="#ffffff">
	<H2>Registering editor actions</H2>
	<p>The text editor framework provides many utility classes that aid in presenting
	and updating text and source code.  Now we will turn our attention to the workbench in
	which the editor is but one part.  How does the editor interact with other
	workbench features such as context menus, menu bars, and tool bars?</p>

	<h3>Editor menu bar actions</h3>

	<p>To understand how editors register themselves with the workbench and provide
	actions for the workbench menu bar, see the section discussing <a href="workbench_basicext_editors.htm">org.eclipse.ui.editors</a>.
	We won't rehash that information here.  We'll just take a quick look
	at the markup where the Java example editor registers its editor.</p>

	<pre><extension
	point="org.eclipse.ui.editors">
	<editor
	name="%javaEditorName"
	icon="icons/obj16/java.png"
	extensions="jav"
	<b>contributorClass="org.eclipse.ui.examples.javaeditor.JavaActionContributor"</b>
	class="org.eclipse.ui.examples.javaeditor.JavaEditor"
	id="org.eclipse.ui.JavaEditor">
	</editor>
	</extension></pre>

	<p>Workbench menu bar actions are contributed by the <b>JavaActionContributor</b>.
	It implements actions that are placed in the workbench <b>Edit</b> menu and
	the workbench tool bar.</p>

	<pre>public JavaActionContributor() {
	super();
	fContentAssistProposal= <b>new RetargetTextEditorAction</b>(JavaEditorMessages.getResourceBundle(), "ContentAssistProposal."); //$NON-NLS-1$
	...
	fContentAssistTip= new RetargetTextEditorAction(JavaEditorMessages.getResourceBundle(), "ContentAssistTip."); //$NON-NLS-1$
	...
	fTogglePresentation= new PresentationAction();
	}</pre>
	<p>The first two actions are defined as retargetable text editor actions. The
	principle is similar to the <a href="wrkAdv_retarget.htm">retargetable actions</a>
	provided by the workbench. Retargetable text editor actions represent menu entries
	which the action contributor dynamically binds to corresponding actions provided
	by the active editor. When the active editor changes, the action to which a
	retargetable text editor action is bound changes as well. The following snippet
	shows that the editor action contributor finds the corresponding action by asking
	the editor for an action of a given id:</p>
	<pre>protected final IAction getAction(ITextEditor editor, String actionId) {<br> return (editor == null ? null : editor.getAction(actionId));<br>}

	public void setActiveEditor(IEditorPart part) {<br> super.setActiveEditor(part);<br> ITextEditor editor= null;<br> if (part instanceof ITextEditor)<br> editor= (ITextEditor) part;<br> fContentAssistProposal.setAction(getAction(editor, "ContentAssistProposal"));<br> fContentAssistTip.setAction(getAction(editor, "ContentAssistTip"));<br> fTogglePresentation.setEditor(editor);<br> fTogglePresentation.update();<br>}</pre>
	<p>The id must be the same under which the action is registered with the editor
	as given here for the <b>JavaTextEditor</b>. (See also next section.):<br>
	</p>
	<pre>protected void createActions() {
	super.createActions();

	IAction a= new TextOperationAction(JavaEditorMessages.getResourceBundle(), "ContentAssistProposal.", this, ISourceViewer.CONTENTASSIST_PROPOSALS); //$NON-NLS-1$
	<b>a.setActionDefinitionId(ITextEditorActionDefinitionIds.CONTENT_ASSIST_PROPOSALS);</b>
	setAction("ContentAssistProposal", a);

	a= new TextOperationAction(JavaEditorMessages.getResourceBundle(), "ContentAssistTip.", this, ISourceViewer.CONTENTASSIST_CONTEXT_INFORMATION); //$NON-NLS-1$
	a.setActionDefinitionId(ITextEditorActionDefinitionIds.CONTENT_ASSIST_CONTEXT_INFORMATION);
	setAction("ContentAssistTip", a);
	}</pre>

	<p>The third action in the contributor is a concrete action added to the workbench
	tool bar.  It toggles the state of the editor between showing the highlighted
	range (as dictated by the Java example's content outliner) and showing the entire
	file.  This action only appears in the tool bar.</p>

	<h3>Editor context menus</h3>

	The editor context menus are created and managed in the <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>
	and <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a><b>
	</b>framework.
	<p>The method <b>createActions</b> is used to register actions with the editor.
	This includes actions appropriate for the editor context menus or any actions
	contributed in extension definitions.  In the Java example editor, only
	the actions that get bound to the retargetable actions are created.  However,
	the Java example editor also inherits the actions created by <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a>
	and its superclasses.  These actions can be used in the editor context
	menus.</p>
	<p>The <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a>
	method <b>editorContextMenuAboutToShow</b> is used in the framework to allow
	editors to add actions to the context menu for the editing area.  You can
	use a menu path to decide exactly where your action should appear.  Valid
	menu paths inside the editor context menu are defined in the implementation of
	this method in <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>.</p>
	<p>There are several ways to add an action to this menu.  The first way is
	by adding an action using only the id under which it is registered with the
	editor.  For example, the <b>JavaTextEditor</b> adds its actions for content
	assistance to the menu when this method is called.  Actions will not appear
	in the menu when no action is registered under the used id.</p>
	<pre>public void editorContextMenuAboutToShow(MenuManager menu) {
	super.editorContextMenuAboutToShow(menu);
	addAction(menu, "ContentAssistProposal");
	addAction(menu, "ContentAssistTip");
	}</pre>
	<p>The superclass <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a>
	adds actions a second way - by specifying a menu group in the context menu
	for placing the action.  In this case the actions (<b>Shift Left</b>, <b>Shift
	Right</b>) do appear in the context menu in the group defined by <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>.</p>
	<pre>protected void editorContextMenuAboutToShow(IMenuManager menu) {
	super.editorContextMenuAboutToShow(menu);
	addAction(menu, ITextEditorActionConstants.GROUP_EDIT, ITextEditorActionConstants.SHIFT_RIGHT);
	addAction(menu, ITextEditorActionConstants.GROUP_EDIT, ITextEditorActionConstants.SHIFT_LEFT);
	}</pre>
	<p><img src="images/javaeditorcontextmenu.png" alt="Editor context menu" border="0"> </p>
	<p>The method <b>rulerContextMenuAboutToShow</b> is used in the same way before
	the ruler's context menu is shown.  The implementation of this method in <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>
	defines the groups in which items can be added to the menu. </p>
	<h3>Menu ids </h3>
	<p>The editor context and ruler context menus can be assigned ids so that other
	plug-ins can contribute to these menus in their extensions.  The scheme for
	establishing menu ids is more flexible since the original version of the
	platform.  However, the framework can run in a compatibility mode in order
	to remain compatible with plug-ins developed for the original version.  You
	can use <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setCompatibilityMode()"><b>AbstractTextEditor.setCompatibilityMode()</b></a>
	to control this behavior.  The default setting is true. </p>

	<h4>1.0 compatible menu ids </h4>
	<p>When the compatibility mode is true, the ids of the editor and ruler context
	menus can be set using <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>
	protocol.  The methods <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setEditorContextMenuId(java.lang.String)"><b>setEditorContextMenuId</b></a>
	and <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setRulerContextMenuId(java.lang.String)"><b>setRulerContextMenuId</b></a>
	can be used for this purpose.  Resetting the ids can be useful if you want
	to prevent inheriting menus that were contributed to superclass menus.
	For example, the <b>JavaTextEditor</b> in the example resets its context menu
	ids to be Java specific in order to prevent inheriting any generic text contributions
	from other plug-ins. </p>
	<pre>protected void initializeEditor() {
	super.initializeEditor();
	JavaEditorEnvironment.connect(this);
	setSourceViewerConfiguration(new JavaSourceViewerConfiguration());
	<b>setEditorContextMenuId("#JavaEditorContext");
	setRulerContextMenuId("#JavaRulerContext"); </b>
	}</pre>
	<p>If no id is set anywhere in the
	concrete hierarchy, the default ids defined by <b><a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html">AbstractTextEditor</a></b>
	will be used. </p>
	<h4>1.0 non-compatible menu ids </h4>
	<p>The editor context menu id is always <code><editor id>.EditorContext</code>,
	where <code><editor id></code> is the id of the editor . The id of an
	editor is defined in the xml declaration of the editor. The ruler context menu
	id is always <code><editor id>.RulerContext</code>.</p>


	</BODY>
	</HTML>