Declarative Menus in JDeveloper Extensions – Part Four
By John 'JB' Brock on Sep 12, 2010
Part Four: Creating Toolbar and Menubar menus
If you came to this post directly, you may want to take a look at the previous posts first.
Part One: Introduction and Creating an Action
Part Two: Creating Context Menus
Part Three: Creating Gallery menus (File / New) using a Wizard
The main Menubar and Toolbar areas at the top of the IDE are natural places to add your extension to the IDE. It's extremely simple to add a menu item or icon to these locations, but it takes a little more info to get things into the right location and arranged the way you want them. We'll cover all of this in the final part of this topic.
I'm going to use the JDeveloper SDK Sample project, "First Sample" to demonstrate the menu layouts.
Adding a menu item or toolbar icon can be done completely from the extension.xml file. The example below shows both a menu and a toolbar being added.
Both the Menubar and Toolbar elements are placed inside of the "<menu-hook>" element section.
Getting down to where you can actually define your menu or toolbar item is just a matter of nesting into the proper structure.
Menus go inside the "<menus>" element and toolbars go inside the "<toolbars>" element, just as you would expect.
Remember that the icon and text that your menu item uses, like the name of the menu or description, are defined in the <action> element, not in the menu or toolbar element. Go back and look at Part One of this topic if you are not familiar with creating Actions.
The more complex part of creating menus is getting the menu item into the location that you want it on the Menubar, or creating a more complex nested menu structure for more then one action.
Within this basic structure in the xml file:
The ID argument in the "menubar" element is set to point at the main menubar at the top of the IDE.
The ID argument in the "menu" element is set to what existing menu you want to add your menu item to.
The RefID's for all of the main IDE Menubar menus are:
File -- javax.ide.FILE_MENU_ID
Edit -- Edit
View -- javax.ide.VIEW_MENU_ID
Application -- APPLICATION_MENU
Refactor -- RefactorMenuId
Search -- Search
Navigate -- Navigate
Build -- Build
Run -- Run
Source -- This is a dynamic menu and not recommended for adding your own items
Versioning -- Versioning
Tools -- Tools
Window -- It is not recommended to add menu items to this menu
Help -- javax.ide.HELP_MENU_ID
Inside of the menu element you will create your own <section> element to place your menu item into.
The section element has it's own ID argument that you can set to whatever name you like. It's important to set an ID so that it can be used with the Before and After arguments if you need to control the order that the menu sections are displayed in. More on ordering in a little bit.
After you have your section defined, you can add as many menu "item" elements as you like in that section. The item element has the "action-ref" argument that references back to your action ID to get all of the details about your menu and what it's supposed to do.
Creating your own Top Level menu
If you find that your extension just doesn't quite fit into one of the existing top level menus, you can create your own. Follow the same structure as above, but you now set a "label" element to the name of your new menu. It all looks like this:
Notice that I also set the mnemonic for my new menu item to be the first "M" in the menu name. The result looks like this:
Nesting Menu items
Many times you will have more then one menu item that you want to group into the same topic. You could create your own menu like we just described, and list all of the items in there, or you can create your own section under an existing menu, then nest your menu items into a submenu list.
The nesting of menus is simply done by nesting the xml elements.
This xml section:
produces this menu structure:
Ordering the menu items
Throughout the examples in this blog, you have probably seen the "After" argument used in a lot of places. You can control the placement of your menu item and menu section by using the After or Before arguments to tell the IDE where to place your item or section in relation to those items and sections around it.
This sounds pretty easy in theory, but the implementation side of this is a little more on the trial and error side of things.
To place a menu item or section before or after another item or section, you have to know the ID(IdRef) for that menu item or section. I showed a really good way to find those IdRef's in a previous post on my blog: How to find the idref for most menu commands.
This will help you find the ID for the menu items. For the Sections, it is a little bit more difficult to find them. I was able to track most of them down in the Jdev SDK API Reference Docs
Finding the Section ID's is a bit of work, but here are a few tips that may make things a little easier for you:
- If the Menu ID starts with "javax.ide.*" there is a good chance that the section ID's for those menu sections will be found in the javax.ide.* IDEConstants Class.
- For most of the other section ID's a good place to start is the Constant Field Values list in the API Docs.
Using the SDK sample project, if we change the line:
<section id="esdksample.customsection" before="javax.ide.NEW_SECTION_ID">
<section id="esdksample.customsection" after="javax.ide.PRINT_SECTION_ID">
The new menu item will show up at the bottom of the File menu, just after the Print section instead of at the top like it was doing.
The Basics of Toolbar icons
Adding an icon to the Toolbar is really the same as the Menubar in almost all aspects. The xml structure is the same, except you replace <menus> with <toolbars> and <menu> with <toolbar>.
To add icons to the IDE's main Toolbar, the ID argument in the <toolbar> element should be:
The placement of your icon is still controlled by the Before and After arguments in the <section> element.
The four main sections of the Toolbar menu are:
File_New -- javax.ide.NEW_SECTION_ID
Undo_Redo -- oracle.ide.TB_UNDO_REDO_SECTION_ID
Copy_Paste -- javax.ide.COPY_PASTE_SECTION_ID
Forward_Back -- oracle.ide.TB_BACK_FORWARD_SECTION_ID
To place an icon after the last section in the Toolbar (the Debug icon) you can use:
Debug -- oracle.jdeveloper.TB_RUN_DEBUG_SECTION
The code above will add an icon as the last item on the Toolbar like this:
The main thing to remember when working with the Toolbar, is that you will be adding your own "section" to the Toolbar and not adding an icon to an existing section like you do when adding a menu to an existing Menu section.
That covers pretty much all there is to know about Declarative Menus and Toolbars. I hope this four part series has been helpful to everyone.
As usual, please post up any questions or personal experiences in the comments.