New menu contribution extension

Background

I started this post to help me and hopefully you understand what is involved in using org.eclipse.ui.menus. I'm assuming you have a good understanding of Eclipse RCP and you would use this as a reference guide. It stems from my fustration in using the Eclipse wiki and finding help with the new features of Eclipse Europa.

The Eclipse Europa (3.3) release has changed the org.eclipse.ui.menus extension to improve menu, toolbar, and popup placement and visibility. The idea is to move away from the old extensions.

• org.eclipse.ui.actionSets
• org.eclipse.ui.editorActions
• org.eclipse.ui.popupMenus
• org.eclipse.ui.viewActions

Where to start

I've listed the extensions with links to appropriate Eclipse help page and wiki page.

Scared yet? It is well worth the effort to learn and thus avoid, as much as possible, the legacy action extensions listed above.

What do you get? A very flexible and powerful way of creating menus, toolbars, and popup menus. I found the legacy action extensions to be difficult to implement complex menu and toolbar interactions and I ended up writing less java code.

org.eclipse.ui.commands

A logical representation of a task. A handler does the work. See wiki and help guide.

org.eclipse.ui.handlers

A handler does what the command represents. See wiki and help guide.

org.eclipse.ui.bindings

Bind a command to a key. See wiki and help guide.

org.eclipse.ui.contexts

Bindings can be organized into a context. See wiki.

org.eclipse.ui.commandImages

Give a command an image.

org.eclipse.ui.editor

See RCP Text Editor Example.

org.eclipse.ui.view

See Creating an Eclipse View.

org.eclipse.ui.menus

Add custom additions to the main menu, main toolbars, and view/editor context menus, toolbars, popup menu, and trim. See wiki and help guide.

Important to understand

Command Core Expressions needs to be understood to make your commands visible and handlers enabled.

Read up on Basic workbench extension points using commands.

How the old maps to the new.

Examples

Example code can be found in org.eclipse.ui.examples.contributions.

Development strategies

Keep notes of the commands you are creating and how they can be reused.

1. Create or reuse a org.eclipse.ui.contexts.
2. Create a command category.
3. Create a command.
4. Create a command image (optional).
5. Create a binding schema.
6. Create a binding for a command.
7. Create a handler.
8. Create a menu contribution.

Debugging and tracing

Check out this wiki page for details on a few debugging strategies.

Common mistakes

• Commands added to a view toolbar must have either a label or icon defined in the menuContribution or icons defined in the org.eclipse.ui.commandImages.
• Forget to look at org.eclipse.ui.menus.MenuUtil for correct spelling of menu constants.

Europa help, gone without a trace

The org.eclipse.help* plugins have had all of the tracing features removed for the Europa release. Why? Only this bug 197335 report will possibly tell.

They did leave the .options file in the plugins so that your run configuration appears to support help tracing. It doesn't so don't waste your time trying.

What you can do is set a break point in org.eclipse.help.HelpSystem.getContext(String). It will show you the help context id being used. Most problems are due to simple typos in your help *.xml file or in your view/editor/dialog call to PlatformUI.getWorkbench().getHelpSystem().setHelp(Control, String).

I come to praise TPTP and bury it

I tried out the new TPTP (Test & Performance Tools Platform) tool yesterday. In the end I was able to get it to work but there are a number of very annoying problems.

The first issue is the new monitor page in the run configuration will randomly forget its settings. If Memory Analysis is selected make sure you edit its options to track object allocation sites. Otherwise you'll have a hard time tracing object allocation back to your source code.

The big issue is with the Java Profiling options. Manually setting a content filter set does not work as expected. The Default filter set does not work as expected (already reported to Eclipse). The filter below hides all org* classes instead of only showing org.apache* classes.

    org*                 *    EXCLUDE
    org.apache*          *    INCLUDE

Specify the filter below worked only for me in our group.

    com.kelman.*         *    INCLUDE

Everyone else had to use the following.

    com.kelman*         *    INCLUDE

The potential issue is Java 1.6 is not supported by TPTP. For the project I'm working on it is not an issue since Java 1.5 works extremely well for us.

The documentation for TPTP is overly complex for someone wanting to simply run an application and do a bit of performance analysis.

Now that I've buried TPTP its time for a bit of praise.

Once we figured out the monitor configuration problems the tool worked like a charm. A great new feature is the integration of the Agent Controller. If you are debugging an application on a local machine, TPTP will start the Agent Controller. No more worries about installing and managing the Agent Controller as a service.

