/*______________ ______ U I Z E J A V A S C R I P T F R A M E W O R K / / --------------------------------------------------/ O / MODULE : Uize.Curve.Rubber Package / / / / / / / ONLINE : http://www.uize.

com /____/ /__/_ COPYRIGHT : (c)2009-2012 UIZE /___ LICENSE : Available under MIT License or GNU General Public License _______________ http://www.uize.com/license.html */ /*ScruncherSettings Mappings="=" LineCompacting="TRUE"*/ /* Module Meta Data type: Package importance: 5 codeCompleteness: 100 testCompleteness: 0 docCompleteness: 100 */ /*? Introduction The =Uize.Curve.Rubber= module defines various "rubbery" easing curve functi on generators that emulate qualities of motion, like bounce and elasticity. *DEVELOPERS:* `Chris van Rensburg`, with thanks to `Robert Penner` for his e asing equations work The =Uize.Curve.Rubber= module defines various "rubbery" easing curve functi on generators, some of which are based on the easing equations work of `Robert P enner`. In A Nutshell Whereas the =Uize.Curve= module provides some of the most commonly used ea se-in, ease-out, ease-in-out, and ease-in-the-middle curve function generators, the =Uize.Curve.Rubber= module offers curve function generators for more exotic types of curves that emulate the complex properties of motion. Credit Where Credit Is Due Thanks go to `Robert Penner` for his work on [[http://www.robertpenner.c om/easing/][his easing equations]], which provided a starting point and inspirat ion for work that has been done in the =Uize.Curve.Rubber= module. In some cases, his original methods have merely been refactored, such as with the =Uize.Curve.Rubber.easeInElastic= method and related elastic easing cu rve function generators provided in this module. In other cases, the original im plementations have been completely replaced, such as with the =Uize.Curve.Rubber .easeInBounce= method and related bounce easing curve function generators provid ed in this module, with the new implementation being much more versatile than th e original. Either way, his excellent work has been an inspiration. Using the Curve Function Generators Using the curve function generators in the =Uize.Curve.Rubber= module is just as easy as using those contained inside the =Uize.Curve= module. Simply call the curve function generator static method, supplying parame ter values as needed in order to produce a curve with the desired properties, an d then provide that curve function to an instance of the =Uize.Fade= class, an i

nstance of the =Uize.Widget.HoverFader= class, a static method of the =Uize.Fx= module, or any method or instance of a class that uses the =Uize.Fade= class to drive its animation or value interpolation. EXAMPLE ........................................................................ .......... page.addChild ( 'hoverFader', Uize.Widget.HoverFader, { defaultStyle:{width:150,marginLeft:90,letterSpacing:2,borderRightCol or:'0'}, hoverStyle:{width:240,marginLeft:0,letterSpacing:9,borderRightColor: 'f'}, fadeIn:{duration:1200,curve:Uize.Curve.Rubber.easeOutElastic (.2)}, fadeOut:{duration:1000,curve:Uize.Curve.Rubber.easeOutBounce (5,-2,1 .5)} } ); ........................................................................ .......... In the above example, an instance of the =Uize.Widget.HoverFader= class is being added as a child widget of the page widget (which is assumed to already exist). For the =fadeIn= set-get property of the =Uize.Widget.HoverFader= insta nce, an elastic ease-out curve function is being supplied as a curve. For the =f adeOut= set-get property, a bounce ease-out curve function is being supplied as a curve. This will make the fade-in to the hover style have an elastic quality t o it, and the fade-out to the default style have a bounce quality to it. VISUALIZE IT To better visualize how the "rubbery" easing curve function generators wor k and how they affect motion, visit the interactive [[../examples/curve-explorer .html][Curve Explorer]] tool. BACKGROUND READING For an in-depth discussion on animation in the UIZE JavaScript Framework, and for a discussion on how this module fits into the larger picture, consult th e explainer [[../explainers/javascript-animation-and-effects.html][JavaScript An imation and Effects]] and read through the section `Curves`. */ Uize.module ({ name:'Uize.Curve.Rubber', builder:function (_host) { var _package = function () {}, _makeEasingCurveGenerators = _host.makeEasingCurveGenerators, _resolve = _host.resolve ; /*** Curve Function Generators ***/ /*** elastic easing ***/ _makeEasingCurveGenerators ( 'elastic', function (_period,_amplitude) { /*** paramter defaulting ***/

if (!_period) _period = .3; if (!_amplitude _amplitude < 1) _amplitude = 1; /*** capture some calculation results ***/ var _2piDivPeriod = 2 * Math.PI / _period, _someValueOffset = Math.asin (1 / _amplitude) / _2piDivPeriod ; return function (_value) { return ( _value && _value != 1 ? ( -_amplitude * Math.pow (2,10 * (_value -= 1)) * Math.sin ((_value - _someValueOffset) * _2piDivPeriod) ) : _value ) } }, _package /*? Static Methods Uize.Curve.Rubber.easeInElastic Elastic easing in - exponentially growing sine wave. SYNTAX ................................................................ ......... curveFUNC = Uize.Curve.Rubber.easeInElastic (periodFLOAT,amplitu deFLOAT); ................................................................ ......... Parameters periodFLOAT A floating point number between =0= to =25=, representing th e width of a single elastic stretch-past and spring-back cycle as a fraction of the total curve width. A value of =.1=, for example, will produce a curve with =10= stretch-past and spring-back cycles, whereas a value of =.2= will produce five such cycles. Ever higher values above =1= make the curve progressively more like an exponential curve. The default value for this parameter is =.3=. amplitudeFLOAT A floating point number in the range of =1= to =Infinity=. Values greater than =1= produce more springy elastic curves with more pronounced peaks and greater overshoot. The default value for this par ameter is =1=. Variations VARIATION 1 .......................................................... curveFUNC = Uize.Curve.Rubber.easeInElastic (periodFLOAT); .......................................................... When the optional =amplitudeFLOAT= parameter is not specified, its value will be defaulted to =1=.

VARIATION 2 ............................................... curveFUNC = Uize.Curve.Rubber.easeInElastic (); ............................................... When the optional =periodFLOAT= parameter is not specified, it s value will be defaulted to =.3=. NOTES - see also the companion =Uize.Curve.Rubber.easeOutElastic=, =Ui ze.Curve.Rubber.easeInOutElastic=, and =Uize.Curve.Rubber.easeMiddleElastic= sta tic methods - thanks to `Robert Penner` for his original implementation Uize.Curve.Rubber.easeOutElastic Elastic easing out - exponentially decaying sine wave. SYNTAX ................................................................ .......... curveFUNC = Uize.Curve.Rubber.easeOutElastic (periodFLOAT,amplit udeFLOAT); ................................................................ .......... VARIATIONS ........................................................... curveFUNC = Uize.Curve.Rubber.easeOutElastic (periodFLOAT); curveFUNC = Uize.Curve.Rubber.easeOutElastic (); ........................................................... For a more in-depth discussion of this method's parameters and v ariations, consult the reference for the related =Uize.Curve.Rubber.easeInElasti c= static method. NOTES - see also the companion =Uize.Curve.Rubber.easeInElastic=, =Uiz e.Curve.Rubber.easeInOutElastic=, and =Uize.Curve.Rubber.easeMiddleElastic= stat ic methods - thanks to `Robert Penner` for his original implementation Uize.Curve.Rubber.easeInOutElastic Elastic easing in/out - exponentially building then decaying sin e wave. SYNTAX ................................................................ ............ curveFUNC = Uize.Curve.Rubber.easeInOutElastic (periodFLOAT,ampl itudeFLOAT); ................................................................ ............ VARIATIONS ............................................................. curveFUNC = Uize.Curve.Rubber.easeInOutElastic (periodFLOAT); curveFUNC = Uize.Curve.Rubber.easeInOutElastic (); .............................................................

For a more in-depth discussion of this method's parameters and v ariations, consult the reference for the related =Uize.Curve.Rubber.easeInElasti c= static method. NOTES - see also the companion =Uize.Curve.Rubber.easeInElastic=, =Uiz e.Curve.Rubber.easeOutElastic=, and =Uize.Curve.Rubber.easeMiddleElastic= static methods - thanks to `Robert Penner` for his original implementation Uize.Curve.Rubber.easeMiddleElastic Elastic easing in the middle - exponentially decaying then build ing sine wave. SYNTAX ................................................................ ............. curveFUNC = Uize.Curve.Rubber.easeMiddleElastic (periodFLOAT,amp litudeFLOAT); ................................................................ ............. VARIATIONS .............................................................. curveFUNC = Uize.Curve.Rubber.easeMiddleElastic (periodFLOAT); curveFUNC = Uize.Curve.Rubber.easeMiddleElastic (); .............................................................. For a more in-depth discussion of this method's parameters and v ariations, consult the reference for the related =Uize.Curve.Rubber.easeInElasti c= static method. NOTES - see also the companion =Uize.Curve.Rubber.easeInElastic=, =Uiz e.Curve.Rubber.easeOutElastic=, and =Uize.Curve.Rubber.easeInOutElastic= static methods - thanks to `Robert Penner` for his original implementation */ ); /*** overshoot easing ***/ _makeEasingCurveGenerators ( 'back', function (_overshoot) { /*** paramter defaulting ***/ if (_overshoot == null) _overshoot = 1.70158; /*** capture some calculation results ***/ var _overshootPlus1 = _overshoot + 1; return function (_value) {return _value * _value * (_overshootPlus1 * _value - _overshoot)}; }, _package /*? Static Methods Uize.Curve.Rubber.easeInBack Back easing in - backtracking slightly, then reversing direction and moving to target.

SYNTAX .......................................................... curveFUNC = Uize.Curve.Rubber.easeInBack (overshootFLOAT); .......................................................... The =overshootFLOAT= parameter controls the amount of overshoot, and is typically a value in the range of =0= to =Infinity= (although negative v alues are also supported). Higher positive values for this parameter will produc e greater overshoot. The default value of =1.70158= produces 10% overshoot. A va lue of =0= produces a cubic easing curve with no overshoot. Negative values lowe r than =-3= for this parameter will produce increasing amounts of overshoot on t he opposite side of output value range. VARIATION ............................................ curveFUNC = Uize.Curve.Rubber.easeInBack (); ............................................ When the optional =overshootFLOAT= parameter is not specified, i ts value will be defaulted to =1.70158=. NOTES - see also the companion =Uize.Curve.Rubber.easeOutBack=, =Uize. Curve.Rubber.easeInOutBack=, and =Uize.Curve.Rubber.easeMiddleBack= static metho ds - thanks to `Robert Penner` for his original implementation Uize.Curve.Rubber.easeOutBack Back easing out - moving towards target, overshooting it slightl y, then reversing and coming back to target. SYNTAX ........................................................... curveFUNC = Uize.Curve.Rubber.easeOutBack (overshootFLOAT); ........................................................... For an in-depth discussion of the =overshootFLOAT= parameter, co nsult the reference for the related =Uize.Curve.Rubber.easeInBack= static method . VARIATION ............................................. curveFUNC = Uize.Curve.Rubber.easeOutBack (); ............................................. When the optional =overshootFLOAT= parameter is not specified, i ts value will be defaulted to =1.70158=. NOTES - see also the companion =Uize.Curve.Rubber.easeInBack=, =Uize.C urve.Rubber.easeInOutBack=, and =Uize.Curve.Rubber.easeMiddleBack= static method s - thanks to `Robert Penner` for his original implementation Uize.Curve.Rubber.easeInOutBack Back easing in/out - backtracking slightly, then reversing direc tion and moving to target, then overshooting target, reversing, and finally comi ng back to target. SYNTAX

............................................................. curveFUNC = Uize.Curve.Rubber.easeInOutBack (overshootFLOAT); ............................................................. For an in-depth discussion of the =overshootFLOAT= parameter, co nsult the reference for the related =Uize.Curve.Rubber.easeInBack= static method . VARIATION ............................................... curveFUNC = Uize.Curve.Rubber.easeInOutBack (); ............................................... When the optional =overshootFLOAT= parameter is not specified, i ts value will be defaulted to =1.70158=. NOTES - see also the companion =Uize.Curve.Rubber.easeInBack=, =Uize.C urve.Rubber.easeOutBack=, and =Uize.Curve.Rubber.easeMiddleBack= static methods - thanks to `Robert Penner` for his original implementation Uize.Curve.Rubber.easeMiddleBack Back easing in the middle - overshooting the middle, backtrackin g to the middle, then backtracking even further towards the beginning, then fina lly moving to target. SYNTAX .............................................................. curveFUNC = Uize.Curve.Rubber.easeMiddleBack (overshootFLOAT); .............................................................. For an in-depth discussion of the =overshootFLOAT= parameter, co nsult the reference for the related =Uize.Curve.Rubber.easeInBack= static method . VARIATION ................................................ curveFUNC = Uize.Curve.Rubber.easeMiddleBack (); ................................................ When the optional =overshootFLOAT= parameter is not specified, i ts value will be defaulted to =1.70158=. NOTES - see also the companion =Uize.Curve.Rubber.easeInBack=, =Uize.C urve.Rubber.easeOutBack=, and =Uize.Curve.Rubber.easeInOutBack= static methods - thanks to `Robert Penner` for his original implementation */ ); /*** bounce easing ***/ var _defaultBouncePeakCurveFunction = _host.easeInSweetPow (1.76); _makeEasingCurveGenerators ( 'bounce', function (_bounces,_bouncePeakCurveFunction,_bounceWidthRatio,_bounceC urveFunction) { /*** parameter defaulting ***/ if (!_bounces) _bounces = 4; _bouncePeakCurveFunction = _resolve (_bouncePeakCurveFunction,_defaultBouncePeakCurveFuncti

on,true) ; _bounceWidthRatio = !_bounceWidthRatio ? 2 // 0, null, or undefined, so default to 2 : _bounceWidthRatio * _bounceWidthRatio == 1 ? 1.0001 // 1 or -1, so make sure it's not 1, since 1 breaks f ormula : _bounceWidthRatio < 0 ? -1 / _bounceWidthRatio // negative, so negate and invert : _bounceWidthRatio ; _bounceCurveFunction = _resolve (_bounceCurveFunction,2); /*** pre-calculate profiles for bounces ***/ function _cumulativeWidth (_bounces) {return (Math.pow (_base,_bou nces) - 1) / (_base - 1)} var _base = _bounceWidthRatio, _baseMinus1 = _base - 1, _bouncesMinus1 = _bounces - 1, _bouncesWidthShown = _cumulativeWidth (_bounces) /* combined width of all bounces * / Math.pow (_base,_bouncesMinus1) /* width of widest bounce */ / 2, _logBase = Math.log (_base), _bounceProfiles = [] ; for (var _bounceNo = -1; ++_bounceNo < _bounces;) { var _bounceStartPos = _cumulativeWidth (_bounceNo), _widthDiv2 = (_cumulativeWidth (_bounceNo + 1) /* bounce end p os */ - _bounceStartPos) / 2, _bounceMidPos = _bounceStartPos + _widthDiv2 ; _bounceProfiles.push ({ _height:_bouncePeakCurveFunction (_bounceMidPos / _bouncesWidt hShown), _midPos:_bounceMidPos, _widthDiv2:_widthDiv2 }); } return function (_value) { var _pos = _value * _bouncesWidthShown, _bounceProfile = _bounceProfiles [ Uize.constrain (Math.floor (Math.log (_pos * _baseMinus1 + 1) / _logBase),0,_bouncesMinus1) ] ; return _bounceProfile._height * ( _bounceCurveFunction (1 - Math.abs (_pos - _bounceProfile._midPo s) / _bounceProfile._widthDiv2) ); } }, _package /*? Static Methods

Uize.Curve.Rubber.easeInBounce Bounce, easing in. SYNTAX ................................................................ ....................... curveFUNC = Uize.Curve.Rubber.easeInBounce ( bouncesINT, // number of bounces (optional) bouncePeakCurveFUNCorFLOAT, // bounciness, essentially (optio nal) bounceWidthRatioFLOAT, // ratio of current bounce width to previous (optional) bounceCurveFUNCorFLOAT // the shape of the curve of a bo unce (optional) ); ................................................................ ....................... Parameters bouncesINT An integer, specifying the number of bounces in the curve, w ith the default number of bounces being =4=. bouncePeakCurveFUNCorFLOAT A function reference for a curve function, or a numerical va lue that will be resolved to a power curve function using the =Uize.Curve.resolv e= method. This paramter can be used to affect the bounciness or spring iness of each bounce. Numerical values above =1= will produce progressively boun cier curves as the value of =bouncePeakCurveFUNCorFLOAT= is increased. Numerical values below =-1= will produce progressively more dampened curves as the value of =bouncePeakCurveFUNCorFLOAT= is decreased. When determining the height of the peak of an individual bou nce, a curve function specified for the =bouncePeakCurveFUNCorFLOAT= parameter w ill be used to obtain a value, using the position of the midpoint of the bounce along the x-axis as the input value to the bounce peak curve function. Because t he specified bounce peak curve is only sampled at the bounce midpoints, bounce p eak curves with high amounts of detail will not affect the shape of the bounces, but only the heights of the bounce peaks (so detail will be lost, in other word s). For a linear curve, the value =1= can be specified for this parameter. The default value for this parameter is =1.76=. bounceWidthRatioFLOAT A floating point number, specifying the ratio between the wi dth of the current bounce and the width of the previous bounce. The default value for this parameter is =2=, which means tha t each bounce will be twice as wide as the previous bounce. When the value =1= i s specified for this parameter, all bounces will have the same width. When negat ive values are specified for this parameter, then ratio will be resolved to a po sitive number by negating it and inverting it (dividing it into =1=). In other w ords, the value =-2= will result in a resolved ratio of =.5=, which will result in each bounce being half the width of the previous bounce. You can think of the values in the negative scale as being the ratio of the width of the current bou nce to the width of the next bounce (once negated, of course).

For values of this parameter greater than =1=, the higher th e value, the less noticeable changing the number of bounces with the =bouncesINT = parameter will become. Similarly, on the opposite side of the spectrum, for va lues of =bounceWidthRatioFLOAT= less than =-1=, the lower the value, the less no ticeable changing the number of bounces will become. If each bounce is much smal ler or larger than the previous bounce, the bounces at one end of the curve will become very small and barely noticeable. NOTE It should be noted that for the ease-out version of this cur ve, and for the the ease-out phase of the ease-in-out and ease-in-the-middle ver sions of this curve, the bounce width ratio is actually the ratio of the width o f the current bounce to the width of the next bounce. This is as a result of the curve being rotated 180 degrees. bounceCurveFUNCorFLOAT A function reference for a curve function, or a numerical va lue that will be resolved to a power curve function using the =Uize.Curve.resolv e= method. The curve specified by the =bounceCurveFUNCorFLOAT= paramete r will be used to generate points along the curve of an individual bounce. The s pecified curve is used to produce both the left and right halves of a bounce cur ve, on either side of the bounce's midpoint on the x-axis. For the opposite half , the bounce curve is flipped horizontally. The default value for this parameter is =2=, which produces bounces using a quadratic ease-out power curve. VARIATION 1 .............................................................. curveFUNC = Uize.Curve.Rubber.easeInBounce ( bouncesINT,bouncePeakCurveFUNCorFLOAT,bounceWidthRatioFLOAT ); .............................................................. When no =bounceCurveFUNCorFLOAT= parameter is specified, its val ue will be defaulted to =2=, representing a quadratic ease-out curve function. VARIATION 2 ................................................................ ................... curveFUNC = Uize.Curve.Rubber.easeInBounce (bouncesINT,bouncePea kCurveFUNCorFLOAT); ................................................................ ................... When no =bounceWidthRatioFLOAT= parameter is specified, its valu e will be defaulted to =2= (each bounce will be twice the width of the previous bounce). VARIATION 3 ........................................................ curveFUNC = Uize.Curve.Rubber.easeInBounce (bouncesINT); ........................................................ When no =bouncePeakCurveFUNCorFLOAT= parameter is specified, its value will be defaulted to =1.76=. VARIATION 4 ..............................................

curveFUNC = Uize.Curve.Rubber.easeInBounce (); .............................................. When no =bouncesINT= parameter is specified, its value will be d efaulted to =4=. NOTES - see also the companion =Uize.Curve.Rubber.easeOutBounce=, =Uiz e.Curve.Rubber.easeInOutBounce=, and =Uize.Curve.Rubber.easeMiddleBounce= static methods Uize.Curve.Rubber.easeOutBounce Bounce, easing out. SYNTAX ................................................................ ....................... curveFUNC = Uize.Curve.Rubber.easeOutBounce ( bouncesINT, // number of bounces (optional) bouncePeakCurveFUNCorFLOAT, // bounciness, essentially (optio nal) bounceWidthRatioFLOAT, // ratio of current bounce width to next (optional) bounceCurveFUNCorFLOAT // the shape of the curve of a bo unce (optional) ); ................................................................ ....................... VARIATIONS ................................................................ .................... curveFUNC = Uize.Curve.Rubber.easeOutBounce ( bouncesINT,bouncePeakCurveFUNCorFLOAT,bounceWidthRatioFLOAT ); curveFUNC = Uize.Curve.Rubber.easeOutBounce (bouncesINT,bouncePe akCurveFUNCorFLOAT); curveFUNC = Uize.Curve.Rubber.easeOutBounce (bouncesINT); curveFUNC = Uize.Curve.Rubber.easeOutBounce (); ................................................................ .................... For a more in-depth discussion of this method's parameters and v ariations, consult the reference for the related =Uize.Curve.Rubber.easeInBounce = static method. NOTES - see also the companion =Uize.Curve.Rubber.easeInBounce=, =Uize .Curve.Rubber.easeInOutBounce=, and =Uize.Curve.Rubber.easeMiddleBounce= static methods Uize.Curve.Rubber.easeInOutBounce Bounce, easing in/out. SYNTAX ................................................................ .......................

curveFUNC = Uize.Curve.Rubber.easeInOutBounce ( bouncesINT, // number of bounces (optional) bouncePeakCurveFUNCorFLOAT, // bounciness, essentially (optio nal) bounceWidthRatioFLOAT, // ratio of current bounce width to previous (optional) bounceCurveFUNCorFLOAT // the shape of the curve of a bo unce (optional) ); ................................................................ ....................... VARIATIONS ................................................................ ...................... curveFUNC = Uize.Curve.Rubber.easeInOutBounce ( bouncesINT,bouncePeakCurveFUNCorFLOAT,bounceWidthRatioFLOAT ); curveFUNC = Uize.Curve.Rubber.easeInOutBounce (bouncesINT,bounce PeakCurveFUNCorFLOAT); curveFUNC = Uize.Curve.Rubber.easeInOutBounce (bouncesINT); curveFUNC = Uize.Curve.Rubber.easeInOutBounce (); ................................................................ ...................... For a more in-depth discussion of this method's parameters and v ariations, consult the reference for the related =Uize.Curve.Rubber.easeInBounce = static method. NOTES - see also the companion =Uize.Curve.Rubber.easeInBounce=, =Uize .Curve.Rubber.easeOutBounce=, and =Uize.Curve.Rubber.easeMiddleBounce= static me thods Uize.Curve.Rubber.easeMiddleBounce Bounce, easing in the middle. SYNTAX ................................................................ ....................... curveFUNC = Uize.Curve.Rubber.easeMiddleBounce ( bouncesINT, // number of bounces (optional) bouncePeakCurveFUNCorFLOAT, // bounciness, essentially (optio nal) bounceWidthRatioFLOAT, // ratio of current bounce width to previous (optional) bounceCurveFUNCorFLOAT // the shape of the curve of a bo unce (optional) ); ................................................................ ....................... VARIATIONS ................................................................ ....................... curveFUNC = Uize.Curve.Rubber.easeMiddleBounce ( bouncesINT,bouncePeakCurveFUNCorFLOAT,bounceWidthRatioFLOAT

); curveFUNC = Uize.Curve.Rubber.easeMiddleBounce (bouncesINT,bounc ePeakCurveFUNCorFLOAT); curveFUNC = Uize.Curve.Rubber.easeMiddleBounce (bouncesINT); curveFUNC = Uize.Curve.Rubber.easeMiddleBounce (); ................................................................ ....................... For a more in-depth discussion of this method's parameters and v ariations, consult the reference for the related =Uize.Curve.Rubber.easeInBounce = static method. NOTES - see also the companion =Uize.Curve.Rubber.easeInBounce=, =Uize .Curve.Rubber.easeOutBounce=, and =Uize.Curve.Rubber.easeInOutBounce= static met hods */ ); return _package; } });