Apps will come to live once you can react to users clicking on buttons and other items of your app. This little teaser shows you how to react on clicks on a button and gives you a first insight on how to interact between different widgets.

Good to Know

A Kivy app is made from widgets. Widgets can be every thing. From simple buttons and text labels up to very complex constructs which combine a variety of many simple widgets to build something new. Thes widgets reat to events, such as clicks. Once you learn how to catch these events can you teach your widgets to do anything. 

Another important thing in Kivy are the layouts. They take care of the arrangement of your widgets and let you place them in a convenient way.

The Code

This app will ask the user to click on a button as often as he wants. The clicks will be counted and displayed in a separate label.

The imports are done quickly.  

from kivy.app import App
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.label import Label
from kivy.uix.button import Button
from kivy.properties import NumericProperty

The class MyLabel inherits from Label in gets the function update_text. Thid function will be called each time the button is clicked. And it is going to show the variable value for the counter. This variable is passed on from the button.

class MyLabel(Label):
    def update_text(self, obj, value):
        self.text = 'You clicked the button ' + str(value) + ' times'

Our button is also a standard Button which we top up with a so called NumericProperty. These properties are not to be confused with Python properties. These are Kivy Properties. And the cool thing is that you can bind them to other stuff, like the function update_text in our label. The binding happens a bit further down in the code of the App class. Within the __init__ function do we set the initial text of the button. And we add the function on_press to react to a user pressing the button. We simply increase our counter by one.

class MyButton(Button):
    counter = NumericProperty(0)

    def __init__(self, **kwargs):
        super(MyButton, self).__init__(**kwargs)
        self.text = 'Click Me'

    def on_press(self):
        self.counter = self.counter + 1

The build function of our App class is a bit more complex now. We start by creating a layout. This specific layout is a BoxLayout and it equally sizes all widgets it contains. The standard behaviour is that the widgets are added horizontally and I just leave it like that. Next we create our MyLabel and MyButton instances. Now the mentioned binidng happens. by calling the bind function of the button. In this example are we binding the counter value of the button to the update_text function of the label. Each time the counter variable changes, the function update_text is called and the content of the variable counter is passed by the variable value. Sounds confusing? But we will work in more detail with the various ways of binding and it will become clear by then.

Finally I add the label and button to the layout.

class KlickCounterApp(App):
    def build(self):
        layout = BoxLayout()
        label = MyLabel()
        button = MyButton()

        button.bind(counter = label.update_text)

        layout.add_widget(label)
        layout.add_widget(button)

        return layout

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

When you run the app you can see our button asking for a nice firm press and our label waiting for numbers to display.

Please also try to click on the label. You will notice that the counter is not increased. The function on_press is only called whan this specific button is pressed.

 What's Next?

Now that you have seen some basic widgets and got a glimplse on events (on_press) and binding will we take a short detour on how to draw on the canvas of a widghet before we create a first little game.