Quick search

Table Of Contents

ToggleButton Behavior

The ToggleButtonBehavior mixin class provides ToggleButton behavior. You can combine this class with other widgets, such as an Image, to provide alternative togglebuttons that preserve Kivy togglebutton behavior.

For an overview of behaviors, please refer to the behaviors documentation.


The following example adds togglebutton behavior to an image to make a checkbox that behaves like a togglebutton:

from kivy.app import App
from kivy.uix.image import Image
from kivy.uix.behaviors import ToggleButtonBehavior

class MyButton(ToggleButtonBehavior, Image):
    def __init__(self, **kwargs):
        super(MyButton, self).__init__(**kwargs)
        self.source = 'atlas://data/images/defaulttheme/checkbox_off'

    def on_state(self, widget, value):
        if value == 'down':
            self.source = 'atlas://data/images/defaulttheme/checkbox_on'
            self.source = 'atlas://data/images/defaulttheme/checkbox_off'

class SampleApp(App):
    def build(self):
        return MyButton()

class kivy.uix.behaviors.togglebutton.ToggleButtonBehavior(**kwargs)[source]

Bases: kivy.uix.behaviors.button.ButtonBehavior

This mixin class provides togglebutton behavior. Please see the togglebutton behaviors module documentation for more information.

New in version 1.8.0.


This specifies whether the widgets in a group allow no selection i.e. everything to be deselected.

New in version 1.9.0.

allow_no_selection is a BooleanProperty and defaults to True

static get_widgets(groupname)[source]

Return a list of the widgets contained in a specific group. If the group doesn’t exist, an empty list will be returned.


Always release the result of this method! Holding a reference to any of these widgets can prevent them from being garbage collected. If in doubt, do:

l = ToggleButtonBehavior.get_widgets('mygroup')
# do your job
del l


It’s possible that some widgets that you have previously deleted are still in the list. The garbage collector might need to release other objects before flushing them.


Group of the button. If None, no group will be used (the button will be independent). If specified, group must be a hashable object, like a string. Only one button in a group can be in a ‘down’ state.

group is a ObjectProperty and defaults to None.