Widget class — Kivy v1.0.1-dev documentation

# 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