Jun 01
Quick Review: Defining a Command
In this blog I just want review the basic definition of a command by adding an additional Command to the example application using the steps defined in Part Two of the series on Eclipse RCP Commands.
We already have an Open eBook command that we made visible in the File menu of the MyReader application. Now we want to another item to the File menu, as well as to a context menu, to allow the user to annotate an eBook. Let us call this the Annotate eBook command. So let us follow the same eight steps we did for the Open eBook command.
Step 1: Create RCP application
Done already (I assume you are working from the example in Part Two.)
Step 2: Add org.eclipse.ui.commands extension to plugin.xml.
Done already. (see step 2 of previous blog)
Step 3: Declare Annotate eBook command.
right-click the org.eclipse.ui.commands extension, and select New -> Command from the context menu.
change the id to something like “com.richclientgui.myreader.commands.AnnotateEBook“
change the name to “Annotate eBook“
change description to “Annotates the current eBook”
Our plugin.xml now contains the following entry for the org.eclipse.ui.commands extension:
<extension
point="org.eclipse.ui.commands">
<command
defaultHandler="com.richclientgui.myreader.handlers.DefaultOpenEBookHandler"
description="Open an eBook file for reading"
id="com.richclientgui.myreader.commands.OpenEBook"
name="Open eBook">
</command>
<command
description="Annotates the current eBook"
id="com.richclientgui.myreader.commands.AnnotateEBook"
name="Annotate eBook">
</command>
</extension> |
Step 4: Add the org.eclipse.ui.menus extension to plugin.xml.
Done. (see step 4 of previous blog)
Step 5: Add the menuContribution element
We want to make our Annotate eBook command accessible both in the File menu, and in the context menu of the view. We already declared a menuContribution for the File menu (see step 5 of previous blog).
In order to make the command accessible in any context menu, we add a new menuContribution:
Right-click the org.eclipse.ui.menus extension, and select New -> menuContribution from the context menu
Change the locationURI to popup:org.eclipse.ui.popup.any?after=additions
Step 6: Add the Annotate eBook command to the menuContributions.
Right-click on the menuContribution created in step 5, and select New -> command from the context menu.
Change commandId to the id you provided to your Command definition in step 3.
Change mnemonic to “A” to underline the first letter of “Annotate” as your shortcut mnemonic for your command in the menu.
Repeat the above for the menu:file?before=quit menuContribution element.But now we have an interesting problem: the client wants the menu item in the File menu to read “Annotate eBook“, but the context menu’s item must read only “Annotate“. If we change the name attribute of the command definition, then it will change in both places. Luckily, the Commands API can help us out here. It is possible to change the presentation of commands for specific menu contributions by “overriding” the text to be used for labels and tooltips. To do this we:
Select the command contribution element under the popup:org.eclipse.ui.popup.any?after=additions menu contribution elment,
and change the value of the label attribute to “Annotate”.
Our org.eclipse.ui.menus extension definition in the plugin.xml now looks like:
<extension
point="org.eclipse.ui.menus">
<menuContribution
locationURI="menu:file?before=quit">
<command
commandId="com.richclientgui.myreader.commands.OpenEBook"
mnemonic="O"
style="push">
</command>
<command
commandId="com.richclientgui.myreader.commands.AnnotateEBook"
mnemonic="A"
style="push">
</command>
</menuContribution>
<menuContribution
locationURI="popup:org.eclipse.ui.popup.any?after=additions">
<command
commandId="com.richclientgui.myreader.commands.AnnotateEBook"
label="Annotate"
mnemonic="A"
style="push">
</command>
</menuContribution>
</extension> |
Step 7: Change command menu-item placement.
Let’s assume we are happy with the current placement.
Step 8: Implement a default Handler
Let us be lazy again and implement a very basic handler that just opens a message dialog. I will go into more detail about org.eclipse.core.commands.Handler and a future blog.
Implement a class called DefaultAnnotateEBookHandler that extends AbstractHandler, and only override the execute(…) method to call the JFace MessageDialog class to show some information.
Select the AnnotateEBookCommand definition from step 3 and select the DefaultAnnotateEBookHandler class as the defaultHandler‘s value.
The code for DefaultAnnotateEBookHandler looks something like this:
import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.swt.widgets.Display;
public class DefaultAnnotateEBookHandler extends AbstractHandler {
public Object execute(ExecutionEvent event) throws ExecutionException {
MessageDialog.openInformation(Display.getDefault().getActiveShell(),
"Annotate", "For now: write in the margins of the real book.");
return null;
}
} |
Where’s that context menu?
Those of you who have actually been entering the example code, would have found out by now that there is no context showing when running the example. Why not? Well, we have not created a context menu yet for our View. Do that, open the View class created by the New Plug-in Project Wizard in step 1 of my previous blog.
Change the code to look like this (basically adding the createContextMenu() method):
public class View extends ViewPart {
public static final String ID = "MyReader.view";
private TableViewer viewer;
//other code not shown...
public void createPartControl(Composite parent) {
viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL
| SWT.V_SCROLL);
viewer.setContentProvider(new ViewContentProvider());
viewer.setLabelProvider(new ViewLabelProvider());
viewer.setInput(getViewSite());
createContextMenu();
}
private void createContextMenu(){
final MenuManager mm = new MenuManager("view.popupmenu");
mm.setRemoveAllWhenShown(true);
mm.addMenuListener(new IMenuListener(){
public void menuAboutToShow(IMenuManager manager) {
mm.add(new Separator(IWorkbenchActionConstants.MB_ADDITIONS));
}
});
final Menu menu = mm.createContextMenu(viewer.getTable());
viewer.getTable().setMenu(menu);
getSite().registerContextMenu(mm, viewer);
} |
If you run the MyReader application now, you should get the context menu when right-clicking in the view, proudly showing your “Annotate” item.
Feel free to download the source code for this blog’s example.
Next up
Showing commands only when you want to…
References
Eclipse.org Commands Framework Article in bugzilla
Article on Eclipse Commands Framework, by Marc R. Hoffmann
Eclipse.org Wiki on Command Framework
Eclipse Commands Tutorial, by Lars Vogel
Enough said.
Leave a Reply
You must be logged in to post a comment.
