16.5 Menus

Class Menu implements all kinds of menus: menubars of top-level windows, submenus, and pop-up menus. To use a Menu instance m as the menubar for a top-level window w, set w's configuration option menu=m. To use m as a submenu of a Menu instance x, call x.add_cascade with a named argument menu=m. To use m as a pop-up menu, call method m.post.

Besides configuration options covered in Section 16.2.1 earlier in this chapter, a Menu instance m supports option postcommand=callable. Tkinter calls callable without arguments each time it is about to display m (whether because of a call to m.post or because of user actions). You can use this option to update a dynamic menu just in time when necessary.

By default, a Tkinter menu shows a tear-off entry (a dashed line before other entries), which lets the user get a copy of the menu in a separate Toplevel window. Since such tear-offs are not part of user interface standards on popular platforms, you may want to disable tear-off functionality by using configuration option tearoff=0 for the menu.

16.5.1 Menu-Specific Methods

Besides methods common to all widgets, an instance m of class Menu supplies several menu-specific methods.

add, add_cascade, add_checkbutton, add_command, add_radiobutton, add_separator

m.add(entry_kind, **entry_options)

Adds after m's existing entries a new entry whose kind is the string entry_kind, which is one of the strings 'cascade', 'checkbutton', 'command', 'radiobutton', or 'separator'. Section 16.5.2 later in this chapter covers entry kinds and options.

Methods whose names start with add_ work just like method add, but they accept no positional argument; what kind of entry each method adds is implied by the method's name.

delete

m.delete(i[,j])

m.delete(i) removes m's i entry. m.delete(i,j) removes m's entries from the i one to the j one, included. The first entry has index 0.

entryconfigure, entryconfig

m.entryconfigure(i, **entry_options)

Changes entry options for m's i entry. entryconfig is an exact synonym.

insert, insert_cascade, insert_checkbutton, insert_command, insert_radiobutton, insert_separator

m.insert(i,entry_kind, **entry_options)

Adds before m's entry i a new entry whose kind is the string entry_kind, which is one of the strings 'cascade', 'checkbutton', 'command', 'radiobutton', or 'separator'. Section 16.5.2 later in this chapter covers entry kinds and options.

Methods whose names start with insert_ work just like method insert, except that they don't accept a second positional argument; what kind of entry each method inserts is implied by the method's name.

invoke

m.invoke(i)

Invokes m's i entry, just as if the user clicked on it.

post

m.post(x,y)

Displays m as a pop-up menu, with m's upper left corner at coordinates x,y (offsets in pixels from upper left corner of Tkinter's root window).

unpost

m.unpost(  )

Closes m if m was displaying as a pop-up menu, otherwise does nothing.

16.5.2 Menu Entries

When a menu m displays, it shows a vertical (horizontal for a menubar) list of entries. Each entry can be one of the following kinds:

cascade: A submenu; option menu=x must give as x another Menu instance
checkbutton: Similar to a Checkbutton widget; typical options are variable (which must indicate a Tkinter variable object), onvalue, offvalue, and optionally command, quite similarly to a Checkbutton instance
command: Similar to a Button widget; typical option is command=callable
radiobutton: Similar to a Radiobutton widget; typical options are variable (which must indicate a Tkinter variable object), value, and optionally command, quite similarly to a Radiobutton instance
separator: A line segment that separates groups of other entries

Other entry options often used with menu entries are:

image: Option image=x uses x, a Tkinter image object, to label the entry with an image rather than text
label: Option label=somestring labels the entry with a text string
underline: Option underline=x gives x as the index of the character to underline within the entry's label (0 is the first character, 1 the second one, and so on)

16.5.3 Menu Example

The following example shows how to add a menubar with typical File and Edit menus:

import Tkinter

root = Tkinter.Tk(  )
bar = Tkinter.Menu(  )

def show(menu, entry): print menu, entry

fil = Tkinter.Menu(  )
for x in 'New', 'Open', 'Close', 'Save':
    fil.add_command(label=x,command=lambda x=x:show('File',x))
bar.add_cascade(label='File',menu=fil)

edi = Tkinter.Menu(  )
for x in 'Cut', 'Copy', 'Paste', 'Clear':
    edi.add_command(label=x,command=lambda x=x:show('Edit',x))
bar.add_cascade(label='Edit',menu=edi)

In this example, each menu command just outputs information to standard output for demonstration purposes. Note the x=x idiom to snapshot the value of x at the time we create each lambda. Otherwise, the current value of x at the time a lambda executes, 'Clear', would show up at each menu selection. A good alternative to the lambda expressions would be a closure. Instead of def show, use:

def mkshow(menu):
    def emit(entry, menu=menu): print menu, entry
    return emit

and use command=mkshow('File') and command=mkshow('Edit'), respectively, in the calls to the add_command methods of fil and edi.