An Introduction to Tkinter
  Copyright 1997 by Fredrik Lundh <fredrik@pythonware.com>  
  Updated 11 Aug 1997  

< Application Windows | Standard Dialogues | Dialogue Windows >

Standard Dialogues

Before we look at what to put in that application work area, let's take a look at another important part of GUI programming: displaying dialogues and message boxes.

Starting with Tk 4.2, the Tk library provides a set of standard dialogues that can be used to display message boxes, and to select files and colours. In addition, Tkinter provides some simple dialogues allowing you to ask the user for integers, floating point values, and strings. Where possible, these standard dialogues use platform-specific mechanisms, to get the right look and feel.

Message Boxes

The tkMessageBox module provides an interface to the message dialogues. This module will be included in Python 1.5. If you use 1.4, you can find the necessary sources here.

The easiest way to use this module is to use one of the convenience functions: showinfo, showwarning, showerror, askquestion, askokcancel, askyesno, or askretryignore. They all have the same syntax:

result = tkMessageBox.function(title, message [, options])

The title argument is shown in the window title, and the message in the dialog body. You can use newline characters ("\n") in the message to make it occupy multiple lines. The options can be used to modify the look; they are explained later in this section.

The first group of standard dialogues is used to present information. You provide the title and the message, the function displays these using an appropriate icon, and returns when the user has pressed OK. The return value should be ignored.

Here's an example:

try:
    fp = open(filename)
except:
    tkMessageBox.showwarning(
        "Open file",
        "Cannot open this file\n(%s)" % filename
    )
    return

Figure: showinfo, showwarning, showerror

The second group is used to ask questions. The askquestion function returns the strings "yes" or "no" (you can use options to modify the number and type of buttons shown), while the others return a true value of the user gave a positive answer (ok, yes, and retry, respectively).

if tkMessageBox.askyesno("Print", "Print this report?"):
    report.print()

Figure: askquestion

Figure: askokcancel, askyesno, askretryignore

[Screenshots made on a Swedish version of Windows 95. Hope you don't mind...]

Message Box Options

If the standard message boxes are not appropriate, you can pick the closest alternative (askquestion, in most cases), and use options to change it to exactly suit your needs. You can use the following options (note that message and title are usually given as arguments, not as options).

Option Type Description
default constant Which button to make default: ABORT, RETRY, IGNORE, OK, CANCEL, YES, or NO (the constants are defined in the tkMessageBox module).
icon constant Which icon to display: ERROR, INFO, QUESTION, or WARNING
message string The message to display (the second argument to the convenience functions). May contain newlines.
parent widget Which window to place the message box on top of. When the message box is closed, the focus is returned to the parent window.
title string Message box title (the first argument to the convenience functions)
type constant Message box type; that is, which buttons to display: ABORTRETRYIGNORE, OK, OKCANCEL, RETRYCANCEL, YESNO, or YESNOCANCEL.

Data Entry

The tkSimpleDialog module provides an interface to the following simple dialogues. This module will be included in Python 1.5. If you use 1.4, you can find the necessary sources here.

Strings

The askstring function in the tkSimpleDialog module prompts the user for a string. You specify the dialogue title and the prompt string, and the function returns when the user closes the dialog. The prompt string may include newline characters.

result = tkSimpleDialog.askstring(title, prompt [,options])

If the user pressed Enter, or clicked OK, the function returns the string. If the user closed the dialog by pressing Escape, clicking Cancel, or explicitly via the window manager, this function returns None.

Figure: askstring

The following options can be used with this function:

Option Type Description
initialvalue string Initial value, if any. Default is an empty string.
parent widget Which window to place the dialogue on top of. When the dialog is closed, the focus is returned to the parent window.

Numeric Values

The askinteger and askfloat functions is similar to askstring, but they only accept integers and float values, respectively. You can also use the minvalue and maxvalue options to limit the input range:

result = tkSimpleDialog.askinteger(title, prompt [,options])
result = tkSimpleDialog.askfloat(title, prompt [,options])

If the entered value is not a valid integer or floating point value, a message box is displayed, and the dialogue is not closed. As with the askstring function, the function returns None if the dialogue box is cancelled.

Figure: askinteger, askfloat

The following options can be used with these functions:

Option Type Description
initialvalue integer or float Initial value, if any. Default is an empty string.
parent widget Which window to place the dialogue on top of. When the dialog is closed, the focus is returned to the parent window.
minvalue integer or float Minimum value. If exceeded, a message box is shown when the user clicks OK, and the dialog will not be closed. Default is no check.
maxvalue integer or float Maximum value. If exceeded, a message box is shown when the user clicks OK, and the dialog will not be closed. Default is no check.

File Names

The tkFileDialog module (included in the tkMessageBox kit described earlier) can be used to get a filename from the user. The module provides two convenience functions, one to get an existing filename so you can open it, and one to get a new filename, to save things into.

filename = tkFileDialog.askopenfilename([options])
filename = tkFileDialog.asksaveasfilename([options])

If the dialog is cancelled by the user, the function returns None.

Figure: askopenfilename, asksaveasfilename (Swedish version)

The following options can be used with the askopenfilename and asksavefilename functions:

Option Type Description
defaultextension string An extension to add to the filename, if not explicitly given by the user. The string should include the leading dot (ignored by the open dialog)
filetypes   Sequence of (label, pattern) tuples. The same label may occur with several patterns. Use "*" as the pattern to indicate all files.
initialdir string Initial directory.
initialfile string Initial file (ignored by the open dialog)
parent widget Which window to place the message box on top of. When the dialog is closed, the focus is returned to the parent window.
title string Message box title.

Colours

The tkColorChooser module (included in the tkMessageBox kit described earlier) can be used to specify an RGB colour value.

rgb, col = tkColorChooser.askcolor([color [,options]])

The convenience function returns two values; the first is the colour as a RGB triplet (a 3-tuple containing the red, green and blue values as integers in the range 0-255), the second a Tk colour string. To preset a colour when you display the dialogue, you can pass a colour (in either format) to the function.

If the dialog is cancelled, the function returns (None, None)

Figure: askcolor (in Swedish)

The following options can be used with the askcolor function:

Option Type Description
initialcolor color Colour to mark as selected when dialog is displayed (given as an RGB triplet or a Tk color string). (the first argument to the convenience function).
parent widget Which window to place the message box on top of. When the dialog is closed, the focus is returned to the parent window.
title string Message box title.

< Application Windows | Standard Dialogues | Dialogue Windows >