gillcup.properties

Gillcup’s Animated Properties

To animate Python objects, we need to change values of their attributes over time. There are two kinds of changes we can make: discrete and continuous. A discrete change happens at a single point in time: for example, an object is shown, some output is written, a sound starts playing. Actions are used for effecting discrete changes.

Continuous changes happen over a period of time: an object smoothly moves to the left, or a sound fades out. These changes are made by animating special properties on objects, using Animation classes on so-called animated properties.

Under the hood, Gillcup uses Python’s descriptor interface to provide efficient animated properties.

Assigment to an animated attribute causes the property to get set to the given value and cancels any running animations on it.

class gillcup.AnimatedProperty(default, docstring=None)

A scalar animated property

The idiomatic way to define animated properties is as follows:

class Tone(object):
    pitch = AnimatedProperty(440)
    volume = AnimatedProperty(0)

Now, Tone instances will have pitch and volume set to the corresponding defaults, and can be animated.

The docstring argument becomes the property’s __doc__ attribute.

adjust_value(values)

Convert an animation’s *args values into a property value

For scalar properties, this converts a 1-tuple into its only element

tween_values(function, parent_value, value)

Call a scalar tween function on two values.

class gillcup.TupleProperty(*default, **kwargs)

A tuple animated property

Iterating the TupleProperty itself yields sub-properties that can be animated individually. The intended idiom for declaring a tuple property is:

x, y, z = position = TupleProperty(0, 0, 0)

adjust_value(value)

Convert an animation’s *args values into a property value

For tuple properties, return the tuple unchanged

tween_values(function, parent_value, value)

Call a scalar tween function on two values.

Calls the function on corresponding pairs of elements, returns the tuple of results

class gillcup.properties.ScaleProperty(num_dimensions, **kwargs)

A TupleProperty used for scales or sizes in multiple dimensions

It acts as a regular TupleProperty, but supports scalars or short tuples in assignment or animation.

Instead of a default value, __init__ takes the number of dimensions; the default value will be (1,) * num_dimensions.

If a scalar, or a tuple with only one element, is given, the value is repeated across all dimensions. If another short tuple is given, the remaining dimensions are set to 1.

For example, given:

width, height, length = size = ScaleProperty(3)

the following pairs are equivalent:

obj.size = 2
obj.size = 2, 2, 2

obj.size = 2, 3
obj.size = 2, 3, 1

obj.size = 2,
obj.size = 2, 2, 2

Similarly, Animation(obj, 'size', 2) is equivalent to Animation(obj, 'size', 2, 2, 2).

adjust_value(value)

Expand the given tuple or scalar to a tuple of len=num_dimensions

class gillcup.properties.VectorProperty(num_dimensions, **kwargs)

A TupleProperty used for vectors

It acts as a regular TupleProperty, but supports short tuples in assignment or animation by setting all remaining dimensions to 0.

Instead of a default value, __init__ takes the number of dimensions; the default value will be (0,) * num_dimensions.

For example, given:

x, y, z = position = VectorProperty(3)

the following pairs are equivalent:

obj.position = 2, 3
obj.position = 2, 3, 0

obj.position = 2,
obj.position = 2, 0, 0

Similarly, Animation(obj, 'position', 1, 2) is equivalent to Animation(obj, 'position', 1, 2, 0).

adjust_value(value)

Expand the given tuple to the correct number of dimensions