We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

The Tkinter Toplevel Widget

The Toplevel widget work pretty much like Frame, but it is displayed in a separate, top-level window. Such windows usually have title bars, borders, and other “window decorations”.

When to use the Toplevel Widget

The Toplevel widget is used to display extra application windows, dialogs, and other “pop-up” windows.

Patterns

...

top = Toplevel()
top.title("About this application...")

msg = Message(top, text=about_message)
msg.pack()

button = Button(top, text="Dismiss", command=top.destroy)
button.pack()

FIXME: add more patterns

Reference

Toplevel(master=None, **options) (class) [#]

A widget container placed in a new top level window.

master
Parent widget.
**options
Widget options. See the description of the config method for a list of available options.

config(**options) [#]

Modifies one or more widget options. If no options are given, the method returns a dictionary containing all current option values.

**options
Widget options.
background=
The background color to use in this toplevel. This defaults to the application background color. To prevent updates, set the color to an empty string. (the option database name is background, the class is Background)
bg=
Same as background.
borderwidth=
Width of the 3D border. Defaults to 0 (no border). (borderWidth/BorderWidth)
bd=
Same as borderwidth.
class=
Default value is Toplevel. (class/Class)
colormap=
Some displays support only 256 colors (some use even less). Such displays usually provide a color map to specify which 256 colors to use. This option allows you to specify which color map to use for this toplevel window, and its child widgets.
By default, a new toplevel window uses the same color map as the root window. Using this option, you can reuse the color map of another window instead (this window must be on the same screen and have the same visual characteristics). You can also use the value “new” to allocate a new color map for this window.
You cannot change this option once you’ve created the window. (colormap/Colormap)
container=
Default value is 0. (container/Container)
cursor=
The cursor to show when the mouse pointer is located over the toplevel widget. Default is a system specific arrow cursor. (cursor/Cursor)
height=
Window height, in pixels. If omitted, the widget is made large enough to hold its contents. (height/Height)
highlightbackground=
The color to use for the highlight region when the widget doesn’t have focus. The default is system specific. (highlightBackground/HighlightBackground)
highlightcolor=
The color to use for the highlight region when the widget has focus. The default is system specific. (highlightColor/HighlightColor)
highlightthickness=
The width of the highlight region. Default is 0 (no region). (highlightThickness/HighlightThickness)
menu=
A menu to associate with this toplevel window. On Unix and Windows, the menu is placed at the top of the toplevel window itself. On Macs, the menu is displayed at the top of the screen when the toplevel window is selected. (menu/Menu)
padx=
Horizontal padding. Default is 0. (padX/Pad)
pady=
Vertical padding. Default is 0. (padY/Pad)
relief=
Border decoration: either FLAT, SUNKEN, RAISED, GROOVE, or RIDGE. The default is FLAT. (relief/Relief)
screen=
No default value. (screen/Screen)
takefocus=
Indicates that the user can use the Tab key to move to this widget. Default is false. (takeFocus/TakeFocus)
use=
No default value. (use/Use)
visual=
Controls the “visual” type to use for this window. This option should usually be omitted. In that case, the visual type is inherited from the root window.
Some more advanced displays support “mixed visuals”. This typically means that the root window is a 256-color display (the “pseudocolor” visual type), but that individual windows can be displayed as true 24-bit color (the “truecolor” visual type). On such displays, you may wish to explicitly set the visual option to “truecolor” for any windows used to display full-color images.
Other possible values include “directcolor”, “staticcolor”, “grayscale”, or “staticgray”. See your X window documentation for details.
You cannot change this option once you’ve created the window. (visual/Visual)
width=
Window width, in pixels. If omitted, the widget is made large enough to hold its contents.