Widget class¶
The Widget class is the base class required to create a Widget. Our widget class is designed with a couple of principles in mind:
- Event Driven
- The widget interaction is build on top of events that occur. If a property changes, the widget can do something. If nothing changes in the widget, nothing will be done. That’s the main goal of the Property class.
- Separate the widget and its graphical representation
- Widgets don’t have a draw() method. This is done on purpose: The idea is to allow you to create your own graphical representation outside the widget class. Obviously you can still use all the available properties to do that, so that your representation properly reflects the widget’s current state. Every widget has its own Canvas that you can use to draw. This separation allows Kivy to run your application in a very efficient manner.
- Bounding Box / Collision
- Often you want to know if a certain point is within the bounds of your widget. An example would be a button widget where you want to only trigger an action when the button itself is actually touched. For this, you can use the Widget.collide_point() method, which will return True if the point you pass it is inside the axis-aligned bounding box defined by the widgets position and size. If a simple AABB is not sufficient, you can override the method to perform the collision checks with more complex shapes (e.g. a polygon). You can also check if a widget collides with another widget with Widget.collide_widget().
Using Properties¶
When you read the documentation, all properties are described in the format:
<name> is a <property class>, defaults 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 be notified when the pos attribute changes (i.e. when the widget moves), you can bind your own function (callback) like this:
def callback_pos(instance, value):
print 'The widget', instance, 'moved to', value
wid = Widget()
wid.bind(pos=callback_pos)
- class kivy.uix.widget.Widget(**kwargs)¶
Bases: kivy.event.EventDispatcher
Widget class. See module documentation for more information.
Events : - on_touch_down:
Fired when a new touch appear
- on_touch_move:
Fired when an existing touch is moved
- on_touch_up:
Fired when an existing touch disappears
Changed in version 1.0.9.
- add_widget(widget, index=0)¶
Add a new widget as a child of this widget.
Parameters : - widget: Widget
Widget to add to our list of children.
- index: int, default to 0
(this attribute have been added in 1.0.5) Index to insert the widget in the list
>>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- canvas = None¶
Canvas of the widget.
The canvas is a graphics object that contains all the drawing instructions for the graphical representation of the widget. Check Canvas for more information about the usage.
- center¶
Center position of the widget
center is a ReferenceListProperty of (center_x, center_y)
- center_x¶
X center position of the widget
center_x is a AliasProperty of (x + width / 2.)
- center_y¶
Y center position of the widget
center_y is a AliasProperty of (y + height / 2.)
- children¶
List of children of this widget
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.
- clear_widgets()¶
Remove all widgets added to this widget.
- cls¶
Class of the widget, used for styling.
- collide_point(x, y)¶
Check if a point (x, y) is inside the widget’s axis aligned bounding box.
Parameters : - x: numeric
X position of the point (in window coordinates)
- y: numeric
Y position of the point (in window coordinates)
Returns : bool, True if the point is inside the bounding box.
>>> Widget(pos=(10, 10), size=(50, 50)).collide_point(40, 40) True
- collide_widget(wid)¶
Check if the other widget collides with this widget. Performs an axis-aligned bounding box intersection test by default.
Parameters : - wid: Widget class
Widget to collide with.
Returns : bool, True if the other widget collides with this widget.
>>> 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
- get_parent_window()¶
Return the parent window.
Returns : Instance of the parent window. Can be WindowBase or Widget
- get_root_window()¶
Return the root window.
Returns : Instance of the root window. Can be WindowBase or Widget
- height¶
Height of the widget.
height is a NumericProperty, default to 100.
- id¶
Unique 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 be raised.
- on_touch_down(touch)¶
Receive a touch down event.
Parameters : - touch: MotionEvent class
Touch received
Returns : bool. If True, the dispatching of the touch will stop.
- on_touch_move(touch)¶
Receive a touch move event.
See on_touch_down() for more information
- on_touch_up(touch)¶
Receive a touch up event.
See on_touch_down() for more information
- parent¶
Parent of this 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.
- pos¶
Position of the widget.
pos is a ReferenceListProperty of (x, y) properties.
- pos_hint¶
Position hint. This property allows you to set the position of the widget inside its parent layout, in percent (similar to size_hint).
For example, if you want to set the top of the widget to be at 90% height of its parent layout, you can write:
widget = Widget(pos_hint={‘top’: 0.9})The keys ‘x’, ‘right’, ‘center_x’, will use the parent width. The keys ‘y’, ‘top’, ‘center_y’, will use the parent height.
Check Float Layout for further reference.
Position hint is only used in FloatLayout and Window.
pos_hint is a ObjectProperty containing a dict.
- remove_widget(widget)¶
Remove a widget from the children of this widget.
Parameters : - widget: Widget
Widget to remove from our children list.
>>> root = Widget() >>> button = Button() >>> root.add_widget(button) >>> root.remove_widget(button)
- right¶
Right position of the widget
right is a AliasProperty of (x + width)
- size¶
Size of the widget.
size is a ReferenceListProperty of (width, height) properties.
- size_hint¶
Size hint.
size_hint is a ReferenceListProperty of (size_hint_x, size_hint_y)
See size_hint_x for more information
- size_hint_x¶
X size hint. It represents how much space the widget should use in the direction of the X axis, relative to its parent’s width. Only Layout and Window make use of the hint.
The value is in percent as a float from 0. to 1., where 1. means the full size of his parent, i.e. 100%. 0.5 represents 50%.
size_hint_x is a NumericProperty, default to 1.
- size_hint_y¶
Y size hint.
size_hint_y is a NumericProperty, default to 1.
See size_hint_x for more information
- to_local(x, y, relative=False)¶
Transform parent coordinates to local coordinates.
Parameters : - relative: bool, default to False
Change to True if you want to translate coordinates to relative widget coordinates.
- to_parent(x, y, relative=False)¶
Transform local coordinates to parent coordinates.
Parameters : - relative: bool, default to False
Change to True if you want to translate relative positions from widget to its parent.
- to_widget(x, y, relative=False)¶
Convert the given coordinate from window to local widget coordinates.
- to_window(x, y, initial=True, relative=False)¶
Transform local coordinates to window coordinates.
- top¶
Top position of the widget
top is a AliasProperty of (y + height)
- uid¶
Unique identifier of the widget in the whole Kivy instance.
New in version 1.0.7.
uid is a AliasProperty, read-only.
- width¶
Width of the widget.
width is a NumericProperty, default to 100.
- x¶
X position of the widget.
x is a NumericProperty, default to 0.
- y¶
Y position of the widget.
y is a NumericProperty, default to 0.
- class kivy.uix.widget.WidgetException¶
Bases: exceptions.Exception
Fired when the widget got an exception