Properties

The properties classes are used for creating Widget. Theses classes are supporting:

Value checker
When you assign a new value to a property, the value is checked to pass some contraints implemented in class. For example, an OptionProperty will check that your value is inside a list of possibilities, NumericProperty will check that your value is an int or double, etc.
Observer pattern
You can bind your own function to the change of a Property. If you want to be called when the pos property change, you can bind a function to it.
Better memory management
The same instance of a property is shared across multiple widget instance. The value storage is independant of the Widget.
class kivy.properties.NumericProperty

Bases: kivy.properties.Property

Property that represent a numeric value

The NumericProperty accept only int or float.

>>> Widget.x = 42
>>> print Widget.x
42
>>> Widget.x = "plop"
class kivy.properties.StringProperty

Bases: kivy.properties.Property

Property that represent a string value.

Only string or unicode are accepted.

class kivy.properties.ListProperty

Bases: kivy.properties.Property

Property that represent a list.

Only list are allowed, tuple or any other classes are forbidden.

Warning

To mark the property as changed, you must reassign a new list each time you want to add or remove an object. Don’t rely on append(), remove() and pop() functions.

class kivy.properties.ObjectProperty

Bases: kivy.properties.Property

Property that represent an Python object.

Warning

To mark the property as changed, you must reassign a new python object.

class kivy.properties.BooleanProperty

Bases: kivy.properties.Property

Property that represent only boolean

class kivy.properties.BoundedNumericProperty

Bases: kivy.properties.Property

Property that represent a numeric value, with the possibility of assign minimum bound and/or maximum bound.

Parameters :
min: numeric

If set, minimum bound will be used, with the value of min

max: numeric

If set, maximum bound will be used, with the value of max

class kivy.properties.OptionProperty

Bases: kivy.properties.Property

Property that represent a string from a specific list.

If the string set in the property are not from the list passed at the creation, you will have an exception.

Parameters :
options: list (not tuple.)

List of available options

class kivy.properties.ReferenceListProperty

Bases: kivy.properties.Property

Property that allow to create tuple of other properties.

For example, if x and y are NumericProperty, we can create a ReferenceListProperty for the pos. If you change the value of pos, it will automaticly change the values of x and y. If you read the value of pos, it will return a tuple with the value of x and y.

class kivy.properties.AliasProperty

Bases: kivy.properties.Property

Create a property with a custom getter and setter.

If you don’t found a Property class that fit to your needs, you can still create Python getter and setter, and create a property with both of them.

Exemple from the kivy/uix/widget.py

def get_right(self):
    return self.x + self.width
def set_right(self, value):
    self.x = value - self.width
right = AliasProperty(get_right, set_right, bind=(x, width))
Parameters :
getter: function

Function to use as a property getter

setter: function

Function to use as a property setter

bind: list/tuple

List of properties to observe for changes

class kivy.properties.NumericProperty

Bases: kivy.properties.Property

Property that represent a numeric value

The NumericProperty accept only int or float.

>>> Widget.x = 42
>>> print Widget.x
42
>>> Widget.x = "plop"
class kivy.properties.Property

Bases: object

Base class for build more complex property.

This class handle all the basics setter and getter, None handling, observers list, and storage initialisation. This class should not be directly instanciated.

bind

Add a new observer to be called only when the value is changed

get

Return the value of the property

Link the instance with his real name.

Warning

Internal usage only.

When a widget definition use a Property class, the creation of the property happen, but the instance don’t know anything about his name in the widget class

class MyWidget(Widget):
    uid = NumericProperty(0)

On this example, the uid will be a NumericProperty() instance, but the property instance don’t know his name. That’s why link() is used in Widget.__new__. The link function is also used to create the storage of the property for this specific widget instance.

set

Set a new value for the property

unbind

Remove the observer from our widget observer list

Destroy the storage of a widget