Menus

Menu items can be added to the Add-ins toolbar in Excel using the @ExcelMenu annotation. Different menus can be created, and you can also create submenus.

For example, the following code adds a new menu item Show Message to Excel:

import com.exceljava.jinx.ExcelMenu;
import javax.swing.JOptionPane;

public class MenuFunctions {
    @ExcelMenu("Show Message")
    public static void showMessage() {
        JOptionPane.showMessageDialog(null,
                "Menu item selected",
                "Show Message Menu",
                JOptionPane.INFORMATION_MESSAGE);
    }
}

Once that code is built the class MenuFunctions is added to the Jinx config file:

> javac -cp <path to jinx jar> MenuFunctions.java
> jar -cf MacroFunctions.jar MenuFunctions.class

[JINX]
classes = MenuFunctions

[JAVA]
classpath = ./MenuFunctions.jar

Now when Excel is started the menu item will appear in the Add-ins toolbar under the Jinx menu. It’s possible to create other menus and to create sub-menus using the optional parameters to the @ExcelMenu annotation.

ExcelMenu Options

The @ExcelMenu annotation takes a number of optional parameters. These are used to control how the menu appears in Excel.

Keyboard Shortcuts

A shortcut for a menu item can be set using the shortcut parameter to the @ExcelMenu annotation.

Shortcuts should be one or more modifier key names (Ctrl, Shift or Alt) and a key, separated by the ‘+’ symbol. For example, ‘Ctrl+Shift+R’.

If a key combination is already in use by Excel it may not be possible to assign a menu item to that combination.

In addition to letter, number and function keys, the following special keys may also be used (these are not case sensitive and cannot be used without a modifier key):

• Backspace
• Break
• CapsLock
• Clear
• Delete
• Down
• End
• Enter
• Escape
• Home
• Insert
• Left
• NumLock
• PgDn
• PgUp
• Right
• ScrollLock
• Tab

Menu Ordering

The order in which items appear in a menu is determined using the order set on each item. For items with the same order they are ordered lexicographically. Negative numbers can be used to specify an offset from the bottom of the menu (e.g. -1 is the last item in the menu and -2 would be the second from last).

When multiple items are placed in the same sub-menu by setting subMenu to be the same, their relative order can be specified using subOrder. The relative positioning of the sub-menu within the menu is determined by the largest specified order of all items in the sub-menu. If multiple top level menus are being used by setting menu on one or more menu items, the relative order of the top level menus can be specified by setting menuOrder. The relative position of each top level menu is determined by the largest specified menuOrder of all the items in the top level menu.

Menu ordering can also be specified in the config file. This can use useful when managing large numbers of menu items where setting the ordering via the @ExcelMenu annotation can become cumbersome.

The example config below shows how to order menus with menu items and sub-menus.

[MENUS]
menu_1 = 1  # order of the top level menu menu_1
menu_1.menu_item_1 = 1  # order of the items within menu_1
menu_1.menu_item_2 = 2
menu_1.menu_item_3 = 3
menu_2 = 2  # order of the top level menu menu_2
menu_2.sub_menu_1 = 1  # order of the sub-menu sub_menu_1 within menu_2
menu_2.sub_menu_1.menu_item_1 = 1  # order of the items within sub_menu_1
menu_2.sub_menu_1.menu_item_2 = 2
menu_2.menu_item_1 = 2 # order of item within menu_2
menu_2.sub_menu_2 = 3
menu_2.sub_menu_2.menu_item_1 = 1
menu_2.sub_menu_2.menu_item_2 = 2

Each menu item is identified by the menu name, optionally followed by the sub-menu name and finally followed by the menu item name, separated by full stops.