Jason,
I know this wasn't really your point, which was about having better docs and
not the TweenEffect API specifically, but for what it's worth: the new effects
for the next release of Flex, along with the Animation class (which is used
instead of Tween), avoid the use of Function handles for easing and update/end
handlers. Instead, we use interfaces for easing (and for type interpolation, a
new concept in the effects). And events are sent through event handlers.
Hopefully this all makes it more explicit what's happening to whom and what
developers need to know about it...
Chet.
From: flexcoders@yahoogroups.com [mailto:[EMAIL PROTECTED] On Behalf Of Pan
Troglodytes
Sent: Thursday, September 11, 2008 9:32 AM
To: flexcoders
Subject: [flexcoders] Note to someone at Adobe who is in charge of documentation
Hopefully, someone who reads this can maybe forward it or mention it to someone
who is in the documentation department.
My biggest problem with the documentation is when it comes to function
signatures. Unfortunately in ActionScript, function signatures are not
typeable. If I was using Delphi, I could define
TMyEventCallback = function (param1: String, param2: Integer):Boolean;
So properties always just take a Function and it's up to the developer to
figure out what the function should look like. Okay, I can deal with that,
given proper documentation. But so many times in the docs, no function
signature is listed. I understand that it's hard to create docs while the SDK
is still under development, however there are plenty of examples of it in code
that shipped with 2.0.
For example, from TweenEffect:
easingFunction
property
public var easingFunction:Function../../Function.html = null
The easing function for the animation. The easing function is used to
interpolate between the initial value and the final value. A trivial easing
function would simply do linear interpolation, but more sophisticated easing
functions create the illusion of acceleration and deceleration, which makes the
animation seem more natural.
If no easing function is specified, an easing function based on the Math.sin()
method is used.
The easing function follows the function signature popularized by Robert
Penner. The function accepts four arguments. The first argument is the current
time, where the animation start time is 0. The second argument is the initial
value at the beginning of the animation (a Number). The third argument is the
ending value minus the initial value. The fourth argument is the duration of
the animation. The return value is the interpolated value for the current time.
This is usually a value between the initial value and the ending value.
The value of this property must be a function object.
Flex includes a set of easing functions in the mx.effects.easing package.
This documentation is strange in that a paragraph is dedicated to describing
the function signature, when just putting a
function (currentTime:Number, startValue:Number,
endValueMinusStartValue:Number, duration:Number):Number
alone would have been far more useful than the whole paragraph. I'm not saying
to ditch the paragraph, but a code examples is almost always preferable.
Especially since that paragraph forgot to specify that the last two params and
teh return param should be a Number. This was inferable from context in this
case, but it is not always. These omissions tend to send me on a code hunt,
looking for some place in the SDK where the function is called. For
easingFunction, this was quite a bit of digging until I finally found
defaultEasingFunction in Tween.as.
I could put this in as a bug/enhancement, but it just seems like that falls
short. I'd really just like to see more of a focus on doing it properly the
first time and possibly doing a review of all documentation that mentions a
property or method that involves a type Function.
--
Jason
