libjava/java/awt/FontMetrics.java

   1 /* FontMetrics.java -- Information about about a fonts display characteristics
   2    Copyright (C) 1999, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt;
  40
  41 import java.awt.font.FontRenderContext;
  42 import java.awt.font.LineMetrics;
  43 import java.awt.geom.Rectangle2D;
  44 import java.text.CharacterIterator;
  45
  46 // FIXME: I leave many methods basically unimplemented.  This
  47 // should be reviewed.
  48
  49 /**
  50   * This class returns information about the display characteristics of
  51   * a font.  It is abstract, and concrete subclasses should implement at
  52   * least the following methods:
  53   *
  54   * <ul>
  55   * <li>getAscent()</li>
  56   * <li>getDescent()</li>
  57   * <li>getLeading()</li>
  58   * <li>getMaxAdvance()</li>
  59   * <li>charWidth(char)</li>
  60   * <li>charsWidth(char[], int, int)</li>
  61   * </ul>
  62   *
  63   * @author Aaron M. Renn (arenn@urbanophile.com)
  64   */
  65 public abstract class FontMetrics implements java.io.Serializable
  66 {
  67   // Serialization constant.
  68   private static final long serialVersionUID = 1681126225205050147L;
  69
  70   /**
  71    * This is the font for which metrics will be returned.
  72    */
  73   protected Font font;
  74
  75   /**
  76    * Initializes a new instance of <code>FontMetrics</code> for the
  77    * specified font.
  78    *
  79    * @param font The font to return metric information for.
  80    */
  81   protected FontMetrics(Font font)
  82   {
  83     this.font = font;
  84   }
  85
  86   /**
  87    * Returns the font that this object is creating metric information fo.
  88    *
  89    * @return The font for this object.
  90    */
  91   public Font getFont()
  92   {
  93     return font;
  94   }
  95
  96   /**
  97    * Returns the leading, or spacing between lines, for this font.
  98    *
  99    * @return The font leading.
 100    */
 101   public int getLeading()
 102   {
 103     return 0;
 104   }
 105
 106   /**
 107    * Returns the ascent of the font, which is the distance from the base
 108    * to the top of the majority of characters in the set.  Some characters
 109    * can exceed this value however.
 110    *
 111    * @return The font ascent.
 112    */
 113   public int getAscent()
 114   {
 115     return 1;
 116   }
 117
 118   /**
 119    * Returns the descent of the font, which is the distance from the base
 120    * to the bottom of the majority of characters in the set.  Some characters
 121    * can exceed this value however.
 122    *
 123    * @return The font descent.
 124    */
 125   public int getDescent()
 126   {
 127     return 1;
 128   }
 129
 130   /**
 131    * Returns the height of a line in this font.  This will be the sum
 132    * of the leading, the ascent, and the descent.
 133    *
 134    * @return The height of the font.
 135    */
 136   public int getHeight()
 137   {
 138     return getAscent() + getDescent() + getLeading();
 139   }
 140
 141   /**
 142    * Returns the maximum ascent value.  This is the maximum distance any
 143    * character in the font rised above the baseline.
 144    *
 145    * @return The maximum ascent for this font.
 146    */
 147   public int getMaxAscent()
 148   {
 149     return getAscent();
 150   }
 151
 152   /**
 153    * Returns the maximum descent value.  This is the maximum distance any
 154    * character in the font extends below the baseline.
 155    *
 156    * @return The maximum descent for this font.
 157    */
 158   public int getMaxDescent()
 159   {
 160     return getMaxDecent();
 161   }
 162
 163   /**
 164    * Returns the maximum descent value.  This is the maximum distance any
 165    * character in the font extends below the baseline.
 166    *
 167    * @return The maximum descent for this font.
 168    *
 169    * @deprecated This method is deprecated in favor of
 170    * <code>getMaxDescent()</code>.
 171    */
 172   public int getMaxDecent()
 173   {
 174     return getDescent();
 175   }
 176
 177   /**
 178    * Returns the width of the widest character in the font.
 179    *
 180    * @return The width of the widest character in the font.
 181    */
 182   public int getMaxAdvance()
 183   {
 184     return -1;
 185   }
 186
 187   /**
 188    * Returns the width of the specified character.
 189    *
 190    * @param ch The character to return the width of.
 191    *
 192    * @return The width of the specified character.
 193    */
 194   public int charWidth(int ch)
 195   {
 196     return charWidth((char) ch);
 197   }
 198
 199   /**
 200    * Returns the width of the specified character.
 201    *
 202    * @param ch The character to return the width of.
 203    *
 204    * @return The width of the specified character.
 205    */
 206   public int charWidth(char ch)
 207   {
 208     return 1;
 209   }
 210
 211   /**
 212    * Returns the total width of the specified string
 213    *
 214    * @param str The string to return the width of.
 215    *
 216    * @return The width of the string.
 217    */
 218   public int stringWidth(String str)
 219   {
 220     char[] buf = new char[str.length()];
 221     str.getChars(0, str.length(), buf, 0);
 222
 223     return charsWidth(buf, 0, buf.length);
 224   }
 225
 226   /**
 227    * Returns the total width of the specified character array.
 228    *
 229    * @param buf The character array containing the data.
 230    * @param offset The offset into the array to start calculating from.
 231    * @param len The total number of bytes to process.
 232    *
 233    * @return The width of the requested characters.
 234    */
 235   public int charsWidth(char[] buf, int offset, int len)
 236   {
 237     int total_width = 0;
 238     for (int i = offset; i < len; i++)
 239       total_width += charWidth(buf[i]);
 240     return total_width;
 241   }
 242
 243   /**
 244    * Returns the total width of the specified byte array.
 245    *
 246    * @param buf The byte array containing the data.
 247    * @param offset The offset into the array to start calculating from.
 248    * @param len The total number of bytes to process.
 249    *
 250    * @return The width of the requested characters.
 251    */
 252   public int bytesWidth(byte[] buf, int offset, int len)
 253   {
 254     int total_width = 0;
 255     for (int i = offset; i < len; i++)
 256       total_width = charWidth((char) buf[i]);
 257
 258     return total_width;
 259   }
 260
 261   /**
 262    * Returns the widths of the first 256 characters in the font.
 263    *
 264    * @return The widths of the first 256 characters in the font.
 265    */
 266   public int[] getWidths()
 267   {
 268     int[] result = new int[256];
 269     for (char i = 0; i < 256; i++)
 270       result[i] = charWidth(i);
 271     return result;
 272   }
 273
 274   /**
 275    * Returns a string representation of this object.
 276    *
 277    * @return A string representation of this object.
 278    */
 279   public String toString()
 280   {
 281     return (this.getClass() + "[font=" + font + ",ascent=" + getAscent()
 282             + ",descent=" + getDescent() + ",height=" + getHeight() + "]");
 283   }
 284
 285   // Generic FontRenderContext used when getLineMetrics is called with a
 286   // plain Graphics object.
 287   private static final FontRenderContext gRC = new FontRenderContext(null,
 288                                                                      false,
 289                                                                      false);
 290
 291   /**
 292    * Returns a {@link LineMetrics} object constructed with the
 293    * specified text and the {@link FontRenderContext} of the Graphics
 294    * object when it is an instance of Graphics2D or a generic
 295    * FontRenderContext with a null transform, not anti-aliased and not
 296    * using fractional metrics.
 297    *
 298    * @param text The string to calculate metrics from.
 299    * @param g The Graphics object that will be used.
 300    *
 301    * @return A new {@link LineMetrics} object.
 302    */
 303   public LineMetrics getLineMetrics(String text, Graphics g)
 304   {
 305     return getLineMetrics(text, 0, text.length(), g);
 306   }
 307
 308   /**
 309    * Returns a {@link LineMetrics} object constructed with the
 310    * specified text and the {@link FontRenderContext} of the Graphics
 311    * object when it is an instance of Graphics2D or a generic
 312    * FontRenderContext with a null transform, not anti-aliased and not
 313    * using fractional metrics.
 314    *
 315    * @param text The string to calculate metrics from.
 316    * @param begin Index of first character in <code>text</code> to measure.
 317    * @param limit Index of last character in <code>text</code> to measure.
 318    * @param g The Graphics object that will be used.
 319    *
 320    * @return A new {@link LineMetrics} object.
 321    *
 322    * @throws IndexOutOfBoundsException if the range [begin, limit] is
 323    * invalid in <code>text</code>.
 324    */
 325   public LineMetrics getLineMetrics(String text, int begin, int limit,
 326                                     Graphics g)
 327   {
 328     FontRenderContext rc;
 329     if (g instanceof Graphics2D)
 330       rc = ((Graphics2D) g).getFontRenderContext();
 331     else
 332       rc = gRC;
 333     return font.getLineMetrics(text, begin, limit, rc);
 334   }
 335
 336   /**
 337    * Returns a {@link LineMetrics} object constructed with the
 338    * specified text and the {@link FontRenderContext} of the Graphics
 339    * object when it is an instance of Graphics2D or a generic
 340    * FontRenderContext with a null transform, not anti-aliased and not
 341    * using fractional metrics.
 342    *
 343    * @param chars The string to calculate metrics from.
 344    * @param begin Index of first character in <code>text</code> to measure.
 345    * @param limit Index of last character in <code>text</code> to measure.
 346    * @param g The Graphics object that will be used.
 347    *
 348    * @return A new {@link LineMetrics} object.
 349    *
 350    * @throws IndexOutOfBoundsException if the range [begin, limit] is
 351    * invalid in <code>text</code>.
 352    */
 353   public LineMetrics getLineMetrics(char[] chars, int begin, int limit,
 354                                     Graphics g)
 355   {
 356     FontRenderContext rc;
 357     if (g instanceof Graphics2D)
 358       rc = ((Graphics2D) g).getFontRenderContext();
 359     else
 360       rc = gRC;
 361     return font.getLineMetrics(chars, begin, limit, rc);
 362   }
 363
 364   /**
 365    * Returns a {@link LineMetrics} object constructed with the
 366    * specified text and the {@link FontRenderContext} of the Graphics
 367    * object when it is an instance of Graphics2D or a generic
 368    * FontRenderContext with a null transform, not anti-aliased and not
 369    * using fractional metrics.
 370    *
 371    * @param ci An iterator over the string to calculate metrics from.
 372    * @param begin Index of first character in <code>text</code> to measure.
 373    * @param limit Index of last character in <code>text</code> to measure.
 374    * @param g The Graphics object that will be used.
 375    *
 376    * @return A new {@link LineMetrics} object.
 377    *
 378    * @throws IndexOutOfBoundsException if the range [begin, limit] is
 379    * invalid in <code>text</code>.
 380    */
 381   public LineMetrics getLineMetrics(CharacterIterator ci, int begin,
 382                                     int limit, Graphics g)
 383   {
 384     FontRenderContext rc;
 385     if (g instanceof Graphics2D)
 386       rc = ((Graphics2D) g).getFontRenderContext();
 387     else
 388       rc = gRC;
 389     return font.getLineMetrics(ci, begin, limit, rc);
 390   }
 391
 392   public Rectangle2D getStringBounds(String str, Graphics context)
 393   {
 394     return font.getStringBounds(str, getFontRenderContext(context));
 395   }
 396
 397   public Rectangle2D getStringBounds(String str, int beginIndex, int limit,
 398                                      Graphics context)
 399   {
 400     return font.getStringBounds(str, beginIndex, limit,
 401                                 getFontRenderContext(context));
 402   }
 403
 404   public Rectangle2D getStringBounds(char[] chars, int beginIndex, int limit,
 405                                      Graphics context)
 406   {
 407     return font.getStringBounds(chars, beginIndex, limit,
 408                                 getFontRenderContext(context));
 409   }
 410
 411   public Rectangle2D getStringBounds(CharacterIterator ci, int beginIndex,
 412                                      int limit, Graphics context)
 413   {
 414     return font.getStringBounds(ci, beginIndex, limit,
 415                                 getFontRenderContext(context));
 416   }
 417
 418   private FontRenderContext getFontRenderContext(Graphics context)
 419   {
 420     if (context instanceof Graphics2D)
 421       return ((Graphics2D) context).getFontRenderContext();
 422
 423     return gRC;
 424   }
 425 }