Gillcup’s Animation classes

Animations are Actions that modify animated properties. To use one, create it and schedule it on a Clock. Once an animation is in effect, it will smoothly change a property’s value over a specified time interval.

The value is computed as a tween between the property’s original value and the Animation’s target value. The tween parameters can be set by the timing and easing keyword arguments.

The “original value” of a property is not fixed: it is whatever the value would have been if this animation wasn’t applied (in other words, it’s determined by the effect that was originally on the property). Also, if you set the dynamic argument to Animation, the animation’s target becomes an AnimatedProperty. Animating these allows one to create very complex effects in a modular way.

class gillcup.Animation(instance, property_name, *target, **kwargs)

An object that modifies an AnimatedProperty based on Clock time

Positional init arguments:

  • instance – The object whose property is animated
  • property_name – Name of the animated property
  • target – Value at which the animation should arrive (tuple properties accept more arguments, i.e. Animation(obj, 'position', 1, 2, 3))

Keyword init arguments:

  • time – The duration of the animation
  • delay – Delay between the time the animation is scheduled and its actual start
  • timing

    A function that maps global time to animation’s time.

    Possible values:

    • None: normalizes time so that 0 corresponds to the start of the animation, and 1 to the end (i.e. start + time); clamps to [0, 1]
    • 'infinite': same as above, but doesn’t clamp: the animation goes forever on (in both directions; it only starts to take effect when it’s scheduled, but a delay can cause negative local times). The animation’s time is normalized to 0 at the start and 1 at start + time.
    • 'absolute': the animation is infinite, with the same speed as with the ‘infinite’ option, but zero corresponds to the clock’s zero. Useful for synchronized periodic animations.
    • function(time, start, duration): apply a custom function
  • easing – An easing function to use. Can be either a one-argument function, or a dotted name which is looked up in the gillcup.easing module.
  • dynamic – If true, the target atribute becomes an AnimatedProperty, allowing for more complex animations.


In order to conserve resources, ordinary Animations are released (replaced by a simple ConstantEffect) when they are “done”. Arguments such as timing, or the Add or Multiply animation subclasses, which allow the value to be modified after the time elapses, turn this behavior off by setting the dynamic attibute to true.

When subclassing Animation, remember to do the same if your subclass needs to change its value after time elapses. This includes cases where the value depends on the value of the previous (parent) animation.

class gillcup.animation.Add(instance, property_name, *target, **kwargs)[source]

An additive animation: the target value is added to the original

class gillcup.animation.Multiply(instance, property_name, *target, **kwargs)[source]

A multiplicative animation: target value is multiplied to the original

class gillcup.animation.Computed(instance, property_name, func, **kwargs)[source]

A custom-valued animation: the target is computed by a function

Pass a func keyword argument with the function to the constructor.

The function will get one argument: the time elapsed, normalized by the animation’s timing function.

Previous topic

Next topic


This Page