Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / Element.fx.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.2.1
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.com/license
14  */
15 /**
16  * @class Ext.Element
17  */
18 <div id="prop-Ext.Element-VISIBILITY"></div>/**
19  * Visibility mode constant for use with {@link #setVisibilityMode}. Use visibility to hide element
20  * @static
21  * @type Number
22  */
23 Ext.Element.VISIBILITY = 1;
24 <div id="prop-Ext.Element-DISPLAY"></div>/**
25  * Visibility mode constant for use with {@link #setVisibilityMode}. Use display to hide element
26  * @static
27  * @type Number
28  */
29 Ext.Element.DISPLAY = 2;
30
31 Ext.Element.addMethods(function(){
32     var VISIBILITY = "visibility",
33         DISPLAY = "display",
34         HIDDEN = "hidden",
35         OFFSETS = "offsets",
36         NONE = "none",
37         ORIGINALDISPLAY = 'originalDisplay',
38         VISMODE = 'visibilityMode',
39         ELDISPLAY = Ext.Element.DISPLAY,
40         data = Ext.Element.data,
41         getDisplay = function(dom){
42             var d = data(dom, ORIGINALDISPLAY);
43             if(d === undefined){
44                 data(dom, ORIGINALDISPLAY, d = '');
45             }
46             return d;
47         },
48         getVisMode = function(dom){
49             var m = data(dom, VISMODE);
50             if(m === undefined){
51                 data(dom, VISMODE, m = 1);
52             }
53             return m;
54         };
55
56     return {
57         <div id="prop-Ext.Element-originalDisplay"></div>/**
58          * The element's default display mode  (defaults to "")
59          * @type String
60          */
61         originalDisplay : "",
62         visibilityMode : 1,
63
64         <div id="method-Ext.Element-setVisibilityMode"></div>/**
65          * Sets the element's visibility mode. When setVisible() is called it
66          * will use this to determine whether to set the visibility or the display property.
67          * @param {Number} visMode Ext.Element.VISIBILITY or Ext.Element.DISPLAY
68          * @return {Ext.Element} this
69          */
70         setVisibilityMode : function(visMode){
71             data(this.dom, VISMODE, visMode);
72             return this;
73         },
74
75         <div id="method-Ext.Element-animate"></div>/**
76          * Perform custom animation on this element.
77          * <div><ul class="mdetail-params">
78          * <li><u>Animation Properties</u></li>
79          *
80          * <p>The Animation Control Object enables gradual transitions for any member of an
81          * element's style object that takes a numeric value including but not limited to
82          * these properties:</p><div><ul class="mdetail-params">
83          * <li><tt>bottom, top, left, right</tt></li>
84          * <li><tt>height, width</tt></li>
85          * <li><tt>margin, padding</tt></li>
86          * <li><tt>borderWidth</tt></li>
87          * <li><tt>opacity</tt></li>
88          * <li><tt>fontSize</tt></li>
89          * <li><tt>lineHeight</tt></li>
90          * </ul></div>
91          *
92          *
93          * <li><u>Animation Property Attributes</u></li>
94          *
95          * <p>Each Animation Property is a config object with optional properties:</p>
96          * <div><ul class="mdetail-params">
97          * <li><tt>by</tt>*  : relative change - start at current value, change by this value</li>
98          * <li><tt>from</tt> : ignore current value, start from this value</li>
99          * <li><tt>to</tt>*  : start at current value, go to this value</li>
100          * <li><tt>unit</tt> : any allowable unit specification</li>
101          * <p>* do not specify both <tt>to</tt> and <tt>by</tt> for an animation property</p>
102          * </ul></div>
103          *
104          * <li><u>Animation Types</u></li>
105          *
106          * <p>The supported animation types:</p><div><ul class="mdetail-params">
107          * <li><tt>'run'</tt> : Default
108          * <pre><code>
109 var el = Ext.get('complexEl');
110 el.animate(
111     // animation control object
112     {
113         borderWidth: {to: 3, from: 0},
114         opacity: {to: .3, from: 1},
115         height: {to: 50, from: el.getHeight()},
116         width: {to: 300, from: el.getWidth()},
117         top  : {by: - 100, unit: 'px'},
118     },
119     0.35,      // animation duration
120     null,      // callback
121     'easeOut', // easing method
122     'run'      // animation type ('run','color','motion','scroll')
123 );
124          * </code></pre>
125          * </li>
126          * <li><tt>'color'</tt>
127          * <p>Animates transition of background, text, or border colors.</p>
128          * <pre><code>
129 el.animate(
130     // animation control object
131     {
132         color: { to: '#06e' },
133         backgroundColor: { to: '#e06' }
134     },
135     0.35,      // animation duration
136     null,      // callback
137     'easeOut', // easing method
138     'color'    // animation type ('run','color','motion','scroll')
139 );
140          * </code></pre>
141          * </li>
142          *
143          * <li><tt>'motion'</tt>
144          * <p>Animates the motion of an element to/from specific points using optional bezier
145          * way points during transit.</p>
146          * <pre><code>
147 el.animate(
148     // animation control object
149     {
150         borderWidth: {to: 3, from: 0},
151         opacity: {to: .3, from: 1},
152         height: {to: 50, from: el.getHeight()},
153         width: {to: 300, from: el.getWidth()},
154         top  : {by: - 100, unit: 'px'},
155         points: {
156             to: [50, 100],  // go to this point
157             control: [      // optional bezier way points
158                 [ 600, 800],
159                 [-100, 200]
160             ]
161         }
162     },
163     3000,      // animation duration (milliseconds!)
164     null,      // callback
165     'easeOut', // easing method
166     'motion'   // animation type ('run','color','motion','scroll')
167 );
168          * </code></pre>
169          * </li>
170          * <li><tt>'scroll'</tt>
171          * <p>Animate horizontal or vertical scrolling of an overflowing page element.</p>
172          * <pre><code>
173 el.animate(
174     // animation control object
175     {
176         scroll: {to: [400, 300]}
177     },
178     0.35,      // animation duration
179     null,      // callback
180     'easeOut', // easing method
181     'scroll'   // animation type ('run','color','motion','scroll')
182 );
183          * </code></pre>
184          * </li>
185          * </ul></div>
186          *
187          * </ul></div>
188          *
189          * @param {Object} args The animation control args
190          * @param {Float} duration (optional) How long the animation lasts in seconds (defaults to <tt>.35</tt>)
191          * @param {Function} onComplete (optional) Function to call when animation completes
192          * @param {String} easing (optional) {@link Ext.Fx#easing} method to use (defaults to <tt>'easeOut'</tt>)
193          * @param {String} animType (optional) <tt>'run'</tt> is the default. Can also be <tt>'color'</tt>,
194          * <tt>'motion'</tt>, or <tt>'scroll'</tt>
195          * @return {Ext.Element} this
196          */
197         animate : function(args, duration, onComplete, easing, animType){
198             this.anim(args, {duration: duration, callback: onComplete, easing: easing}, animType);
199             return this;
200         },
201
202         /*
203          * @private Internal animation call
204          */
205         anim : function(args, opt, animType, defaultDur, defaultEase, cb){
206             animType = animType || 'run';
207             opt = opt || {};
208             var me = this,
209                 anim = Ext.lib.Anim[animType](
210                     me.dom,
211                     args,
212                     (opt.duration || defaultDur) || .35,
213                     (opt.easing || defaultEase) || 'easeOut',
214                     function(){
215                         if(cb) cb.call(me);
216                         if(opt.callback) opt.callback.call(opt.scope || me, me, opt);
217                     },
218                     me
219                 );
220             opt.anim = anim;
221             return anim;
222         },
223
224         // private legacy anim prep
225         preanim : function(a, i){
226             return !a[i] ? false : (typeof a[i] == 'object' ? a[i]: {duration: a[i+1], callback: a[i+2], easing: a[i+3]});
227         },
228
229         <div id="method-Ext.Element-isVisible"></div>/**
230          * Checks whether the element is currently visible using both visibility and display properties.
231          * @return {Boolean} True if the element is currently visible, else false
232          */
233         isVisible : function() {
234             return !this.isStyle(VISIBILITY, HIDDEN) && !this.isStyle(DISPLAY, NONE);
235         },
236
237         <div id="method-Ext.Element-setVisible"></div>/**
238          * Sets the visibility of the element (see details). If the visibilityMode is set to Element.DISPLAY, it will use
239          * the display property to hide the element, otherwise it uses visibility. The default is to hide and show using the visibility property.
240          * @param {Boolean} visible Whether the element is visible
241          * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
242          * @return {Ext.Element} this
243          */
244          setVisible : function(visible, animate){
245             var me = this, isDisplay, isVisible, isOffsets,
246                 dom = me.dom;
247
248             // hideMode string override
249             if (typeof animate == 'string'){
250                 isDisplay = animate == DISPLAY;
251                 isVisible = animate == VISIBILITY;
252                 isOffsets = animate == OFFSETS;
253                 animate = false;
254             } else {
255                 isDisplay = getVisMode(this.dom) == ELDISPLAY;
256                 isVisible = !isDisplay;
257             }
258
259             if (!animate || !me.anim) {
260                 if (isDisplay){
261                     me.setDisplayed(visible);
262                 } else if (isOffsets){
263                     if (!visible){
264                         me.hideModeStyles = {
265                             position: me.getStyle('position'),
266                             top: me.getStyle('top'),
267                             left: me.getStyle('left')
268                         };
269
270                         me.applyStyles({position: 'absolute', top: '-10000px', left: '-10000px'});
271                     } else {
272                         me.applyStyles(me.hideModeStyles || {position: '', top: '', left: ''});
273                     }
274                 }else{
275                     me.fixDisplay();
276                     dom.style.visibility = visible ? "visible" : HIDDEN;
277                 }
278             }else{
279                 // closure for composites
280                 if (visible){
281                     me.setOpacity(.01);
282                     me.setVisible(true);
283                 }
284                 me.anim({opacity: { to: (visible?1:0) }},
285                         me.preanim(arguments, 1),
286                         null,
287                         .35,
288                         'easeIn',
289                         function(){
290                              if(!visible){
291                                  dom.style[isDisplay ? DISPLAY : VISIBILITY] = (isDisplay) ? NONE : HIDDEN;
292                                  Ext.fly(dom).setOpacity(1);
293                              }
294                         });
295             }
296             return me;
297         },
298
299         <div id="method-Ext.Element-toggle"></div>/**
300          * Toggles the element's visibility or display, depending on visibility mode.
301          * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
302          * @return {Ext.Element} this
303          */
304         toggle : function(animate){
305             var me = this;
306             me.setVisible(!me.isVisible(), me.preanim(arguments, 0));
307             return me;
308         },
309
310         <div id="method-Ext.Element-setDisplayed"></div>/**
311          * Sets the CSS display property. Uses originalDisplay if the specified value is a boolean true.
312          * @param {Mixed} value Boolean value to display the element using its default display, or a string to set the display directly.
313          * @return {Ext.Element} this
314          */
315         setDisplayed : function(value) {
316             if(typeof value == "boolean"){
317                value = value ? getDisplay(this.dom) : NONE;
318             }
319             this.setStyle(DISPLAY, value);
320             return this;
321         },
322
323         // private
324         fixDisplay : function(){
325             var me = this;
326             if(me.isStyle(DISPLAY, NONE)){
327                 me.setStyle(VISIBILITY, HIDDEN);
328                 me.setStyle(DISPLAY, getDisplay(this.dom)); // first try reverting to default
329                 if(me.isStyle(DISPLAY, NONE)){ // if that fails, default to block
330                     me.setStyle(DISPLAY, "block");
331                 }
332             }
333         },
334
335         <div id="method-Ext.Element-hide"></div>/**
336          * Hide this element - Uses display mode to determine whether to use "display" or "visibility". See {@link #setVisible}.
337          * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
338          * @return {Ext.Element} this
339          */
340         hide : function(animate){
341             // hideMode override
342             if (typeof animate == 'string'){
343                 this.setVisible(false, animate);
344                 return this;
345             }
346             this.setVisible(false, this.preanim(arguments, 0));
347             return this;
348         },
349
350         <div id="method-Ext.Element-show"></div>/**
351         * Show this element - Uses display mode to determine whether to use "display" or "visibility". See {@link #setVisible}.
352         * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
353          * @return {Ext.Element} this
354          */
355         show : function(animate){
356             // hideMode override
357             if (typeof animate == 'string'){
358                 this.setVisible(true, animate);
359                 return this;
360             }
361             this.setVisible(true, this.preanim(arguments, 0));
362             return this;
363         }
364     };
365 }());
366 </pre>    
367 </body>
368 </html>