The tkinter Button Widget

The Button widget is a standard tkinter widget used to implement various kinds of buttons. Buttons can contain text or images, and you can associate a Python function or method with each button. When the button is pressed, tkinter automatically calls that function or method.

The button can only display text in a single font, but the text may span more than one line. In addition, one of the characters can be underlined, for example to mark a keyboard shortcut. By default, the Tab key can be used to move to a button widget.

When to use the Button Widget #

Simply put, button widgets are used to let the user say “do this now!,” where this is either given by the text on the button, or implied by the icon displayed in the button. Buttons are typically used in toolbars, in application windows, and to accept or dismiss data entered into a dialog box.

For buttons suitable for data entry, see the Checkbutton and Radiobutton widgets.

Patterns #

Plain buttons are pretty straightforward to use. All you have to do is to specify the button contents (text, bitmap, or image) and what function or method to call when the button is pressed:

from tkinter import *

master = Tk()

def callback():
    print "click!"

b = Button(master, text="OK", command=callback)
b.pack()

mainloop()

A button without a callback is pretty useless; it simply doesn’t do anything when you press the button. You might wish to use such buttons anyway when developing an application. In that case, it is probably a good idea to disable the button to avoid confusing your beta testers:

b = Button(master, text="Help", state=DISABLED)

If you don’t specify a size, the button is made just large enough to hold its contents. You can use the padx and pady option to add some extra space between the contents and the button border.

You can also use the height and width options to explicitly set the size. If you display text in the button, these options define the size of the button in text units. If you display bitmaps or images instead, they define the size in pixels (or other screen units). You can specify the size in pixels even for text buttons, but that requires some magic. Here’s one way to do it (there are others):

f = Frame(master, height=32, width=32)
f.pack_propagate(0) # don't shrink
f.pack()

b = Button(f, text="Sure!")
b.pack(fill=BOTH, expand=1)

Buttons can display multiple lines of text (but only in one font). You can use newlines, or use the wraplength option to make the button wrap text by itself. When wrapping text, use the anchor, justify, and possibly padx options to make things look exactly as you wish. An example:

b = Button(master, text=longtext, anchor=W, justify=LEFT, padx=2)

To make an ordinary button look like it’s held down, for example if you wish to implement a toolbox of some kind, you can simply change the relief from RAISED to SUNKEN:

b.config(relief=SUNKEN)

You might wish to change the background as well. Note that a possibly better solution is to use a Checkbutton or Radiobutton with the indicatoron option set to false:

b = Checkbutton(master, image=bold, variable=var, indicatoron=0)

In earlier versions of tkinter, the image option overrides the text option. If you specify both, only the image is displayed. In later versions, you can use the compound option to change this behavior. To display text on top of an image, set compound to CENTER:

b = Button(master, text="Click me", image=pattern, compound=CENTER)

To display an icon along with the text, set the option to one of LEFT, RIGHT, TOP, or BOTTOM:

# put the icon to the left of the text label
b = Button(compound=LEFT, image=icon, text="Action")

# put the icon on top of the text
b = Button(compound=TOP, image=icon, text="Quit")

Reference #

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

A command button.

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.
activebackground=: What background color to use when the button is active. The default is system specific. (the option database name is activeBackground, the class is Foreground)
activeforeground=: What foreground color to use when the button is active. The default is system specific. (activeForeground/Background)
anchor=: Controls where in the button the text (or image) should be located. Use one of N, NE, E, SE, S, SW, W, NW, or CENTER. Default is CENTER. (anchor/Anchor)
background=: The background color. The default is system specific. (background/Background)
bg=: Same as background.
bitmap=: The bitmap to display in the widget. If the image option is given, this option is ignored. (bitmap/Bitmap)
borderwidth=: The width of the button border. The default is platform specific, but is usually 1 or 2 pixels. (borderWidth/BorderWidth)
bd=: Same as borderwidth.
command=: A function or method that is called when the button is pressed. The callback can be a function, bound method, or any other callable Python object. If this option is not used, nothing will happen when the user presses the button. (command/Command)
compound=: Controls how to combine text and image in the button. By default, if an image or bitmap is given, it is drawn instead of the text. If this option is set to CENTER, the text is drawn on top of the image. If this option is set to one of BOTTOM, LEFT, RIGHT, or TOP, the image is drawn besides the text (use BOTTOM to draw the image under the text, etc.). Default is NONE. (compound/Compound)
cursor=: The cursor to show when the mouse is moved over the button. (cursor/Cursor)
default=: If set, the button is a default button. tkinter will indicate this by drawing a platform specific indicator (usually an extra border). The default is DISABLED (no default behavior). (default/Default)
disabledforeground=: The color to use when the button is disabled. The background is shown in the background color. The default is system specific. (disabledForeground/DisabledForeground)
font=: The font to use in the button. The button can only contain text in a single font. The default is system specific. (font/Font)
foreground=: The color to use for text and bitmap content. The default is system specific. (foreground/Foreground)
fg=: Same as foreground.
height=: The height of the button. If the button displays text, the size is given in text units. If the button displays an image, the size is given in pixels (or screen units). If the size is omitted, it is calculated based on the button contents. (height/Height)
highlightbackground=: The color to use for the highlight border when the button does not have focus. The default is system specific. (highlightBackground/HighlightBackground)
highlightcolor=: The color to use for the highlight border when the button has focus. The default is system speciific. (highlightColor/HighlightColor)
highlightthickness=: The width of the highlight border. The default is system specific (usually one or two pixels). (highlightThickness/HighlightThickness)
image=: The image to display in the widget. If specified, this takes precedence over the text and bitmap options. (image/Image)
justify=: Defines how to align multiple lines of text. Use LEFT, RIGHT, or CENTER. Default is CENTER. (justify/Justify)
overrelief=: Alternative relief to use when the mouse is moved over the widget. If empty, always use the relief value. (overRelief/OverRelief)
padx=: Extra horizontal padding between the text or image and the border. (padX/Pad)
pady=: Extra vertical padding between the text or image and the border. (padY/Pad)
relief=: Border decoration. Usually, the button is SUNKEN when pressed, and RAISED otherwise. Other possible values are GROOVE, RIDGE, and FLAT. Default is RAISED. (relief/Relief)
repeatdelay=: (repeatDelay/RepeatDelay)
repeatinterval=: (repeatInterval/RepeatInterval)
state=: The button state: NORMAL, ACTIVE or DISABLED. Default is NORMAL. (state/State)
takefocus=: Indicates that the user can use the Tab key to move to this button. Default is an empty string, which means that the button accepts focus only if it has any keyboard bindings (default is on, in other words). (takeFocus/TakeFocus)
text=: The text to display in the button. The text can contain newlines. If the bitmap or image options are used, this option is ignored (unless the compound option is used). (text/Text)
textvariable=: Associates a tkinter variable (usually a StringVar) to the button. If the variable is changed, the button text is updated. (textVariable/Variable)
underline=: Which character to underline, in a text label. Default is -1, which means that no character is underlined. (underline/Underline)
width=: The width of the button. If the button displays text, the size is given in text units. If the button displays an image, the size is given in pixels (or screen units). If the size is omitted, or zero, it is calculated based on the button contents. (width/Width)
wraplength=: Determines when a button’s text should be wrapped into multiple lines. This is given in screen units. Default is 0 (no wrapping). (wrapLength/WrapLength)

flash() [#]

Flash the button. This method redraws the button several times, alternating between active and normal appearance.

invoke() [#]

Call the command associated with the button.

back next