Kivy Part 9 – Kivy Layout Basics

Before we jump into the Kivy layout basics, let’s recap on what we know.

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…

In the previous part we left off with a custom widget consisting of a text input and two buttons. Here’s the code again:

First the Python file:

# File name: main.py

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

class MyCustomButton(Button):
    pass

class MyCustomWidget(Widget):
    pass

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

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

And now the kv file:

# File name: helloworld.kv

<MyCustomButton>:
    size: 120, 40
    color: .7, .6, .4, 1

<MyCustomWidget>: 
    TextInput:
        hint_text: 'Type Something'
        pos: root.x + 20, root.top - self.height - 20
        size: 300, 40
    MyCustomButton:
        text: 'Press Me'
        pos: root.x + 20, root.y + 20
    MyCustomButton:
        text: 'Press Me Too'
        pos: root.right - self.width - 20, root.y + 20

If you run this code, here’s the app window:

As mentioned before, this is still just one widget. But you are not limited to just one widget. If you need more, you can put them in a special container called layout.

A Kivy layout inherits from the Widget class and takes care of organizing the widgets embedded in it. There are a couple of different layouts available and they all organize the widgets in different ways. We’re going to discuss all the particular layouts in the following parts. For now let’s just list them all and characterize them briefly so that you know what there is at your disposal. I’m also going to talk about the basics of positioning and scaling widgets inside layouts in this part. Actually, let’s start with the latter.

Introduction to Positioning and Scaling Widgets in Layouts

Up to now we’ve been using the pos and size properties to position and scale widgets respectively. You can also use them in layouts, but there are more options available. Usually instead of the two aforementioned properties, we use two other properties, pos_hint and size_hint. These are proportional coordinates, so they are expressed as percentages of the total size of the window. It’s going to become clearer when we see some examples in the following  parts. Actually, there are even more options than just pos, size, pos_hint and pos_size. The one thing to remember here is that properties like pos, size, width or height are used with fixed numbers of pixels, whereas properties like pos_hint and size_hint, as well as some others, are used with proportional coordinates.

Kivy Layout Types

So, what layouts do we have? Quite a few.

FloatLayout

The first one to mention is FloatLayout. This layout works pretty much the same as we saw when we were creating custom widgets. It organizes the widgets inside the app window using the proportional coordinates, pos_hint and size_hint, so the values are percentages of the window’s dimensions.

RelativeLayout

This layout differs from the previous one in that positions are relative to the layout and not the window.

BoxLayout

This is a layout we’re going to use a lot throughout the whole project. It organizes the widgets in a single row or column.

StackLayout

This layout is similar to BoxLayout in that it also organizes the widgets in a row or column. The difference is that if it runs out of space, the next widgets are placed in the next row or column depending on its orientation.

GridLayout

This layout organizes the widgets in a grid, with a given number of rows and column.

AnchorLayout

If you want your widgets to stick to the top, bottom or one of the sides, this is the layout to choose. It just anchors the widgets at specific positions.

ScatterLayout

This layout is the way to go if your application uses multitouch gestures for translating, scaling and rotating. Apart from that it’s very much like RelativeLayout.

PageLayout

This layout is slightly different. You can use it to create a multipage effect where the particular pages may be flipped. You will usually put another layout in each page and put the widgets only inside of it.

If you read the last sentence about PageLayout carefully, you noticed that you can nest layouts, so put one layout inside of another. It’s a very flexible feature, which we’ll be using a lot.

These are the Kivy layout basics, more or less. And remember, the descriptions of the layouts above are not exhaustive, to say the least. This just for you so that you know what layouts there are. But we’re only going to discuss most of the layouts in more detail in the following parts, so don’t worry if you don’t understand layouts now. Actually we haven’t even used any of them, which we are going to fix in the next part. So, let’s head to the first layout, FloatLayout, which we will be using in the next part. In the next part we’ll be also talking about scaling and positioning widgets in layouts.