Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / TextMetrics.html
index f433be0..93acaae 100644 (file)
+<!DOCTYPE html>
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
 </head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.3.0
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-<div id="cls-Ext.util.TextMetrics"></div>/**
- * @class Ext.util.TextMetrics
- * Provides precise pixel measurements for blocks of text so that you can determine exactly how high and
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-util-TextMetrics'>/**
+</span> * Provides precise pixel measurements for blocks of text so that you can determine exactly how high and
  * wide, in pixels, a given block of text will be. Note that when measuring text, it should be plain text and
  * should not contain any HTML, otherwise it may not be measured correctly.
- * @singleton
+ *
+ * The measurement works by copying the relevant CSS styles that can affect the font related display, 
+ * then checking the size of an element that is auto-sized. Note that if the text is multi-lined, you must 
+ * provide a **fixed width** when doing the measurement.
+ *
+ * If multiple measurements are being done on the same element, you create a new instance to initialize 
+ * to avoid the overhead of copying the styles to the element repeatedly.
  */
-Ext.util.TextMetrics = function(){
-    var shared;
-    return {
-        <div id="method-Ext.util.TextMetrics-measure"></div>/**
-         * Measures the size of the specified text
+Ext.define('Ext.util.TextMetrics', {
+    statics: {
+        shared: null,
+<span id='Ext-util-TextMetrics-method-measure'>        /**
+</span>         * Measures the size of the specified text
          * @param {String/HTMLElement} el The element, dom node or id from which to copy existing CSS styles
          * that can affect the size of the rendered text
          * @param {String} text The text to measure
          * @param {Number} fixedWidth (optional) If the text will be multiline, you have to set a fixed width
          * in order to accurately measure the text height
-         * @return {Object} An object containing the text's size {width: (width), height: (height)}
+         * @return {Object} An object containing the text's size `{width: (width), height: (height)}`
          */
-        measure : function(el, text, fixedWidth){
+        measure: function(el, text, fixedWidth){
+            var me = this,
+                shared = me.shared;
+            
             if(!shared){
-                shared = Ext.util.TextMetrics.Instance(el, fixedWidth);
+                shared = me.shared = new me(el, fixedWidth);
             }
             shared.bind(el);
             shared.setFixedWidth(fixedWidth || 'auto');
             return shared.getSize(text);
         },
+        
+<span id='Ext-util-TextMetrics-method-destroy'>        /**
+</span>          * Destroy the TextMetrics instance created by {@link #measure}.
+          */
+         destroy: function(){
+             var me = this;
+             Ext.destroy(me.shared);
+             me.shared = null;
+         }
+    },
+    
+<span id='Ext-util-TextMetrics-method-constructor'>    /**
+</span>     * Creates new TextMetrics.
+     * @param {Mixed} bindTo The element to bind to.
+     * @param {Number} fixedWidth (optional) A fixed width to apply to the measuring element.
+     */
+    constructor: function(bindTo, fixedWidth){
+        var measure = this.measure = Ext.getBody().createChild({
+            cls: 'x-textmetrics'
+        });
+        this.el = Ext.get(bindTo);
+        
+        measure.position('absolute');
+        measure.setLeftTop(-1000, -1000);
+        measure.hide();
 
-        <div id="method-Ext.util.TextMetrics-createInstance"></div>/**
-         * Return a unique TextMetrics instance that can be bound directly to an element and reused.  This reduces
-         * the overhead of multiple calls to initialize the style properties on each measurement.
-         * @param {String/HTMLElement} el The element, dom node or id that the instance will be bound to
-         * @param {Number} fixedWidth (optional) If the text will be multiline, you have to set a fixed width
-         * in order to accurately measure the text height
-         * @return {Ext.util.TextMetrics.Instance} instance The new instance
-         */
-        createInstance : function(el, fixedWidth){
-            return Ext.util.TextMetrics.Instance(el, fixedWidth);
+        if (fixedWidth) {
+           measure.setWidth(fixedWidth);
         }
-    };
-}();
-
-Ext.util.TextMetrics.Instance = function(bindTo, fixedWidth){
-    var ml = new Ext.Element(document.createElement('div'));
-    document.body.appendChild(ml.dom);
-    ml.position('absolute');
-    ml.setLeftTop(-1000, -1000);
-    ml.hide();
-
-    if(fixedWidth){
-        ml.setWidth(fixedWidth);
-    }
-
-    var instance = {
-        <div id="method-Ext.util.TextMetrics-getSize"></div>/**
-         * <p><b>Only available on the instance returned from {@link #createInstance}, <u>not</u> on the singleton.</b></p>
-         * Returns the size of the specified text based on the internal element's style and width properties
-         * @param {String} text The text to measure
-         * @return {Object} An object containing the text's size {width: (width), height: (height)}
-         */
-        getSize : function(text){
-            ml.update(text);
-            var s = ml.getSize();
-            ml.update('');
-            return s;
-        },
-
-        <div id="method-Ext.util.TextMetrics-bind"></div>/**
-         * <p><b>Only available on the instance returned from {@link #createInstance}, <u>not</u> on the singleton.</b></p>
-         * Binds this TextMetrics instance to an element from which to copy existing CSS styles
-         * that can affect the size of the rendered text
-         * @param {String/HTMLElement} el The element, dom node or id
-         */
-        bind : function(el){
-            ml.setStyle(
-                Ext.fly(el).getStyles('font-size','font-style', 'font-weight', 'font-family','line-height', 'text-transform', 'letter-spacing')
-            );
-        },
-
-        <div id="method-Ext.util.TextMetrics-setFixedWidth"></div>/**
-         * <p><b>Only available on the instance returned from {@link #createInstance}, <u>not</u> on the singleton.</b></p>
-         * Sets a fixed width on the internal measurement element.  If the text will be multiline, you have
-         * to set a fixed width in order to accurately measure the text height.
-         * @param {Number} width The width to set on the element
-         */
-        setFixedWidth : function(width){
-            ml.setWidth(width);
-        },
-
-        <div id="method-Ext.util.TextMetrics-getWidth"></div>/**
-         * <p><b>Only available on the instance returned from {@link #createInstance}, <u>not</u> on the singleton.</b></p>
-         * Returns the measured width of the specified text
-         * @param {String} text The text to measure
-         * @return {Number} width The width in pixels
-         */
-        getWidth : function(text){
-            ml.dom.style.width = 'auto';
-            return this.getSize(text).width;
-        },
-
-        <div id="method-Ext.util.TextMetrics-getHeight"></div>/**
-         * <p><b>Only available on the instance returned from {@link #createInstance}, <u>not</u> on the singleton.</b></p>
-         * Returns the measured height of the specified text.  For multiline text, be sure to call
-         * {@link #setFixedWidth} if necessary.
-         * @param {String} text The text to measure
-         * @return {Number} height The height in pixels
+    },
+    
+<span id='Ext-util-TextMetrics-method-getSize'>    /**
+</span>     * Returns the size of the specified text based on the internal element's style and width properties
+     * @param {String} text The text to measure
+     * @return {Object} An object containing the text's size `{width: (width), height: (height)}`
+     */
+    getSize: function(text){
+        var measure = this.measure,
+            size;
+        
+        measure.update(text);
+        size = measure.getSize();
+        measure.update('');
+        return size;
+    },
+    
+<span id='Ext-util-TextMetrics-method-bind'>    /**
+</span>     * Binds this TextMetrics instance to a new element
+     * @param {Mixed} el The element
+     */
+    bind: function(el){
+        var me = this;
+        
+        me.el = Ext.get(el);
+        me.measure.setStyle(
+            me.el.getStyles('font-size','font-style', 'font-weight', 'font-family','line-height', 'text-transform', 'letter-spacing')
+        );
+    },
+    
+<span id='Ext-util-TextMetrics-method-setFixedWidth'>    /**
+</span>     * Sets a fixed width on the internal measurement element.  If the text will be multiline, you have
+     * to set a fixed width in order to accurately measure the text height.
+     * @param {Number} width The width to set on the element
+     */
+     setFixedWidth : function(width){
+         this.measure.setWidth(width);
+     },
+     
+<span id='Ext-util-TextMetrics-method-getWidth'>     /**
+</span>      * Returns the measured width of the specified text
+      * @param {String} text The text to measure
+      * @return {Number} width The width in pixels
+      */
+     getWidth : function(text){
+         this.measure.dom.style.width = 'auto';
+         return this.getSize(text).width;
+     },
+     
+<span id='Ext-util-TextMetrics-method-getHeight'>     /**
+</span>      * Returns the measured height of the specified text
+      * @param {String} text The text to measure
+      * @return {Number} height The height in pixels
+      */
+     getHeight : function(text){
+         return this.getSize(text).height;
+     },
+     
+<span id='Ext-util-TextMetrics-method-destroy'>     /**
+</span>      * Destroy this instance
+      */
+     destroy: function(){
+         var me = this;
+         me.measure.remove();
+         delete me.el;
+         delete me.measure;
+     }
+}, function(){
+    Ext.core.Element.addMethods({
+<span id='Ext-core-Element-method-getTextWidth'>        /**
+</span>         * Returns the width in pixels of the passed text, or the width of the text in this Element.
+         * @param {String} text The text to measure. Defaults to the innerHTML of the element.
+         * @param {Number} min (optional) The minumum value to return.
+         * @param {Number} max (optional) The maximum value to return.
+         * @return {Number} The text width in pixels.
+         * @member Ext.core.Element
          */
-        getHeight : function(text){
-            return this.getSize(text).height;
+        getTextWidth : function(text, min, max){
+            return Ext.Number.constrain(Ext.util.TextMetrics.measure(this.dom, Ext.value(text, this.dom.innerHTML, true)).width, min || 0, max || 1000000);
         }
-    };
-
-    instance.bind(bindTo);
-
-    return instance;
-};
-
-Ext.Element.addMethods({
-    <div id="method-Ext.Element-getTextWidth"></div>/**
-     * Returns the width in pixels of the passed text, or the width of the text in this Element.
-     * @param {String} text The text to measure. Defaults to the innerHTML of the element.
-     * @param {Number} min (Optional) The minumum value to return.
-     * @param {Number} max (Optional) The maximum value to return.
-     * @return {Number} The text width in pixels.
-     * @member Ext.Element getTextWidth
-     */
-    getTextWidth : function(text, min, max){
-        return (Ext.util.TextMetrics.measure(this.dom, Ext.value(text, this.dom.innerHTML, true)).width).constrain(min || 0, max || 1000000);
-    }
+    });
 });
-</pre>    
+</pre>
 </body>
-</html>
\ No newline at end of file
+</html>