Properties — Kivy v1.0.1-dev documentation

# 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`

    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

  `unlink`

    Destroy the storage of a widget