Docs/Fx/Fx.Morph.md

   1 Class: Fx.Morph {#Fx-Morph}
   2 ===========================
   3
   4 Allows for the animation of multiple CSS properties at once, even by a simple CSS selector. Inherits methods, properties, options and events from [Fx][].
   5
   6 ### Extends:
   7
   8 - [Fx][]
   9
  10 ### Syntax:
  11
  12         var myFx = new Fx.Morph(element[, options]);
  13
  14 ### Arguments:
  15
  16 1. element - (*mixed*) A string ID of the Element or an Element to apply the style transitions to.
  17 2. options - (*object*, optional) The [Fx][] options object.
  18
  19 ### Returns:
  20
  21 * (*object*) A new Fx.Morph instance.
  22
  23 ### Examples:
  24
  25 Multiple styles with start and end values using an object:
  26
  27         var myEffect = new Fx.Morph('myElement', {
  28                 duration: 'long',
  29                 transition: Fx.Transitions.Sine.easeOut
  30         });
  31
  32         myEffect.start({
  33                 'height': [10, 100], // Morphs the 'height' style from 10px to 100px.
  34                 'width': [900, 300]  // Morphs the 'width' style from 900px to 300px.
  35         });
  36
  37
  38 Multiple styles with the start value omitted will default to the current Element's value:
  39
  40         var myEffect = new Fx.Morph('myElement', {
  41                 duration: 'short',
  42                 transition: Fx.Transitions.Sine.easeOut
  43         });
  44
  45         myEffect.start({
  46                 'height': 100, // Morphs the height from the current to 100px.
  47                 'width': 300   // Morphs the width from the current to 300px.
  48         });
  49
  50
  51 Morphing one Element to match the CSS values within a CSS class. This is useful when
  52 separating the logic and styles:
  53
  54         var myEffect = new Fx.Morph('myElement', {
  55                 duration: 1000,
  56                 transition: Fx.Transitions.Sine.easeOut
  57         });
  58
  59         // the styles of myClassName will be applied to the target Element.
  60         myEffect.start('.myClassName');
  61
  62 ### Notes:
  63
  64 - This feature only works for simple selectors like a single class or id due to limited browser support for complex selectors.
  65
  66 ### See Also:
  67
  68 - [Fx][]
  69
  70
  71
  72 Fx.Morph Method: set {#Fx-Morph:set}
  73 ------------------------------------
  74
  75 Sets the Element's CSS properties to the specified values immediately.
  76
  77 ### Syntax:
  78
  79         myFx.set(to);
  80
  81 ### Arguments:
  82
  83 1. properties - (*mixed*) Either an *object* of key/value pairs of CSS attributes to change or a *string* representing a CSS selector which can be found within the CSS of the page.  If only one value is given for any CSS property, the transition will be from the current value of that property to the value given.
  84
  85 ### Returns:
  86
  87 * (*object*) This Fx.Morph instance.
  88
  89 ### Examples:
  90
  91         var myFx = new Fx.Morph('myElement').set({
  92                 'height': 200,
  93                 'width': 200,
  94                 'background-color': '#f00',
  95                 'opacity': 0
  96         });
  97         var myFx = new Fx.Morph('myElement').set('.myClass');
  98
  99
 100
 101 Fx.Morph Method: start {#Fx-Morph:start}
 102 ----------------------------------------
 103
 104 Executes a transition for any number of CSS properties in tandem.
 105
 106 ### Syntax:
 107
 108         myFx.start(properties);
 109
 110 ### Arguments:
 111
 112 1. properties - (*mixed*) An *object* of key/value pairs of CSS attributes to change or a *string* representing a CSS selector which can be found within the CSS of the page.
 113         If only one value is given for any CSS property, the transition will be from the current value of that property to the value given.
 114
 115 ### Returns:
 116
 117 * (*object*) This Fx.Morph instance.
 118
 119 ### Examples:
 120
 121         var myEffects = new Fx.Morph('myElement', {duration: 1000, transition: Fx.Transitions.Sine.easeOut});
 122
 123         myEffects.start({
 124                 'height': [10, 100],
 125                 'width': [900, 300],
 126                 'opacity': 0,
 127                 'background-color': '#00f'
 128         });
 129
 130 ### Notes:
 131
 132 - If a string is passed as the CSS selector, the selector must be identical to the one within the CSS.
 133 - Multiple selectors (with commas) are not supported.
 134 - @import'ed CSS rules will not be available for Morph calls. All CSS selectors must be present in CSS directly loaded into the page.
 135
 136
 137 Object: Element.Properties {#Element-Properties}
 138 ==============================================
 139
 140 see [Element.Properties][]
 141
 142 Element Property: morph {#Element-Properties:morph}
 143 ---------------------------------------------------
 144
 145 ### Setter
 146
 147 Sets a default Fx.Morph instance for an Element.
 148
 149 #### Syntax:
 150
 151         el.set('morph'[, options]);
 152
 153 #### Arguments:
 154
 155 1. options - (*object*, optional) The Fx.Morph options.
 156
 157 #### Returns:
 158
 159 * (*element*) This Element.
 160
 161 #### Examples:
 162
 163         el.set('morph', {duration: 'long', transition: 'bounce:out'});
 164         el.morph({height: 100, width: 100});
 165
 166 ### Getter
 167
 168 Gets the default Fx.Morph instance for the Element.
 169
 170 #### Syntax:
 171
 172         el.get('morph');
 173
 174 #### Arguments:
 175
 176 1. property - (*string*) the Fx.Morph property argument.
 177
 178 #### Returns:
 179
 180 * (*object*) The Fx.Morph instance.
 181
 182 #### Examples:
 183
 184         el.set('morph', {duration: 'long', transition: 'bounce:out'});
 185         el.morph({height: 100, width: 100});
 186         el.get('morph'); // the Fx.Morph instance.
 187
 188
 189
 190 Type: Element {#Element}
 191 ==========================
 192
 193 Element Method: morph {#Element:morph}
 194 --------------------------------------
 195
 196 Animates an Element given the properties passed in.
 197
 198 ### Syntax:
 199
 200         myElement.morph(properties);
 201
 202 ### Arguments:
 203
 204 1. properties - (*mixed*) The CSS properties to animate. Can be either an object of CSS properties or a string representing a CSS selector.  If only one value is given for any CSS property, the transition will be from the current value of that property to the value given.
 205
 206 ### Returns:
 207
 208 * (*element*) This Element.
 209
 210 ### Example:
 211
 212 With an object:
 213
 214         $('myElement').morph({height: 100, width: 200});
 215
 216 With a selector:
 217
 218         $('myElement').morph('.class1');
 219
 220 ### See Also:
 221
 222 - [Fx.Morph][]
 223
 224
 225
 226 [$]: /core/Element/Element#Window:dollar
 227 [Fx]: /core/Fx/Fx
 228 [Fx.Morph]: #Fx-Morph
 229 [Element.Properties]: /core/Element/Element/#Element-Properties