The Widget class is base class required to create a Widget. Our widget class is designed for:
- Event managed
- The widget interaction is build on top of event. If a property change, the widget will do something. If nothing change in the widget, nothing will be done. That’s the main goal of the Property class.
- Seperate widget and graphical representation
- We don’t have a draw() method. The idea is to let you the possibility to create your own graphical representation outside the widget class. And you’ll use all the available properties to do that. Every widget have his own Canvas.
- Bounding box / Collision
- Since the graphical representation is seperated, the position and size of the widget represent his bounding box. You can check if a point is inside the widget with Widget.collide_point(), or if a widget is colliding another widget with Widget.collide_widget().
When you read the documentation, every property are described in the format:
<name> is a <property class>, default to <default value>
For example:
:data:`Widget.pos` is a :class:`~kivy.properties.ReferenceListProperty` of
(:data:`Widget.x`, :data:`Widget.y`) properties.
If you want to know when a the pos attribute change (meaning when the widget move), you can bind your own function like this:
def callback_pos(instance, value):
print 'the widget', instance, 'have moved to', value
wid = Widget()
wid.bind(pos=callback_pos)
Bases: kivy.event.EventDispatcher
Widget class. See module documentation for more informations.
Events : |
|
---|
Add a new widget as a child of current widget
Parameters : |
|
---|
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
Bind properties or event to handler.
Example of usage:
def my_x_callback(obj, value):
print 'on object', obj', 'x changed to', value
def my_width_callback(obj, value):
print 'on object', obj, 'width changed to', value
self.bind(x=my_x_callback, width=my_width_callback)
Canvas of the widget.
The canvas is a graphics object that contain all the drawing instruction. Check Canvas for more information about usage.
Center position of the widget
center is a ReferenceListProperty of (center_x, center_y)
X center position of the widget
center_x is a AliasProperty of (x + width / 2.)
Y center position of the widget
center_y is a AliasProperty of (y + height / 2.)
Children list
children is a ListProperty instance, default to an empty list.
Use add_widget() and remove_widget() for manipulate children list. Don’t manipulate children list directly until you know what you are doing.
Remove all widgets added to the widget.
Class of the widget, used for styling.
Check if a point (x, y) is inside the widget bounding box.
Parameters : |
|
---|---|
Returns : | bool, True if the point is inside the bounding box |
>>> Widget(pos=(10, 10), size=(50, 50)).collide_point(40, 40)
True
Check if widget (bounding box) is colliding with our widget bounding box.
Parameters : |
|
---|---|
Returns : | bool, True if the widget is colliding us. |
>>> wid = Widget(size=(50, 50))
>>> wid2 = Widget(size=(50, 50), pos=(25, 25))
>>> wid.collide_widget(wid2)
True
>>> wid2.pos = (55, 55)
>>> wid.collide_widget(wid2)
False
Create a new property at runtime.
Warning
This function is designed for the Kivy language, don’t use it in your code. You should declare the property in your class instead of using this method.
Parameters : |
|
---|
The class of the property cannot be specified, it will be always an ObjectProperty class. The default value of the property will be None, until you set a new value.
>>> mywidget = Widget()
>>> mywidget.create_property('custom')
>>> mywidget.custom = True
>>> print mywidget.custom
True
Return the parent window
Returns : | Instance of the root window. Can be WindowBase or Widget |
---|
Return the root window
Returns : | Instance of the root window. Can be WindowBase or Widget |
---|
Return the getter of a property.
Height of the widget.
height is a NumericProperty, default to 100.
Uniq identifier of the widget in the tree.
id is a StringProperty, default to None.
Warning
If the id is already used in the tree, an exception will occur.
Receive a touch down event
Parameters : |
|
---|---|
Returns : | bool. If True, the dispatching will stop. |
Receive a touch move event.
See on_touch_down() for more information
Receive a touch up event.
See on_touch_down() for more information
Parent of the widget
parent is a ObjectProperty instance, default to None.
The parent of a widget is set when the widget is added to another one, and unset when the widget is removed from his parent.
Position of the widget.
pos is a ReferenceListProperty of (x, y) properties.
Position hint. This property permit you to set the position of the widget inside his parent layout, in percent.
For example, if you want to set the top of the widget to be at 90% height of his parent layout, you can write:
widget = Widget(pos_hint={‘top’: 0.9})
The keys ‘x’, ‘right’ will use the parent width. The keys ‘y’, ‘top’ will use the parent height.
Check Float Layout for more informations.
Position hint is only used in FloatLayout and Window.
pos_hint is a ObjectProperty containing a dict.
Remove a widget from the children of current widget
Parameters : |
|
---|
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)
Right position of the widget
right is a AliasProperty of (x + width)
Return the setter of a property. Useful if you want to directly bind a property to another.
For example, if you want to position one widget next to you
self.bind(right=nextchild.setter('x'))
Size of the widget.
size is a ReferenceListProperty of (width, height) properties.
Size hint.
size_hint is a ReferenceListProperty of (size_hint_x, size_hint_y)
See size_hint_x for more information
X size hint. It represent how much space the widget should use in the X axis from his parent. Only Layout and Window are using the hint.
Value is in percent, 1. will mean the full size of his parent, aka 100%. 0.5 will represent 50%.
size_hint_x is a NumericProperty, default to 1.
Y size hint.
size_hint_y is a NumericProperty, default to 1.
See size_hint_x for more information
Transform parent coordinate to local coordinate
Parameters : |
|
---|
Transform local coordinate to parent coordinate
Parameters : |
|
---|
Return the coordinate from window to local widget
Transform local coordinate to window coordinate
Top position of the widget
top is a AliasProperty of (y + height)
Width of the widget.
width is a NumericProperty, default to 100.
X position of the widget.
x is a NumericProperty, default to 0.
Y position of the widget.
y is a NumericProperty, default to 0.
Bases: exceptions.Exception
Fired when the widget got an exception