Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / TextMetrics.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-util-TextMetrics'>/**
19 </span> * Provides precise pixel measurements for blocks of text so that you can determine exactly how high and
20  * wide, in pixels, a given block of text will be. Note that when measuring text, it should be plain text and
21  * should not contain any HTML, otherwise it may not be measured correctly.
22  *
23  * The measurement works by copying the relevant CSS styles that can affect the font related display, 
24  * then checking the size of an element that is auto-sized. Note that if the text is multi-lined, you must 
25  * provide a **fixed width** when doing the measurement.
26  *
27  * If multiple measurements are being done on the same element, you create a new instance to initialize 
28  * to avoid the overhead of copying the styles to the element repeatedly.
29  */
30 Ext.define('Ext.util.TextMetrics', {
31     statics: {
32         shared: null,
33 <span id='Ext-util-TextMetrics-method-measure'>        /**
34 </span>         * Measures the size of the specified text
35          * @param {String/HTMLElement} el The element, dom node or id from which to copy existing CSS styles
36          * that can affect the size of the rendered text
37          * @param {String} text The text to measure
38          * @param {Number} fixedWidth (optional) If the text will be multiline, you have to set a fixed width
39          * in order to accurately measure the text height
40          * @return {Object} An object containing the text's size `{width: (width), height: (height)}`
41          */
42         measure: function(el, text, fixedWidth){
43             var me = this,
44                 shared = me.shared;
45             
46             if(!shared){
47                 shared = me.shared = new me(el, fixedWidth);
48             }
49             shared.bind(el);
50             shared.setFixedWidth(fixedWidth || 'auto');
51             return shared.getSize(text);
52         },
53         
54 <span id='Ext-util-TextMetrics-method-destroy'>        /**
55 </span>          * Destroy the TextMetrics instance created by {@link #measure}.
56           */
57          destroy: function(){
58              var me = this;
59              Ext.destroy(me.shared);
60              me.shared = null;
61          }
62     },
63     
64 <span id='Ext-util-TextMetrics-method-constructor'>    /**
65 </span>     * Creates new TextMetrics.
66      * @param {Mixed} bindTo The element to bind to.
67      * @param {Number} fixedWidth (optional) A fixed width to apply to the measuring element.
68      */
69     constructor: function(bindTo, fixedWidth){
70         var measure = this.measure = Ext.getBody().createChild({
71             cls: 'x-textmetrics'
72         });
73         this.el = Ext.get(bindTo);
74         
75         measure.position('absolute');
76         measure.setLeftTop(-1000, -1000);
77         measure.hide();
78
79         if (fixedWidth) {
80            measure.setWidth(fixedWidth);
81         }
82     },
83     
84 <span id='Ext-util-TextMetrics-method-getSize'>    /**
85 </span>     * Returns the size of the specified text based on the internal element's style and width properties
86      * @param {String} text The text to measure
87      * @return {Object} An object containing the text's size `{width: (width), height: (height)}`
88      */
89     getSize: function(text){
90         var measure = this.measure,
91             size;
92         
93         measure.update(text);
94         size = measure.getSize();
95         measure.update('');
96         return size;
97     },
98     
99 <span id='Ext-util-TextMetrics-method-bind'>    /**
100 </span>     * Binds this TextMetrics instance to a new element
101      * @param {Mixed} el The element
102      */
103     bind: function(el){
104         var me = this;
105         
106         me.el = Ext.get(el);
107         me.measure.setStyle(
108             me.el.getStyles('font-size','font-style', 'font-weight', 'font-family','line-height', 'text-transform', 'letter-spacing')
109         );
110     },
111     
112 <span id='Ext-util-TextMetrics-method-setFixedWidth'>    /**
113 </span>     * Sets a fixed width on the internal measurement element.  If the text will be multiline, you have
114      * to set a fixed width in order to accurately measure the text height.
115      * @param {Number} width The width to set on the element
116      */
117      setFixedWidth : function(width){
118          this.measure.setWidth(width);
119      },
120      
121 <span id='Ext-util-TextMetrics-method-getWidth'>     /**
122 </span>      * Returns the measured width of the specified text
123       * @param {String} text The text to measure
124       * @return {Number} width The width in pixels
125       */
126      getWidth : function(text){
127          this.measure.dom.style.width = 'auto';
128          return this.getSize(text).width;
129      },
130      
131 <span id='Ext-util-TextMetrics-method-getHeight'>     /**
132 </span>      * Returns the measured height of the specified text
133       * @param {String} text The text to measure
134       * @return {Number} height The height in pixels
135       */
136      getHeight : function(text){
137          return this.getSize(text).height;
138      },
139      
140 <span id='Ext-util-TextMetrics-method-destroy'>     /**
141 </span>      * Destroy this instance
142       */
143      destroy: function(){
144          var me = this;
145          me.measure.remove();
146          delete me.el;
147          delete me.measure;
148      }
149 }, function(){
150     Ext.core.Element.addMethods({
151 <span id='Ext-core-Element-method-getTextWidth'>        /**
152 </span>         * Returns the width in pixels of the passed text, or the width of the text in this Element.
153          * @param {String} text The text to measure. Defaults to the innerHTML of the element.
154          * @param {Number} min (optional) The minumum value to return.
155          * @param {Number} max (optional) The maximum value to return.
156          * @return {Number} The text width in pixels.
157          * @member Ext.core.Element
158          */
159         getTextWidth : function(text, min, max){
160             return Ext.Number.constrain(Ext.util.TextMetrics.measure(this.dom, Ext.value(text, this.dom.innerHTML, true)).width, min || 0, max || 1000000);
161         }
162     });
163 });
164 </pre>
165 </body>
166 </html>