Updating canvas instructions declared in Python

Continuing the theme of my last few posts, a common problem for new kivy users is creating canvas instructions that follow their parent widgets. For instance, here’s some code for a custom widget that tries to draw a red rectangle in its upper-right corner - this is fairly standard kivy code to draw directly on the widget canvas, and is documented here.

from kivy.uix.widget import Widget
from kivy.graphics import Rectangle, Color

class CornerRectangleWidget(Widget)
    def __init__(self, **kwargs):
        super(CornerRectangleWidget, self).__init__(**kwargs)

        with self.canvas:
            Color(1, 0, 0, 1)  # set the colour to red
            self.rect = Rectangle(pos=self.center,
                                  size=(self.width/2.,
                                        self.height/2.))

This looks like it will create a red rectangle, whose length is half the parent size in both directions, and whose position is the parent centre.

The surprise is that this is actually not what happens. Instead, the rectangle is always positioned at (50, 50) with size (50, 50), regardless of where the widget appears.

The reason for this is that these values really are based on the pos and size of the widget at the point where the canvas code was run; all widgets have a default position of (0, 0) and size of (100, 100), and this will not necessarily be updated (for instance by a parent layout class) until after their __init__ is run. However, the Rectangle properties receive only these initial values, and don’t know about the new position of the widget.

The solution is to simply hook into kivy’s event system to update the rectangle pos and size ourselves whenever the widget changes:

from kivy.uix.widget import Widget
from kivy.graphics import Rectangle, Color

class CornerRectangleWidget(Widget)
    def __init__(self, **kwargs):
        super(CornerRectangleWidget, self).__init__(**kwargs)

        with self.canvas:
            Color(1, 0, 0, 1)  # set the colour to red
            self.rect = Rectangle(pos=self.center,
                                  size=(self.width/2.,
                                        self.height/2.))

        self.bind(pos=self.update_rect,
                  size=self.update_rect)

    def update_rect(self, *args):
        self.rect.pos = self.pos
        self.rect.size = self.size

Now whenever the widget pos or size changes, our new method is called and the rectangle resized or repositioned as necessary. It will always track the widget’s upper right corner, so we get the visual effect we were originally looking for.

Of course, an even better solution (where possible) is to use kv language:

<CornerRectangleWidget@Widget>
    canvas:
        Color:
           rgba: 1, 0, 0, 1
        Rectangle:
           pos: self.center
           size: self.width / 2., self.height / 2.

This is shorter, simpler and clearer. We don’t need to manually set up the binding because kv automatically detects that we referred to properties of the parent widget and creates it automatically - something that isn’t really possible in python. This is one reason that we recommend using kv language wherever possible.

Updating canvas instructions declared in Python

Continuing the theme of my last few posts, a common problem for new kivy users is creating canvas instructions that follow their parent widgets. For instance, here’s some code for a custom widget that tries to draw a red rectangle in its upper-right corner - this is fairly standard kivy code to draw directly on the widget canvas, and is documented here.

from kivy.uix.widget import Widget
from kivy.graphics import Rectangle, Color

class CornerRectangleWidget(Widget)
    def __init__(self, **kwargs):
        super(CornerRectangleWidget, self).__init__(**kwargs)

        with self.canvas:
            Color(1, 0, 0, 1)  # set the colour to red
            self.rect = Rectangle(pos=self.center,
                                  size=(self.width/2.,
                                        self.height/2.))

This looks like it will create a red rectangle, whose length is half the parent size in both directions, and whose position is the parent centre.

The surprise is that this is actually not what happens. Instead, the rectangle is always positioned at (50, 50) with size (50, 50), regardless of where the widget appears.

The reason for this is that these values really are based on the pos and size of the widget at the point where the canvas code was run; all widgets have a default position of (0, 0) and size of (100, 100), and this will not necessarily be updated (for instance by a parent layout class) until after their __init__ is run. However, the Rectangle properties receive only these initial values, and don’t know about the new position of the widget.

The solution is to simply hook into kivy’s event system to update the rectangle pos and size ourselves whenever the widget changes:

