src/util/TextMetrics.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * Provides precise pixel measurements for blocks of text so that you can determine exactly how high and
  17  * wide, in pixels, a given block of text will be. Note that when measuring text, it should be plain text and
  18  * should not contain any HTML, otherwise it may not be measured correctly.
  19  *
  20  * The measurement works by copying the relevant CSS styles that can affect the font related display,
  21  * then checking the size of an element that is auto-sized. Note that if the text is multi-lined, you must
  22  * provide a **fixed width** when doing the measurement.
  23  *
  24  * If multiple measurements are being done on the same element, you create a new instance to initialize
  25  * to avoid the overhead of copying the styles to the element repeatedly.
  26  */
  27 Ext.define('Ext.util.TextMetrics', {
  28     statics: {
  29         shared: null,
  30         /**
  31          * Measures the size of the specified text
  32          * @param {String/HTMLElement} el The element, dom node or id from which to copy existing CSS styles
  33          * that can affect the size of the rendered text
  34          * @param {String} text The text to measure
  35          * @param {Number} fixedWidth (optional) If the text will be multiline, you have to set a fixed width
  36          * in order to accurately measure the text height
  37          * @return {Object} An object containing the text's size `{width: (width), height: (height)}`
  38          */
  39         measure: function(el, text, fixedWidth){
  40             var me = this,
  41                 shared = me.shared;
  42
  43             if(!shared){
  44                 shared = me.shared = new me(el, fixedWidth);
  45             }
  46             shared.bind(el);
  47             shared.setFixedWidth(fixedWidth || 'auto');
  48             return shared.getSize(text);
  49         },
  50
  51         /**
  52           * Destroy the TextMetrics instance created by {@link #measure}.
  53           */
  54          destroy: function(){
  55              var me = this;
  56              Ext.destroy(me.shared);
  57              me.shared = null;
  58          }
  59     },
  60
  61     /**
  62      * Creates new TextMetrics.
  63      * @param {String/HTMLElement/Ext.Element} bindTo The element or its ID to bind to.
  64      * @param {Number} fixedWidth (optional) A fixed width to apply to the measuring element.
  65      */
  66     constructor: function(bindTo, fixedWidth){
  67         var measure = this.measure = Ext.getBody().createChild({
  68             cls: 'x-textmetrics'
  69         });
  70         this.el = Ext.get(bindTo);
  71
  72         measure.position('absolute');
  73         measure.setLeftTop(-1000, -1000);
  74         measure.hide();
  75
  76         if (fixedWidth) {
  77            measure.setWidth(fixedWidth);
  78         }
  79     },
  80
  81     /**
  82      * Returns the size of the specified text based on the internal element's style and width properties
  83      * @param {String} text The text to measure
  84      * @return {Object} An object containing the text's size `{width: (width), height: (height)}`
  85      */
  86     getSize: function(text){
  87         var measure = this.measure,
  88             size;
  89
  90         measure.update(text);
  91         size = measure.getSize();
  92         measure.update('');
  93         return size;
  94     },
  95
  96     /**
  97      * Binds this TextMetrics instance to a new element
  98      * @param {String/HTMLElement/Ext.Element} el The element or its ID.
  99      */
 100     bind: function(el){
 101         var me = this;
 102
 103         me.el = Ext.get(el);
 104         me.measure.setStyle(
 105             me.el.getStyles('font-size','font-style', 'font-weight', 'font-family','line-height', 'text-transform', 'letter-spacing')
 106         );
 107     },
 108
 109     /**
 110      * Sets a fixed width on the internal measurement element.  If the text will be multiline, you have
 111      * to set a fixed width in order to accurately measure the text height.
 112      * @param {Number} width The width to set on the element
 113      */
 114      setFixedWidth : function(width){
 115          this.measure.setWidth(width);
 116      },
 117
 118      /**
 119       * Returns the measured width of the specified text
 120       * @param {String} text The text to measure
 121       * @return {Number} width The width in pixels
 122       */
 123      getWidth : function(text){
 124          this.measure.dom.style.width = 'auto';
 125          return this.getSize(text).width;
 126      },
 127
 128      /**
 129       * Returns the measured height of the specified text
 130       * @param {String} text The text to measure
 131       * @return {Number} height The height in pixels
 132       */
 133      getHeight : function(text){
 134          return this.getSize(text).height;
 135      },
 136
 137      /**
 138       * Destroy this instance
 139       */
 140      destroy: function(){
 141          var me = this;
 142          me.measure.remove();
 143          delete me.el;
 144          delete me.measure;
 145      }
 146 }, function(){
 147     Ext.Element.addMethods({
 148         /**
 149          * Returns the width in pixels of the passed text, or the width of the text in this Element.
 150          * @param {String} text The text to measure. Defaults to the innerHTML of the element.
 151          * @param {Number} min (optional) The minumum value to return.
 152          * @param {Number} max (optional) The maximum value to return.
 153          * @return {Number} The text width in pixels.
 154          * @member Ext.Element
 155          */
 156         getTextWidth : function(text, min, max){
 157             return Ext.Number.constrain(Ext.util.TextMetrics.measure(this.dom, Ext.value(text, this.dom.innerHTML, true)).width, min || 0, max || 1000000);
 158         }
 159     });
 160 });
 161