sugar3.graphics.animator module

The animator module provides a simple framework to create animations.

Example

Animate the size of a window:

from gi.repository import Gtk
from sugar3.graphics.animator import Animator, Animation

# Construct a window to animate
w = Gtk.Window()
w.connect('destroy', Gtk.main_quit)
# Start the animation when the window is shown
w.connect('realize', lambda self: animator.start())
w.show()

# Construct a 5 second animator
animator = Animator(5, widget=w)

# Create an animation subclass to animate the widget
class SizeAnimation(Animation):
    def __init__(self):
        # Tell the animation to give us values between 20 and
        # 420 during the animation
        Animation.__init__(self, 20, 420)

    def next_frame(self, frame):
        size = int(frame)
        w.resize(size, size)
# Add the animation the the animator
animation = SizeAnimation()
animator.add(animation)

# The animation needs to run inside a GObject main loop
Gtk.main()

STABLE.

class sugar3.graphics.animator.Animation(start, end)

Bases: object

The animation class is a base class for creating an animation. It should be subclassed. Subclasses should specify a next_frame function to set the required properties based on the animation progress. The range of the frame value passed to the next_frame function is defined by the start and end values.

Parameters

• start (float) – the first frame value for the next_frame method

• end (float) – the last frame value for the next_frame method

# Create an animation subclass
class MyAnimation(Animation):
    def __init__(self, thing):
        # Tell the animation to give us values between 0.0 and
        # 1.0 during the animation
        Animation.__init__(self, 0.0, 1.0)
        self._thing = thing

    def next_frame(self, frame):
        # Use the `frame` value to set properties
        self._thing.set_green_value(frame)

do_frame(t, duration, easing)

This method is called by the animator class every frame. This method calculated the frame value to then call next_frame.

Parameters

• t (float) – the current time elapsed of the animation in seconds

• duration (float) – the length of the animation in seconds

• easing (int) – the easing mode passed to the animator

do_stop()

This method is called whenever the animation is stopped, either due to the animation ending or being stopped by the animation. next_frame will not be called after do_stop, unless the animation is restarted.

New in version 0.109.0.3.

This should be used in subclasses if they bind any signals. Eg. if they bind the draw signal for a widget:

class SignalAnimation(Animation):

    def __init__(self, widget):
        Animation.__init__(self, 0, 1)
        self._draw_hid = None
        self._widget = widget

    def next_frame(self, frame):
        self._frame = frame
        if self._draw_hid is None:
            self._draw_hid = self._widget.connect_after(
                'draw', self.__draw_cb)
        self._widget.queue_draw()

    def __draw_cb(self, widget, cr):
        cr.save()
        # Do the draw
        cr.restore()

    def do_stop(self):
        self._widget.disconnect(self._draw_hid)
        self._widget.queue_draw()

next_frame(frame)

This method is called every frame and should be overridden by subclasses.

Parameters

frame (float) – a value between start and end representing the current progress in the animation

class sugar3.graphics.animator.Animator(duration, fps=20, easing=0, widget=None)

Bases: gi.overrides.GObject.Object

The animator class manages the timing for calling the animations. The animations can be added using the add function and then started with the start function. If multiple animations are added, then they will be played back at the same time and rate as each other.

The completed signal is emitted upon the completion of the animation and also when the stop function is called.

Parameters

• duration (float) – the duration of the animation in seconds

• fps (int, optional) – the number of animation callbacks to make per second (frames per second)

• easing (int) – the desired easing mode, either EASE_OUT_EXPO or EASE_IN_EXPO

• widget (Gtk.Widget) – one of the widgets that the animation is acting on. If supplied and if the user’s Gtk+ version supports it, the animation will run on the frame clock of the widget, resulting in a smoother animation and the fps value will be disregarded.

Note

When creating an animation, take into account the limited cpu power on some devices, such as the XO. Setting the fps too high on can use significant cpu usage on the XO.

add(animation)

Add an animation to this animator

Parameters

animation (sugar3.graphics.animator.Animation) – the animation instance to add

remove_all()

Remove all animations and stop this animator

start()

Start the animation running. This will stop and restart the animation if the animation is currently running

stop()

Stop the animation and emit the completed signal