Application

The App class is the base for creating Kivy applications. Think of it as your main entry point into the Kivy runloop. In most cases, you subclass this class and make your own app. You create an instance of your specific app class and then, when you are ready to start the application’s life cycle, you call your instance’s App.run() method.

Create an application by overidding build()

To initialize your app with a widget tree, override the build() method in your app class and return the widget tree you constructed.

Here’s an example of very simple application that just shows a button:

from kivy.app import App
from kivy.uix.button import Button

class TestApp(App):
    def build(self):
        return Button(text='hello world')

if __name__ == '__main__':
    TestApp().run()

Check kivy/examples/application/app_with_build.py.

Create an application with kv file

You can also use the Kivy language for creating application. The .kv can contain rules and root widget definitions at the same time. Here is the same example as the Button one in a kv file.

Content of ‘test.kv’:

#:kivy 1.0

Button:
    text: 'Hello world'

Content of ‘main.py’:

from kivy.app import App

class TestApp(App):
    pass

if __name__ == '__main__':
    TestApp().run()

Check kivy/examples/application/app_with_kv.py.

The relation between main.py and test.kv is explained in App.load_kv().

class kivy.app.App(**kwargs)

Bases: kivy.event.EventDispatcher

Application class, see module documentation for more informations.

Events :
on_start:

Fired when the application is beeing started (before the runTouchApp() call.

on_stop:

Fired when the application stop.

build()

Initializes the application, will be called only once. If this method returns a widget (tree), it will be used as the root widget and added to the window.

load_kv()

If the application have never been built, try to found the kv of the application in the same directory as the application class.

For example, if you have a file named main.py that contains:

class ShowcaseApp(App):
    pass

The load_kv() will search for a filename named showcase.kv in the directory of the main.py. The name of the kv file is the lower name of the class, without the App at the end if exist.

You can define rules and root widget in your kv file:

<ClassName>: # this is a rule
    ...

ClassName: # this is a root widget
    ...

You cannot declare a root widget twice. Check Kivy language documentation for more information about how to create kv files. If your kv file return a root widget, it will be set in self.root

on_start()

Event handler for the on_start event, which is fired after initialization (after build() has been called), and before the application is being run.

on_stop()

Event handler for the on_stop event, which is fired when the application has finished running (e.g. the window is about to be closed).

root

Root widget setted by the build() method or by the load_kv() method if the kv file return a root widget.

run()

Launches the app in standalone mode.

stop(*largs)

Stop the application.

If you use this method, the whole application will stop by using stopTouchApp() call.