Keywords for root, self, and app, and app.root in Kivy KV Language

This section describes the root, self, and app, and app.root keywords used to refer to widgets in the kv language.

Three Keywords to Refer to Widgets

In the kv language, there are three keywords used to refer to widgets, similar to self and super used in Python, and in Kivy, the keywords are used for widgets and class instances, but from different perspectives.

• self: refers to the widget itself, which in Python code is a normal instance reference. This keyword is used to refer to instances or widgets of the class.
  
• root: refers to the root widget of the application; root is the widget returned by the build method.
  
• app: refers to the instance of the currently running application, which is an instance of a class defined by inheriting from the App class.

self Keyword

In the case of Python code, self is an ordinary instance reference, a keyword used to refer to an instance or widget of that class.
in the case of a Kv file, it refers to the widget itself. For example, when self is used in the definition of a Label widget, it refers to the Label itself.

example_keywords1.py

from kivy.app import App
from kivy.uix.boxlayout import BoxLayout

class MyWidget(BoxLayout):
    def update_label1(self):
        # Label widget as seen by the root widget.
        self.ids.label1.text = 'Changed text of Label 1'

class ExampleKeywords1(App):
    def build(self):
        return MyWidget()

if __name__ == "__main__":
    ExampleKeywords1().run()

examplekeywords1.kv

<MyWidget>:
    orientation: 'vertical'

    Label:
        id: label1
        text: 'Press the button to change the text.'
        
    Label:
        id: label2
        text: self.text  # Reference to own property.
        on_touch_down: self.text = 'It's clicked'  # Updating Ourselves.

    Button:
        text: 'Click here'
        on_press: root.update_label1()

self as Seen From a KV File

Used when you want to reference a property of the widget itself.

text: self.text

Since it refers to its own text property, the keyword is self.

on_touch_down: self.text = 'It's clicked'

This keyword will be self as it is updating its own text.

self as Seen from a Python File

From a Python perspective, self is an instance of the current class (MainWidget). In other words, from the root’s perspective, Label and Button are under its own tree, so it becomes self from the MainWidget’s perspective.

self.ids.label1.text = 'Changed text of Label 1'

The Label widget belongs to the MainWidget, so it is self as seen from the root widget.

root Keyword

refers to the root widget of the application. root is a subclass that inherits from the widget returned by the build method. root refers to the root widget and other widgets defined in the kv file. It is also used to refer to the methods of instances of the root widget (instances of subclasses that inherit from the widget written in Python code).

example_keywords2.py

from kivy.app import App
from kivy.uix.boxlayout import BoxLayout

class MainWidget(BoxLayout):
    label_text = 'This is the root widget class variable string.'

    def on_button_click(self):
        self.ids.mylabel.text = 'Changed the text of Label in root.'

class ExampleKeywords2(App):
    def build(self):
        return MainWidget()

if __name__ == "__main__":
    ExampleKeywords2().run()

examplekeywords2.kv

<MainWidget>:
    orientation: 'vertical'

    Label:
        id: mylabel
        text: 'Get from root widget: ' + root.label_text

    Button:
        text: 'Click here'
        on_press: root.on_button_click()

root as Seen From a KV File

The root from the kv file is the root widget. The root widget here is the MainWidget class.

<MainWidget>
+--- BoxLayout
+---+--- Label
+---+--- Button

In this code example, the tree structure is as shown above. When a widget at the described location references another widget, that widget becomes the root. In other words, Label as seen from Button is the root, and Button as seen from Label is the root.

The root is also used when referencing a class variable or method of the MainWidget.

text: 'Get from root widget: ' + root.label_text

The keyword is root because it refers to the label_text variable of the MainWidget.

on_press: root.on_button_click()

Since we are calling the on_button_click method of MainWidget, the keyword is root.

root as Seen From a Python File

In this case, it replaces self because it is itself root.

self.ids.mylabel.text = 'Changed the text of Label in root.'

