Adding Menus and Toolbar Buttons

When you want to add support for a new command through the menu or toolbar, you add an action. The actions in your extensions are typically ways for your extension's user to get to the extension's core functionality.

You can associate actions with:

You define the user interface for actions by specifying buttons or menus in your extension XML file. You define the logic for actions in Java code, then specify those Java classes in the extension XML.

Be sure to see the reference for ActionSvc for information on building action extensions. Also, for action extension samples, see MenuItems Sample, PopupAction Sample, and ToolbarButton Sample.

Building Action Extensions

In your extension.xml file you sketch out your action's user interface as well as connect the action UI and logic to the IDE. The UI for your action will be a menu command (including a popup) or a toolbar button. In your extension XML, part of your user interface can be defined through the <action-ui> element, but you may want to generate user interface dynamically with Java code.

You add support for new actions by:

Extension XML for Actions

Through the extension.xml for an action extension, you define the following:

Note: For reference information on action extension XML, see Action Extension XML Reference.

For an example, take a look at the menu commands defined in the MenuItems action sample included with the ExtensionDevKit, in the IdeDevKit application. The following illustration shows menu the extension creates.

As you can see, the extension creates a Favorites menu in the main menu bar, along with a Links submenu. It also creates commands such as Add Favorite, Delete Favorite, and commands to open three URLs. The URL commands open a browser to the selected URL, and you can use the Add Favorite and Delete Favorite commands to add or remove custom URLs. In the following XML code from this sample's extension.xml, the <action-ui> stanza defines the structure of the user interface (although not all of the UI), while the lower <action-set> stanza points the IDE to the logic for actions.

Items grouped with <action-group> stanzas are separated by a visual cue in the IDE, such as a line between groups. These are statically-defined groups, in that they're defined here in the extension.xml and will exist when the extension is loaded.

<extension-xml id="urn:com-bea-ide:actions">
    <action-ui>
        <menu id="favorites" path="menu/main" priority="100" label="Favorites">
            <action-group id="linkssubmenugroup" priority="5" path="menu/favorites">
                <menu id="favoritesMenu" priority="10" label="Links">
                    <action-group id="favoritesSubMenu1" priority="10"/>
                    <action-group id="favoritesSubMenu2" priority="10" 
                        generator="ideExtensions.menuItems.FavoritesGenerator"/>
                </menu>
            </action-group>
            <action-group id="addremovecommandsgroup" priority="10"/>
        </menu>
    </action-ui>
    
    <action-set>
        <action class="ideExtensions.menuItems.AddFavoriteAction" label="Add Favorite" 
		    icon="images/workshop/debugger/icons/debug_watch.gif" show-always="true">
            <location priority="10" path="menu/favorites/addremovecommandsgroup"/>
        </action>
        <action class="ideExtensions.menuItems.DeleteFavoriteAction" label="Delete Favorite" 
		    icon="images/workshop/debugger/icons/debug_watch.gif" show-always="true">
            <location priority="10" path="menu/favorites/addremovecommandsgroup" />
        </action>
        <action class="ideExtensions.menuItems.LaunchBrowserAction1" label="http://www.bea.com" 
		    icon="images/workshop/debugger/icons/debug_watch.gif" show-always="true">
            <location priority="10" path="menu/favorites/favoritesMenu/favoritesSubMenu1"/>
        </action>
        <action class="ideExtensions.menuItems.LaunchBrowserAction2" label="http://www.google.com" 
		    icon="images/workshop/debugger/icons/debug_watch.gif" show-always="true">
            <location priority="10" path="menu/favorites/favoritesMenu/favoritesSubMenu1"/>
        </action>
        <action class="ideExtensions.menuItems.LaunchBrowserAction3" label="http://www.yahoo.com" 
		    icon="images/workshop/debugger/icons/debug_watch.gif" show-always="true">
            <location priority="10" path="menu/favorites/favoritesMenu/favoritesSubMenu1"/>
        </action>
    </action-set>
</extension-xml>

Specifying Paths

The <action-ui> stanza is largely intended to set up the user interface structure of the commands (such as the menu hierarchy), along with simple bits of user interface. The <action-ui> stanza doesn't specify any logic, so the user interface it specifies is for those items that have no logic, such as a menu command that has only a submenu. The <action-set> stanza, on the other hand, specifies the classes that are plugged into parts of this structure to support commands. It also specifies UI for those commands (such as a command's label).

The hierarchy of elements in the <action-ui> stanza establishes the structure of the menus. The id attributes are strung together in the <action-set> stanza's path attributes to tell the IDE where to hook the Java classes that define logic for the commands.

Defining Action Scope

The <action-set> element provides a scope attribute that you can use to specify when the action should be available to the user. In other words, you can specify that the action should only be available when a document of a particular type is open and visible in the IDE. For example, you might want to do this if you've created an action that is only relevant for a certain document type, such as a web service (JWS), JavaServer Pages page (JSP), or a document that you may have defined in a document extension.

Defining Action UI Mnemonics

For action user interface that's specified in the extension.xml file (such as the mnemonic for a menu command), you add an entitized ampersand character — &amp; — immediately preceding the label character that will be the mnemonic. In the following example, the letter "r" is the mnemonic:

 <menu id="favorites" path="menu/main" priority="100" 
    label="Favo&amp;rites">

In the extension.xml file itself, the & character must be entitized in order for the attribute value that contains it to be valid XML.

Implementing an Action's Logic

You will typically implement the IAction interface or extend the abstract DefaultAction class (which itself implements IAction). You tell the IDE which class to use for action logic by specifying that class in an <action> element of your extension XML, as in the following snippet, where the class name is in bold text:

<action class="ideExtensions.menuItems.LaunchBrowserAction1" 
    label="http://www.bea.com"
    icon="images/workshop/debugger/icons/debug_watch.gif" show-always="true">
    <location priority="10" path="menu/favorites/favoritesMenu/favoritesSubMenu1"/>
</action>

The com.bea.ide.action package includes classes and interfaces that represent particular kinds of actions. These include:

Other action-related parts of the API you might want to use include:

Defining Actions Dynamically

You can add actions dynamically by implementing the IGenerator interface. In particular, the IDE calls your implementation of the interface's populate method, passing to the implementation an instance of the container (such as a menu or toolbar) to which you can add actions. That container implements the IContainer interface, which provides methods through which you can discover the container's action type (whether it is a menu, toolbar, and so on), and add actions, containers, and separators.

In your extension.xml file, you assign the generator class to the action UI under which generated actions will be available. For an example, see the preceding extension.xml code. Note that the ideExtensions.menuItems.FavoritesGenerator class is assigned to the favoritesSubMenu2 branch of the action structure with the <action-set> element's generator attribute:

<action-group id="favoritesSubMenu2" priority="10" 
    generator="ideExtensions.menuItems.FavoritesGenerator"/>

The generator class is responsible for creating the user interface and associated actions.

Related Topics

MenuItems Sample

PopupAction Sample

ToolbarButton Sample

ActionSvc Class

DefaultAction Class