How to create custom menus, palettes, and MultiItems


Summary
This topic shows the basic steps to create custom menus, submenus, palettes, and MultiItems. It also describes the steps to create context menus for your application.

In this topic


Creating custom menus

Custom menus and submenus can be created to group similar items. These items can be ESRI provided standard commands and tools, or custom tools and commands. Custom menus can be created by the following:
The IMenuDef ArcObjects is used to create simple menus using ESRI standard commands and tools as its menu items. To create menus with custom commands and tools as menu items, use the ToolbarMenu ArcObjects. The ToolbarMenu ArcObjects is also used to create pop-up menus.

Differences between IMenuDef and ToolbarMenu

The following table shows the differences between IMenuDef and ToolbarMenu ArcObjects:
IMenuDef
ToolbarMenu
  • Contains only ESRI standard components as its menu items
  • Placed only on toolbar
  • Placed on toolbar
  • Appears as pop-up menu anywhere in response to keyboard or mouse events

Creating custom menus using IMenuDef

Do the following steps to create custom menus using IMenuDef:
  1. Create a custom class that implements IMenuDef ArcObjects and implement its methods as follows:
The following code example creates a custom menu object (NavigationMenu) with ESRI commands and tools as its menu items:
[Java]
class NavigationMenu implements IMenuDef{
    // Set the menu caption.

    public String getCaption(){
        return "Navigation";
    }

    //Set the menu name.
    public String getName(){
        return "Navigation";
    }


    // Set the number of menu items.
    public int getItemCount(){
        return 5;
    }

    /*
     *Set the implementation for every menu item.
     *Note that the number of cases in the getItemInfo() is equivalent 
     * to the number of items returned by getItemCount() method.
     */

    public void getItemInfo(int pos, IItemDef itemDef){
        try{
            switch (pos){

                case 0:
                    itemDef.setID(ControlsMapZoomInFixedCommand.getClsid());
                    break;
                case 1:
                    itemDef.setID(ControlsMapZoomOutFixedCommand.getClsid());
                    break;
                case 2:
                    itemDef.setID(ControlsMapFullExtentCommand.getClsid());
                    break;
                case 3:
                    itemDef.setID(ControlsMapZoomToLastExtentBackCommand.getClsid());
                    break;
                case 4:
                    itemDef.setID(ControlsMapZoomToLastExtentForwardCommand.getClsid
                        ());
                    break;
                default:
                    //Do nothing.
            }
        }
        catch (IOException ex){
            System.out.println("Exception in Custom Menu : " + ex);
            ex.printStackTrace();
        }
    }
}
  1. Add the custom menu to the toolbar, using the ToolbarBean.addMenuItem() method. See the following code example: 
[Java]
//Instantiate the menu object.
NavigationMenu navMenu = new NavigationMenu();
int pos = toolbarBean.getCount();
/*
 *Add to the toolbar: variable pos specifies the position of the menu in the toolbar items.
 *The default value -1 for pos adds it to the end of the toolbar items.
 */
toolbarBean.addMenuItem(navMenu, 0, pos, true);

Creating custom menus using ToolbarMenu

Do the following steps to create custom menus using ToolbarMenu:
  1. Instantiate a ToolbarMenu ArcObjects and call the setCaption() and setBitmap() methods to set the caption and bitmap for the menu.
  2. Using the ToolbarMenu.addItem() method, add menu items, such as standard ESRI commands and tools, and custom objects that implement IMenuDef, ICommand, ITool, IPaletteDef, IToolbarMenu, or IToolbarPalette.
  3. Add the menu to the toolbar using ToolbarBean.addMenuItem(). See the following code example:
