Button Behavior¶

The ButtonBehavior mixin class provides button behavior for Kivy widgets. You can combine this class with other widgets to add specialized press/release/cancel events and reactive pressed state tracking.

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

Examples¶

Basic button with visual feedback:

from kivy.app import App
from kivy.uix.label import Label
from kivy.uix.behaviors import ButtonBehavior

class MyButton(ButtonBehavior, Label):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.text = "Press me!"

    def on_pressed(self, instance, is_pressed):
        # Visual feedback: red when pressed, white otherwise
        self.color = [1, 0, 0, 1] if is_pressed else [1, 1, 1, 1]

    def on_press(self):
        print("Button pressed")

    def on_release(self):
        print("Button released")

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

SampleApp().run()

Handling button cancellation:

from kivy.app import App
from kivy.uix.label import Label
from kivy.uix.behaviors import ButtonBehavior

class MyButton(ButtonBehavior, Label):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.text = 'Press me!'
        self.always_release = False  # Enable cancellation

    def on_press(self):
        self.text = 'Pressed - drag outside to cancel'

    def on_release(self):
        self.text = 'Released!'

    def on_cancel(self):
        self.text = 'Action cancelled!'

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

SampleApp().run()

See ButtonBehavior for details.

class kivy.uix.behaviors.button.ButtonBehavior(**kwargs)¶

Bases: builtins.object

Mixin to add button behavior to any Kivy widget.

This mixin enables widgets to respond to press/release interactions with automatic multi-touch support. It provides three specialized events: on_press(), on_release(), and on_cancel(), along with a reactive pressed property.

Button State Management¶

Tracks active touches internally using a set-based approach. Each touch gets a unique ID (supports multi-touch). When first touch enters widget bounds, button becomes pressed. When ALL touches are released or cancelled, button returns to unpressed state. The pressed property is True when any touches are active.

Multi-Touch Behavior¶

The button automatically handles multiple simultaneous touches:

First touch down: Triggers on_press(), sets pressed to True
Additional touches: Tracked but don’t trigger on_press() again
Touch release: Only triggers on_release() after ALL touches released
Touch cancel: Removes touch from tracking, updates pressed state

Release Modes¶

Controlled by always_release property:

False (default): Standard button behavior. on_release() only fires if touch ends within button bounds. on_cancel() fires when touch moves outside bounds during drag (touch move).
True: Always fires on_release() regardless of touch position. on_cancel() never fires. Useful for drag-and-drop or gesture-based interfaces.

Events¶

on_press()

First touch down on button

on_release()

All touches released (respects always_release mode)

on_cancel()

Touch moved outside bounds during drag (only when always_release: is False)

Changed in version 3.0.0: - Replaced state OptionProperty with pressed BooleanProperty - Made pressed read-only via AliasProperty - Added on_cancel() event - Improved multi-touch handling with explicit touch sets

on_cancel()¶

Event handler called when touch leaves button bounds during drag.

This event is only fired when always_release is False and a touch moves outside the button’s bounds during a drag operation. It provides an opportunity to give visual feedback that the button action has been cancelled.

Use this to restore the button’s original appearance or cancel any pending actions that would have occurred on release.

New in version 3.0.0.

on_press()¶

Event handler called when the button is pressed.

This event is fired when the first touch down occurs on the button. In multi-touch scenarios, only the first touch triggers this event.

on_release()¶

Event handler called when the button is released.

This event is fired when the last active touch is released, and only if: - The touch is released within button bounds, OR - The always_release property is True

on_touch_down(touch)¶

Handle touch down events.

Implements core press detection:

Test collision with widget bounds
Grab touch if colliding (marks widget as touch owner)
Add to active touches tracking
Dispatch on_press() on first touch

Parameters:: touch – MotionEvent instance
Returns:: True if event was handled (collided with widget)

on_touch_move(touch)¶

Handle touch move events.

Detects when touch moves outside button bounds during drag and triggers cancellation if always_release is False.

Cancellation flow: 1. Touch owned by this widget moves outside bounds 2. Remove from active touches, add to cancelled touches 3. Dispatch on_cancel() if this was the last active touch

Parameters:: touch – MotionEvent instance
Returns:: True if event was handled

on_touch_up(touch) → bool¶

Handle touch up events.

Implements release detection:

Verify we own this touch
Ungrab touch to release ownership
Remove from active/cancelled tracking
Dispatch on_release() if appropriate: - Touch wasn’t cancelled, AND - (Touch ended within bounds OR always_release is True), AND - This was the last active touch

Parameters:: touch – MotionEvent instance
Returns:: True if event was handled

« Behaviors

Code Navigation Behavior »

Version

Quick search

Table Of Contents