Kivy Part 4 – Using Python and the Kivy Language

Before we rewrite our app using the Kivy language, let’s have a look at what we have. In the previous part we left off with a basic Kivy app written entirely in Python. Here’s the code again:

# File name: main.py 
# We're using Kivy, so we'll need the kivy module
import kivy

# We need the App class. Our application is going to inherit from it.
from kivy.app import App

# We also need the Label widget.
from kivy.uix.button import Label

# Here comes the application class. It inherits from App.
class HelloWorldApp(App):
    def build(self):
        return Label(text='Hello World!')

# And this is where we actually run the app.
if __name__ == '__main__':
    HelloWorldApp().run()

I also mentioned that for such a basic program it doesn’t make much sense to split it into two files, one for the logic and one for the presentation. However, let’s do it just so that you know how to do it.

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…

Our program contains just one widget, the label. This is all as far as presentation is concerned. We’ll move that part to a new file and leave the rest in the main.py file. So, after we remove the presentation part from the main.py, as well as the comments to make the file clear and transparent, this is what we’ll have:

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

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

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

As you can see, now we’re just telling the app that a label should be used, but it doesn’t know anything more about the label. In particular, it doesn’t know what text should go in the label. This is what the kv file is going to take care of. By the way, I’m going to call the files written in the Kivy language kv files, for the sake of brevity. These files are easily recognizable by the kv extension.

kv Files and the Kivy Language

Now we are ready to create the kv file. Actually, there are two approaches to this. If you have just one kv file, you can go with the simpler approach that I’m going to present as first. But if you have multiple kv files, which will be the case in our program as we proceed, you often have to take the slightly more complicated approach that I’m going to discuss as second.

Naming Convention

Anyway, first the simpler approach. In this approach we use a naming convention according to which we name the file the same as the app class (the class that inherits from App), but without the ‘App’ part and all lowercase. So, in our example the app class is HelloWorldApp, so the kv file should be named helloworld.kv.

Now, in Visual Studio Code (which I’m going to refer to as VSC from now on, also for brevity’s sake), create a new file, just as you did before and name it helloworld.kv:

As soon as you hit Enter, the file will open in a new tab. Type the following Kivy language code:

<Label>:
    text: 'Hello World!'

We’re going to talk about the Kivy language in more detail later on, for now it’s enough to say that this is all you need to take care of the label. The <Label>: part means we’re working on the Label class, and below we set the text property to a string of our choice.

Now save the kv file and go back to the main.py. Run the program. This is what you should see:

The Builder Class

And now let’s have a look at the second approach. This is the one without a naming convention. First of all let’s get rid of the kv file we just created by right-clicking it and selecting Delete:

You will be asked to confirm that you want to delete the file. Just confirm and the file will be deleted. Now create a new file and name it example.kv or any other arbitrary name except helloworld.kv. Then type the same code as before:

<Label>:
    text: 'Hello World!'

Save the file, go back to the main.py file and run the program. This time you will get a blank window, without the label:

Linking with a kv file

This is because the main.py file doesn’t know that it should be linked with the example.kv file. It can’t figure it out on its own because we can have multiple kv files, so how should it know which one to choose. That’s why we have to tell it explicitly that we want it to use the example.kv file.

To do that, we’ll need the Builder class from the kivy.lang module. It contains the load_file function that we can use to load the file we need.

Now modify your main.py file so that it imports the class and loads the file. Here’s the full code with comments:

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

# We must import the Builder class from kivy.lang.
from kivy.lang import Builder

# We must also load the kv file that we need.
Builder.load_file('example.kv')

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

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

If you now run the program, it will work again. But, as mentioned before, there’s no need for importing the Builder class and using the load_file function in such a basic program like ours. The first approach with the naming convention is the way to go. Now, you can delete the example.kv file because we’re not going to need it anymore. Create the helloworld.kv file again and type in the same code as before. Make all the necessary changes in the main.py file again. At this moment the two files should look like this:

The Python file :

# File name: main.py

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

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

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

and the kv file:

# File name: helloworld.kv

<Label>:
    text: 'Hello World!'

We’ve been using just the text property of the Label class so far, but this class has a lot of other interesting properties. In the next part we’ll have a look at some of them.