Upgrade to ExtJS 3.2.0 - Released 03/30/2010
[extjs.git] / docs / source / Element.style.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.0
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.com/license
14  */
15 <div id="cls-Ext.Element"></div>/**
16  * @class Ext.Element
17  */
18 Ext.Element.addMethods(function(){
19     // local style camelizing for speed
20     var propCache = {},
21         camelRe = /(-[a-z])/gi,
22         classReCache = {},
23         view = document.defaultView,
24         propFloat = Ext.isIE ? 'styleFloat' : 'cssFloat',
25         opacityRe = /alpha\(opacity=(.*)\)/i,
26         trimRe = /^\s+|\s+$/g,
27         EL = Ext.Element,
28         PADDING = "padding",
29         MARGIN = "margin",
30         BORDER = "border",
31         LEFT = "-left",
32         RIGHT = "-right",
33         TOP = "-top",
34         BOTTOM = "-bottom",
35         WIDTH = "-width",
36         MATH = Math,
37         HIDDEN = 'hidden',
38         ISCLIPPED = 'isClipped',
39         OVERFLOW = 'overflow',
40         OVERFLOWX = 'overflow-x',
41         OVERFLOWY = 'overflow-y',
42         ORIGINALCLIP = 'originalClip',
43         // special markup used throughout Ext when box wrapping elements
44         borders = {l: BORDER + LEFT + WIDTH, r: BORDER + RIGHT + WIDTH, t: BORDER + TOP + WIDTH, b: BORDER + BOTTOM + WIDTH},
45         paddings = {l: PADDING + LEFT, r: PADDING + RIGHT, t: PADDING + TOP, b: PADDING + BOTTOM},
46         margins = {l: MARGIN + LEFT, r: MARGIN + RIGHT, t: MARGIN + TOP, b: MARGIN + BOTTOM},
47         data = Ext.Element.data;
48
49
50     // private
51     function camelFn(m, a) {
52         return a.charAt(1).toUpperCase();
53     }
54
55     function chkCache(prop) {
56         return propCache[prop] || (propCache[prop] = prop == 'float' ? propFloat : prop.replace(camelRe, camelFn));
57     }
58
59     return {
60         // private  ==> used by Fx
61         adjustWidth : function(width) {
62             var me = this;
63             var isNum = Ext.isNumber(width);
64             if(isNum && me.autoBoxAdjust && !me.isBorderBox()){
65                width -= (me.getBorderWidth("lr") + me.getPadding("lr"));
66             }
67             return (isNum && width < 0) ? 0 : width;
68         },
69
70         // private   ==> used by Fx
71         adjustHeight : function(height) {
72             var me = this;
73             var isNum = Ext.isNumber(height);
74             if(isNum && me.autoBoxAdjust && !me.isBorderBox()){
75                height -= (me.getBorderWidth("tb") + me.getPadding("tb"));
76             }
77             return (isNum && height < 0) ? 0 : height;
78         },
79
80
81         <div id="method-Ext.Element-addClass"></div>/**
82          * Adds one or more CSS classes to the element. Duplicate classes are automatically filtered out.
83          * @param {String/Array} className The CSS class to add, or an array of classes
84          * @return {Ext.Element} this
85          */
86         addClass : function(className){
87             var me = this, i, len, v;
88             className = Ext.isArray(className) ? className : [className];
89             for (i=0, len = className.length; i < len; i++) {
90                 v = className[i];
91                 if (v) {
92                     me.dom.className += (!me.hasClass(v) && v ? " " + v : "");
93                 };
94             };
95             return me;
96         },
97
98         <div id="method-Ext.Element-radioClass"></div>/**
99          * Adds one or more CSS classes to this element and removes the same class(es) from all siblings.
100          * @param {String/Array} className The CSS class to add, or an array of classes
101          * @return {Ext.Element} this
102          */
103         radioClass : function(className){
104             var cn = this.dom.parentNode.childNodes, v;
105             className = Ext.isArray(className) ? className : [className];
106             for (var i=0, len = cn.length; i < len; i++) {
107                 v = cn[i];
108                 if(v && v.nodeType == 1) {
109                     Ext.fly(v, '_internal').removeClass(className);
110                 }
111             };
112             return this.addClass(className);
113         },
114
115         <div id="method-Ext.Element-removeClass"></div>/**
116          * Removes one or more CSS classes from the element.
117          * @param {String/Array} className The CSS class to remove, or an array of classes
118          * @return {Ext.Element} this
119          */
120         removeClass : function(className){
121             var me = this, v;
122             className = Ext.isArray(className) ? className : [className];
123             if (me.dom && me.dom.className) {
124                 for (var i=0, len=className.length; i < len; i++) {
125                     v = className[i];
126                     if(v) {
127                         me.dom.className = me.dom.className.replace(
128                             classReCache[v] = classReCache[v] || new RegExp('(?:^|\\s+)' + v + '(?:\\s+|$)', "g"), " "
129                         );
130                     }
131                 };
132             }
133             return me;
134         },
135
136         <div id="method-Ext.Element-toggleClass"></div>/**
137          * Toggles the specified CSS class on this element (removes it if it already exists, otherwise adds it).
138          * @param {String} className The CSS class to toggle
139          * @return {Ext.Element} this
140          */
141         toggleClass : function(className){
142             return this.hasClass(className) ? this.removeClass(className) : this.addClass(className);
143         },
144
145         <div id="method-Ext.Element-hasClass"></div>/**
146          * Checks if the specified CSS class exists on this element's DOM node.
147          * @param {String} className The CSS class to check for
148          * @return {Boolean} True if the class exists, else false
149          */
150         hasClass : function(className){
151             return className && (' '+this.dom.className+' ').indexOf(' '+className+' ') != -1;
152         },
153
154         <div id="method-Ext.Element-replaceClass"></div>/**
155          * Replaces a CSS class on the element with another.  If the old name does not exist, the new name will simply be added.
156          * @param {String} oldClassName The CSS class to replace
157          * @param {String} newClassName The replacement CSS class
158          * @return {Ext.Element} this
159          */
160         replaceClass : function(oldClassName, newClassName){
161             return this.removeClass(oldClassName).addClass(newClassName);
162         },
163
164         isStyle : function(style, val) {
165             return this.getStyle(style) == val;
166         },
167
168         <div id="method-Ext.Element-getStyle"></div>/**
169          * Normalizes currentStyle and computedStyle.
170          * @param {String} property The style property whose value is returned.
171          * @return {String} The current value of the style property for this element.
172          */
173         getStyle : function(){
174             return view && view.getComputedStyle ?
175                 function(prop){
176                     var el = this.dom,
177                         v,
178                         cs,
179                         out,
180                         display,
181                         wk = Ext.isWebKit,
182                         display;
183                         
184                     if(el == document){
185                         return null;
186                     }
187                     prop = chkCache(prop);
188                     // Fix bug caused by this: https://bugs.webkit.org/show_bug.cgi?id=13343
189                     if(wk && /marginRight/.test(prop)){
190                         display = this.getStyle('display');
191                         el.style.display = 'inline-block';
192                     }
193                     out = (v = el.style[prop]) ? v :
194                            (cs = view.getComputedStyle(el, "")) ? cs[prop] : null;
195
196                     // Webkit returns rgb values for transparent.
197                     if(wk){
198                         if(out == 'rgba(0, 0, 0, 0)'){
199                             out = 'transparent';
200                         }else if(display){
201                             el.style.display = display;
202                         }
203                     }
204                     return out;
205                 } :
206                 function(prop){
207                     var el = this.dom,
208                         m,
209                         cs;
210
211                     if(el == document) return null;
212                     if (prop == 'opacity') {
213                         if (el.style.filter.match) {
214                             if(m = el.style.filter.match(opacityRe)){
215                                 var fv = parseFloat(m[1]);
216                                 if(!isNaN(fv)){
217                                     return fv ? fv / 100 : 0;
218                                 }
219                             }
220                         }
221                         return 1;
222                     }
223                     prop = chkCache(prop);
224                     return el.style[prop] || ((cs = el.currentStyle) ? cs[prop] : null);
225                 };
226         }(),
227
228         <div id="method-Ext.Element-getColor"></div>/**
229          * Return the CSS color for the specified CSS attribute. rgb, 3 digit (like #fff) and valid values
230          * are convert to standard 6 digit hex color.
231          * @param {String} attr The css attribute
232          * @param {String} defaultValue The default value to use when a valid color isn't found
233          * @param {String} prefix (optional) defaults to #. Use an empty string when working with
234          * color anims.
235          */
236         getColor : function(attr, defaultValue, prefix){
237             var v = this.getStyle(attr),
238                 color = Ext.isDefined(prefix) ? prefix : '#',
239                 h;
240
241             if(!v || /transparent|inherit/.test(v)){
242                 return defaultValue;
243             }
244             if(/^r/.test(v)){
245                 Ext.each(v.slice(4, v.length -1).split(','), function(s){
246                     h = parseInt(s, 10);
247                     color += (h < 16 ? '0' : '') + h.toString(16);
248                 });
249             }else{
250                 v = v.replace('#', '');
251                 color += v.length == 3 ? v.replace(/^(\w)(\w)(\w)$/, '$1$1$2$2$3$3') : v;
252             }
253             return(color.length > 5 ? color.toLowerCase() : defaultValue);
254         },
255
256         <div id="method-Ext.Element-setStyle"></div>/**
257          * Wrapper for setting style properties, also takes single object parameter of multiple styles.
258          * @param {String/Object} property The style property to be set, or an object of multiple styles.
259          * @param {String} value (optional) The value to apply to the given property, or null if an object was passed.
260          * @return {Ext.Element} this
261          */
262         setStyle : function(prop, value){
263             var tmp,
264                 style,
265                 camel;
266             if (!Ext.isObject(prop)) {
267                 tmp = {};
268                 tmp[prop] = value;
269                 prop = tmp;
270             }
271             for (style in prop) {
272                 value = prop[style];
273                 style == 'opacity' ?
274                     this.setOpacity(value) :
275                     this.dom.style[chkCache(style)] = value;
276             }
277             return this;
278         },
279
280         <div id="method-Ext.Element-setOpacity"></div>/**
281          * Set the opacity of the element
282          * @param {Float} opacity The new opacity. 0 = transparent, .5 = 50% visibile, 1 = fully visible, etc
283          * @param {Boolean/Object} animate (optional) a standard Element animation config object or <tt>true</tt> for
284          * the default animation (<tt>{duration: .35, easing: 'easeIn'}</tt>)
285          * @return {Ext.Element} this
286          */
287          setOpacity : function(opacity, animate){
288             var me = this,
289                 s = me.dom.style;
290
291             if(!animate || !me.anim){
292                 if(Ext.isIE){
293                     var opac = opacity < 1 ? 'alpha(opacity=' + opacity * 100 + ')' : '',
294                     val = s.filter.replace(opacityRe, '').replace(trimRe, '');
295
296                     s.zoom = 1;
297                     s.filter = val + (val.length > 0 ? ' ' : '') + opac;
298                 }else{
299                     s.opacity = opacity;
300                 }
301             }else{
302                 me.anim({opacity: {to: opacity}}, me.preanim(arguments, 1), null, .35, 'easeIn');
303             }
304             return me;
305         },
306
307         <div id="method-Ext.Element-clearOpacity"></div>/**
308          * Clears any opacity settings from this element. Required in some cases for IE.
309          * @return {Ext.Element} this
310          */
311         clearOpacity : function(){
312             var style = this.dom.style;
313             if(Ext.isIE){
314                 if(!Ext.isEmpty(style.filter)){
315                     style.filter = style.filter.replace(opacityRe, '').replace(trimRe, '');
316                 }
317             }else{
318                 style.opacity = style['-moz-opacity'] = style['-khtml-opacity'] = '';
319             }
320             return this;
321         },
322
323         <div id="method-Ext.Element-getHeight"></div>/**
324          * Returns the offset height of the element
325          * @param {Boolean} contentHeight (optional) true to get the height minus borders and padding
326          * @return {Number} The element's height
327          */
328         getHeight : function(contentHeight){
329             var me = this,
330                 dom = me.dom,
331                 hidden = Ext.isIE && me.isStyle('display', 'none'),
332                 h = MATH.max(dom.offsetHeight, hidden ? 0 : dom.clientHeight) || 0;
333
334             h = !contentHeight ? h : h - me.getBorderWidth("tb") - me.getPadding("tb");
335             return h < 0 ? 0 : h;
336         },
337
338         <div id="method-Ext.Element-getWidth"></div>/**
339          * Returns the offset width of the element
340          * @param {Boolean} contentWidth (optional) true to get the width minus borders and padding
341          * @return {Number} The element's width
342          */
343         getWidth : function(contentWidth){
344             var me = this,
345                 dom = me.dom,
346                 hidden = Ext.isIE && me.isStyle('display', 'none'),
347                 w = MATH.max(dom.offsetWidth, hidden ? 0 : dom.clientWidth) || 0;
348             w = !contentWidth ? w : w - me.getBorderWidth("lr") - me.getPadding("lr");
349             return w < 0 ? 0 : w;
350         },
351
352         <div id="method-Ext.Element-setWidth"></div>/**
353          * Set the width of this Element.
354          * @param {Mixed} width The new width. This may be one of:<div class="mdetail-params"><ul>
355          * <li>A Number specifying the new width in this Element's {@link #defaultUnit}s (by default, pixels).</li>
356          * <li>A String used to set the CSS width style. Animation may <b>not</b> be used.
357          * </ul></div>
358          * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
359          * @return {Ext.Element} this
360          */
361         setWidth : function(width, animate){
362             var me = this;
363             width = me.adjustWidth(width);
364             !animate || !me.anim ?
365                 me.dom.style.width = me.addUnits(width) :
366                 me.anim({width : {to : width}}, me.preanim(arguments, 1));
367             return me;
368         },
369
370         <div id="method-Ext.Element-setHeight"></div>/**
371          * Set the height of this Element.
372          * <pre><code>
373 // change the height to 200px and animate with default configuration
374 Ext.fly('elementId').setHeight(200, true);
375
376 // change the height to 150px and animate with a custom configuration
377 Ext.fly('elId').setHeight(150, {
378     duration : .5, // animation will have a duration of .5 seconds
379     // will change the content to "finished"
380     callback: function(){ this.{@link #update}("finished"); }
381 });
382          * </code></pre>
383          * @param {Mixed} height The new height. This may be one of:<div class="mdetail-params"><ul>
384          * <li>A Number specifying the new height in this Element's {@link #defaultUnit}s (by default, pixels.)</li>
385          * <li>A String used to set the CSS height style. Animation may <b>not</b> be used.</li>
386          * </ul></div>
387          * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
388          * @return {Ext.Element} this
389          */
390          setHeight : function(height, animate){
391             var me = this;
392             height = me.adjustHeight(height);
393             !animate || !me.anim ?
394                 me.dom.style.height = me.addUnits(height) :
395                 me.anim({height : {to : height}}, me.preanim(arguments, 1));
396             return me;
397         },
398
399         <div id="method-Ext.Element-getBorderWidth"></div>/**
400          * Gets the width of the border(s) for the specified side(s)
401          * @param {String} side Can be t, l, r, b or any combination of those to add multiple values. For example,
402          * passing <tt>'lr'</tt> would get the border <b><u>l</u></b>eft width + the border <b><u>r</u></b>ight width.
403          * @return {Number} The width of the sides passed added together
404          */
405         getBorderWidth : function(side){
406             return this.addStyles(side, borders);
407         },
408
409         <div id="method-Ext.Element-getPadding"></div>/**
410          * Gets the width of the padding(s) for the specified side(s)
411          * @param {String} side Can be t, l, r, b or any combination of those to add multiple values. For example,
412          * passing <tt>'lr'</tt> would get the padding <b><u>l</u></b>eft + the padding <b><u>r</u></b>ight.
413          * @return {Number} The padding of the sides passed added together
414          */
415         getPadding : function(side){
416             return this.addStyles(side, paddings);
417         },
418
419         <div id="method-Ext.Element-clip"></div>/**
420          *  Store the current overflow setting and clip overflow on the element - use <tt>{@link #unclip}</tt> to remove
421          * @return {Ext.Element} this
422          */
423         clip : function(){
424             var me = this,
425                 dom = me.dom;
426
427             if(!data(dom, ISCLIPPED)){
428                 data(dom, ISCLIPPED, true);
429                 data(dom, ORIGINALCLIP, {
430                     o: me.getStyle(OVERFLOW),
431                     x: me.getStyle(OVERFLOWX),
432                     y: me.getStyle(OVERFLOWY)
433                 });
434                 me.setStyle(OVERFLOW, HIDDEN);
435                 me.setStyle(OVERFLOWX, HIDDEN);
436                 me.setStyle(OVERFLOWY, HIDDEN);
437             }
438             return me;
439         },
440
441         <div id="method-Ext.Element-unclip"></div>/**
442          *  Return clipping (overflow) to original clipping before <tt>{@link #clip}</tt> was called
443          * @return {Ext.Element} this
444          */
445         unclip : function(){
446             var me = this,
447                 dom = me.dom;
448
449             if(data(dom, ISCLIPPED)){
450                 data(dom, ISCLIPPED, false);
451                 var o = data(dom, ORIGINALCLIP);
452                 if(o.o){
453                     me.setStyle(OVERFLOW, o.o);
454                 }
455                 if(o.x){
456                     me.setStyle(OVERFLOWX, o.x);
457                 }
458                 if(o.y){
459                     me.setStyle(OVERFLOWY, o.y);
460                 }
461             }
462             return me;
463         },
464
465         // private
466         addStyles : function(sides, styles){
467             var val = 0,
468                 m = sides.match(/\w/g),
469                 s;
470             for (var i=0, len=m.length; i<len; i++) {
471                 s = m[i] && parseInt(this.getStyle(styles[m[i]]), 10);
472                 if (s) {
473                     val += MATH.abs(s);
474                 }
475             }
476             return val;
477         },
478
479         margins : margins
480     }
481 }()
482 );
483 </pre>    
484 </body>
485 </html>