Upgrade to ExtJS 3.0.3 - Released 10/11/2009
[extjs.git] / docs / source / Element.style-more.html
1 <html>
2 <head>
3   <title>The source code</title>
4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
6 </head>
7 <body  onload="prettyPrint();">
8     <pre class="prettyprint lang-js">/*!
9  * Ext JS Library 3.0.3
10  * Copyright(c) 2006-2009 Ext JS, LLC
11  * licensing@extjs.com
12  * http://www.extjs.com/license
13  */
14 /**\r
15  * @class Ext.Element\r
16  */\r
17 \r
18 // special markup used throughout Ext when box wrapping elements\r
19 Ext.Element.boxMarkup = '<div class="{0}-tl"><div class="{0}-tr"><div class="{0}-tc"></div></div></div><div class="{0}-ml"><div class="{0}-mr"><div class="{0}-mc"></div></div></div><div class="{0}-bl"><div class="{0}-br"><div class="{0}-bc"></div></div></div>';\r
20 \r
21 Ext.Element.addMethods(function(){\r
22         var INTERNAL = "_internal";\r
23         return {\r
24             <div id="method-Ext.Element-applyStyles"></div>/**\r
25              * More flexible version of {@link #setStyle} for setting style properties.\r
26              * @param {String/Object/Function} styles A style specification string, e.g. "width:100px", or object in the form {width:"100px"}, or\r
27              * a function which returns such a specification.\r
28              * @return {Ext.Element} this\r
29              */\r
30             applyStyles : function(style){\r
31                 Ext.DomHelper.applyStyles(this.dom, style);\r
32                 return this;\r
33             },\r
34 \r
35                 <div id="method-Ext.Element-getStyles"></div>/**\r
36              * Returns an object with properties matching the styles requested.\r
37              * For example, el.getStyles('color', 'font-size', 'width') might return\r
38              * {'color': '#FFFFFF', 'font-size': '13px', 'width': '100px'}.\r
39              * @param {String} style1 A style name\r
40              * @param {String} style2 A style name\r
41              * @param {String} etc.\r
42              * @return {Object} The style object\r
43              */\r
44             getStyles : function(){\r
45                     var ret = {};\r
46                     Ext.each(arguments, function(v) {\r
47                            ret[v] = this.getStyle(v);\r
48                     },\r
49                     this);\r
50                     return ret;\r
51             },\r
52 \r
53                 getStyleSize : function(){\r
54                 var me = this,\r
55                         w,\r
56                         h,\r
57                         d = this.dom,\r
58                         s = d.style;\r
59                 if(s.width && s.width != 'auto'){\r
60                     w = parseInt(s.width, 10);\r
61                     if(me.isBorderBox()){\r
62                        w -= me.getFrameWidth('lr');\r
63                     }\r
64                 }\r
65                 if(s.height && s.height != 'auto'){\r
66                     h = parseInt(s.height, 10);\r
67                     if(me.isBorderBox()){\r
68                        h -= me.getFrameWidth('tb');\r
69                     }\r
70                 }\r
71                 return {width: w || me.getWidth(true), height: h || me.getHeight(true)};\r
72             },\r
73 \r
74             // private  ==> used by ext full\r
75                 setOverflow : function(v){\r
76                         var dom = this.dom;\r
77                 if(v=='auto' && Ext.isMac && Ext.isGecko2){ // work around stupid FF 2.0/Mac scroll bar bug\r
78                         dom.style.overflow = 'hidden';\r
79                         (function(){dom.style.overflow = 'auto';}).defer(1);\r
80                 }else{\r
81                         dom.style.overflow = v;\r
82                 }\r
83                 },\r
84 \r
85            <div id="method-Ext.Element-boxWrap"></div>/**\r
86                 * <p>Wraps the specified element with a special 9 element markup/CSS block that renders by default as\r
87                 * a gray container with a gradient background, rounded corners and a 4-way shadow.</p>\r
88                 * <p>This special markup is used throughout Ext when box wrapping elements ({@link Ext.Button},\r
89                 * {@link Ext.Panel} when <tt>{@link Ext.Panel#frame frame=true}</tt>, {@link Ext.Window}).  The markup\r
90                 * is of this form:</p>\r
91                 * <pre><code>\r
92 Ext.Element.boxMarkup =\r
93     &#39;&lt;div class="{0}-tl">&lt;div class="{0}-tr">&lt;div class="{0}-tc">&lt;/div>&lt;/div>&lt;/div>\r
94      &lt;div class="{0}-ml">&lt;div class="{0}-mr">&lt;div class="{0}-mc">&lt;/div>&lt;/div>&lt;/div>\r
95      &lt;div class="{0}-bl">&lt;div class="{0}-br">&lt;div class="{0}-bc">&lt;/div>&lt;/div>&lt;/div>&#39;;\r
96                 * </code></pre>\r
97                 * <p>Example usage:</p>\r
98                 * <pre><code>\r
99 // Basic box wrap\r
100 Ext.get("foo").boxWrap();\r
101 \r
102 // You can also add a custom class and use CSS inheritance rules to customize the box look.\r
103 // 'x-box-blue' is a built-in alternative -- look at the related CSS definitions as an example\r
104 // for how to create a custom box wrap style.\r
105 Ext.get("foo").boxWrap().addClass("x-box-blue");\r
106                 * </code></pre>\r
107                 * @param {String} class (optional) A base CSS class to apply to the containing wrapper element\r
108                 * (defaults to <tt>'x-box'</tt>). Note that there are a number of CSS rules that are dependent on\r
109                 * this name to make the overall effect work, so if you supply an alternate base class, make sure you\r
110                 * also supply all of the necessary rules.\r
111                 * @return {Ext.Element} this\r
112                 */\r
113             boxWrap : function(cls){\r
114                 cls = cls || 'x-box';\r
115                 var el = Ext.get(this.insertHtml("beforeBegin", "<div class='" + cls + "'>" + String.format(Ext.Element.boxMarkup, cls) + "</div>"));        //String.format('<div class="{0}">'+Ext.Element.boxMarkup+'</div>', cls)));\r
116                 Ext.DomQuery.selectNode('.' + cls + '-mc', el.dom).appendChild(this.dom);\r
117                 return el;\r
118             },\r
119 \r
120         <div id="method-Ext.Element-setSize"></div>/**\r
121          * Set the size of this Element. If animation is true, both width and height will be animated concurrently.\r
122          * @param {Mixed} width The new width. This may be one of:<div class="mdetail-params"><ul>\r
123          * <li>A Number specifying the new width in this Element's {@link #defaultUnit}s (by default, pixels).</li>\r
124          * <li>A String used to set the CSS width style. Animation may <b>not</b> be used.\r
125          * <li>A size object in the format <code>{width: widthValue, height: heightValue}</code>.</li>\r
126          * </ul></div>\r
127          * @param {Mixed} height The new height. This may be one of:<div class="mdetail-params"><ul>\r
128          * <li>A Number specifying the new height in this Element's {@link #defaultUnit}s (by default, pixels).</li>\r
129          * <li>A String used to set the CSS height style. Animation may <b>not</b> be used.</li>\r
130          * </ul></div>\r
131          * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object\r
132          * @return {Ext.Element} this\r
133          */\r
134             setSize : function(width, height, animate){\r
135                         var me = this;\r
136                         if(Ext.isObject(width)){ // in case of object from getSize()\r
137                             height = width.height;\r
138                             width = width.width;\r
139                         }\r
140                         width = me.adjustWidth(width);\r
141                         height = me.adjustHeight(height);\r
142                         if(!animate || !me.anim){\r
143                             me.dom.style.width = me.addUnits(width);\r
144                             me.dom.style.height = me.addUnits(height);\r
145                         }else{\r
146                             me.anim({width: {to: width}, height: {to: height}}, me.preanim(arguments, 2));\r
147                         }\r
148                         return me;\r
149             },\r
150 \r
151             <div id="method-Ext.Element-getComputedHeight"></div>/**\r
152              * Returns either the offsetHeight or the height of this element based on CSS height adjusted by padding or borders\r
153              * when needed to simulate offsetHeight when offsets aren't available. This may not work on display:none elements\r
154              * if a height has not been set using CSS.\r
155              * @return {Number}\r
156              */\r
157             getComputedHeight : function(){\r
158                     var me = this,\r
159                         h = Math.max(me.dom.offsetHeight, me.dom.clientHeight);\r
160                 if(!h){\r
161                     h = parseInt(me.getStyle('height'), 10) || 0;\r
162                     if(!me.isBorderBox()){\r
163                         h += me.getFrameWidth('tb');\r
164                     }\r
165                 }\r
166                 return h;\r
167             },\r
168 \r
169             <div id="method-Ext.Element-getComputedWidth"></div>/**\r
170              * Returns either the offsetWidth or the width of this element based on CSS width adjusted by padding or borders\r
171              * when needed to simulate offsetWidth when offsets aren't available. This may not work on display:none elements\r
172              * if a width has not been set using CSS.\r
173              * @return {Number}\r
174              */\r
175             getComputedWidth : function(){\r
176                 var w = Math.max(this.dom.offsetWidth, this.dom.clientWidth);\r
177                 if(!w){\r
178                     w = parseInt(this.getStyle('width'), 10) || 0;\r
179                     if(!this.isBorderBox()){\r
180                         w += this.getFrameWidth('lr');\r
181                     }\r
182                 }\r
183                 return w;\r
184             },\r
185 \r
186             <div id="method-Ext.Element-getFrameWidth"></div>/**\r
187              * Returns the sum width of the padding and borders for the passed "sides". See getBorderWidth()\r
188              for more information about the sides.\r
189              * @param {String} sides\r
190              * @return {Number}\r
191              */\r
192             getFrameWidth : function(sides, onlyContentBox){\r
193                 return onlyContentBox && this.isBorderBox() ? 0 : (this.getPadding(sides) + this.getBorderWidth(sides));\r
194             },\r
195 \r
196             <div id="method-Ext.Element-addClassOnOver"></div>/**\r
197              * Sets up event handlers to add and remove a css class when the mouse is over this element\r
198              * @param {String} className\r
199              * @return {Ext.Element} this\r
200              */\r
201             addClassOnOver : function(className){\r
202                 this.hover(\r
203                     function(){\r
204                         Ext.fly(this, INTERNAL).addClass(className);\r
205                     },\r
206                     function(){\r
207                         Ext.fly(this, INTERNAL).removeClass(className);\r
208                     }\r
209                 );\r
210                 return this;\r
211             },\r
212 \r
213             <div id="method-Ext.Element-addClassOnFocus"></div>/**\r
214              * Sets up event handlers to add and remove a css class when this element has the focus\r
215              * @param {String} className\r
216              * @return {Ext.Element} this\r
217              */\r
218             addClassOnFocus : function(className){\r
219                     this.on("focus", function(){\r
220                         Ext.fly(this, INTERNAL).addClass(className);\r
221                     }, this.dom);\r
222                     this.on("blur", function(){\r
223                         Ext.fly(this, INTERNAL).removeClass(className);\r
224                     }, this.dom);\r
225                     return this;\r
226             },\r
227 \r
228             <div id="method-Ext.Element-addClassOnClick"></div>/**\r
229              * Sets up event handlers to add and remove a css class when the mouse is down and then up on this element (a click effect)\r
230              * @param {String} className\r
231              * @return {Ext.Element} this\r
232              */\r
233             addClassOnClick : function(className){\r
234                 var dom = this.dom;\r
235                 this.on("mousedown", function(){\r
236                     Ext.fly(dom, INTERNAL).addClass(className);\r
237                     var d = Ext.getDoc(),\r
238                         fn = function(){\r
239                                 Ext.fly(dom, INTERNAL).removeClass(className);\r
240                                 d.removeListener("mouseup", fn);\r
241                             };\r
242                     d.on("mouseup", fn);\r
243                 });\r
244                 return this;\r
245             },\r
246 \r
247             <div id="method-Ext.Element-getViewSize"></div>/**\r
248              * Returns the width and height of the viewport.\r
249         * <pre><code>\r
250         var vpSize = Ext.getBody().getViewSize();\r
251 \r
252         // all Windows created afterwards will have a default value of 90% height and 95% width\r
253         Ext.Window.override({\r
254             width: vpSize.width * 0.9,\r
255             height: vpSize.height * 0.95\r
256         });\r
257         // To handle window resizing you would have to hook onto onWindowResize.\r
258         </code></pre>\r
259              * @return {Object} An object containing the viewport's size {width: (viewport width), height: (viewport height)}\r
260              */\r
261             getViewSize : function(){\r
262                 var doc = document,\r
263                         d = this.dom,\r
264                         extdom = Ext.lib.Dom,\r
265                         isDoc = (d == doc || d == doc.body);\r
266                 return { width : (isDoc ? extdom.getViewWidth() : d.clientWidth),\r
267                                  height : (isDoc ? extdom.getViewHeight() : d.clientHeight) };\r
268             },\r
269 \r
270             <div id="method-Ext.Element-getSize"></div>/**\r
271              * Returns the size of the element.\r
272              * @param {Boolean} contentSize (optional) true to get the width/size minus borders and padding\r
273              * @return {Object} An object containing the element's size {width: (element width), height: (element height)}\r
274              */\r
275             getSize : function(contentSize){\r
276                 return {width: this.getWidth(contentSize), height: this.getHeight(contentSize)};\r
277             },\r
278 \r
279             <div id="method-Ext.Element-repaint"></div>/**\r
280              * Forces the browser to repaint this element\r
281              * @return {Ext.Element} this\r
282              */\r
283             repaint : function(){\r
284                 var dom = this.dom;\r
285                 this.addClass("x-repaint");\r
286                 setTimeout(function(){\r
287                     Ext.fly(dom).removeClass("x-repaint");\r
288                 }, 1);\r
289                 return this;\r
290             },\r
291 \r
292             <div id="method-Ext.Element-unselectable"></div>/**\r
293              * Disables text selection for this element (normalized across browsers)\r
294              * @return {Ext.Element} this\r
295              */\r
296             unselectable : function(){\r
297                 this.dom.unselectable = "on";\r
298                 return this.swallowEvent("selectstart", true).\r
299                                     applyStyles("-moz-user-select:none;-khtml-user-select:none;").\r
300                                     addClass("x-unselectable");\r
301             },\r
302 \r
303             <div id="method-Ext.Element-getMargins"></div>/**\r
304              * Returns an object with properties top, left, right and bottom representing the margins of this element unless sides is passed,\r
305              * then it returns the calculated width of the sides (see getPadding)\r
306              * @param {String} sides (optional) Any combination of l, r, t, b to get the sum of those sides\r
307              * @return {Object/Number}\r
308              */\r
309             getMargins : function(side){\r
310                     var me = this,\r
311                         key,\r
312                         hash = {t:"top", l:"left", r:"right", b: "bottom"},\r
313                         o = {};\r
314 \r
315                     if (!side) {\r
316                         for (key in me.margins){\r
317                                 o[hash[key]] = parseInt(me.getStyle(me.margins[key]), 10) || 0;\r
318                 }\r
319                         return o;\r
320                 } else {\r
321                     return me.addStyles.call(me, side, me.margins);\r
322                 }\r
323             }\r
324     };\r
325 }());</pre>
326 </body>
327 </html>