Registering editor actions

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?

Editor menu bar actions

To understand how editors register themselves with the workbench and provide actions for the workbench menu bar, see the section discussing org.eclipse.ui.editors.  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.

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

Workbench menu bar actions are contributed by the JavaActionContributor.  It implements actions that are placed in the workbench Edit menu and the workbench tool bar.

public JavaActionContributor() {
	super();
	fContentAssistProposal= new RetargetTextEditorAction(JavaEditorMessages.getResourceBundle(), "ContentAssistProposal."); //$NON-NLS-1$
	...
	fContentAssistTip= new RetargetTextEditorAction(JavaEditorMessages.getResourceBundle(), "ContentAssistTip."); //$NON-NLS-1$
	...
	fTogglePresentation= new PresentationAction();
}

The first two actions are defined as retargetable text editor actions. The principle is similar to the retargetable actions 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:

protected final IAction getAction(ITextEditor editor, String actionId) {
return (editor == null ? null : editor.getAction(actionId));
} public void setActiveEditor(IEditorPart part) {
super.setActiveEditor(part);
ITextEditor editor= null;
if (part instanceof ITextEditor)
editor= (ITextEditor) part;
fContentAssistProposal.setAction(getAction(editor, "ContentAssistProposal"));
fContentAssistTip.setAction(getAction(editor, "ContentAssistTip"));
fTogglePresentation.setEditor(editor);
fTogglePresentation.update();
}

The id must be the same under which the action is registered with the editor as given here for the JavaTextEditor. (See also next section.):

protected void createActions() {
	super.createActions();
		
	IAction a= new TextOperationAction(JavaEditorMessages.getResourceBundle(), "ContentAssistProposal.", this, ISourceViewer.CONTENTASSIST_PROPOSALS); //$NON-NLS-1$
	a.setActionDefinitionId(ITextEditorActionDefinitionIds.CONTENT_ASSIST_PROPOSALS);
	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); 
}

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.

Editor context menus

The editor context menus are created and managed in the AbstractTextEditor and TextEditor framework.

The method createActions 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 TextEditor and its superclasses.  These actions can be used in the editor context menus.

The TextEditor method editorContextMenuAboutToShow 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 AbstractTextEditor.

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 JavaTextEditor 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.

public void editorContextMenuAboutToShow(MenuManager menu) {
	super.editorContextMenuAboutToShow(menu);
	addAction(menu, "ContentAssistProposal"); 
	addAction(menu, "ContentAssistTip"); 
}

The superclass TextEditor adds actions a second way - by specifying a menu group in the context menu for placing the action.  In this case the actions (Shift Left, Shift Right) do appear in the context menu in the group defined by AbstractTextEditor.

protected void editorContextMenuAboutToShow(IMenuManager menu) {
	super.editorContextMenuAboutToShow(menu);
	addAction(menu, ITextEditorActionConstants.GROUP_EDIT, ITextEditorActionConstants.SHIFT_RIGHT);
	addAction(menu, ITextEditorActionConstants.GROUP_EDIT, ITextEditorActionConstants.SHIFT_LEFT);
}

Editor context menu

The method rulerContextMenuAboutToShow is used in the same way before the ruler's context menu is shown.  The implementation of this method in AbstractTextEditor defines the groups in which items can be added to the menu.

Menu ids

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 AbstractTextEditor.setCompatibilityMode() to control this behavior.  The default setting is true.

1.0 compatible menu ids

When the compatibility mode is true, the ids of the editor and ruler context menus can be set using AbstractTextEditor protocol.  The methods setEditorContextMenuId and setRulerContextMenuId 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 JavaTextEditor 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.

protected void initializeEditor() {
	super.initializeEditor();
	JavaEditorEnvironment.connect(this);
	setSourceViewerConfiguration(new JavaSourceViewerConfiguration());
	setEditorContextMenuId("#JavaEditorContext"); 
	setRulerContextMenuId("#JavaRulerContext"); 
}

If no id is set anywhere in the concrete hierarchy, the default ids defined by AbstractTextEditor will be used.

1.0 non-compatible menu ids

The editor context menu id is always <editor id>.EditorContext, where <editor id> 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 <editor id>.RulerContext.