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