Writing an Eclipse Plug-in (Part 16): Custom Project: Customizing the Perspective Menus (Toolbar)

In this post we will add three custom toolbar buttons to the main toolbar of the Custom Perspective of the Eclipse workbench.

Before we do that, I would like to point out that one of the default buttons on the toolbar is the New button. When you click on the downward pointing arrow of the New button you will see something shocking (shocking I say!): the same entries as we added to File –> New appear in the New toolbar button. That’s because they are tied together; change one and you change the other. We could disable it, but why not leave well enough alone? While it is true we didn’t mean to turn on this behavior we can bask in the glory of a job accidentally well done.

Life is full of disappointments.

Today we will add three buttons to the toolbar and have them create either a new Custom Project, Schema file or Deployment file. Seems kinda redundant in light of the behavior of the New toolbar button, but I want single custom command buttons in any case.

We need 3 new images; one for each button. I am reusing the images from a Hidden Clause Custom Project, Schema file and Deployment file:

How (are we doing it?)

Let’s add the buttons to the toolbar together with the configuration needed to open the appropriate New Wizards.

1. Open plugin.xml
2. Add –> org.eclipse.ui.menus
3. org.eclipse.ui.menus –> menuContribution
   • locationURI: toolbar:org.eclipse.ui.main.toolbar
4. toolbar:org.eclipse.ui.main.toolbar (menuContribution) –> toolbar
   • id: customplugin.toolbar
5. customplugin.toolbar (toolbar) –> command
   • commandId: org.eclipse.ui.newWizard
   • label: New Custom Project
   • icon: icons/project-folder.png
   • tooltip: New Custom Project
   • style: push
6. New Custom Project (command) –> parameter
   • name: newWizardId
   • value: customplugin.wizard.new.custom
7. customplugin.toolbar (toolbar) –> command
   • commandId: org.eclipse.ui.newWizard
   • label: New Schema File
   • icon: icons/schema-file_16x16.png
   • tooltip: New Schema File
   • style: push
8. New Schema File (command)–> parameter
   • name: newWizardId
   • value: customplugin.wizard.file.schema
9. customplugin.toolbar (toolbar) –> command
   • commandId: org.eclipse.ui.newWizard
   • label: New Deployment File
   • icon: icons/deployment-file_16x16.png
   • tooltip: New Deployment File
   • style: push
10. New Deployment File (command)–> parameter
    • name: newWizardId
    • value: customplugin.wizard.file.deployment
11. Save plugin.xml
12. Start the runtime workbench. Pressing any of the new buttons should open the appropriate New Wizard
13. Hold the mouse over the buttons; the tooltips should display the string for which we configured each button

Oh oh! A bug! The toolbar buttons appear in all of the perspectives not just in the Custom Perspective. That behavior is just offensive; okay, maybe not offensive, but wrong in this case.

We will fix that with the following configuration.

1. New Custom Project (command) –> visibleWhen
   • false (visibleWhen) –> with
     • variable: activeWorkbenchWindow.activePerspective
       • activeWorkbenchWindow.activePerspective (with) –> equals
         • value: customplugin.perspective
2. New Schema File (command)–> visibleWhen
   • false (visibleWhen) –> with
     • variable: activeWorkbenchWindow.activePerspective
       • activeWorkbenchWindow.activePerspective (with) –> equals
         • value: customplugin.perspective
3. New Deployment File (command)–> visibleWhen
   • false (visibleWhen) –> with
     • variable: activeWorkbenchWindow.activePerspective
       • activeWorkbenchWindow.activePerspective (with) –> equals
         • value: customplugin.perspective

So where did the variable name activeWorkbenchWindow.activePerspective come from? From Eclipse, of course! Oh, okay, take a look at the Command Core Expressions entry in the Eclipse wiki for more interesting variables you can use in your elements. We won’t be using any others…this time.

Why (did we do it that way?)

There is a lot of configuration going on here. There are only two obscure/interesting points.

Step #3:

