Next / Previous / Contents

15. The Menu widget

“Drop-down” menus are a popular way to present the user with a number of choices, yet take up minimal space on the face of the application when the user is not making a choice.

  • A menubutton is the part that always appears on the application.

  • A menu is the list of choices that appears only after the user clicks on the menubutton.

  • To select a choice, the user can drag the mouse from the menubutton down onto one of the choices. Alternatively, they can click and release the menubutton: the choices will appear and stay until the user clicks one of them.

  • The Unix version of Tkinter (at least) supports “tear-off menus.” If you as the designer wish it, a dotted line will appear above the choices. The user can click on this line to “tear off” the menu: a new, separate, independent window appears containing the choices.

Refer to Section 16, “The Menubutton widget”, below, to see how to create a menubutton and connect it to a menu widget. First let's look at the Menu widget, which displays the list of choices.

The choices displayed on a menu may be any of these things:

To create a menu widget, you must first have created a Menubutton, which we will call mb:

    w = tk.Menu(mb, option, ...)

This constructor returns the new Menu widget. Options include:

Table 23. Menu widget options

activebackground The background color that will appear on a choice when it is under the mouse. See Section 5.3, “Colors”.
activeborderwidth Specifies the width of a border drawn around a choice when it is under the mouse. Default is 1 pixel. For possible values, see Section 5.1, “Dimensions”.
activeforeground The foreground color that will appear on a choice when it is under the mouse.
bg or background The background color for choices not under the mouse.
bd or borderwidth The width of the border around all the choices; see Section 5.1, “Dimensions”. The default is one pixel.
cursor The cursor that appears when the mouse is over the choices, but only when the menu has been torn off. See Section 5.8, “Cursors”.
disabledforeground The color of the text for items whose state is tk.DISABLED.
font The default font for textual choices. See Section 5.4, “Type fonts”.
fg or foreground The foreground color used for choices not under the mouse.
postcommand You can set this option to a procedure, and that procedure will be called every time someone brings up this menu.
relief The default 3-D effect for menus is relief=tk.RAISED. For other options, see Section 5.6, “Relief styles”.
selectcolor Specifies the color displayed in checkbuttons and radiobuttons when they are selected.
tearoff Normally, a menu can be torn off: the first position (position 0) in the list of choices is occupied by the tear-off element, and the additional choices are added starting at position 1. If you set tearoff=0, the menu will not have a tear-off feature, and choices will be added starting at position 0.
tearoffcommand If you would like your program to be notified when the user clicks on the tear-off entry in a menu, set this option to your procedure. It will be called with two arguments: the window ID of the parent window, and the window ID of the new tear-off menu's root window.
title Normally, the title of a tear-off menu window will be the same as the text of the menubutton or cascade that lead to this menu. If you want to change the title of that window, set the title option to that string.

These methods are available on Menu objects. The ones that create choices on the menu have their own particular options; see Section 15.1, “Menu item creation (coption) options”.

.add(kind, coption, ...)

Add a new element of the given kind as the next available choice in this menu. The kind argument may be any of 'cascade', 'checkbutton', 'command', 'radiobutton', or 'separator'. Depending on the kind argument, this method is equivalent to .add_cascade(), .add_checkbutton(), and so on; refer to those methods below for details.

.add_cascade(coption, ...)

Add a new cascade element as the next available choice in this menu. Use the menu option in this call to connect the cascade to the next level's menu, an object of type Menu.

.add_checkbutton(coption, ...)

Add a new checkbutton as the next available choice in self. The options allow you to set up the checkbutton much the same way as you would set up a Checkbutton object; see Section 15.1, “Menu item creation (coption) options”.

.add_command(coption, ...)

Add a new command as the next available choice in self. Use the label, bitmap, or image option to place text or an image on the menu; use the command option to connect this choice to a procedure that will be called when this choice is picked.

.add_radiobutton(coption, ...)

Add a new radiobutton as the next available choice in self. The options allow you to set up the radiobutton in much the same way as you would set up a Radiobutton object; see Section 20, “The Radiobutton widget”.

.add_separator()

Add a separator after the last currently defined option. This is just a ruled horizontal line you can use to set off groups of choices. Separators are counted as choices, so if you already have three choices, and you add a separator, the separator will occupy position 3 (counting from 0).

.delete(index1, index2=None)

This method deletes the choices numbered from index1 through index2, inclusive. To delete one choice, omit the index2 argument. You can't use this method to delete a tear-off choice, but you can do that by setting the menu object's tearoff option to 0.

.entrycget(index, coption)

To retrieve the current value of some coption for a choice, call this method with index set to the index of that choice and coption set to the name of the desired option.

.entryconfigure(index, coption, ...)

To change the current value of some coption for a choice, call this method with index set to the index of that choice and one or more coption=value arguments.

.index(i)

Returns the position of the choice specified by index i. For example, you can use .index(tk.END) to find the index of the last choice (or None if there are no choices).

.insert_cascade(index, coption, ...)

Inserts a new cascade at the position given by index, counting from 0. Any choices after that position move down one. The options are the same as for .add_cascade(), above.

.insert_checkbutton(index, coption, ...)

Insert a new checkbutton at the position specified by index. Options are the same as for .add_checkbutton(), above.

.insert_command(index, coption, ...)

Insert a new command at position index. Options are the same as for .add_command(), above.

.insert_radiobutton(index, coption, ...)

Insert a new radiobutton at position index. Options are the same as for .add_radiobutton(), above.

.insert_separator(index)

Insert a new separator at the position specified by index.

.invoke(index)

Calls the command callback associated with the choice at position index. If a checkbutton, its state is toggled between set and cleared; if a radiobutton, that choice is set.

.post(x, y)

Display this menu at position (x, y) relative to the root window.

.type(index)

Returns the type of the choice specified by index: either tk.CASCADE, tk.CHECKBUTTON, tk.COMMAND, tk.RADIOBUTTON, tk.SEPARATOR, or tk.TEAROFF.

.yposition(n)

For the nth menu choice, return the vertical offset in pixels relative to the menu's top. The purpose of this method is to allow you to place a popup menu precisely relative to the current mouse position.