[Java]
//Instantiate ToolbarMenu.
ToolbarMenu myToolbarMenu = new ToolbarMenu();
myToolbarMenu.setCaption(� � �CustomMenu ");

//Add standard components.
myToolbarMenu.addItem(ControlsMapMeasureTool.getClsid(), 0,  - 1, false,
    esriCommandStyles.esriCommandStyleTextOnly); 

//Add custom created commands or tools. 
ICommand myCommand = new MyCommand(); myToolbarMenu.addItem(myCommand, 0,  - 1,
    false, esriCommandStyles.esriCommandStyleTextOnly); 

//Add to the toolbar: variable pos specifies the position of the menu in the toolbar items.
//The value -1 adds it to the end of the toolbar items.

toolbarBean.addMenuItem(myToolbarMenu, pos, true, 0);
  1. Create submenus (optional). Submenus on a menu are implemented as another instance of a ToolbarMenu or IMenuDef ArcObjects. To create a submenu, implement IMenuDef or use ToolbarMenu ArcObjects as previously described, and create a menu object. To add the submenu to the menu, invoke the ToolbarMenu.addSubMenu() method of the menu object. See the following code example:
[Java]
IToolbarMenu toolbarMenu = new ToolbarMenu();

// Define a class (NavigationMenu) that implements IMenuDef and instantiate it.
IMenuDef navigationMenu = new NavigationMenu();

//Define a class (NavigationSubMenu) that implements IMenuDef and instantiate it.
IMenuDef subMenu = new NavigationSubMenu();

//Add SubMenu to the NavigationMenu:
// subMenuPos is the integer position where the submenu is to be added.
toolbarMenu.addSubMenu(subMenu, subMenuPos, true);

//Add the custom menu to the toolbar.
toolbarBean.addMenuItem(navigationMenu, pos, false, 0);

Creating custom context menus

Custom menus and submenus can appear as context menus on a MapControl, PageLayoutControl, SceneControl, GlobeControl, or TOCControl in the application. The ToolbarMenu.setHook() and ToolbarMenu.popupMenu() methods are used to create context menus. The following code example explains how a context menu can be created for a right-click mouse event on a MapControl using the ToolbarMenu ArcObjects.
The following code example also assumes a ToolbarBean and MapBean object have been initialized in the ArcGIS Engine Visual Java Beans application:
[Java]
//Context menu.

//Instantiate a menu object.
IMenuDef menudef = new NavigationMenu();

//Create a ToolbarMenu.
ToolbarMenu toolbarMenu = new ToolbarMenu();
toolbarMenu.addItem(menudef, 0,  - 1, false,
    esriCommandStyles.esriCommandStyleIconAndText);
/* The setHook method sets the object that is passed 
 * as a hook to the OnCreate event of each item's command. 
 */
toolbarMenu.setHook(toolbarbean);


/*
 * The following context menu is designed to appear 
 * in response to right-click mouse events on a MapControl.
 */
mapBean.addIMapControlEvents2Listener(new IMapControlEvents2Adapter(){
    public void onMouseDown(IMapControlEvents2OnMouseDownEvent theEvent){
        try{
            // On right-click, pop up the menu.

            if (theEvent.getButton() == 2)
            //The popupMenu() method pops up the context menu. 
            toolbarMenu.popupMenu(theEvent.getX(), theEvent.getY(), mapBean.getHWnd()
                ); 
        }
        catch (Exception ex){
            System.out.println("Exception in MapControlListener#onMouseMove : " + ex)
                ; ex.printStackTrace(); 
        }
    }
}

    ;

Creating custom palettes

Similar to creating custom menus, custom palettes can be created by implementing the IPaletteDef ArcObjects or using the ToolbarPalette ArcObjects. Do the following to create a custom palette using IPaletteDef:
  1. Implement the methods of the IPaletteDef interface as follows:
  2. Using the ToolbarBean.addItem() method, add the custom palette menu to the toolbar.
The following code example shows how to create a simple custom palette using IPaletteDef:
[Java]
class MyPalette implements IPaletteDef{
    // Set the menu caption.

    public String getCaption(){
        return "MyPalette";
    }

    //Set the menu name.
    public String getName(){
        return "MyPalette";
    }
}

// Set the number of menu items.
public int getItemCount(){
    return 3;
}

//Set the item info for every command in the menu.

public void getItemInfo(int pos, IItemDef itemDef){
    try{
        switch (pos){
            case 0:
                itemDef.setID(ControlsNewMarkerTool.getClsid());
                break;
            case 1:
                itemDef.setID(ControlsNewLineTool.getClsid());
                break;
            case 2:
                itemDef.setID(ControlsNewCircleTool.getClsid());
                break;
            default:
                //Do nothing.
        }
    }
    catch (IOException ex){
        //System.out.println("Exception")
    }
}

}

//Step 2: Host the menu item on the toolbar.

MyPalette palette = new MyPalette();
toolbarBean.addItem(palette, 0,  - 1, true,  - 1,
    esriCommandStyles.esriCommandStyleIconOnly);
Custom palettes can also as appear as context menus. The ToolbarPalette.setHook() and ToolbarPalette.popupPalette() methods are used to create custom context palettes.
The following code example assumes a ToolbarBean and MapBean object have been initialized in the ArcGIS Engine Visual Java Bean application:
[Java]
//Create a ToolbarPalette object.
ToolbarPalette palette = new MyPalette();
palette.setHook(toolbarBean);

/*
 * The following context menu is designed to appear 
 * in response to right-click mouse events on a MapControl.
 */
mapBean.addIMapControlEvents2Listener(new IMapControlEvents2Adapter(){
    public void onMouseDown(IMapControlEvents2OnMouseDownEvent theEvent){
        try{
            if (theEvent.getButton() == 2) //Check for right-click. 

            //Pop up the palette.
            palette.popupPalette(theEvent.getX(), theEvent.getY(), mapBean.getHWnd())
                ; 
        }
        catch (Exception ex){
            System.out.println("Exception in MapControlListener#onMouseMove : " + ex)
                ; ex.printStackTrace(); 
        }

    }

Creating MultiItems

A MultiItem can be used when items on a menu cannot be determined before runtime or the items need to be modified based on the state of the system. For example, the menu items at the bottom of the File menu representing the most recently used files. 
Do the following to create a MultiItem menu:
  1. Create an object that implements IMultiItem, then implement the following methods:
The following code example creates a list of bookmark MultiItems:
The following code example is also available as a sample. For more information, see ArcGISInstallDir\java\samples\engine\Controls.ToolbarControl.MultiItemBookmarks.
[Java]
public class SpatialBookmarks implements IMultiItem{
    private int activeBookmarkIndex =  - 1;

    //Return the MultiItem name.
    public String getName()throws IOException, AutomationException{
        return "Spatial Bookmarks";
    }

    //Return the MultiItem caption.
    public String getCaption()throws IOException, AutomationException{
        return "Spatial Bookmarks";
    }

    //Return the item caption specified by pos.
    public String getItemCaption(int pos)throws IOException, AutomationException{
        try{
            // Get focus map bookmarks.
            IMapBookmarks mapBookmarks = (IMapBookmarks)hookHelper.getFocusMap();
            // Get enumerator bookmarks.
            IEnumSpatialBookmark enumSpatialBookmarks = mapBookmarks.getBookmarks();
            enumSpatialBookmarks.reset();
            // Loop through the bookmarks to get bookmark names.
            ISpatialBookmark spatialBookmark = enumSpatialBookmarks.next();
            int bookmarkCount = 0;
            while (spatialBookmark != null){
                // Get the correct bookmark.
                if (bookmarkCount == pos){
                    // Return the bookmark name.
                    return spatialBookmark.getName();
                }
                bookmarkCount = bookmarkCount + 1;
                spatialBookmark = enumSpatialBookmarks.next();
            }
        }
        catch (Exception e){}
        return "";
    }

    //Provide implementation for the onClick event for every item.
    public void onItemClick(int index)throws IOException, AutomationException{
        //Set the current active bookmark.
        this.activeBookmarkIndex = index;
        // Get the focus map bookmarks.
        IMapBookmarks mapBookmarks = (IMapBookmarks)hookHelper.getFocusMap();
        // Get enumerator bookmarks. 
        IEnumSpatialBookmark enumSpatialBookmarks = mapBookmarks.getBookmarks();
        enumSpatialBookmarks.reset();
        // Loop through the bookmarks to get bookmark to zoom to.
        ISpatialBookmark spatialBookmark = enumSpatialBookmarks.next();
        int bookmarkCount = 0;
        while (spatialBookmark != null){
            // Get the correct bookmark.
            if (bookmarkCount == index){
                // Zoom to the bookmark.
                spatialBookmark.zoomTo(hookHelper.getFocusMap());
                // Refresh the map.
                hookHelper.getActiveView().refresh();
            }
            bookmarkCount = bookmarkCount + 1;
            spatialBookmark = enumSpatialBookmarks.next();
        }
    }

}
  1. Add the custom created MultiItem to the ToolbarMenu using ToolbarMenu.addMultiItem() and add the menu to the toolbar using the ToolbarBean.addItem() method. See the following code example:
[Java]
// Add the custom MultiItem to the ToolbarMenu.
toolbarMenu.addMultiItem(new SpatialBookmarks(),  - 1, true,
    esriCommandStyles.esriCommandStyleTextOnly);

// Add the menu item to the ToolbarControl.
toolbarBean.addItem(toolbarMenu,  - 1,  - 1, true, 0,
    esriCommandStyles.esriCommandStyleMenuBar);
  1. Custom created MultiItems can also appear as pop-up menus using the ToolbarMenu.setHook() and ToolbarMenu.popupMenu() methods. You can also customize the implementation for pop-up events using the IMultiItem.onPopup() method (optional).

    For more information, see the MultiItemBookmarks sample.

Differences and relationships

The following illustration shows the differences and relationships between the ToolbarBean, ToolbarMenu, and ToolbarPalette ArcObjects:
 


See Also:

Sample: ToolbarMenu
Sample: PopupMenu
Sample: Palette
Sample: MultiItem




Development licensingDeployment licensing
Engine Developer KitEngine
ArcGIS for Desktop Basic
ArcGIS for Desktop Advanced
ArcGIS for Desktop Standard