dotsDrawableAnimator Class Reference

Overview

Update properties or methods of dotsDrawable objects, over time.

dotsDrawableAnimator organizes time-dependent value changes for dotsDrawable objects. An array of times specifies the time course for value changes, and an array of values specifies the changes themselves.

Value changes may be applied to any object member: they may be assigned to object properties, or passed to object methods. Furthermore, each member may be updated in a variety of ways. Some members may have values interpolated between times while others may change by abrupt steps. Some members may reach a stopping point and remain fixed, others may drift endlessly, and others may wrap endlessly.

Member values must be numeric, to alow for interpolation. They may be scalars, or matrices of any size. Matrices will be interpolated element-wise, so all of the values for a given member must have the same size.

dotsDrawableAnimator is itself a subclass of dotsDrawable, so it may be used as an aggregate of one or more other dotsDrawable objects. The draw() method performs member updating and can invoke draw() on each aggregated object. Similarly, prepareToDrawInWindow() invokes prepareToDrawInWindow() on each aggregated object.

The aggregated drawables may belong to different dotsDrawable subclasses. But the same members must apply to all of the drawables, so that the animator can treat them uniformly.

Inheritance diagram for dotsDrawableAnimator:

Properties and Events
Property	clockFunction
	function that returns the current time as a number
Property	isAggregateDraw = true
	whether draw() should invoke draw() on aggregated drawables
Property	allMembers = struct([])
	struct array of values, times, and other animation data More...
Properties and Events inherited from dotsDrawable
Property	isVisible = true
	true or false, whether to draw() this object

Protected Properties
Property	drawables
	cell array of aggregated dotsDrawable objects to animate
Property	startTime
	zero-time for the beginning of each animation sequence
Property	validCompletionStyle = {'stop', 'wrap', 'drift'}
	cell array of strings for supported completionStyle

Methods
self	dotsDrawableAnimator ()
	Constructor takes no arguments.
	prepareToDrawInWindow (self)
	Invoke prepareToDrawInWindow() on aggregated drawables.
	draw (self)
	Update member values and invoke draw() on aggregated drawables.
	updateMembers (self)
	Update the time-varying currentValue value for each member.
index	addDrawable (self, drawable)
	Add a dotsDrawable object to the aggregated drawables. More...
index	removeDrawable (self, drawable)
	Remove a dotsDrawable object from the aggregated drawables. More...
index	addMember (self, member, times, values, isInterpolated)
	Specify new values and times for animating a drawable member. More...
index	removeMember (self, member)
	Remove an animation specification. More...
index	setMemberCompletionStyle (self, member, style, hint)
	Choose what to do when a member runs out of times and values. More...
Methods inherited from dotsDrawable
self	dotsDrawable ()
	Constructor takes no arguments.
	prepareToDrawInWindow (self)
	Do any pre-draw setup that requires an OpenGL drawing window.
	mayDrawNow (self)
	Draw() or not, depending on isVisible and possibly other factors.
	draw (self)
	Subclass must redefine draw() to draw graphics.
	show (self)
	Shorthand to set isVisible=true.
	hide (self)
	Shorthand to set isVisible=false.

Additional Inherited Members
Static Methods inherited from dotsDrawable
static frameInfo	drawFrame (drawables, doClear)
	draw() several drawable objects and show the next Screen frame. More...
static ensemble	makeEnsemble (name, objects)
	Convenient utility for combining a bunch of drawables into an ensemble. More...
static frameInfo	drawEnsemble (ensemble, args, prepareFlag, showDuration, pauseDuration)
	Convenient utility for drawing an ensemble either locally or remotely. More...

Methods

addDrawable()

index addDrawable	(	self	,
		drawable
	)

Add a dotsDrawable object to the aggregated drawables.

Parameters

drawable

dotsDrawable object

addDrawable() adds the given drawable to the array of dotsDrawable objects in drawables. Returns the index into drawables where drawable was added.

removeDrawable()

index removeDrawable	(	self	,
		drawable
	)

Remove a dotsDrawable object from the aggregated drawables.

Parameters

drawable

dotsDrawable object

removeDrawable() searches the array of dotsDrawable objects in drawables for the given drawable, and removes all instances it finds.

