Docs/Fx/Fx.md

   1 Class: Fx {#Fx}
   2 ===============
   3
   4 This Class will rarely be used on its own, but provides the foundation for all custom Fx Classes.
   5 All of the other Fx Classes inherit from this one.
   6
   7 ### Implements:
   8
   9 - [Chain][], [Class.Thenable][], [Events][], [Options][]
  10
  11
  12
  13 Fx Method: constructor {#Fx:constructor}
  14 ----------------------------------------
  15
  16 ### Syntax:
  17
  18         var myFx = new Fx([options]);
  19
  20 ### Arguments:
  21
  22 1. options - (*object*, optional) An object with options for the effect. See below.
  23
  24 ### Options:
  25
  26 * fps        - (*number*: defaults to 50) The frames per second for the transition.
  27 * frames     - (*number*) The numbers of frames in the animation, defaults to the duration and fps calculations.
  28 * frameSkip  - (*boolean*: defaults to true) If sets to true, it evaluates the current frame based on the current time.
  29 * unit       - (*string*: defaults to false) The unit, e.g. 'px', 'em', or '%'. See [Element:setStyle][].
  30 * link       - (*string*: defaults to ignore) Can be 'ignore', 'cancel' and 'chain'.
  31         * 'ignore' - Any calls made to start while the effect is running will be ignored. (Synonymous with 'wait': true from 1.x)
  32         * 'cancel' - Any calls made to start while the effect is running will take precedence over the currently running transition. The new transition will start immediately, canceling the one that is currently running. (Synonymous with 'wait': false from 1.x)
  33         * 'chain'  - Any calls made to start while the effect is running will be chained up, and will take place as soon as the current effect has finished, one after another. [Take care][resetThenable-note] when using "chain" in combination with Fx's thenable properties.
  34 * duration   - (*number*: defaults to 500) The duration of the effect in ms. Can also be one of:
  35         * 'short'  - 250ms
  36         * 'normal' - 500ms
  37         * 'long'   - 1000ms
  38 * transition - (*function*: defaults to ['sine:in:out'][Fx.Transitions:sine] The equation to use for the effect see [Fx.Transitions][]. Also accepts a string in the following form:
  39
  40   transition\[:in\]\[:out\] - for example, 'linear', 'quad:in', 'back:in', 'bounce:out', 'elastic:out', 'sine:in:out'
  41
  42 ### Thenable:
  43
  44 Fx implements `Class.Thenable` to make an Fx instance "thenable", i.e. `myFx.start().then(function(){ console.log('Done.'); });`. See [Class.Thenable][] for more information.
  45
  46 ### Events:
  47
  48 * start                 - (*function*) The function to execute when the effect begins.
  49 * cancel                - (*function*) The function to execute when you manually stop the effect.
  50 * complete              - (*function*) The function to execute after the effect has processed.
  51 * chainComplete - (*function*) The function to execute when using link 'chain' ([see options](#Fx:constructor)). It gets called after all effects in the chain have completed.
  52
  53 ### Notes:
  54
  55 - You cannot change the transition if you haven't included Fx.Transitions.js, (unless you plan on developing your own curve). ;)
  56 - The Fx Class is just a skeleton for other Classes to extend the basic functionality.
  57
  58 ### See Also:
  59
  60 - [Fx.Tween][], [Fx.Morph][].
  61
  62
  63
  64 Fx Method: start {#Fx:start}
  65 ----------------------------
  66
  67 The start method is used to begin a transition.  Fires the 'start' event.
  68
  69 ### Syntax:
  70
  71         myFx.start(from[, to]);
  72
  73 ### Arguments:
  74
  75 1. from - (*mixed*) The starting value for the effect. If only one argument is provided, this value will be used as the target value.
  76 2. to   - (*mixed*, optional) The target value for the effect.
  77
  78 ### Returns:
  79
  80 * (*object*) - This Fx instance.
  81
  82 ### Examples:
  83
  84 - See examples in the documentation for each Fx subclass.
  85
  86 ### Notes:
  87
  88 - If only one parameter is provided, the first argument to start will be used as the target value, and the initial value will be calculated from the current state of the element.
  89 - The format and type of this value will be dependent upon implementation, and may vary greatly on a case by case basis.  Check each implementation for more details.
  90
  91
  92
  93 Fx Method: set {#Fx:set}
  94 ------------------------
  95
  96 The set method is fired on every step of a transition.  It can also be called manually to set a specific value to be immediately applied to the effect.
  97
  98 ### Syntax:
  99
 100         myFx.set(value);
 101
 102 ### Arguments:
 103
 104 1. value - (*mixed*) The value to immediately apply to the transition.
 105
 106 ### Returns:
 107
 108 * (*object*) - This Fx instance.
 109
 110 ### Examples:
 111
 112 - See examples in the documentation for each Fx subclass.
 113
 114
 115
 116 Fx Method: cancel {#Fx:cancel}
 117 ------------------------------
 118
 119 The cancel method is used to cancel a running transition.  Fires the 'cancel' event.
 120
 121 ### Syntax:
 122
 123         myFx.cancel();
 124
 125 ### Returns:
 126
 127 * (*object*) - This Fx instance.
 128
 129
 130
 131 Fx Method: pause {#Fx:pause}
 132 ----------------------------
 133
 134 Temporarily pause a currently running effect.
 135
 136 ### Syntax:
 137
 138         myFx.pause();
 139
 140 ### Returns:
 141
 142 * (*object*) - This Fx instance.
 143
 144 ### Notes:
 145
 146 - The timer will be stopped to allow the effect to continue where it left off by calling [Fx:resume](#Fx:resume).
 147 - If you call start on a paused effect, the timer will simply be cleared allowing the new transition to start.
 148
 149
 150
 151 Fx Method: resume {#Fx:resume}
 152 ------------------------------
 153
 154 Resume a previously paused effect.
 155
 156 ### Syntax:
 157
 158         myFx.resume();
 159
 160 ### Returns:
 161
 162 * (*object*) - This Fx instance.
 163
 164 ### Notes:
 165
 166 - The effect will only be resumed if it has been previously paused.  Otherwise, the call to resume will be ignored.
 167
 168
 169
 170 Fx Method: isRunning {#Fx:isRunning}
 171 ------------------------------------
 172
 173 Returns true if the animation is running.
 174
 175 ### Syntax:
 176
 177         var isRunning = myFx.isRunning();
 178
 179 ### Returns:
 180
 181 * (*boolean*) - If the animation is running, returns true. Otherwise, returns false.
 182
 183 ### Notes:
 184
 185 - Returns false if the animation is paused.
 186
 187
 188
 189 Fx Method: isPaused {#Fx:isPaused}
 190 ------------------------------------
 191
 192 Returns true if the animation is paused. You can use this to check if you need to call [Fx:resume](#Fx:resume) to resume an animation instead of restarting it.
 193
 194 ### Syntax:
 195
 196         var isPaused = myFx.isPaused();
 197
 198 ### Returns:
 199
 200 * (*boolean*) - If the animation is paused, returns true. Otherwise, returns false.
 201
 202
 203
 204 [Fx]: #Fx
 205 [Fx.Transitions]: /core/Fx/Fx.Transitions
 206 [Fx.Transitions:sine]: /core/Fx/Fx.Transitions#Fx-Transitions:sine
 207 [Element:setStyle]: /core/Element/Element.Style#Element:setStyle
 208 [Chain]: /core/Class/Class.Extras#Chain
 209 [Class.Thenable]: /core/Class/Class.Thenable
 210 [Events]: /core/Class/Class.Extras#Events
 211 [Options]: /core/Class/Class.Extras#Options
 212 [Fx.Tween]: /core/Fx/Fx.Tween
 213 [Fx.Morph]: /core/Fx/Fx.Morph
 214 [resetThenable-note]: /core/Class/Class.Thenable#Class.Thenable:resetThenable-note