Declarative Menus in JDeveloper Extensions – Part Four

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.

The Basics

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.

image

 

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.

Menu Placement

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:

image

The ID argument in the "menubar" element is set to point at the main menubar at the top of the IDE.

<menubar id="javax.ide.view.MAIN_WINDOW_MENUBAR_ID">

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:

image

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:

image

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:

image

 

produces this menu structure:

image

 

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">

to read:

<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.

image image

 

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:

<toolbar id="javax.ide.view.MAIN_WINDOW_TOOLBAR_ID">

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

image

The code above will add an icon as the last item on the Toolbar like this:

image

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.

 

Conclusion

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.

 

Previous parts in this topic:

Part One: Introduction and Creating an Action
Part Two: Creating Context Menus
Part Three: Creating Gallery menus (File / New) using a Wizard

Comments:

Thanks alot for this post !!!
Very short and clear.

When I studied this topic I found that developer can choose declarative tag "<menu-hook" in section "<hooks>" instead of section "<triggers-hooks>\<triggers>". IDE helps to make this mistake. In this case menu will not be appeared. I killed some time to understand it.

Posted by guest on January 06, 2013 at 01:02 PM PST #

Excellent post, thank you!

Posted by Alexis Lopez on January 27, 2014 at 05:53 AM PST #

Post a Comment:
  • HTML Syntax: NOT allowed
About

profile image
My name is John 'JB' Brock.
This Blog will focus on tips and tricks for working with the JDeveloper Extension SDK.
I hope to bring clarity to some of the mysteries around developing extensions for JDeveloper.


Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today