Kivy Part 6 – More Widgets – the Button Widget

In the previous part we left off with a basic Kivy app that displays a label. Now let’s explore some other widgets. In particular, I’m going to briefly discuss the widgets I’ll be making use of later in this tutorial, so the button widget, the toggle button widget, as well as the check box, text input and slider widgets.

But before we delve into the topic, here’s some info for you.

*****

Book Info

I just published my Kivy book, GUI Programming with Python and Kivy. It’s pretty long (over 800 pages) and comprehensive. And, which also counts, easy to read. The book contains lots of illustrations.

This book covers all the basics that you need to know to start programming GUI applications with Python and Kivy. Throughout the book we are building a GUI application from scratch, a fully functional game using all kinds of tools that Kivy has to offer. It’s our Slugrace project, but covered in a much more in-depth manner.

Each part of the book starts with a theoretical introduction of a topic or idea that we then implement in the project. I assume you have no prior knowledge of the Kivy library, but you should have at least some basic knowledge of the Python programming language, including the object-oriented programming paradigm as this is what we will be using a lot in this book.

The book covers all the basic elements of Kivy that you have to know, like widgets, layouts, Kivy ids and properties, graphics, screens, animation, sound. Finally we’ll deploy the app to Windows. It is pretty comprehensive and after you finish it, I’m sure you’ll be able to create your own awesome GUI apps of any kind, not just games.

I hope you will have at least as much fun reading the book as I had writing it.

As far as this Kivy series is concerned, the following parts will contain the most important elements covered in the book. However, some elements will be presented in a simplified way here on my blog or omitted completely.

____________

If you are interested, you can purchase the book in four versions. Here are the links:

1) ebook – pdf version on my website – in full color

Here you can see the description of the book, sample graphics from the book and the full table of contents.

2) ebook – Kindle version on Amazon – in full color

3) paperback version on Amazon – in black and white

4) paperback version on Amazon – in full color

*****

And Now Let’s Move On…

I’m going to start with the Button widget in this part and I’ll discuss the other widgets in the following parts.

A Button Widget is Basically a Label…

In Kivy the Button class inherits from Label, so they have the same properties in common, plus the button has some extra functionality. In particular they share the text property. Let’s modify our main.py and helloworld.kv files so that our program displays a button widget instead of a label. First, let the changes be as few as possible. Here’s the main.py file:

# File name: main.py

import kivy
from kivy.app import App

# We're not importing Label anymore.
#from kivy.uix.button import Label

# Instead we're importing Button
from kivy.uix.button import Button

class HelloWorldApp(App):
    def build(self):
        # We don't want to return a label, but rather...
        #return Label()

        # a button
        return Button()

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

and here’s the kv file:

# File name: helloworld.kv

# Let's just change Label to Button.
<Button>:    
    text: 'normal [b]bold[/b] [i]italic[/i] \n[u]underlined[/u] [s]strikethrough[/s] \n[sub]subscript[/sub] [sup]superscript[/sup] [size=100]big[/size] [color=#ff0f]yellow[/color]'
    font_size: 50
    color: [126/255, 45/255, 210/255, 1]
    markup: True

Again, the whole string in the text property should be on one line. Anyway, this code is exactly the same as we left off at in the previous part except for one detail: now we have the Button class instead of Label. Run this code and the output will be very much like before. But this time the whole window is filled with our big button with lots of formatted text on it. If it’s a button, you can click it. Give it a try and you will see that it changes color when clicked. Naturally nothing else is going to happen because there isn’t any code yet that would handle the button click. But we now have a fully functional button:

How About a Button Widget that Looks More Like a Button?

What we just saw is definitely a button, although usually we don’t put so much text on a button. We don’t format the text on a button in such a way either. Let’s simplify our button a bit so that it looks more like a button you’re used to. Let’s say we want the button text to read: ‘Click here’, without any markup formatting or any fancy colors. Here’s the modified code that will give us a simple button. The main.py file remains untouched, I just cleared it up a little by removing the comments:

# File name: main.py

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

class HelloWorldApp(App):
    def build(self):
        return Button()

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

And now the kv file:

# File name: helloworld.kv

<Button>:    
    text: 'Click here'
    font_size: 50   

If you now run this code, the button will look more familiar. It’s still going to fill up all the available space, because it’s the only widget for the time being.

Basic Button Events

Why do we even use buttons instead of labels? Well, as mentioned before, they have some extra functionality. They can be clicked, or pressed, as you just saw. I’m going to talk about events in Kivy a bit later, but as we are at it, let’s just see how to handle pressing the button directly in kv. For more advanced scenarios, we’ll be handling events in Python code later on.

So, let’s say we want the font size to be 100 instead the original 50 when the button is pressed. The main.py code remains the same, but in kv we just add the code that will handle the press event:

<Button>:    
    text: 'Click here'
    font_size: 50 

    # You should use self to refer to the Button object itself.
    # So, self.text refers to the text property on the Button object
    # and self.font_size refers to the Button object's font_size property.  
    on_press: self.font_size = 100

If you now run the program and press the button, the font size will be changed.

The problem with this code is that the font_size doesn’t change back after you release the button. Fortunately there’s an easy way to fix it. All you have to do is tell the program what to do when the button is released:

# File name: helloworld.kv

<Button>:    
    text: 'Click here'
    font_size: 50      
    on_press: self.font_size = 100
    on_release: self.font_size = 50

Now it will work as expected, but don’t take my word for it.

Multiple Commands

And now suppose we want the button not only to resize its font when pressed, but also to change the text to ‘pressed’. When released, the font_size should be set back to 50 and the text should change to ‘Click again’. You can do it in two ways. The first way is just to add as many on_press and on_release lines as needed:

# File name: helloworld.kv

<Button>:    
    text: 'Click here'
    font_size: 50      
    on_press: self.font_size = 100
    on_press: self.text = 'pressed'
    on_release: self.font_size = 50
    on_release: self.text = 'Click again'

The second, more concise way is to separate the commands by semicolons:

<Button>:    
    text: 'Click here'
    font_size: 50   
    on_press: self.font_size = 100; self.text = 'pressed'
    on_release: self.font_size = 50; self.text = 'Click again'

Either way you choose, the result will be the same:

This is all you need to know about the Button class for now. We’ll be using buttons a lot, so we’re definitely going to learn more about them in near future. Anyways, in the next part I’d like to just touch upon all the other widgets that we’ll be making use of, so toggle button, check box, text input and slider.