.. _widgets:

Widgets
=======

Introduction to Widget
----------------------

A :class:`kivy.uix.widget.Widget` is the basic component of the interface, it
can display things at places, and recieve touch (and other) events, and react to
them. It's representation and behaviour.

Manipulating the Widget tree
----------------------------

Widgets are organized in Trees, your application have a root widget, which
usually have children, which can have children on their own. Children of a
widget are represented as the :attr:`kivy.uix.widget.Widget.children`
:class:`kivy.properties.ListProperty`. The way to add a children to a widget is
to call :meth:`kivy.uix.widget.Widget.add_widget`, likely, to remove a widget,
you use :meth:`kivy.uix.widget.Widget.remove_widget`.

Organize with Layouts
---------------------

Layouts are a special kind of widget that allows automatic control of the size
and position of their children. There are different kind of layouts, allowing
for different automatic organisation. A common caracteristic of layouts is that
they use (even if differently) of the :attr:`kivy.uix.widget.Widget.size_hint`
and :attr:`kivy.uix.widget.Widget.pos_hint` properties. Those properties allow
to define size and pos of the widget relatively to the parent layout.

Look at the documentation of the various Layouts to see to which situation each
one applies:

- :mod:`kivy.uix.floatlayout`
- :mod:`kivy.uix.boxlayout`
- :mod:`kivy.uix.gridlayout`
- :mod:`kivy.uix.stacklayout`
- :mod:`kivy.uix.relativelayout`
- :mod:`kivy.uix.anchorlayout`

Seperate with Screen Manager
----------------------------

If your application is composed of various screens, you likely want an easy way
to navigate from one to another, fortunately, there is the
:class:`kivy.uix.screenmanager.ScreenManager` class, that allows you to define
screens separatly, and to set the transitions from one to another.