Archive
Writing an Eclipse Plug-in (Part 17): Custom Project: Customizing the Perspective Menus Using Customize Perspective
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:
- Main menu File menu
- Toolbar
- 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.
- plugin.xml –>Extensions –> Add
- Select org.eclipse.ui.actionSets and click Finish
- Change label (actionSet) to:
- id: customplugin.toolbar
- label: Hidden Clause Toolbar Commands
- Save plugin.xml
- Start the runtime workbench
- 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)
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.
- Open plugin.xml
- Add –> org.eclipse.ui.menus
- org.eclipse.ui.menus –> menuContribution
- locationURI: toolbar:org.eclipse.ui.main.toolbar
- toolbar:org.eclipse.ui.main.toolbar (menuContribution) –> toolbar
- id: customplugin.toolbar
- customplugin.toolbar (toolbar) –> command
- commandId: org.eclipse.ui.newWizard
- label: New Custom Project
- icon: icons/project-folder.png
- tooltip: New Custom Project
- style: push
- New Custom Project (command) –> parameter
- name: newWizardId
- value: customplugin.wizard.new.custom
- 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
- New Schema File (command)–> parameter
- name: newWizardId
- value: customplugin.wizard.file.schema
- 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
- New Deployment File (command)–> parameter
- name: newWizardId
- value: customplugin.wizard.file.deployment
- Save plugin.xml
- Start the runtime workbench. Pressing any of the new buttons should open the appropriate New Wizard
- 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.
- New Custom Project (command) –> visibleWhen
- false (visibleWhen) –> with
- variable: activeWorkbenchWindow.activePerspective
- activeWorkbenchWindow.activePerspective (with) –> equals
- value: customplugin.perspective
- activeWorkbenchWindow.activePerspective (with) –> equals
- variable: activeWorkbenchWindow.activePerspective
- false (visibleWhen) –> with
- New Schema File (command)–> visibleWhen
- false (visibleWhen) –> with
- variable: activeWorkbenchWindow.activePerspective
- activeWorkbenchWindow.activePerspective (with) –> equals
- value: customplugin.perspective
- activeWorkbenchWindow.activePerspective (with) –> equals
- variable: activeWorkbenchWindow.activePerspective
- false (visibleWhen) –> with
- New Deployment File (command)–> visibleWhen
- false (visibleWhen) –> with
- variable: activeWorkbenchWindow.activePerspective
- activeWorkbenchWindow.activePerspective (with) –> equals
- value: customplugin.perspective
- activeWorkbenchWindow.activePerspective (with) –> equals
- variable: activeWorkbenchWindow.activePerspective
- false (visibleWhen) –> with
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
- activeWorkbenchWindow.activePerspective (with) –> equals
- variable: activeWorkbenchWindow.activePerspective
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
