Widget class

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().

Usage of properties

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)
class kivy.uix.widget.Widget(**kwargs)

Bases: kivy.event.EventDispatcher

Widget class. See module documentation for more informations.

Events :
on_touch_down:

Fired when a new touch appear

on_touch_move:

Fired when an existing touch is moved

on_touch_down:

Fired when an existing touch disapear

add_widget(widget)

Add a new widget as a child of current widget

Parameters :
widget: Widget

Widget to add in our children list.

>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
bind(**kwargs)

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

Canvas of the widget.

The canvas is a graphics object that contain all the drawing instruction. Check Canvas for more information about 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

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.

clear_widgets()

Remove all widgets added to the widget.

cls

Class of the widget, used for styling.

collide_point(x, y)

Check if a point (x, y) is inside the widget bounding box.

Parameters :
x: numeric

X position of the point

y: numeric

Y position of the point

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 widget (bounding box) is colliding with our widget bounding box.

Parameters :
wid: Widget class

Widget to collide to.

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_property(name)

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 :
name: string

Name of the property

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
get_parent_window()

Return the parent window

Returns :Instance of the root window. Can be WindowBase or Widget
get_root_window()

Return the root window

Returns :Instance of the root window. Can be WindowBase or Widget
getter(name)

Return the getter of a property.

height

Height of the widget.

height is a NumericProperty, default to 100.

id

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.

on_touch_down(touch)

Receive a touch down event

Parameters :
touch: MotionEvent class

Touch received

Returns :

bool. If True, the dispatching 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 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.

pos

Position of the widget.

pos is a ReferenceListProperty of (x, y) properties.

pos_hint

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_widget(widget)

Remove a widget from the children of current widget

Parameters :
widget: Widget

Widget to add in 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)

setter(name)

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

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 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.

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 coordinate to local coordinate

Parameters :
relative: bool, default to False

Change to True is you want to translate a coordinate to a relative coordinate from widget.

to_parent(x, y, relative=False)

Transform local coordinate to parent coordinate

Parameters :
relative: bool, default to False

Change to True is you want to translate relative position from widget to his parent.

to_widget(x, y, relative=False)

Return the coordinate from window to local widget

to_window(x, y, initial=True, relative=False)

Transform local coordinate to window coordinate

top

Top position of the widget

top is a AliasProperty of (y + height)

unbind(**kwargs)

Unbind properties or event from handler

See bind() for more information.

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