Upgrade to ExtJS 3.3.0 - Released 10/06/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.3.0
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 <div id="prop-Ext.Element-OFFSETS"></div>/**
32  * Visibility mode constant for use with {@link #setVisibilityMode}. Use offsets (x and y positioning offscreen)
33  * to hide element.
34  * @static
35  * @type Number
36  */
37 Ext.Element.OFFSETS = 3;
38
39
40 Ext.Element.ASCLASS = 4;
41
42 <div id="prop-Ext.Element-visibilityCls"></div>/**
43  * Defaults to 'x-hide-nosize'
44  * @static
45  * @type String
46  */
47 Ext.Element.visibilityCls = 'x-hide-nosize';
48
49 Ext.Element.addMethods(function(){
50     var El = Ext.Element,
51         OPACITY = "opacity",
52         VISIBILITY = "visibility",
53         DISPLAY = "display",
54         HIDDEN = "hidden",
55         OFFSETS = "offsets",
56         ASCLASS = "asclass",
57         NONE = "none",
58         NOSIZE = 'nosize',
59         ORIGINALDISPLAY = 'originalDisplay',
60         VISMODE = 'visibilityMode',
61         ISVISIBLE = 'isVisible',
62         data = El.data,
63         getDisplay = function(dom){
64             var d = data(dom, ORIGINALDISPLAY);
65             if(d === undefined){
66                 data(dom, ORIGINALDISPLAY, d = '');
67             }
68             return d;
69         },
70         getVisMode = function(dom){
71             var m = data(dom, VISMODE);
72             if(m === undefined){
73                 data(dom, VISMODE, m = 1);
74             }
75             return m;
76         };
77
78     return {
79         <div id="prop-Ext.Element-originalDisplay"></div>/**
80          * The element's default display mode  (defaults to "")
81          * @type String
82          */
83         originalDisplay : "",
84         visibilityMode : 1,
85
86         <div id="method-Ext.Element-setVisibilityMode"></div>/**
87          * Sets the element's visibility mode. When setVisible() is called it
88          * will use this to determine whether to set the visibility or the display property.
89          * @param {Number} visMode Ext.Element.VISIBILITY or Ext.Element.DISPLAY
90          * @return {Ext.Element} this
91          */
92         setVisibilityMode : function(visMode){
93             data(this.dom, VISMODE, visMode);
94             return this;
95         },
96
97         <div id="method-Ext.Element-animate"></div>/**
98          * Perform custom animation on this element.
99          * <div><ul class="mdetail-params">
100          * <li><u>Animation Properties</u></li>
101          *
102          * <p>The Animation Control Object enables gradual transitions for any member of an
103          * element's style object that takes a numeric value including but not limited to
104          * these properties:</p><div><ul class="mdetail-params">
105          * <li><tt>bottom, top, left, right</tt></li>
106          * <li><tt>height, width</tt></li>
107          * <li><tt>margin, padding</tt></li>
108          * <li><tt>borderWidth</tt></li>
109          * <li><tt>opacity</tt></li>
110          * <li><tt>fontSize</tt></li>
111          * <li><tt>lineHeight</tt></li>
112          * </ul></div>
113          *
114          *
115          * <li><u>Animation Property Attributes</u></li>
116          *
117          * <p>Each Animation Property is a config object with optional properties:</p>
118          * <div><ul class="mdetail-params">
119          * <li><tt>by</tt>*  : relative change - start at current value, change by this value</li>
120          * <li><tt>from</tt> : ignore current value, start from this value</li>
121          * <li><tt>to</tt>*  : start at current value, go to this value</li>
122          * <li><tt>unit</tt> : any allowable unit specification</li>
123          * <p>* do not specify both <tt>to</tt> and <tt>by</tt> for an animation property</p>
124          * </ul></div>
125          *
126          * <li><u>Animation Types</u></li>
127          *
128          * <p>The supported animation types:</p><div><ul class="mdetail-params">
129          * <li><tt>'run'</tt> : Default
130          * <pre><code>
131 var el = Ext.get('complexEl');
132 el.animate(
133     // animation control object
134     {
135         borderWidth: {to: 3, from: 0},
136         opacity: {to: .3, from: 1},
137         height: {to: 50, from: el.getHeight()},
138         width: {to: 300, from: el.getWidth()},
139         top  : {by: - 100, unit: 'px'},
140     },
141     0.35,      // animation duration
142     null,      // callback
143     'easeOut', // easing method
144     'run'      // animation type ('run','color','motion','scroll')
145 );
146          * </code></pre>
147          * </li>
148          * <li><tt>'color'</tt>
149          * <p>Animates transition of background, text, or border colors.</p>
150          * <pre><code>
151 el.animate(
152     // animation control object
153     {
154         color: { to: '#06e' },
155         backgroundColor: { to: '#e06' }
156     },
157     0.35,      // animation duration
158     null,      // callback
159     'easeOut', // easing method
160     'color'    // animation type ('run','color','motion','scroll')
161 );
162          * </code></pre>
163          * </li>
164          *
165          * <li><tt>'motion'</tt>
166          * <p>Animates the motion of an element to/from specific points using optional bezier
167          * way points during transit.</p>
168          * <pre><code>
169 el.animate(
170     // animation control object
171     {
172         borderWidth: {to: 3, from: 0},
173         opacity: {to: .3, from: 1},
174         height: {to: 50, from: el.getHeight()},
175         width: {to: 300, from: el.getWidth()},
176         top  : {by: - 100, unit: 'px'},
177         points: {
178             to: [50, 100],  // go to this point
179             control: [      // optional bezier way points
180                 [ 600, 800],
181                 [-100, 200]
182             ]
183         }
184     },
185     3000,      // animation duration (milliseconds!)
186     null,      // callback
187     'easeOut', // easing method
188     'motion'   // animation type ('run','color','motion','scroll')
189 );
190          * </code></pre>
191          * </li>
192          * <li><tt>'scroll'</tt>
193          * <p>Animate horizontal or vertical scrolling of an overflowing page element.</p>
194          * <pre><code>
195 el.animate(
196     // animation control object
197     {
198         scroll: {to: [400, 300]}
199     },
200     0.35,      // animation duration
201     null,      // callback
202     'easeOut', // easing method
203     'scroll'   // animation type ('run','color','motion','scroll')
204 );
205          * </code></pre>
206          * </li>
207          * </ul></div>
208          *
209          * </ul></div>
210          *
211          * @param {Object} args The animation control args
212          * @param {Float} duration (optional) How long the animation lasts in seconds (defaults to <tt>.35</tt>)
213          * @param {Function} onComplete (optional) Function to call when animation completes
214          * @param {String} easing (optional) {@link Ext.Fx#easing} method to use (defaults to <tt>'easeOut'</tt>)
215          * @param {String} animType (optional) <tt>'run'</tt> is the default. Can also be <tt>'color'</tt>,
216          * <tt>'motion'</tt>, or <tt>'scroll'</tt>
217          * @return {Ext.Element} this
218          */
219         animate : function(args, duration, onComplete, easing, animType){
220             this.anim(args, {duration: duration, callback: onComplete, easing: easing}, animType);
221             return this;
222         },
223
224         /*
225          * @private Internal animation call
226          */
227         anim : function(args, opt, animType, defaultDur, defaultEase, cb){
228             animType = animType || 'run';
229             opt = opt || {};
230             var me = this,
231                 anim = Ext.lib.Anim[animType](
232                     me.dom,
233                     args,
234                     (opt.duration || defaultDur) || .35,
235                     (opt.easing || defaultEase) || 'easeOut',
236                     function(){
237                         if(cb) cb.call(me);
238                         if(opt.callback) opt.callback.call(opt.scope || me, me, opt);
239                     },
240                     me
241                 );
242             opt.anim = anim;
243             return anim;
244         },
245
246         // private legacy anim prep
247         preanim : function(a, i){
248             return !a[i] ? false : (typeof a[i] == 'object' ? a[i]: {duration: a[i+1], callback: a[i+2], easing: a[i+3]});
249         },
250
251         <div id="method-Ext.Element-isVisible"></div>/**
252          * Checks whether the element is currently visible using both visibility and display properties.
253          * @return {Boolean} True if the element is currently visible, else false
254          */
255         isVisible : function() {
256             var me = this,
257                 dom = me.dom,
258                 visible = data(dom, ISVISIBLE);
259
260             if(typeof visible == 'boolean'){ //return the cached value if registered
261                 return visible;
262             }
263             //Determine the current state based on display states
264             visible = !me.isStyle(VISIBILITY, HIDDEN) &&
265                       !me.isStyle(DISPLAY, NONE) &&
266                       !((getVisMode(dom) == El.ASCLASS) && me.hasClass(me.visibilityCls || El.visibilityCls));
267
268             data(dom, ISVISIBLE, visible);
269             return visible;
270         },
271
272         <div id="method-Ext.Element-setVisible"></div>/**
273          * Sets the visibility of the element (see details). If the visibilityMode is set to Element.DISPLAY, it will use
274          * the display property to hide the element, otherwise it uses visibility. The default is to hide and show using the visibility property.
275          * @param {Boolean} visible Whether the element is visible
276          * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
277          * @return {Ext.Element} this
278          */
279         setVisible : function(visible, animate){
280             var me = this, isDisplay, isVisibility, isOffsets, isNosize,
281                 dom = me.dom,
282                 visMode = getVisMode(dom);
283
284
285             // hideMode string override
286             if (typeof animate == 'string'){
287                 switch (animate) {
288                     case DISPLAY:
289                         visMode = El.DISPLAY;
290                         break;
291                     case VISIBILITY:
292                         visMode = El.VISIBILITY;
293                         break;
294                     case OFFSETS:
295                         visMode = El.OFFSETS;
296                         break;
297                     case NOSIZE:
298                     case ASCLASS:
299                         visMode = El.ASCLASS;
300                         break;
301                 }
302                 me.setVisibilityMode(visMode);
303                 animate = false;
304             }
305
306             if (!animate || !me.anim) {
307                 if(visMode == El.ASCLASS ){
308
309                     me[visible?'removeClass':'addClass'](me.visibilityCls || El.visibilityCls);
310
311                 } else if (visMode == El.DISPLAY){
312
313                     return me.setDisplayed(visible);
314
315                 } else if (visMode == El.OFFSETS){
316
317                     if (!visible){
318                         me.hideModeStyles = {
319                             position: me.getStyle('position'),
320                             top: me.getStyle('top'),
321                             left: me.getStyle('left')
322                         };
323                         me.applyStyles({position: 'absolute', top: '-10000px', left: '-10000px'});
324                     } else {
325                         me.applyStyles(me.hideModeStyles || {position: '', top: '', left: ''});
326                         delete me.hideModeStyles;
327                     }
328
329                 }else{
330                     me.fixDisplay();
331                     dom.style.visibility = visible ? "visible" : HIDDEN;
332                 }
333             }else{
334                 // closure for composites
335                 if(visible){
336                     me.setOpacity(.01);
337                     me.setVisible(true);
338                 }
339                 me.anim({opacity: { to: (visible?1:0) }},
340                         me.preanim(arguments, 1),
341                         null,
342                         .35,
343                         'easeIn',
344                         function(){
345                             visible || me.setVisible(false).setOpacity(1);
346                         });
347             }
348             data(dom, ISVISIBLE, visible);  //set logical visibility state
349             return me;
350         },
351
352
353         /**
354          * @private
355          * Determine if the Element has a relevant height and width available based
356          * upon current logical visibility state
357          */
358         hasMetrics  : function(){
359             var dom = this.dom;
360             return this.isVisible() || (getVisMode(dom) == El.VISIBILITY);
361         },
362
363         <div id="method-Ext.Element-toggle"></div>/**
364          * Toggles the element's visibility or display, depending on visibility mode.
365          * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
366          * @return {Ext.Element} this
367          */
368         toggle : function(animate){
369             var me = this;
370             me.setVisible(!me.isVisible(), me.preanim(arguments, 0));
371             return me;
372         },
373
374         <div id="method-Ext.Element-setDisplayed"></div>/**
375          * Sets the CSS display property. Uses originalDisplay if the specified value is a boolean true.
376          * @param {Mixed} value Boolean value to display the element using its default display, or a string to set the display directly.
377          * @return {Ext.Element} this
378          */
379         setDisplayed : function(value) {
380             if(typeof value == "boolean"){
381                value = value ? getDisplay(this.dom) : NONE;
382             }
383             this.setStyle(DISPLAY, value);
384             return this;
385         },
386
387         // private
388         fixDisplay : function(){
389             var me = this;
390             if(me.isStyle(DISPLAY, NONE)){
391                 me.setStyle(VISIBILITY, HIDDEN);
392                 me.setStyle(DISPLAY, getDisplay(this.dom)); // first try reverting to default
393                 if(me.isStyle(DISPLAY, NONE)){ // if that fails, default to block
394                     me.setStyle(DISPLAY, "block");
395                 }
396             }
397         },
398
399         <div id="method-Ext.Element-hide"></div>/**
400          * Hide this element - Uses display mode to determine whether to use "display" or "visibility". See {@link #setVisible}.
401          * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
402          * @return {Ext.Element} this
403          */
404         hide : function(animate){
405             // hideMode override
406             if (typeof animate == 'string'){
407                 this.setVisible(false, animate);
408                 return this;
409             }
410             this.setVisible(false, this.preanim(arguments, 0));
411             return this;
412         },
413
414         <div id="method-Ext.Element-show"></div>/**
415         * Show this element - Uses display mode to determine whether to use "display" or "visibility". See {@link #setVisible}.
416         * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
417          * @return {Ext.Element} this
418          */
419         show : function(animate){
420             // hideMode override
421             if (typeof animate == 'string'){
422                 this.setVisible(true, animate);
423                 return this;
424             }
425             this.setVisible(true, this.preanim(arguments, 0));
426             return this;
427         }
428     };
429 }());</pre>    
430 </body>
431 </html>