Scatter¶
Scatter is used to build interactive widgets that can be translated, rotated and scaled with two or more fingers on a multitouch system.
The Scatter have its own matrix transformation: the modelview matrix are changing before the childs draw, and the previous matrix is restored when the drawing is finished. That make possible the rotation / scale / translate of its whole children tree, without changing them.
That specific behavior make the scatter unique, and their is some advantages / constraint that you should care about:
- The children are positionned relative to the 0, 0. The scatter position have no impact of the children position. This applies to the size too.
- If you want to resize the scatter, use scale, not size. (read #1.)
- The scatter is not a layout, you must take care of the children size yourself.
For touch events, the scatter convert from the parent matrix to scatter matrix automatically in on_touch_down/move/up event. If you are doing all the things manually, you will need to use to_parent(), to_local().
Usage¶
By default, the widget doesn’t have any 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 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.
- 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.