Archive

Archive for January, 2010

Writing an Eclipse Plug-in (Part 17): Custom Project: Customizing the Perspective Menus Using Customize Perspective

January 9, 2010 2 comments

Almost time to add submenus!

But not today. I said almost.

Today, I want to take a look at the Customize Perspective dialog, what we got for free and what we still have to do to get that final finished look.

Back in Part 15 I mentioned that we should update three things when we add a New Wizard:

  1. Main menu File menu
  2. Toolbar
  3. Customize Perspective window

In Part 15 we updated the File menu, in part 16 we updated the toolbar and now we will take a look at what needs to be done to allow us to customize the custom perspective’s version of the File menu and the toolbar.

Before we do that let’s take a look at what Eclipse gave us for free and review how a user might customize a perspective.

Start the runtime workbench, switch to the Custom Perspective and open the Customize Perspective window by doing the following:

  • Window –> Open Perspective –> Other –> Custom Plug-in Perspective –> OK
  • Window –> Customize Perspective

Click on the Menu Visibility tab.

From the Menu Structure list we can see that our three New Wizard types are already listed. If a user were to decide that they did not want to see one or more of the custom wizards they could simply uncheck the undesired types. Simply adding the items to perspectiveExtensions as newWizardShortcuts added them to the File –> New main menu, the toolbar New button and this user configuration window.

Clicking on the Command Groups Availability tab does not show us anything related to our current task.

Click on the Shortcuts tab.

The Submenus choice of New has our Custom Wizards all selected. Anything checked/unchecked here will have the same impact as the Menu Visibility tab; things will appear or disappear from the main menu File –> New submenu and from the toolbar New drop down button.

The Submenus choice of Open Perspective will display the checked item under the main menu Window –> Open Perspective submenu. Since none of the items are check none of them appear when the user selects Window –> Open Perspective (they see the ubiquitous Other).

The Submenus choice of Show View will display the checked item under the main menu Window –> Show View. Again, none are chosen so Other will be seen instead.

Click on the Tool Bar Visibility tab. Be prepared to cover your eyes; it could get ugly.

The Tool Bar Structure list shows the second entry as existing, having three entries, but no label. What happened?

Way back in the history of Eclipse, say the 3.5 release, the Platform Command Framework was introduced. It deprecated the use of the actionSets extension to both make adding commands simpler and more flexible. The recommended way of doing what we did was the way we did it: use the org.eclipse.ui.menus extension. There is only one problem: the actionSets extension is still useful and is the missing part of today’s puzzle.

Today’s puzzle: how do we give our toolbar group a label?

I’m glad you asked.

How (are we doing it?)

Let’s walk the steps to give our custom wizard toolbar commands a label.

  1. plugin.xml –>Extensions –> Add
  2. Select org.eclipse.ui.actionSets and click Finish
  3. Change label (actionSet) to:
    • id: customplugin.toolbar
    • label: Hidden Clause Toolbar Commands
  4. Save plugin.xml
  5. Start the runtime workbench
  6. Change to the Custom Perspective and go to Window –> Customize Perspective

Woo hoo! Yes, success tastes sweet.

Now use the Externalize Strings Wizard to move the string Hidden Clause Toolbar Commands to our properties file.

Why (did we do it that way?)

As you may have already guessed, not using the actionSets extension had 0 impact on the behavior of the buttons we added. None. Nada. Zilch.

That didn’t stop me from spending a few hours to track down the proper configuration to make sure that I had a respectable label for my new toolbar buttons. Why bother spending the time? Because it matters to the user even if that user is me or my most hated enemy (well, maybe not my most hated enemy).

In this case, the use of the actionSets extension just got us our label and burned part of my Saturday afternoon. The use of actionSets continues the configuration-only streak I like so much.

Hey, if I can’t burn a few hours to help spread the good word about Eclipse then what can I do?

The cat is alive and has company.

What Just Happened?

With a simple addition to plugin.xml we were able to complete a successful addition of New Wizard functionality to the main menu, the toolbar and the Customize Perspective window. I’m happy. I hope you are too (but that doesn’t matter to me so much).

Thanks

Thanks to Michael Scharf at the Eclipse and Java Blog for just the example I was looking for on how to give the Customize Perspective Tool Bar Visibility toolbar group a label using just configuration.

Reference

Every pixel counts! The new eclipse fullscreen plugin…

Code

No code! Again!

plugin.xml

<?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>
   <extension
         point="org.eclipse.ui.actionSets">
      <actionSet
            id="customplugin.toolbar"
            label="Hidden Clause Toolbar Commands">
      </actionSet>
   </extension>

</plugin>

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
toolbar.actionSet.label = Hidden Clause Toolbar Commands

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

January 8, 2010 4 comments

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