Application — Kivy v1.0.1-dev documentation

# 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.