Adding to an existing menu

Revision as of 14:39, 18 November 2022 by David Geleßus (talk | contribs) (Update homepage link)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

We use the Eclipse Command Framework. This page describes how you can add a menu item "Open Website" to one of the ProB submenus (in this case Contact).If you want to contribute your own menu to the ProB menubar (i.e., the main menu in the standalone version or the ProB menu in the Rodin plug-in version of ProB) see Adding an own submenu


1. Create an extension to org.eclipse.ui.commands and add a new command.
You will end up with something like

<extension point="org.eclipse.ui.commands">
    <command
           categoryId="de.prob.ui.commands.category"
           id="de.prob.ui.openWebsite"
           name="Open Website">
        <commandParameter
              id="de.prob.ui.openwebsite.url"
              name="URL"
              optional="false">
        </commandParameter>
     </command>
</extension>

The example also shows that commands can have parameters. In this case we want to provide different URLs. Section 3 will explain how the command is parameterized.

2. Create an extension to org.eclipse.ui.handlers and add a handler. The handler will link the command with its implementation, i.e., when the command is triggered the execute method of the handler is being called.

<extension
        point="org.eclipse.ui.handlers">
     <handler
           class="de.prob.ui.internal.OpenWebsiteCommand"
           commandId="de.prob.ui.openWebsite">
     </handler>
  </extension>

The implementation of the execute method of OpenWebsiteCommand looks like

public Object execute(final ExecutionEvent event) throws ExecutionException {
  String url = event.getParameter("de.prob.ui.openwebsite.url");
  try {
    URL u = new URL(url)
    PlatformUI.getWorkbench().getBrowserSupport().getExternalBrowser().openURL(u);
  } 
  catch (PartInitException e) { /* handle exception */ } 
  catch (MalformedURLException e) { /* handle exception */ } 
  return null;
}

The event object passed to the method contains the information about parameters, in our case we get a String containing the URL, but the parameters can also be more complex. For more complex types one needs to create a commandParameterType within the command extension.

Aside: It is quite usefull in User Interfaces to get the IWorkbenchWindow object related to the event (we don't need it in this particular example). This can be done within the execute method using

IWorkbenchWindow window = HandlerUtil.getActiveWorkbenchWindowChecked(event); 

3. Now we add an instance of the command to the menu bar

 <extension
        point="org.eclipse.ui.menus">
     <menuContribution
           locationURI="menu:contact">
        <command
              commandId="de.prob.ui.openWebsite"
              label="Open ProB Website"
              mnemonic="W"
              style="push">
           <parameter
                 name="de.prob.ui.openwebsite.url"
                 value="https://prob.hhu.de/">
           </parameter>
        </command>
       </menuContribution>
</extension>

This will show a menu item in the contact submenu and it will pass the parameter into the command. We can instantiate the same command with a different URL and add it to the same menu

<extension
        point="org.eclipse.ui.menus">
     <menuContribution
           locationURI="menu:contact">
     <command
              commandId="de.prob.ui.openWebsite"
              label="Open Google"
              mnemonic="G"
              style="push">
           <parameter
                 name="de.prob.ui.openwebsite.url"
                 value="http://www.google.com">
           </parameter>
        </command>
       </menuContribution>
</extension>