Docs/Fx/Fx.Tween.md

   1 Class: Fx.Tween {#Fx-Tween}
   2 ===========================
   3
   4 Contains [Fx.Tween][] and the Element shortcut [Element.tween][].
   5
   6 ### Extends:
   7
   8 [Fx][]
   9
  10
  11
  12 Fx.Tween Method: constructor {#Fx-Tween:constructor}
  13 ----------------------------------------------------
  14
  15 The Tween effect, used to transition any CSS property from one value to another.
  16
  17 ### Syntax:
  18
  19         var myFx = new Fx.Tween(element, [, options]);
  20
  21 ### Arguments:
  22
  23 1. element  - (*mixed*) An Element or the string id of an Element to apply the transition to.
  24 2. options  - (*object*, optional) The [Fx][] options object, plus the options described below:
  25
  26 ### Options:
  27
  28 * property - (*string*) The CSS property to transition to, for example 'width', 'color', 'font-size', 'border', etc. If this option is omitted, you are required to use the property as a first argument for the start and set methods. Defaults to null.
  29
  30
  31 ### Notes:
  32
  33 - Any CSS property that can be set with Element:setStyle can be transitioned with Fx.Tween.
  34 - If a property is not mathematically calculable, like border-style or background-image, it will be set immediately upon start of the transition.
  35 - If you use the property option, you must not use the property argument in the start and set methods.
  36
  37 ### See Also:
  38
  39 - [Fx][]
  40
  41 ### Examples:
  42
  43 Tweens the height of a element while clicking a link (which stops the default behavior), using a transition and a long duration.
  44 It uses the `link` option so when clicking the link twice it behaves smoothly. When the start value is omitted, the current
  45 value of the property (in this example the height property) will be used.
  46
  47         var myFx = new Fx.Tween('myElement', {
  48                 duration: 'long',
  49                 transition: 'bounce:out',
  50                 link: 'cancel',
  51                 property: 'height'
  52         });
  53
  54         document.id('myLink').addEvent('click', function(event){
  55                 event.stop();
  56                 myFx.start(40, 100);
  57         });
  58
  59 It is also possible to use the Element properties: `.get('tween')` and `.set('tween')` and the `tween` method.
  60 In this example the property method is not set as an option, now it should be set as argument of the `tween` method.
  61 This is something you can choose for both the `Fx.Tween` constructor or this approach.
  62
  63         var myElement = document.id('myElement');
  64         myElement.set('tween', {
  65                 duration: 'long',
  66                 transition: 'bounce:out',
  67                 link: 'cancel'
  68         });
  69
  70         document.id('myLink').addEvent('click', function(event){
  71                 event.stop();
  72                 myElement.tween('height', 40, 100);
  73         });
  74
  75
  76
  77 Fx.Tween Method: set {#Fx-Tween:set}
  78 ------------------------------------
  79
  80 Sets the Element's CSS property to the specified value immediately.
  81
  82 ### Syntax:
  83
  84         myFx.set(property, value);
  85
  86 ### Arguments:
  87
  88 1. property - (*string*) The css property to set the value to. Omit this if you use the property option.
  89 2. value - (*mixed*) The value to set the CSS property of this instance to.
  90
  91 ### Returns:
  92
  93 * (*object*) This Fx.Tween instance.
  94
  95 ### Examples:
  96
  97         var myFx = new Fx.Tween(element);
  98         // sets the background color of the element to red:
  99         myFx.set('background-color', '#f00');
 100
 101 ### Note:
 102
 103 If you use the property option, you must not use the property argument in the start and set methods.
 104
 105
 106 Fx.Tween Method: start {#Fx-Tween:start}
 107 ----------------------------------------
 108
 109 Transitions the Element's CSS property to the specified value.
 110
 111 ### Syntax:
 112
 113         myFx.start([property,] [from,] to);
 114
 115 ### Arguments:
 116
 117 1. property - (*string*, if not in options) The css property to tween. Omit this if you use the property option.
 118 2. from     - (*mixed*, optional) The starting CSS property value for the effect.
 119 3. to       - (*mixed*) The target CSS property value for the effect.
 120
 121 ### Returns:
 122
 123 * (*object*) This Fx.Tween instance.
 124
 125 ### Examples:
 126
 127         var myFx = new Fx.Tween(element);
 128         // transitions the background color of the Element from black to red:
 129         myFx.start('background-color', '#000', '#f00');
 130         // transitions the background color of the Element from its current color to blue:
 131         myFx.start('background-color', '#00f');
 132
 133 ### Notes:
 134
 135 - If only one argument is provided, other than the property argument, 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.
 136 - When using colors, either RGB or Hex values may be used.
 137 - If you use the property option, you must not use the property argument in the start and set methods.
 138
 139
 140
 141 Object: Element.Properties {#Element-Properties}
 142 ==============================================
 143
 144 see [Element.Properties][]
 145
 146 Element Property: tween {#Element-Properties:tween}
 147 ---------------------------------------------------
 148
 149 Sets and gets default options for the Fx.Tween instance of an Element.
 150
 151 ### Setter:
 152
 153 #### Syntax:
 154
 155         el.set('tween'[, options]);
 156
 157 #### Arguments:
 158
 159 * options - (*object*) the Fx.Tween options.
 160
 161 #### Returns:
 162
 163 * (*element*) This Element.
 164
 165 #### Examples:
 166
 167         el.set('tween', {duration: 'long'});
 168         el.tween('color', '#f00');
 169
 170 ### Getter:
 171
 172 #### Syntax:
 173
 174         el.get('tween');
 175
 176 #### Arguments:
 177
 178 1. property - (*string*) the Fx.Tween property argument.
 179
 180 #### Returns:
 181
 182 * (*object*) The Element's internal Fx.Tween instance.
 183
 184 #### Examples:
 185
 186         el.get('tween').start(0);
 187
 188 ### Notes:
 189
 190 - When initializing the Element's tween instance with Element:set, the property to tween SHOULD NOT be passed.
 191 - The property must be specified when using Element:get to retrieve the actual Fx.Tween instance, and in calls to Element:tween.
 192 - When options are passed to the setter, the instance will be reset.
 193 - As with the other Element shortcuts, the difference between a setter and a getter is that the getter returns the instance, while the setter returns the element (for chaining and initialization).
 194
 195
 196
 197 Type: Element {#Element}
 198 ========================
 199
 200 Custom Type to allow all of its methods to be used with any DOM element via the dollar function [$][].
 201
 202
 203
 204 Element Method: tween {#Element:tween}
 205 --------------------------------------
 206
 207 Element shortcut method which immediately transitions any single CSS property of an Element from one value to another.
 208
 209 ### Syntax:
 210
 211         myElement.tween(property, startValue[, endValue]);
 212
 213 ### Arguments:
 214
 215 1. property   - (*string*) the css property you want to animate. Omit this if you previously set the property option.
 216 2. startValue - (*mixed*) The start value for the transition.
 217 2. endValue   - (*mixed*) The end value for the transition. If this is omitted, startValue will be used as endValue.
 218
 219 ### Returns:
 220
 221 * (*element*) This Element.
 222
 223 ### Examples:
 224
 225         // transitions the width of 'myElement' from its current width to 100px:
 226         $('myElement').tween('width', '100');
 227         // transitions the height of 'myElement' from 20px to 200px:
 228         $('myElement').tween('height', [20, 200]);
 229         // transitions the border of 'myElement' from its current to '6px solid blue':
 230         $('myElement').tween('border', '6px solid #36f');
 231
 232 ### See Also:
 233
 234 - [Fx.Tween][]
 235
 236
 237
 238 Element Method: fade {#Element:fade}
 239 ------------------------------------
 240
 241 Element shortcut method for tween with opacity.  Useful for fading an Element in and out or to a certain opacity level.
 242
 243 ### Syntax:
 244
 245         myElement.fade([how]);
 246
 247 ### Arguments:
 248
 249 1. how - (*mixed*, optional: defaults to 'toggle') The opacity level as a number or string representation.  Possible values include:
 250  * 'in'     - Fade the element to 100% opacity.
 251  * 'out'    - Fade the element to 0% opacity.
 252  * 'show'   - Immediately set the element's opacity to 100%.
 253  * 'hide'   - Immediately set the element's opacity to 0%.
 254  * 'toggle' - If visible, fade the element out, otherwise, fade it in.
 255  * (*number*)  - A float value between 0 and 1. Will fade the element to this opacity.
 256
 257 ### Returns:
 258
 259 * This Element.
 260
 261 ### Examples:
 262
 263         $('myElement').fade('out'); // fades 'myElement' out.
 264         $('myElement').fade(0.7); // fades 'myElement' to 70% opacity.
 265
 266
 267
 268 Element Method: highlight {#Element:highlight}
 269 ----------------------------------------------
 270
 271 Element shortcut method for tweening the background color.  Immediately transitions an Element's background color to a specified highlight color then back to its set background color.
 272
 273 ### Syntax:
 274
 275         myElement.highlight([start, end]);
 276
 277 ### Arguments:
 278
 279 1. start - (*string*, optional: defaults to '#ff8') The color from which to start the transition.
 280 2. end - (*string*, optional: defaults to Element's set background-color) The background color to return to after the highlight effect.
 281
 282 ### Note:
 283
 284 If no background color is set on the Element, or its background color is set to 'transparent', the default end value will be white.
 285
 286 ### Returns:
 287
 288 * (*element*) This Element.
 289
 290 ### Examples:
 291
 292     //immediately changes the background to light blue, then back to its original color (or white):
 293         $('myElement').highlight('#ddf');
 294
 295         //immediately changes the background to light blue, then fades to grey:
 296         $('myElement').highlight('#ddf', '#ccc');
 297
 298
 299 [$]: /core/Element/Element#Window:dollar
 300 [Fx]: /core/Fx/Fx
 301 [Fx.Tween]: #Fx-Tween
 302 [Element.tween]: #Element-Properties:tween
 303 [Element.Properties]: /core/Element/Element/#Element-Properties