• org.eclipse.ui.menus –> menuContribution
  • locationURI: toolbar:org.eclipse.ui.main.toolbar

The locationURI field tells Eclipse where to place the three buttons: in the toolbar (hence the use of a scheme named toolbar) and which toolbar to use (the main toolbar which has an id of org.eclipse.ui.main.toolbar). Makes sense once you know it, but it would be helpful to have more examples. But that’s just me.

Step #1, 2 and 3 take care of hiding the toolbar buttons in all perspectives except the Custom Perspective.

• false (visibleWhen) –> with
  • variable: activeWorkbenchWindow.activePerspective
    • activeWorkbenchWindow.activePerspective (with) –> equals
      • value: customplugin.perspective

The visibleWhen element works with the usual choices of adapt, and, count, equals, etc. By selecting the with element you have to supply one of the variables listed in the Command Core Expressions listed in the Eclipse wiki. At runtime the variable activeWorkbenchWindow.activePerspective contains the id of the current perspective so including the equals element with the id of the Custom Perspective (customplugin.perspective) means that the only time the selected button will appear is when the Custom Perspective is open.

Don’t forget to open plugin.xml and externalize the new strings otherwise you will be stuck with a bunch of warnings that are not worth tolerating.

What Just Happened?

In today’s episode:

• we added 3 buttons to the main toolbar
• configured the toolbar buttons to open the appropriate wizards
• configured the toolbar buttons to only appear in the custom perspective

Once again, we have managed to add a significant amount of behavior and not had to write any code. It doesn’t get any better than that (well, maybe it does, but I’m not sure if I’m ready to brag about that kind of thing).

Thanks

David Carver and his blog entry Adding Wizards To Toolbars.

Code

Oh, yeah. None.

