Creating custom menu items

Basic menu items

New menu items can be added to the PyXLL Excel Addin menu easily by using the xl_menu decorator.

pyxll.xl_menu(name [, menu=None] [, sub_menu=None] [, order=0] [, menu_order=0] [, allow_abort=?])

xl_menu is a function that returns a decorator for creating menu items that call Python functions.

param string name:
 name of the menu item that the user will see in the menu
param string menu:
 name of the menu that the item will be added to. If a menu of that name doesn’t already exist it will be created. By default the PyXLL menu is used
param string sub_menu:
 name of the submenu that this item belongs to. If a submenu of that name doesn’t exist it will be created
param int order:
 influences where the item appears in the menu. The higher the number, the further down the list. Items with the same sort order are ordered lexographically. If the item is a sub-menu item, this order influences where the sub-menu will appear in the main menu
param int sub_order:
 similar to order but it is used to set the order of items within a sub-menu
param int menu_order:
 used when there are multiple menus and controls the order in which the menus are added
Parameters:allow_abort (boolean) – If True the function may be cancelled by the user pressing Esc. A KeyboardInterrupt exception is raised when Esc is pressed. If not specified the behavior is determined by the allow_abort setting in the config (see Config file).

To add a new menu entry to the PyXLL menu you use the xl_menu decorator with the label you want to use for that menu item, and a function that takes no arguments that will be called when that menu item is selected.

Here is an example of a simple menu item that uses win32api to display a message box to the user:

from pyxll import xl_menu
import win32api

@xl_menu("My menu item")
def my_menu_item():
    win32api.MessageBox(0, "Hello from PyXLL", "Menu button example")

Menu items may modify the current workbook, or in fact do anything that you can do via the Excel automatition API. This allows you to do anything in Python that you previously would have had to have done in VBA.

Below is an example that uses the win32com module to call back into Excel from a menu item:

from pyxll import xl_menu, get_active_object
import win32com.client

@xl_menu("win32com menu item")
def win32com_menu_item():
    # get the Excel application object
    xl_window = get_active_object()
    xl_app = win32com.client.Dispatch(xl_window).Application

    # get the current selected range
    selection = xl.Selection

    # set some text to the selection
    selection.Value = "Hello!"

New menus

As well as adding menu items to the main PyXLL addin menu it’s possible to create entirely new menus.

To create a new menu, use the menu keyword argument to the xl_menu decorator.

In addition, if you want to control the order in which menus are added you may use the menu_order integer keyword argument. The higher the value, the later in the ordering the menu will be added.

Below is a modification of an earlier menu example that puts the menu item in a new menu, called “New Menu”:

from pyxll import xl_menu
import win32api

@xl_menu("My menu item", menu="New Menu")
def my_menu_item():
    win32api.MessageBox(0, "Hello from PyXLL", "new menu example")