Kivy Part 33 – Introduction to Kivy Properties

In the previous part we were referencing widgets by ids. You can also reference widgets using Kivy properties, but before we learn how to do it, let’s talk about Kivy properties in general.

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…

What Are Kivy Properties?

To start with, what are Kivy properties? Don’t be mislead by the name, they are not to be confused with the regular Python properties that you know. We’ve been using the word PROPERTY a lot since the first parts of this series. You know that there’s a text property in the Label class, there’s a size property in the Widget class, there are the min, max and value properties in the Slider class and many, many more. These are all examples of inherited properties – you get them out of the box when you inherit from a class where they are defined.

Now, before we go any further, let’s have a look at our test files from the previous part. Here’s the Python code:

 # File name: test.py
  
 import kivy
 from kivy.app import App
 from kivy.uix.boxlayout import BoxLayout
  
 class TestLayout(BoxLayout):
     def set_text(self):
         self.ids._label.text = 'CHANGED'
  
 class TestApp(App):
     def build(self):
         return TestLayout()
  
 if __name__ == '__main__':
     TestApp().run() 

And here’s the kv code:

 # File name: test.kv
  
 <TestLayout>:     
     Button:
         id: _button1
         text: _label.text
         on_press: root.set_text()
  
     Label:
         id: _label
         text: 'hey'
  
     Button:
         text: str(_button1.size) 

If you run this program, you will see the following window:

As you remember, when you press the first button, the value of the text property on the label will change to ‘CHANGED’.

So, when the first button is pressed, the set_text method defined in the TestLayout class is called. This method changes the text property on the label. But the text on the first button changes too, although we didn’t write any code telling it to do so. This is how properties work, they react to changes. Even if you had tens of other widgets with their text properties set to the label’s text, they would all react to any change of the text property.

Now, before we really dive into the realm of properties, let’s just briefly discuss their main features.

Features of Kivy Properties

The one feature that you already know is that Kivy properties automatically observe any changes and react accordingly. Kivy properties implement the Observer Design Pattern. You can specify what should happen when a property’s value changes. You can bind your own function as a callback to changes of a property’s value.

Besides, Kivy properties can be used with validation constraints. We use this to validate the values that we try to set our property to.

Finally, Kivy properties optimize memory management, because a single instance of a property is shared across all the instances of the class where they were defined.

Types of Kivy Properties

There are actually a couple types of Kivy properties. If you look at the documentation of the Label class, for example, you will find the following description of the text property:

text

Text of the label.

Creation of a simple hello world:

widget = Label(text=’Hello world’)

If you want to create the widget with an unicode string, use:

widget = Label(text=u’My unicode string’)

text is a StringProperty and defaults to ‘’.

The last sentence, the one in bold type, is what interests us most at this moment. It says that the text property is a StringProperty.

Now, let’s have a look at some more properties in the documentation. For example, there’s the size property in the Widget class:

size

Size of the widget.

size is a ReferenceListProperty of (width, height) properties.

This is a ReferenceListProperty. What about the max property in the Slider class? Here’s what we can see in the documentation:

max

Maximum value allowed for value.

max is a NumericProperty and defaults to 100.

So, this time it’s a NumericProperty. These are just a couple examples, but there are more property types. In particular, there are:

– NumericProperty

– StringProperty

– ListProperty

– ObjectProperty

– BooleanProperty

– BoundedNumericProperty

– OptionProperty

– ReferenceListProperty

– AliasProperty

– DictProperty

We’re going to use many of them in our project. Some of them have pretty self-explanatory names, like the NumericProperty or BooleanProperty. But there are also some that we can use in more advanced scenarios like the OptionProperty or AliasProperty, for example. First, though, we’ll see how to use Kivy properties to reference widgets.