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);
}
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
.