Scatter — Kivy v1.0.1-dev documentation

# Scatter

Scatter is a widget that you can translate, rotate and scale, with two or more fingers. This is the famous widget as you can see on many multitouch demo.

## Usage

By default, the widget itself don’t have any graphical representation. The idea is to combine Scatter widget with other widget, like `Image` widget.

> scatter = Scatter() image = Image(source=’sun.jpg’) scatter.add_widget(image)

## Control interactions

You can also avoid some interaction, like rotation.

    scatter = Scatter(do_rotation=False)

Or allow only translation.

    scatter = Scatter(do_rotation=False, do_scale=False)

## Automatic bring to front

If you add and manipulate multiple scatter, you can have trouble if the scatter is behind another scatter. We have a property named `Scatter.auto_bring_to_front` that remove and re-add the scatter in his parent. The scatter will be on top as soon as you touch it.

## Scale limitation

We are using 32 bits matrix, in double representation. That’s mean, we have limitation for scaling. You cannot do infite scale down/up with our implementation. Generally, you don’t hit the minimum scale (because you don’t see it on the screen), but the maximum scale : 9.99506983235e+19 (2^66)

You can also limit the minimum and maximum zoom allowed.

    scatter = Scatter(scale_min=.5, scale_max=3.)

class `kivy.uix.scatter.` `Scatter`(**kwargs)

  Bases: `kivy.uix.widget.Widget`

  Scatter class. See module documentation for more information.

  `apply_angle_scale_trans`(angle, scale, trans, point=[, 0, 0])
    Update matrix transformation by adding new angle,
      scale and translate.

    Parameters : | angle : float Rotation angle to add scale : float Scaling value to add trans : Vector Vector translation to add point : Vector, default to (0, 0) Point to apply transformation

  `apply_transform`(trans, post_multiply=False, anchor=(0, 0))

    Transforms scatter by trans (on top of its current transformation state)

    Parameters : | trans: transformation matrix from transformation lib. Transformation to be applied to the scatter widget anchor: tuple, default to (0, 0) The point to use as the origin of the transformation (uses local widget space) post_multiply: bool, default to False If true the transform matrix is post multiplied (as if applied before the current transform)

  `auto_bring_to_front`

    If True, the widget will be automatically pushed on the top of parent widget list for drawing.

    `auto_bring_to_front` is a `BooleanProperty`, default to True.

  `bbox`

    Bounding box of the widget in parent space

        ((x, y), (w, h))
        # x, y = lower left corner

    `bbox` is a `AliasProperty`.

  `center`

    Create a property with a custom getter and setter.

    If you don’t found a Property class that fit to your needs, you can still create Python getter and setter, and create a property with both of them.

    Exemple from the kivy/uix/widget.py

        def get_right(self):
            return self.x + self.width
        def set_right(self, value):
            self.x = value - self.width
        right = AliasProperty(get_right, set_right, bind=(x, width))

    Parameters : | getter: function Function to use as a property getter setter: function Function to use as a property setter bind: list/tuple List of properties to observe for changes

  `do_rotation`

    Allow rotation

    `do_rotation` is a `BooleanProperty`, default to True.

  `do_scale`

    Allow scaling

    `do_scale` is a `BooleanProperty`, default to True.

  `do_translation`

    Allow translation on X or Y axis

    `do_translation` is a `AliasProperty` of (`do_translation_x` + `do_translation_y`)

  `do_translation_x`

    Allow translation on X axis

    `do_translation_x` is a `BooleanProperty`, default to True.

  `do_translation_y`

    Allow translation on Y axis

    `do_translation_y` is a `BooleanProperty`, default to True.

  `pos`

    Create a property with a custom getter and setter.

    If you don’t found a Property class that fit to your needs, you can still create Python getter and setter, and create a property with both of them.

    Exemple from the kivy/uix/widget.py

        def get_right(self):
            return self.x + self.width
        def set_right(self, value):
            self.x = value - self.width
        right = AliasProperty(get_right, set_right, bind=(x, width))

    Parameters : | getter: function Function to use as a property getter setter: function Function to use as a property setter bind: list/tuple List of properties to observe for changes

  `rotation`

    Rotation value of the scatter

    `rotation` is a `AliasProperty`.

  `scale`

    Scale value of the scatter

    `scale` is a `AliasProperty`.

  `scale_max`

    Maximum scaling factor allowed

    `scale_max` is a `NumericProperty`, default to 1e20

  `scale_min`

    Minimum scaling factor allowed

    `scale_min` is a `NumericProperty`, default to 0.01

  `transform`

    Transformation matrix

    `transform` is a `ObjectProperty`, default to the identity matrix.

  `transform_inv`

    Inverse of the transformation matrix

    `transform_inv` is a `ObjectProperty`, default to the identity matrix.

  `x`

    Create a property with a custom getter and setter.

    If you don’t found a Property class that fit to your needs, you can still create Python getter and setter, and create a property with both of them.

    Exemple from the kivy/uix/widget.py

        def get_right(self):
            return self.x + self.width
        def set_right(self, value):
            self.x = value - self.width
        right = AliasProperty(get_right, set_right, bind=(x, width))

    Parameters : | getter: function Function to use as a property getter setter: function Function to use as a property setter bind: list/tuple List of properties to observe for changes

  `y`

    Create a property with a custom getter and setter.

    If you don’t found a Property class that fit to your needs, you can still create Python getter and setter, and create a property with both of them.

    Exemple from the kivy/uix/widget.py

        def get_right(self):
            return self.x + self.width
        def set_right(self, value):
            self.x = value - self.width
        right = AliasProperty(get_right, set_right, bind=(x, width))

    Parameters : | getter: function Function to use as a property getter setter: function Function to use as a property setter bind: list/tuple List of properties to observe for changes