Kivy Part 25 – Canvas Vertex Instructions

In the previous part we were talking in general about Canvas, coordinate space and Canvas drawing instructions, so vertex instructions and context instructions. In this part we’ll concentrate on the vertex instructions that we use to draw basic shapes on a widget.

Here’s the video version of this article:

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…

Test Files

In order to draw a shape, we have to choose a widget we want to draw it on. Let’s create a simple file, which will not be included in our project, that we can use to practice. Let’s name it test.py and let’s also create the corresponding test.kv file, where the actual drawing will be done.

The root widget is going to be a 2 by 2 GridLayout in which we’ll draw 4 shapes. They are going to be all white for now, which we will be able to change after we discuss colors.

I’m not going to type the whole kv code in one go, but rather piece by piece so that you can see exactly what’s going on. Let’s start with the Python code, which is pretty simple and straightforward:

# File name: test.py

import kivy
from kivy.app import App
from kivy.uix.boxlayout import BoxLayout

class TestScreen(BoxLayout):
    pass

class TestApp(App):
    def build(self):
        return TestScreen()

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

Drawing a Rectangle

And now we’ll start out kv file and draw the first shape, a rectangle. Here’s the initial code in test.kv :

# File name: test.kv

<TestScreen>:
    orientation: 'vertical'
    
    ### A 2x2 GRIDLAYOUT WHERE WE ARE GOING TO DRAW SHAPES ###
    GridLayout:
        cols: 2
        spacing: 4
        padding: 10

        # Shape 1 - A Rectangle on a BoxLayout
        BoxLayout:
            canvas:
                Rectangle:
                    pos: self.x, self.y
                    size: self.width, self.height

If you now run the app (from the test.py file), you will see a rectangle:

Now the BoxLayout is the only widget and it occupies the whole app window. If I hadn’t added some padding and sizing, the rectangle would occupy the whole RelativeLayout, so also the whole app window.

Drawing an Ellipse

And now let’s draw an ellipse. Here’s the code:

# File name: test.kv

<TestScreen>:
    …
    
    ### A 2x2 GRIDLAYOUT WHERE WE ARE GOING TO DRAW SHAPES ###
    GridLayout:
        …

        # Shape 1 - A Rectangle on a BoxLayout
        …

        # Shape 2 - An Ellipse on a Button
        Button:
            canvas:
                Ellipse:
                    pos: self.center_x - 50, self.center_y - 25
                    size: 100, 60

From now on I’m only going to add small snippets with code for each particular shape. Just add them below the code that you added before, watching the indentation. If you run this code now, you will see two widgets: the BoxLayout you added before and the button you just added now. Each occupies half the available space:

Drawing Lines

And now let’s draw a line, or better two lines. A line is basically a sequence of points. Each point is a pair of X and Y coordinates. We can also specify the width of the line:

        # Shape 3 - Lines on a Button
        Button:
            canvas:
                Line:                    
                    points: self.x + 20, self.y + 20, self.x + 120, self.y + 100
                    width: 4
                Line:                    
                    points: 200, 200, 200, 260, 260, 260, 320, 320

And here’s what we get:

As you can see, the first line is straight and thicker. It consists of just two points, the coordinates of which are relative to the coordinates of the button they’re drawn on. The second line consists of more points, which are connected to form segments. Here the coordinates are absolute, so the line is always drawn at the same coordinates, which may be outside the button. The difference between relative and absolute coordinates is even more visible if you maximize or resize in any other way the window:

Drawing the Border of a Rounded Rectangle

The next shape we’re going to draw is the border of a rounded rectangle. We’ll be using this shape in our application to draw the rounded borders of the particular parts of our GUI, lik the Game Info panel or Bets Screen, to mention just a few. Again, as this is going to be just the border, we have to use Line instructions. The rounded_rectangle property specifies the X and Y coordinates, the width and height of the rounded rectangle and the radius.

        # Shape 4 - The Border of a Rounded Rectangle on a Button
        Button:
            canvas:
                Line:
                    rounded_rectangle: self.x + 100, self.y + 10, 30, 90, 10
                    width: 3

Here’s what we get:

These are just a couple examples, there are lots of other vertex instructions that let you draw other shapes, but I think you have the general idea now how it works. In the next part we’ll add rounded rectangles, or rather just the borders, to our app.