Since the Label widget belongs to the MainWidget, it becomes self when viewed from the root widget.

app Keyword

The app keyword refers to the instance of the App class that is currently running. In other words, it is used to refer to variables and methods defined in the App class. app may or may not be used, depending on the design. app is suitable for app-wide operations, whereas self and root refer to things in the local scope. If you want to manage data used throughout the application or methods that control the application, you should write them in a subclass that inherits from the App class.

example_keywords3.py

from kivy.app import App

class ExampleKeywords3(App):
    app_value = 'It's a variable in the App subclass.'

    def on_button_press(self):
        self.root.ids.my_label.text = 'Button pressed.'

if __name__ == "__main__":
    ExampleKeywords3().run()

examplekeywords3.kv

BoxLayout:
    orientation: 'vertical'

    Label:
        id: my_label
        text: app.app_value  # Refer to App subclass variables.

    Button:
        text: 'Button'
        on_press: app.on_button_press() #　Call methods of App subclass.

app as Seen From a KV File

When referring to a class variable or class method of an App subclass, it becomes app.

 text: app.app_value

Since it refers to a class variable of the App subclass, it becomes app.

 on_press: app.on_button_press()

Since it refers to a class method of the App subclass, it becomes app.

app as Seen From a Python File

To refer to the widget in the root widget from the App subclass, it will be ” self.root“. It has the same meaning as app.root in the next chapter. Here, app is self.root because it is itself.

self.root.ids.my_label.text = 'Button pressed.'

The keyword is “self.root” because it refers to the Label widget belonging to the root object that app itself has.

app.root Keyword

If a reference to a different class or the hierarchy of the tree structure is deep, it may not be possible to refer to it for reasons of scope or parent-child relationship. In that case, try app.root. app.root refers to the root widget (root) of the currently running application instance (app). In other words, app.root allows you to access root via app.

The following is a sample code to check app.root. A message is displayed on the console.

from kivy.app import App
from kivy.uix.boxlayout import BoxLayout
from kivy.lang import Builder
from kivy.uix.widget import Widget

# Write kv language directly in Python files.
kv_code = '''
<MyWidget>:
    Button:
        text: 'Click here'
        on_press: app.root.other_widget.scope_test1()
'''

Builder.load_string(kv_code)

class OtherWidget(Widget):
    def scope_test1(self):
        print('Refer to OtherWidget')
        app = App.get_running_app() # Get current application instance.
        app.root.scope_test2()

class MyWidget(BoxLayout):
    other_widget = OtherWidget()  # Create an instance of OtherWidget.

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.add_widget(self.other_widget)  # Add OtherWidget to MyWidget.

    def scope_test2(self):
        print('Refer to MyWidget.')

class ExampleKeywords4(App):
    def build(self):
        return MyWidget()

if __name__ == "__main__":
    ExampleKeywords4().run()

Since we cannot access other classes directly from OtherWidget(), we use app.root.

app.root.other_widget.scope_test1()

In kv code, the root widget, MyWidget(), calls the scope_test1 method of the out-of-scope OtherWidget(), so app.root is used. Since an instance of OtherWidget() is assigned to the instance variable other_widget, it is written to be called in namespace order as above.

App application -> root widget -> instance of OtherWidget() -> method of OtherWidget()

app = App.get_running_app() #Get the current application instance
    app.root.scope_test2()

In the Python code, ExampleKeywords4() cannot be referenced because it is out of scope from the perspective of OtherWidget(). Therefore, it is necessary to get an instance of App and refer to a subclass of App. get_running_app() is used to get an instance of App. Here we assign this to the app instance variable. Now all that remains is to call these in namespace order.

App application -> root widget -> MyWidget() method

Please also see the following article for a good example of using app.root.

Summary

Note that the keywords are different depending on which widget you are looking at this from.

• When referring to own widget, use self.
• When referring to a widget other than itself, use root or app.
• When referring to a widget from the root widget, it is self.
• When referring to a widget from App, self.root.