from kivy.uix.widget import Widget
from kivy.graphics import Rectangle, Color

class CornerRectangleWidget(Widget)
    def __init__(self, **kwargs):
        super(CornerRectangleWidget, self).__init__(**kwargs)

        with self.canvas:
            Color(1, 0, 0, 1)  # set the colour to red
            self.rect = Rectangle(pos=self.center,
                                  size=(self.width/2.,
                                        self.height/2.))

        self.bind(pos=self.update_rect,
                  size=self.update_rect)

    def update_rect(self, *args):
        self.rect.pos = self.pos
        self.rect.size = self.size

Now whenever the widget pos or size changes, our new method is called and the rectangle resized or repositioned as necessary. It will always track the widget’s upper right corner, so we get the visual effect we were originally looking for.

Of course, an even better solution (where possible) is to use kv language:

<CornerRectangleWidget@Widget>
    canvas:
        Color:
           rgba: 1, 0, 0, 1
        Rectangle:
           pos: self.center
           size: self.width / 2., self.height / 2.

This is shorter, simpler and clearer. We don’t need to manually set up the binding because kv automatically detects that we referred to properties of the parent widget and creates it automatically - something that isn’t really possible in python. This is one reason that we recommend using kv language wherever possible.

Wrapping text in Kivy’s Label

Another Kivy question that I often see (particularly recently for some reason) is about using the Label widget - how to have text wrap automatically, or the opposite, how to have the label automatically grow to accommodate its text. I’ve covered this before in the 9th Kivy crash course video, but here’s a quick write up of the basics.

The first thing to realise is how the Label works by default, it takes the text and draws it to a texture - in practical terms that’s an image of the characters. Everything you might want to do with the Label revolves around what this texture is really doing. By default, it does not wrap the text (unless you put in linebreak characters manually), it just makes one long image on a single row. This image is is placed right in the middle of the label, centered in both directions, which is fine for short text snippets but will overhang the Label on both sides if the text is too long.

This also leads to some other annoying behaviour - as well as the text not wrapping, you might have observed that the halign and valign properties seem to do nothing by default. This is because they orient things not inside the widget, but inside the texture…which is the exact size it needs to contain the text so alignments change nothing.

To solve all these problems, you can manually set the size of the texture with text_size, a tuple of width and height, e.g.

Label:
    text_size: self.size

This reverses the default behaviour - instead of the texture growing to fit the text, the text will be wrapped to fit the texture! If there is space to spare, it is aligned within the texture according to the halign and valign properties.

The Label also has another useful property, the texture_size, which holds the actual size of the texture. You can use that do bind behaviour to the size of the text. For instance, a common requirement is to create a Label that grows as long as it needs to contain its text, but which wraps it to a certain width. We can combine both of the above ideas to accomplish this:

Label:
    size_hint_y: None
    text_size: self.width, None
    height: self.texture_size[1]

If you (for instance) place this label in a ScrollView, it will be Scrollable over exactly the right distance to fit in all the text.

Wrapping text in Kivy’s Label

Another Kivy question that I often see (particularly recently for some reason) is about using the Label widget - how to have text wrap automatically, or the opposite, how to have the label automatically grow to accommodate its text. I’ve covered this before in the 9th Kivy crash course video, but here’s a quick write up of the basics.

The first thing to realise is how the Label works by default, it takes the text and draws it to a texture - in practical terms that’s an image of the characters. Everything you might want to do with the Label revolves around what this texture is really doing. By default, it does not wrap the text (unless you put in linebreak characters manually), it just makes one long image on a single row. This image is is placed right in the middle of the label, centered in both directions, which is fine for short text snippets but will overhang the Label on both sides if the text is too long.

This also leads to some other annoying behaviour - as well as the text not wrapping, you might have observed that the halign and valign properties seem to do nothing by default. This is because they orient things not inside the widget, but inside the texture…which is the exact size it needs to contain the text so alignments change nothing.

To solve all these problems, you can manually set the size of the texture with text_size, a tuple of width and height, e.g.

Label:
    text_size: self.size

