Quick search

Scatter Layout

New in version 1.6.0.

This layout behaves just like a RelativeLayout. When a widget is added with position = (0,0) to a ScatterLayout, the child widget will also move when you change the position of the ScatterLayout. The child widget’s coordinates remain (0,0) as they are relative to the parent layout.

However, since ScatterLayout is implemented using a Scatter widget, you can also translate, rotate and scale the layout using touches or clicks, just like in the case of a normal Scatter widget, and the child widgets will behave as expected.

In contrast to a Scatter, the Layout favors ‘hint’ properties, such as size_hint, size_hint_x, size_hint_y and pos_hint.


The ScatterLayout is implemented as a FloatLayout inside a Scatter.


Since the actual ScatterLayout is a Scatter, its add_widget and remove_widget functions are overridden to add children to the embedded FloatLayout (accessible as the content property of Scatter) automatically. So if you want to access the added child elements, you need self.content.children instead of self.children.


The ScatterLayout was introduced in 1.7.0 and was called RelativeLayout in prior versions. The RelativeLayout is now an optimized implementation that uses only a positional transform to avoid some of the heavier calculation involved for Scatter.

class kivy.uix.scatterlayout.ScatterLayout(**kw)[source]

Bases: kivy.uix.scatter.Scatter

ScatterLayout class, see module documentation for more information.

add_widget(*args, **kwargs)[source]

Add a new widget as a child of this widget.

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
clear_widgets(*args, **kwargs)[source]

Remove all (or the specified) children of this widget. If the ‘children’ argument is specified, it should be a list (or filtered list) of children of the current widget.

Changed in version 1.8.0: The children argument can be used to specify the children you want to remove.

Changed in version 2.1.0: Specifying an empty children list leaves the widgets unchanged. Previously it was treated like None and all children were removed.

remove_widget(*args, **kwargs)[source]

Remove a widget from the children of this widget.

widget: Widget

Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)
class kivy.uix.scatterlayout.ScatterPlaneLayout(**kwargs)[source]

Bases: kivy.uix.scatter.ScatterPlane

ScatterPlaneLayout class, see module documentation for more information.

Similar to ScatterLayout, but based on ScatterPlane - so the input is not bounded.

New in version 1.9.0.

collide_point(x, y)[source]

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

x: numeric

x position of the point (in parent coordinates)

y: numeric

y position of the point (in parent coordinates)


A bool. True if the point is inside the bounding box, False otherwise.

>>> Widget(pos=(10, 10), size=(50, 50)).collide_point(40, 40)