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