Widget tree

Like most GUI toolkits, Kivy has a tree for handling a hierarchy of widgets. The top level widget is called “root”. Each widget can be connected to other widgets, as a parent or as a child.

You cannot add into the widget tree something that is not a Widget subclass.

Manipulating the tree

The tree can be manipulated with 3 methods:

For example, if you want to add a button inside a boxlayout, you can do:

layout = BoxLayout(padding=10)
button = Button(text='My first button')
layout.add_widget(button)

Now, the button parent will be set to layout, and layout will have button in his children list. To remove the button from the layout:

layout.remove_widget(button)

The button parent will be set to None, and layout will remove button from his children list.

If you want to clear all the children inside a widget, use clear_widgets() method:

layout.clear_widgets()

Warning

Never manipulate the children list yourself, if you don’t know what you are doing. The widget tree is associated to a graphic tree. For example, if you add a widget into the children list without adding its canvas to the graphics tree, the widget will be a child yes, but nothing will be drawn on the screen. More than that, you might have issues on further calls of add_widget, remove_widget and clear_widgets.

Traversing the tree

The widget class has a children list property that contains all the children. You can easily traverse the tree by doing

root = BoxLayout()
# ... add widgets to root ...
for child in root.children:
    print child

However, this must be used carefuly. If you intend to modify the children list with one of the methods shown in the previous section, you must use a copy of the list like this:

for child in root.children[:]:
    # manipulate the tree. For example here, remove all widgets that have a
    # width < 100
    if child.width < 100:
        root.remove_widget(child)