TPTP by default tries to show you as little as possible. I think this is a good thing. It keeps TPTP responsive and forces you to think hard about what packages or classes should be included in the performance analysis.

BIRT is not evil

I'm at the point in my project that most programmers dread. It is report generating time! Yeah, its not very exciting stuff to code. With the growing buzz around BIRT (2.2) (Business Intelligence and Reporting Tools) I thought I would give it a try.

I'm using BIRT with Eclipse Europa (3.3). Talk about a nice reporting tool. Building a report using the design tools was easy and obvious. I hooked it up to one of our Postgres databases (8.2.3) using a type 4 JDBC driver without any problems. A little SQL coding for a query and I was dragging and dropping fields into the report.

Creating customized formats for the duration fields and integrating the report into our application wasn't obvious so I went and bought the only two books available about BIRT.

	BIRT: A Field Guide to Reporting (The Eclipse Series) by Diana Peh, Alethea Hannemann, Nola Hague ISBN: 0321442598
	Integrating and Extending BIRT (The Eclipse Series) by Jason Weathersby, Don French, Tom Bondur, Jane Tatchell, Iana Chatalbasheva ISBN: 0321443853

Both are easy to read, gave me additional background to how BIRT works and most importantly saved me a good deal of time learning how to use BIRT and integrating it into our application.

Adding Go Into and Go Up to CNF view

I have always liked the Go Into and Up features of the navigation view in the Eclipse IDE. Here is a simple way of adding it to your CNF (Common Navigator Framework) view. I'm assuming you are familiar with CNF, if not check out Common Navigator Framework.
You will need to add the Go Into action to your CNF view toolbar and the Up feature to the CNF view actions.

public class GoIntoAction extends Action {
    private IWorkbenchPage page;
    private CommonViewer commonViewer;

    public GoIntoAction(IWorkbenchPage p, ISelectionProvider selectionProvider) {
        page = p;
        commonViewer = (CommonViewer) selectionProvider;
    }

    @SuppressWarnings("unchecked")
    protected List getSelectedResources() {
        ISelection selection = commonViewer.getSelection();
        List resources = null;
        if (selection.isEmpty()) {
            resources = new ArrayList();
            resources.add(ResourcesPlugin.getWorkspace().getRoot());
        } else {
            resources = ((IStructuredSelection) selection).toList();
        }
        return resources;
    }

    @Override
    @SuppressWarnings("unchecked")
    public boolean isEnabled() {
        List resources = getSelectedResources();
        return (resources.size() == 1) && (resources.get(0) instanceof IContainer);
    }

    @Override
    @SuppressWarnings("unchecked")
    public void run() {
        ((ProjectExplorerView)page.getActivePart()).setInput(getSelectedResources().get(0));
    }
}

The GoIntoAction is added to the CNF view actionProvider extension. See here for Michael Elder's article on defining the viewer.

public class GoUpAction extends Action implements IViewActionDelegate {
    private ProjectExplorerView view;
    private CommonViewer commonViewer;

    public void init(IViewPart aView) {
        view = (ProjectExplorerView) aView;
        commonViewer = ((ProjectExplorerView) aView).getCommonViewer();
    }

    @SuppressWarnings("unchecked")
    @Override
    public boolean isEnabled() {
        return !(commonViewer.getInput() instanceof IWorkspaceRoot);
    }

    public void run(IAction action) {
        view.setInput(((IResource) commonViewer.getInput()).getParent());
        action.setEnabled(isEnabled());
    }

    public void selectionChanged(IAction action, ISelection aSelection) {
        action.setEnabled(isEnabled());
    }
}

Now add the GoUpAction to the CNF view toolbar.

<extension point="org.eclipse.ui.viewActions">
    <viewContribution
        id="com.kelman.navigator.ui.view.projectexplorercontribution"
        targetID="com.kelman.navigator.ui.view.ProjectExplorer">
       <action
            class="com.kelman.navigator.ui.actions.GoUpAction"
            icon="icons/elcl16/up_nav.gif"
            id="com.kelman.navigator.ui.actions.goupaction"
            label="%goUp.label"
            style="push"
            toolbarPath="Normal/additions"
            tooltip="%goUp.tooltip">
       </action>
    </viewContribution>
</extension>

I extracted the icons from the org.eclipse.ui.ide_3.*.jar file and dropped them into my plugin. You will need the following method in your CommonNavigator implementation.

    public void setInput(Object aObject) {
        IResource resource = (IResource) aObject;
        getCommonViewer().setInput(resource);
        setContentDescription(resource.getName());
    };