Properties¶
The Properties classes are used when you create a Widget.
Warning
Kivy’s Properties are not to be confused with Python’s properties (i.e. the @property decorator and the <property> type).
Kivy’s property classes support:
- Value Checking / Validation
- When you assign a new value to a property, the value is checked to pass some constraints implemented in the class. I.e., validation is performed. For example, an OptionProperty will make sure that the value is in a predefined list of possibilities. A NumericProperty will check that your value is a numeric type, i.e. int, float, etc. This prevents many errors early on.
- Observer 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. If, for example, you want a piece of code to be called when a widget’s pos property changes, you can bind a function to it.
- Better Memory Management
- The same instance of a property is shared across multiple widget instances.
- class kivy.properties.Property¶
Bases: object
Base class for building more complex properties.
This class handles all the basic setters and getters, None type handling, the observer list and storage initialisation. This class should not be directly instantiated.
By default, a Property always take a default value:
class MyObject(Widget): hello = Property('Hello world')
The default value must be a value that agreed about the Property type. For example, you can’t set a list to a StringProperty, because the StringProperty will check the default value.
None is a special case: you can set the default value of a Property to None, but you can’t set None to a property afterwise. If you really want to do that, you must declare the Property with allownone=True:
class MyObject(Widget): hello = ObjectProperty(None, allownone=True) # then later a = MyObject() a.hello = 'bleh' # working a.hello = None # working too, because allownone is True.
- bind()¶
Add a new observer to be called only when the value is changed
- dispatch()¶
Dispatch the value change to all observers
Changed in version 1.1.0.
This can be used to force the dispatch of the property, even if the value didn’t changed:
button = Button() # get the Property class instance prop = button.property('text') # dispatch this property on the button instance prop.dispatch(button)
- get()¶
Return the value of the property
- link()¶
Link the instance with its real name.
Warning
Internal usage only.
When a widget is defined and uses a Property class, the creation of the property object happens, but the instance doesn’t know anything about its name in the widget class:
class MyWidget(Widget): uid = NumericProperty(0)
In this example, the uid will be a NumericProperty() instance, but the property instance doesn’t know its name. That’s why link() is used in Widget.__new__. The link function is also used to create the storage space 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
- class kivy.properties.NumericProperty¶
Bases: kivy.properties.Property
Property that represents 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 represents a string value.
Only string or unicode are accepted.
- class kivy.properties.ListProperty¶
Bases: kivy.properties.Property
Property that represents a list.
Only lists are allowed, tuple or any other classes are forbidden.
- class kivy.properties.ObjectProperty¶
Bases: kivy.properties.Property
Property that represents a 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 represents only boolean
- class kivy.properties.BoundedNumericProperty¶
Bases: kivy.properties.Property
Property that represents a numeric value within a minimum bound and/or maximum bound (i.e. a numeric range).
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
- bounds¶
Return min/max of the value
New in version 1.0.9.
- get_max()¶
Return the maximum value acceptable for the BoundedNumericProperty in obj, None if no maximum value are set. Check get_min for an usage example.
New in version 1.1.0.
- get_min()¶
Return the minimum value acceptable for the BoundedNumericProperty in obj, None if no minimum value are set:
class MyWidget(Widget): number = BoundedNumericProperty(0, min=-5, max=5) widget = MyWidget() print widget.property('number').get_min(widget) # will output -5
New in version 1.1.0.
- set_max()¶
Change the maximum value acceptable for the BoundedNumericProperty, only for the obj instance, None if you want to disable it. Check set_min for an usage example.
Warning
Changing the bounds doesn’t revalidate the current value.
New in version 1.1.0.
- set_min()¶
Change the minimum value acceptable for the BoundedNumericProperty, only for the obj instance, None if you want to disable it:
class MyWidget(Widget): number = BoundedNumericProperty(0, min=-5, max=5) widget = MyWidget() # change the minmium to -10 widget.property('number').set_min(widget, -10) # or disable the minimum check widget.property('number').set_min(widget, None)
Warning
Changing the bounds doesn’t revalidate the current value.
New in version 1.1.0.
- class kivy.properties.OptionProperty¶
Bases: kivy.properties.Property
Property that represents a string from a predefined list of valid options.
If the string set in the property is not in the list of valid options (passed at property creation time), a ValueError exception will be raised.
Parameters : - options: list (not tuple.)
List of valid options
- options¶
Return the options available.
New in version 1.0.9.
- class kivy.properties.ReferenceListProperty¶
Bases: kivy.properties.Property
Property that allows to create a tuple of other properties.
For example, if x and y are NumericProperty`s, we can create a :class:`ReferenceListProperty for the pos. If you change the value of pos, it will automatically change the values of x and y accordingly. If you read the value of pos, it will return a tuple with the values of x and y.
- class kivy.properties.AliasProperty¶
Bases: kivy.properties.Property
Create a property with a custom getter and setter.
If you didn’t find a Property class that fits to your needs, you can still create Python getters and setters and create a property with both of them.
Example from 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.DictProperty¶
Bases: kivy.properties.Property
Property that represents a dict.
Only dict are allowed, any other classes are forbidden.