Scatter

Scatter is used to build interactive widgets that can be translated, rotated and scaled with two or more fingers on a multitouch system.

Scatter has its own matrix transformation: the modelview matrix is changed before the child is drawn, and the previous matrix is restored when the drawing is finished. That makes possible the rotation / scale / translation of the entire children tree, without changing them.

That specific behavior makes the scatter unique, and there are some advantages / constraints that you should consider:

  1. The children are positionned relative to 0, 0. The scatter position has no impact of the position of children. This applies to the size too.
  2. If you want to resize the scatter, use scale, not size. (read #1.)
  3. The scatter is not a layout. You must take care of size of children yourself.

For touch events, the scatter converts from the parent matrix to the scatter matrix automatically in on_touch_down/move/up events. If you are doing things manually, you will need to use to_parent(), to_local().

Usage

By default, the widget does not have a graphical representation. It is a container only. The idea is to combine Scatter with another widget, for example Image:

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

Control Interactions

By default, all interactions are enabled. You can selectively disable them using the do_{rotation, translation, scale} properties.

Disable rotation:

scatter = Scatter(do_rotation=False)

Allow only translation:

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

Allow only translation on x axis:

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

Automatic Bring to Front

If the Scatter.auto_bring_to_front property is True, the scatter widget will be removed and re-added to the parent when it is touched (brought to front, above all other widgets in the parent). This is useful when you are manipulating several scatter widgets and don’t want the active one to be partially hidden.

Scale Limitation

We are using a 32-bit matrix in double representation. That means we have a limit for scaling. You cannot do infinite 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 is 9.99506983235e+19 (2^66).

You can also limit the minimum and maximum scale allowed:

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

Behaviors

Changed in version 1.1.0: If no control interactions are enabled, then touch handler will never return True.

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

Bases: kivy.uix.widget.Widget

Scatter class. See module documentation for more information.

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.

do_collide_after_children

If True, the collision detection for limiting the touch inside the scatter will be done after dispaching the touch to the children. You can put children outside the bounding box of the scatter, and be able to touch them.

New in version 1.3.0.

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.

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.

class kivy.uix.scatter.ScatterPlane(**kwargs)

Bases: kivy.uix.scatter.Scatter

This is essentially an unbounded Scatter widget, convenience class to make easier the writting of infinite planes