However, there are the entries in the plugin.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
   <extension
         point="org.eclipse.ui.newWizards">
      <category
            id="customplugin.category.wizards"
            name="%category.name">
      </category>
      <wizard
            category="customplugin.category.wizards"
            class="customplugin.wizards.CustomProjectNewWizard"
            finalPerspective="customplugin.perspective"
            icon="icons/project-folder.png"
            id="customplugin.wizard.new.custom"
            name="%wizard.name">
      </wizard>
      <wizard
            category="customplugin.category.wizards"
            class="customplugin.wizards.CustomProjectNewSchemaFile"
            descriptionImage="icons/schema-file_32x32.png"
            icon="icons/schema-file_16x16.png"
            id="customplugin.wizard.file.schema"
            name="%wizard.name.schema">
      </wizard>
      <wizard
            category="customplugin.category.wizards"
            class="customplugin.wizards.CustomProjectNewDeploymentFile"
            descriptionImage="icons/deployment-file_32x32.png"
            icon="icons/deployment-file_16x16.png"
            id="customplugin.wizard.file.deployment"
            name="%wizard.name.deployment">
      </wizard>
   </extension>
   <extension
         point="org.eclipse.ui.perspectives">
      <perspective
            class="customplugin.perspectives.Perspective"
            icon="icons/perspective.png"
            id="customplugin.perspective"
            name="%perspective.name">
      </perspective>
   </extension>
   <extension
         point="org.eclipse.ui.perspectiveExtensions">
      <perspectiveExtension
            targetID="customplugin.perspective">
         <view
               id="customnavigator.navigator"
               minimized="false"
               ratio=".25"
               relationship="left"
               relative="org.eclipse.ui.editorss">
         </view>
      </perspectiveExtension>
   </extension>
   <extension
         id="customplugin.projectNature"
         point="org.eclipse.core.resources.natures">
      <runtime>
         <run
               class="customplugin.natures.ProjectNature">
         </run>
      </runtime>
   </extension>
   <extension
         point="org.eclipse.ui.ide.projectNatureImages">
      <image
            icon="icons/project-folder.png"
            id="customplugin.natureImage"
            natureId="customplugin.projectNature">
      </image>
   </extension>
   <extension
         id="customplugin.contenttype"
         point="org.eclipse.core.contenttype.contentTypes">
      <content-type
            base-type="org.eclipse.core.runtime.xml"
            file-extensions="xml"
            id="customplugin.contenttype.schema"
            name="%content-type.name.schema"
            priority="normal">
         <describer
               class="org.eclipse.core.runtime.content.XMLRootElementContentDescriber2">
            <parameter
                  name="element"
                  value="hc-schema">
            </parameter>
         </describer>
      </content-type>
      <content-type
            base-type="org.eclipse.core.runtime.xml"
            file-extensions="xml"
            id="customplugin.contenttype.deployment"
            name="%content-type.name.deployment"
            priority="normal">
         <describer
               class="org.eclipse.core.runtime.content.XMLRootElementContentDescriber2">
            <parameter
                  name="element"
                  value="hc-deployment">
            </parameter>
         </describer>
      </content-type>
   </extension>
   <extension
         point="org.eclipse.ui.perspectiveExtensions">
      <perspectiveExtension
            targetID="customplugin.perspective">
         <newWizardShortcut
               id="customplugin.wizard.new.custom">
         </newWizardShortcut>
         <newWizardShortcut
               id="customplugin.wizard.file.schema">
         </newWizardShortcut>
         <newWizardShortcut
               id="customplugin.wizard.file.deployment">
         </newWizardShortcut>
      </perspectiveExtension>
   </extension>
   <extension
         point="org.eclipse.ui.menus">
      <menuContribution
            locationURI="toolbar:org.eclipse.ui.main.toolbar">
         <toolbar
               id="customplugin.toolbar">
            <command
                  commandId="org.eclipse.ui.newWizard"
                  icon="icons/project-folder.png"
                  label="%customproject.label"
                  style="push"
                  tooltip="%customproject.tooltip">
               <parameter
                     name="newWizardId"
                     value="customplugin.wizard.new.custom">
               </parameter>
               <visibleWhen
                     checkEnabled="false">
                  <with
                        variable="activeWorkbenchWindow.activePerspective">
                     <equals
                           value="customplugin.perspective">
                     </equals>
                  </with>
               </visibleWhen>
            </command>
            <command
                  commandId="org.eclipse.ui.newWizard"
                  icon="icons/schema-file_16x16.png"
                  label="%schema.label"
                  style="push"
                  tooltip="%schema.tooltip">
               <parameter
                     name="newWizardId"
                     value="customplugin.wizard.file.schema">
               </parameter>
               <visibleWhen
                     checkEnabled="false">
                  <with
                        variable="activeWorkbenchWindow.activePerspective">
                     <equals
                           value="customplugin.perspective">
                     </equals>
                  </with>
               </visibleWhen>
            </command>
            <command
                  commandId="org.eclipse.ui.newWizard"
                  icon="icons/deployment-file_16x16.png"
                  label="%deployment.label"
                  style="push"
                  tooltip="%deployment.tooltip">
               <parameter
                     name="newWizardId"
                     value="customplugin.wizard.file.deployment">
               </parameter>
               <visibleWhen
                     checkEnabled="false">
                  <with
                        variable="activeWorkbenchWindow.activePerspective">
                     <equals
                           value="customplugin.perspective">
                     </equals>
                  </with>
               </visibleWhen>
            </command>
         </toolbar>
      </menuContribution>
   </extension>

</plugin>

OSGI-INF/I10n/bundle.properties

#Properties file for customplugin
Bundle-Name = Customplugin Plug-in
category.name = Custom Wizards
wizard.name = Custom Project
perspective.name = Custom Plug-in Perspective
content-type.name.schema = Hidden Clause Schema Definition
content-type.name.deployment = Hidden Clause Deployment Definition
wizard.name.schema = Schema File
wizard.name.deployment = Deployment File

customproject.label = New Custom Project
customproject.tooltip = New Custom Project
schema.label = New Schema File
schema.tooltip = New Schema File
deployment.label = New Deployment File
deployment.tooltip = New Deployment File