Quick search

Kivy Base

This module contains the Kivy core functionality and is not intended for end users. Feel free to look through it, but bare in mind that calling any of these methods directly may result in an unpredictable behavior as the calls access directly the event loop of an application.

kivy.base.EventLoop = <kivy.base.EventLoopBase object>

EventLoop instance

class kivy.base.EventLoopBase[source]

Bases: kivy.event.EventDispatcher

Main event loop. This loop handles the updating of input and dispatching events.


Add a new event listener for getting touch events.

add_input_provider(provider, auto_remove=False)[source]

Add a new input provider to listen for touch events.


Add a postproc input module (DoubleTap, TripleTap, DeJitter RetainTouch are defaults).

async async_idle()[source]

Identical to idle(), but instead used when running within an async event loop.


Exit from the main loop and stop all configured input providers.


Called by EventLoopBase.idle() to read events from input providers, pass events to postproc, and dispatch final events.


Ensure that we have a window.


Close the main loop and close the window.


This function is called after every frame. By default:

  • it “ticks” the clock to the next frame.

  • it reads all input and dispatches events.

  • it dispatches on_update, on_draw and on_flip events to the window.


Event handler for on_pause which will be fired when the event loop is paused.


Event handler for on_start which will be fired right after all input providers have been started.


Event handler for on_stop events which will be fired right after all input providers have been stopped.

post_dispatch_input(etype, me)[source]

This function is called by EventLoopBase.dispatch_input() when we want to dispatch an input event. The event is dispatched to all listeners and if grabbed, it’s dispatched to grabbed widgets.


Remove android presplash in SDL2 bootstrap.


Remove an event listener from the list.


Remove an input provider.

Changed in version 2.1.0: Provider will be also removed if it exist in auto-remove list.


Remove a postproc module.


Main loop


Set the window used for the event loop.


Must be called before This starts all configured input providers.

Changed in version 2.1.0: Method can be called multiple times, but event loop will start only once.


Stop all input providers and call callbacks registered using EventLoop.add_stop_callback().

Changed in version 2.1.0: Method can be called multiple times, but event loop will stop only once.

property touches

Return the list of all touches currently in down or move states.

class kivy.base.ExceptionHandler[source]

Bases: builtins.object

Base handler that catches exceptions in runTouchApp(). You can subclass and extend it as follows:

class E(ExceptionHandler):
    def handle_exception(self, inst):
        Logger.exception('Exception caught by ExceptionHandler')
        return ExceptionManager.PASS


Then, all exceptions will be set to PASS, and logged to the console!


Called by ExceptionManagerBase to handle a exception.

Defaults to returning ExceptionManager.RAISE that re-raises the exception. Return ExceptionManager.PASS to indicate that the exception was handled and should be ignored.

This may be called multiple times with the same exception, if ExceptionManager.RAISE is returned as the exception bubbles through multiple kivy exception handling levels.

kivy.base.ExceptionManager: ExceptionManagerBase = <kivy.base.ExceptionManagerBase object>

The ExceptionManagerBase instance that handles kivy exceptions.

class kivy.base.ExceptionManagerBase[source]

Bases: builtins.object

ExceptionManager manages exceptions handlers.

PASS = 1

The exception should be ignored as it was handled by the handler.


The exception should be re-raised.


Add a new exception handler to the stack.


Called when an exception occurred in the runTouchApp() main loop.


Remove the exception handler from the stack.

async kivy.base.async_runTouchApp(widget=None, embedded=False, async_lib=None)[source]

Identical to runTouchApp() but instead it is a coroutine that can be run in an existing async event loop.

async_lib is the async library to use. See for details and example usage.

New in version 2.0.0.

kivy.base.runTouchApp(widget=None, embedded=False)[source]

Static main function that starts the application loop. You can access some magic via the following arguments:

See for example usage.


To make dispatching work, you need at least one input listener. If not, application will leave. (MTWindow act as an input listener)


If you pass only a widget, a MTWindow will be created and your widget will be added to the window as the root widget.


No event dispatching is done. This will be your job.

widget + embedded

No event dispatching is done. This will be your job but we try to get the window (must be created by you beforehand) and add the widget to it. Very useful for embedding Kivy in another toolkit. (like Qt, check kivy-designed)


Stop the current application by leaving the main loop.

See for example usage.