The tkinter Radiobutton Widget

The Radiobutton is a standard tkinter widget used to implement one-of-many selections. Radiobuttons 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.

Each group of Radiobutton widgets should be associated with single variable. Each button then represents a single value for that variable.

When to use the Radiobutton Widget

The radiobutton widget is used to implement one-of-many selections. It’s almost always used in groups, where all group members use the same variable.

Patterns #

The Radiobutton widget is very similar to the check button. To get a proper radio behavior, make sure to have all buttons in a group point to the same variable, and use the value option to specify what value each button represents:

from tkinter import *

master = Tk()

v = IntVar()

Radiobutton(master, text="One", variable=v, value=1).pack(anchor=W)
Radiobutton(master, text="Two", variable=v, value=2).pack(anchor=W)

mainloop()

If you need to get notified when the value changes, attach a command callback to each button.

To create a large number of buttons, use a loop:

    MODES = [
        ("Monochrome", "1"),
        ("Grayscale", "L"),
        ("True color", "RGB"),
        ("Color separation", "CMYK"),
    ]

    v = StringVar()
    v.set("L") # initialize

    for text, mode in MODES:
        b = Radiobutton(master, text=text,
                        variable=v, value=mode)
        b.pack(anchor=W)

Figure: Standard radiobuttons

To turn the above example into a “button box” rather than a set of radio buttons, set the indicatoron option to 0. In this case, there’s no separate radio button indicator, and the selected button is drawn as SUNKEN instead of RAISED:

Figure: Using indicatoron=0

Reference

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

A radio button. Radio buttons are usually used in groups, where all buttons in the group share a common variable.

__init__(master=None, **options) [#]

Create a radiobutton widget.

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. (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)
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)
indicatoron=: If true, the widget uses the standard radio button look. If false, the selected button is drawn as SUNKEN instead. Default is true. (indicatorOn/IndicatorOn)
justify=: Defines how to align multiple lines of text. Use LEFT, RIGHT, or CENTER. Default is CENTER. (justify/Justify)
offrelief=: Default is raised. (offRelief/OffRelief)
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. One of SUNKEN, RAISED, GROOVE, RIDGE, or FLAT. Default is FLAT if indicatoron is true, otherwise RAISED. (relief/Relief)
selectcolor=: Default value is ‘SystemWindow’. (selectColor/Background)
selectimage=: No default value. (selectImage/SelectImage)
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)
value=: The value associated with this radiobutton. All buttons in the same group should have distinct values. (value/Value)
variable=: The variable that’s associated with this button. To get proper radio behaviour, you need to associate the same variable to all buttons in the same group. (variable/Variable)
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)

deselect() [#]

Deselects the button.

flash() [#]

Redraws the button a couple of times, alternating between active and normal appearance. This can be useful when debugging, or to indicate when some other user action has activate the button.

invoke() [#]

Calls the command associated with the button.

select() [#]

Selects the button.

back next