This reverses the default behaviour - instead of the texture growing to fit the text, the text will be wrapped to fit the texture! If there is space to spare, it is aligned within the texture according to the halign and valign properties.

The Label also has another useful property, the texture_size, which holds the actual size of the texture. You can use that do bind behaviour to the size of the text. For instance, a common requirement is to create a Label that grows as long as it needs to contain its text, but which wraps it to a certain width. We can combine both of the above ideas to accomplish this:

Label:
    size_hint_y: None
    text_size: self.width, None
    height: self.texture_size[1]

If you (for instance) place this label in a ScrollView, it will be Scrollable over exactly the right distance to fit in all the text.

Kivy Contest 2014

Just to announce here for anyone that hasn’t seen already…Kivy recently announced the Kivy org second programming contest! You can check out all the details at http://kivy.org/#contest!

To cover the key details here, entries are open now (you can sign up at the link above), and the contest starts in full on 15th April. There will be a broad theme, announced on that day, but many different kinds of app will be possible. You’ll have 4 weeks from the start date to complete your entry.

Entries will be judged on a range of criteria, so don’t be afraid to jump in!

Kivy Contest 2014

Just to announce here for anyone that hasn’t seen already…Kivy recently announced the Kivy org second programming contest! You can check out all the details at http://kivy.org/#contest!

To cover the key details here, entries are open now (you can sign up at the link above), and the contest starts in full on 15th April. There will be a broad theme, announced on that day, but many different kinds of app will be possible. You’ll have 4 weeks from the start date to complete your entry.

Entries will be judged on a range of criteria, so don’t be afraid to jump in!

Kivy’s bind method

One of the most common problems for new Kivy users is misunderstanding how the bind method works, especially amongst newer Python users who haven’t fully formed their intuition about function calls. For instance, a user will write code like:

some_screenmanager.bind(current=a_function(arg1, arg2))

Here, the idea is that when the current property changes, it will call a_function with the arguments arg1 and arg2.

The problem is that Python itself doesn’t work like this; the bind method doesn’t know about the existence of a_function or its arguments, it only receives the result of this function call. This often leads to confusion when a user doesn’t understand why the binding is only called once, during the declaration of the binding.

Stepping back, our real goal is to call a_function with the given arguments, but bind needs to be passed a function if it is to work correctly. That means we can solve our problem by creating a new function with these arguments already passed (and discarding the extra arguments automatically passed by bind).

It’s usually convenient to do this with the partial function from the functools module:

from functools import partial
some_screenmanager.bind(current=partial(a_function,arg1, arg2))

partial returns a new function that will automatically be passed arg1 and arg2, exactly as we want. You can also pass kwargs this way.

This isn’t the only way to solve the problem, we could have created a lambda function (though the syntax is longer and can have scope problems) or an entire new function with def syntax, but both of these are more complicated than the simple use of partial. So if you need to do a binding in Python, look at this way first!

Kivy’s bind method

One of the most common problems for new Kivy users is misunderstanding how the bind method works, especially amongst newer Python users who haven’t fully formed their intuition about function calls. For instance, a user will write code like:

some_screenmanager.bind(current=a_function(arg1, arg2))

Here, the idea is that when the current property changes, it will call a_function with the arguments arg1 and arg2.

The problem is that Python itself doesn’t work like this; the bind method doesn’t know about the existence of a_function or its arguments, it only receives the result of this function call. This often leads to confusion when a user doesn’t understand why the binding is only called once, during the declaration of the binding.

Stepping back, our real goal is to call a_function with the given arguments, but bind needs to be passed a function if it is to work correctly. That means we can solve our problem by creating a new function with these arguments already passed (and discarding the extra arguments automatically passed by bind).

It’s usually convenient to do this with the partial function from the functools module:

from functools import partial
some_screenmanager.bind(current=partial(a_function,arg1, arg2))

partial returns a new function that will automatically be passed arg1 and arg2, exactly as we want. You can also pass kwargs this way.

This isn’t the only way to solve the problem, we could have created a lambda function (though the syntax is longer and can have scope problems) or an entire new function with def syntax, but both of these are more complicated than the simple use of partial. So if you need to do a binding in Python, look at this way first!