Returns an array of indexes into drawables where drawable was found and removed. The returned indexes are no longer valid, because drawable is gone and drawables has changed length.

addMember()

index addMember	(	self	,
		member	,
		times	,
		values	,
		isInterpolated
	)

Specify new values and times for animating a drawable member.

Parameters

member	string name of a drawable property, or handle of a drawable method
times	monotonic increasing vector of animation time points
values	numeric vector or cell array of matrices of animation values, with the same size as times
isInterpolated	whether values should be interpolated between @times (true), or applied in abrupt steps (false, default)

addMember() specifies a new drawable property or method to be animated. The given mamber should match the name of a property or match a method shared by all of the dotsDrawable objects in drawables.

times and values specify the time course and values to be applied during animation. During each draw(), the current time is used as a key to pick the current element of times and the corresponding element of values. The current value is applied to member for all the objects in drawables.

If member is a string property name, objects will receive the current value by assignment:

object.(member) = currentValue;

If member is a method function handle, each object and the current value will be passed to the method:

feval(member, object, currentValue);

Note that this "method" syntax will work for any function that expects an object and a value as the first two arguments.

If isInterpolated is false (the default), the current value will always be equal to one of the elements of @values, and the current value will change abruptly for each element of times. If isInterpolated is true, the current value will be interpolated between neighboring elements of values, based on the fraction of time that has passed between neighboring elements of times.

addMember() returns the index into allMembers where the new animation specification was stored. If allMembers already contains a specification for member, the existing specification will be replaced. Otherwise, the new specification will be appended to allMembers.

removeMember()

index removeMember	(	self	,
		member
	)

Remove an animation specification.

Parameters

member

string name of a drawable property, or handle of a drawable method, that was added with addMember()

removeMember() searches allMembers for an animation specification with member equal to the given member, and removes it.

removeMember() returns the index into allMembers where member was found and removed, or [] if it did not find member. The returned index is no longer a valid because @member is gone and allMembers has changed length.

setMemberCompletionStyle()

index setMemberCompletionStyle	(	self	,
		member	,
		style	,
		hint
	)

Choose what to do when a member runs out of times and values.

Parameters

member	string name of a drawable property, or handle of a drawable method, that was added with addMember()
style	string name of an animation completion style, must be 'stop', 'wrap', or 'drift'.
hint	parameter which affects 'wrap' or 'drift' behavior

Each animation specification in allMembers contains a finite number of times. So how should member behave when the current time surpasses the last elements of times? setMemberCompletionStyle() selects one of three completion styles: 'stop', 'wrap', or 'drift'.

If style is 'stop', then member will progress through times and values once, then stop at the last element of values. In this case, hint should be omitted.

If style is 'wrap', then member will loop forever through times and values. In this case, hint must be the wrapping period, which will be used as a divisor for the current time. Note that the wrapping period need not be equal to the last element of times.

If style is 'drift', then member will progress through times and values once, then drift at a constant rate. In this case, hint must be the constant drift rate. The current value will be calculated as the last element of values, plus the drift since the last element of times.

The default completion style for each member is 'stop'.

setMemberCompletionStyle() returns the index into allMembers where member was found and updated, or [] if it did not find member.

Properties and Events

allMembers

Property allMembers = struct([])

struct array of values, times, and other animation data

Each element of allMembers contains information for updating a drawable property or invoking a method, over time. The fields of allMembers are:

• name a string name of an object property or method

method a function handle, if name is a method name. Any function that takes an object as the first argument and currentValue as the second argument may be used as a "method".

• times a vector of monotonic increasing times, with one element for each element of values

values a cell array of values to be applied to the member, based on the time course specified in times.

• currentValue the current time-varying value of the member
• isInterpolated whether values are interpolated between times (true), or changed abruptly (false, default).
• completionStyle how to behave when the member runs out of times and values. See setMemberCompletionStyle(). Default is 'stop'.
• completionHint parameter for guiding 'wrap' or 'drift' completion style.

Users should call addMember(), editMemberByName(), and setMemberCompletionStyle() instead of manipulating allMembers directly.

---

The documentation for this class was generated from the following file:

• dotsDrawableAnimator.m