'''
Scatter
=======
.. image:: images/scatter.gif
:align: right
:class:`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 children are drawn and the previous matrix is restored when the
drawing is finished. That makes it possible to perform rotation, scaling and
translation over the entire children tree without changing any widget
properties. That specific behavior makes the scatter unique, but there are some
advantages / constraints that you should consider:
#. The children are positioned relative to the scatter similarly to a
:mod:`~kivy.uix.relativelayout.RelativeLayout`. So when dragging the
scatter, the position of the children don't change, only the position of
the scatter does.
#. The scatter size has no impact on the size of its children.
#. If you want to resize the scatter, use scale, not size (read #2). Scale
transforms both the scatter and its children, but does not change size.
#. The scatter is not a layout. You must manage the size of the 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 :meth:`~kivy.uix.widget.Widget.to_parent` and
:meth:`~kivy.uix.widget.Widget.to_local`.
Usage
-----
By default, the Scatter does not have a graphical representation: it is a
container only. The idea is to combine the Scatter with another widget, for
example an :class:`~kivy.uix.image.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, do_translation and do_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 :attr:`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 scaling 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.)
Behavior
--------
.. versionchanged:: 1.1.0
If no control interactions are enabled, then the touch handler will never
return True.
'''
__all__ = ('Scatter', 'ScatterPlane')
from math import radians
from kivy.properties import BooleanProperty, AliasProperty, \
NumericProperty, ObjectProperty, BoundedNumericProperty
from kivy.vector import Vector
from kivy.uix.widget import Widget
from kivy.graphics.transformation import Matrix
[docs]class Scatter(Widget):
'''Scatter class. See module documentation for more information.
:Events:
`on_transform_with_touch`:
Fired when the scatter has been transformed by user touch
or multitouch, such as panning or zooming.
`on_bring_to_front`:
Fired when the scatter is brought to the front.
.. versionchanged:: 1.9.0
Event `on_bring_to_front` added.
.. versionchanged:: 1.8.0
Event `on_transform_with_touch` added.
'''
__events__ = ('on_transform_with_touch', 'on_bring_to_front')
auto_bring_to_front = BooleanProperty(True)
'''If True, the widget will be automatically pushed on the top of parent
widget list for drawing.
:attr:`auto_bring_to_front` is a :class:`~kivy.properties.BooleanProperty`
and defaults to True.
'''
do_translation_x = BooleanProperty(True)
'''Allow translation on the X axis.
:attr:`do_translation_x` is a :class:`~kivy.properties.BooleanProperty` and
defaults to True.
'''
do_translation_y = BooleanProperty(True)
'''Allow translation on Y axis.
:attr:`do_translation_y` is a :class:`~kivy.properties.BooleanProperty` and
defaults to True.
'''
def _get_do_translation(self):
return (self.do_translation_x, self.do_translation_y)
def _set_do_translation(self, value):
if type(value) in (list, tuple):
self.do_translation_x, self.do_translation_y = value
else:
self.do_translation_x = self.do_translation_y = bool(value)
do_translation = AliasProperty(_get_do_translation, _set_do_translation,
bind=('do_translation_x',
'do_translation_y'),
cache=True)
'''Allow translation on the X or Y axis.
:attr:`do_translation` is an :class:`~kivy.properties.AliasProperty` of
(:attr:`do_translation_x` + :attr:`do_translation_y`)
'''
translation_touches = BoundedNumericProperty(1, min=1)
'''Determine whether translation was triggered by a single or multiple
touches. This only has effect when :attr:`do_translation` = True.
:attr:`translation_touches` is a :class:`~kivy.properties.NumericProperty`
and defaults to 1.
.. versionadded:: 1.7.0
'''
do_rotation = BooleanProperty(True)
'''Allow rotation.
:attr:`do_rotation` is a :class:`~kivy.properties.BooleanProperty` and
defaults to True.
'''
do_scale = BooleanProperty(True)
'''Allow scaling.
:attr:`do_scale` is a :class:`~kivy.properties.BooleanProperty` and
defaults to True.
'''
do_collide_after_children = BooleanProperty(False)
'''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 still be
able to touch them.
:attr:`do_collide_after_children` is a
:class:`~kivy.properties.BooleanProperty` and defaults to False.
.. versionadded:: 1.3.0
'''
scale_min = NumericProperty(0.01)
'''Minimum scaling factor allowed.
:attr:`scale_min` is a :class:`~kivy.properties.NumericProperty` and
defaults to 0.01.
'''
scale_max = NumericProperty(1e20)
'''Maximum scaling factor allowed.
:attr:`scale_max` is a :class:`~kivy.properties.NumericProperty` and
defaults to 1e20.
'''
transform = ObjectProperty(Matrix())
'''Transformation matrix.
:attr:`transform` is an :class:`~kivy.properties.ObjectProperty` and
defaults to the identity matrix.
.. note::
This matrix reflects the current state of the transformation matrix
but setting it directly will erase previously applied
transformations. To apply a transformation considering context,
please use the :attr:`~Scatter.apply_transform` method.
'''
transform_inv = ObjectProperty(Matrix())
'''Inverse of the transformation matrix.
:attr:`transform_inv` is an :class:`~kivy.properties.ObjectProperty` and
defaults to the identity matrix.
'''
def _get_bbox(self):
xmin, ymin = xmax, ymax = self.to_parent(0, 0)
for point in [(self.width, 0), (0, self.height), self.size]:
x, y = self.to_parent(*point)
if x < xmin:
xmin = x
if y < ymin:
ymin = y
if x > xmax:
xmax = x
if y > ymax:
ymax = y
return (xmin, ymin), (xmax - xmin, ymax - ymin)
bbox = AliasProperty(_get_bbox, bind=('transform', 'width', 'height'))
'''Bounding box of the widget in parent space::
((x, y), (w, h))
# x, y = lower left corner
:attr:`bbox` is an :class:`~kivy.properties.AliasProperty`.
'''
def _get_rotation(self):
v1 = Vector(0, 10)
tp = self.to_parent
v2 = Vector(*tp(*self.pos)) - tp(self.x, self.y + 10)
return -1.0 * (v1.angle(v2) + 180) % 360
def _set_rotation(self, rotation):
angle_change = self.rotation - rotation
r = Matrix().rotate(-radians(angle_change), 0, 0, 1)
self.apply_transform(r, post_multiply=True,
anchor=self.to_local(*self.center))
rotation = AliasProperty(_get_rotation, _set_rotation,
bind=('x', 'y', 'transform'))
'''Rotation value of the scatter in degrees moving in a counterclockwise
direction.
:attr:`rotation` is an :class:`~kivy.properties.AliasProperty` and defaults
to 0.0.
'''
def _get_scale(self):
p1 = Vector(*self.to_parent(0, 0))
p2 = Vector(*self.to_parent(1, 0))
scale = p1.distance(p2)
# XXX float calculation are not accurate, and then, scale can be
# throwed again even with only the position change. So to
# prevent anything wrong with scale, just avoid to dispatch it
# if the scale "visually" didn't change. #947
# Remove this ugly hack when we'll be Python 3 only.
if hasattr(self, '_scale_p'):
if str(scale) == str(self._scale_p):
return self._scale_p
self._scale_p = scale
return scale
def _set_scale(self, scale):
rescale = scale * 1.0 / self.scale
self.apply_transform(Matrix().scale(rescale, rescale, rescale),
post_multiply=True,
anchor=self.to_local(*self.center))
scale = AliasProperty(_get_scale, _set_scale, bind=('x', 'y', 'transform'))
'''Scale value of the scatter.
:attr:`scale` is an :class:`~kivy.properties.AliasProperty` and defaults to
1.0.
'''
def _get_center(self):
return (self.bbox[0][0] + self.bbox[1][0] / 2.0,
self.bbox[0][1] + self.bbox[1][1] / 2.0)
def _set_center(self, center):
if center == self.center:
return False
t = Vector(*center) - self.center
trans = Matrix().translate(t.x, t.y, 0)
self.apply_transform(trans)
center = AliasProperty(_get_center, _set_center, bind=('bbox',))
def _get_pos(self):
return self.bbox[0]
def _set_pos(self, pos):
_pos = self.bbox[0]
if pos == _pos:
return
t = Vector(*pos) - _pos
trans = Matrix().translate(t.x, t.y, 0)
self.apply_transform(trans)
pos = AliasProperty(_get_pos, _set_pos, bind=('bbox',))
def _get_x(self):
return self.bbox[0][0]
def _set_x(self, x):
if x == self.bbox[0][0]:
return False
self.pos = (x, self.y)
return True
x = AliasProperty(_get_x, _set_x, bind=('bbox',))
def _get_y(self):
return self.bbox[0][1]
def _set_y(self, y):
if y == self.bbox[0][1]:
return False
self.pos = (self.x, y)
return True
y = AliasProperty(_get_y, _set_y, bind=('bbox',))
def get_right(self):
return self.x + self.bbox[1][0]
def set_right(self, value):
self.x = value - self.bbox[1][0]
right = AliasProperty(get_right, set_right, bind=('x', 'bbox'))
def get_top(self):
return self.y + self.bbox[1][1]
def set_top(self, value):
self.y = value - self.bbox[1][1]
top = AliasProperty(get_top, set_top, bind=('y', 'bbox'))
def get_center_x(self):
return self.x + self.bbox[1][0] / 2.
def set_center_x(self, value):
self.x = value - self.bbox[1][0] / 2.
center_x = AliasProperty(get_center_x, set_center_x, bind=('x', 'bbox'))
def get_center_y(self):
return self.y + self.bbox[1][1] / 2.
def set_center_y(self, value):
self.y = value - self.bbox[1][1] / 2.
center_y = AliasProperty(get_center_y, set_center_y, bind=('y', 'bbox'))
def __init__(self, **kwargs):
self._touches = []
self._last_touch_pos = {}
super(Scatter, self).__init__(**kwargs)
def on_transform(self, instance, value):
self.transform_inv = value.inverse()
[docs] def collide_point(self, x, y):
x, y = self.to_local(x, y)
return 0 <= x <= self.width and 0 <= y <= self.height
[docs] def to_parent(self, x, y, **k):
p = self.transform.transform_point(x, y, 0)
return (p[0], p[1])
[docs] def to_local(self, x, y, **k):
p = self.transform_inv.transform_point(x, y, 0)
return (p[0], p[1])
def _apply_transform(self, m, pos=None):
m = self.transform.multiply(m)
return super(Scatter, self)._apply_transform(m, (0, 0))
def transform_with_touch(self, touch):
# just do a simple one finger drag
changed = False
if len(self._touches) == self.translation_touches:
# _last_touch_pos has last pos in correct parent space,
# just like incoming touch
dx = (touch.x - self._last_touch_pos[touch][0]) \
* self.do_translation_x
dy = (touch.y - self._last_touch_pos[touch][1]) \
* self.do_translation_y
dx = dx / self.translation_touches
dy = dy / self.translation_touches
self.apply_transform(Matrix().translate(dx, dy, 0))
changed = True
if len(self._touches) == 1:
return changed
# we have more than one touch... list of last known pos
points = [Vector(self._last_touch_pos[t]) for t in self._touches
if t is not touch]
# add current touch last
points.append(Vector(touch.pos))
# we only want to transform if the touch is part of the two touches
# farthest apart! So first we find anchor, the point to transform
# around as another touch farthest away from current touch's pos
anchor = max(points[:-1], key=lambda p: p.distance(touch.pos))
# now we find the touch farthest away from anchor, if its not the
# same as touch. Touch is not one of the two touches used to transform
farthest = max(points, key=anchor.distance)
if farthest is not points[-1]:
return changed
# ok, so we have touch, and anchor, so we can actually compute the
# transformation
old_line = Vector(*touch.ppos) - anchor
new_line = Vector(*touch.pos) - anchor
if not old_line.length(): # div by zero
return changed
angle = radians(new_line.angle(old_line)) * self.do_rotation
if angle:
changed = True
self.apply_transform(Matrix().rotate(angle, 0, 0, 1), anchor=anchor)
if self.do_scale:
scale = new_line.length() / old_line.length()
new_scale = scale * self.scale
if new_scale < self.scale_min:
scale = self.scale_min / self.scale
elif new_scale > self.scale_max:
scale = self.scale_max / self.scale
self.apply_transform(Matrix().scale(scale, scale, scale),
anchor=anchor)
changed = True
return changed
def _bring_to_front(self, touch):
# auto bring to front
if self.auto_bring_to_front and self.parent:
parent = self.parent
if parent.children[0] is self:
return
parent.remove_widget(self)
parent.add_widget(self)
self.dispatch('on_bring_to_front', touch)
[docs] def on_touch_down(self, touch):
x, y = touch.x, touch.y
# if the touch isnt on the widget we do nothing
if not self.do_collide_after_children:
if not self.collide_point(x, y):
return False
# let the child widgets handle the event if they want
touch.push()
touch.apply_transform_2d(self.to_local)
if super(Scatter, self).on_touch_down(touch):
touch.pop()
self._bring_to_front(touch)
return True
touch.pop()
# if our child didn't do anything, and if we don't have any active
# interaction control, then don't accept the touch.
if not self.do_translation_x and \
not self.do_translation_y and \
not self.do_rotation and \
not self.do_scale:
return False
if self.do_collide_after_children:
if not self.collide_point(x, y):
return False
if 'multitouch_sim' in touch.profile:
touch.multitouch_sim = True
# grab the touch so we get all it later move events for sure
self._bring_to_front(touch)
touch.grab(self)
self._touches.append(touch)
self._last_touch_pos[touch] = touch.pos
return True
[docs] def on_touch_move(self, touch):
x, y = touch.x, touch.y
# let the child widgets handle the event if they want
if self.collide_point(x, y) and not touch.grab_current == self:
touch.push()
touch.apply_transform_2d(self.to_local)
if super(Scatter, self).on_touch_move(touch):
touch.pop()
return True
touch.pop()
# rotate/scale/translate
if touch in self._touches and touch.grab_current == self:
if self.transform_with_touch(touch):
self.dispatch('on_transform_with_touch', touch)
self._last_touch_pos[touch] = touch.pos
# stop propagating if its within our bounds
if self.collide_point(x, y):
return True
[docs] def on_bring_to_front(self, touch):
'''
Called when a touch event causes the scatter to be brought to the
front of the parent (only if :attr:`auto_bring_to_front` is True)
:Parameters:
`touch`:
The touch object which brought the scatter to front.
.. versionadded:: 1.9.0
'''
pass
[docs] def on_touch_up(self, touch):
x, y = touch.x, touch.y
# if the touch isnt on the widget we do nothing, just try children
if not touch.grab_current == self:
touch.push()
touch.apply_transform_2d(self.to_local)
if super(Scatter, self).on_touch_up(touch):
touch.pop()
return True
touch.pop()
# remove it from our saved touches
if touch in self._touches and touch.grab_state:
touch.ungrab(self)
del self._last_touch_pos[touch]
self._touches.remove(touch)
# stop propagating if its within our bounds
if self.collide_point(x, y):
return True
[docs]class ScatterPlane(Scatter):
'''This is essentially an unbounded Scatter widget. It's a convenience
class to make it easier to handle infinite planes.
'''
def __init__(self, **kwargs):
if 'auto_bring_to_front' not in kwargs:
self.auto_bring_to_front = False
super(ScatterPlane, self).__init__(**kwargs)
[docs] def collide_point(self, x, y):
return True
