libjava/classpath/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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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     char[] chars = Character.toChars(ch);
 197     return charsWidth(chars, 0, chars.length);
 198   }
 199
 200   /**
 201    * Returns the width of the specified character.
 202    *
 203    * @param ch The character to return the width of.
 204    *
 205    * @return The width of the specified character.
 206    */
 207   public int charWidth(char ch)
 208   {
 209     return 1;
 210   }
 211
 212   /**
 213    * Returns the total width of the specified string
 214    *
 215    * @param str The string to return the width of.
 216    *
 217    * @return The width of the string.
 218    */
 219   public int stringWidth(String str)
 220   {
 221     char[] buf = new char[str.length()];
 222     str.getChars(0, str.length(), buf, 0);
 223
 224     return charsWidth(buf, 0, buf.length);
 225   }
 226
 227   /**
 228    * Returns the total width of the specified character array.
 229    *
 230    * @param buf The character array containing the data.
 231    * @param offset The offset into the array to start calculating from.
 232    * @param len The total number of bytes to process.
 233    *
 234    * @return The width of the requested characters.
 235    */
 236   public int charsWidth(char[] buf, int offset, int len)
 237   {
 238     int total_width = 0;
 239     int endOffset = offset + len;
 240     for (int i = offset; i < endOffset; i++)
 241       total_width += charWidth(buf[i]);
 242     return total_width;
 243   }
 244
 245   /**
 246    * Returns the total width of the specified byte array.
 247    *
 248    * @param buf The byte array containing the data.
 249    * @param offset The offset into the array to start calculating from.
 250    * @param len The total number of bytes to process.
 251    *
 252    * @return The width of the requested characters.
 253    */
 254   public int bytesWidth(byte[] buf, int offset, int len)
 255   {
 256     int total_width = 0;
 257     for (int i = offset; i < len; i++)
 258       total_width = charWidth((char) buf[i]);
 259
 260     return total_width;
 261   }
 262
 263   /**
 264    * Returns the widths of the first 256 characters in the font.
 265    *
 266    * @return The widths of the first 256 characters in the font.
 267    */
 268   public int[] getWidths()
 269   {
 270     int[] result = new int[256];
 271     for (char i = 0; i < 256; i++)
 272       result[i] = charWidth(i);
 273     return result;
 274   }
 275
 276   /**
 277    * Returns a string representation of this object.
 278    *
 279    * @return A string representation of this object.
 280    */
 281   public String toString()
 282   {
 283     return (this.getClass() + "[font=" + font + ",ascent=" + getAscent()
 284             + ",descent=" + getDescent() + ",height=" + getHeight() + "]");
 285   }
 286
 287   // Generic FontRenderContext used when getLineMetrics is called with a
 288   // plain Graphics object.
 289   private static final FontRenderContext gRC = new FontRenderContext(null,
 290                                                                      false,
 291                                                                      false);
 292
 293   /**
 294    * Returns a {@link LineMetrics} object constructed with the
 295    * specified text and the {@link FontRenderContext} of the Graphics
 296    * object when it is an instance of Graphics2D or a generic
 297    * FontRenderContext with a null transform, not anti-aliased and not
 298    * using fractional metrics.
 299    *
 300    * @param text The string to calculate metrics from.
 301    * @param g The Graphics object that will be used.
 302    *
 303    * @return A new {@link LineMetrics} object.
 304    */
 305   public LineMetrics getLineMetrics(String text, Graphics g)
 306   {
 307     return getLineMetrics(text, 0, text.length(), g);
 308   }
 309
 310   /**
 311    * Returns a {@link LineMetrics} object constructed with the
 312    * specified text and the {@link FontRenderContext} of the Graphics
 313    * object when it is an instance of Graphics2D or a generic
 314    * FontRenderContext with a null transform, not anti-aliased and not
 315    * using fractional metrics.
 316    *
 317    * @param text The string to calculate metrics from.
 318    * @param begin Index of first character in <code>text</code> to measure.
 319    * @param limit Index of last character in <code>text</code> to measure.
 320    * @param g The Graphics object that will be used.
 321    *
 322    * @return A new {@link LineMetrics} object.
 323    *
 324    * @throws IndexOutOfBoundsException if the range [begin, limit] is
 325    * invalid in <code>text</code>.
 326    */
 327   public LineMetrics getLineMetrics(String text, int begin, int limit,
 328                                     Graphics g)
 329   {
 330     FontRenderContext rc;
 331     if (g instanceof Graphics2D)
 332       rc = ((Graphics2D) g).getFontRenderContext();
 333     else
 334       rc = gRC;
 335     return font.getLineMetrics(text, begin, limit, rc);
 336   }
 337
 338   /**
 339    * Returns a {@link LineMetrics} object constructed with the
 340    * specified text and the {@link FontRenderContext} of the Graphics
 341    * object when it is an instance of Graphics2D or a generic
 342    * FontRenderContext with a null transform, not anti-aliased and not
 343    * using fractional metrics.
 344    *
 345    * @param chars The string to calculate metrics from.
 346    * @param begin Index of first character in <code>text</code> to measure.
 347    * @param limit Index of last character in <code>text</code> to measure.
 348    * @param g The Graphics object that will be used.
 349    *
 350    * @return A new {@link LineMetrics} object.
 351    *
 352    * @throws IndexOutOfBoundsException if the range [begin, limit] is
 353    * invalid in <code>text</code>.
 354    */
 355   public LineMetrics getLineMetrics(char[] chars, int begin, int limit,
 356                                     Graphics g)
 357   {
 358     FontRenderContext rc;
 359     if (g instanceof Graphics2D)
 360       rc = ((Graphics2D) g).getFontRenderContext();
 361     else
 362       rc = gRC;
 363     return font.getLineMetrics(chars, begin, limit, rc);
 364   }
 365
 366   /**
 367    * Returns the bounds of the largest character in a Graphics context.
 368    * @param context the Graphics context object.
 369    * @return a <code>Rectangle2D</code> representing the bounds
 370    */
 371   public Rectangle2D getMaxCharBounds(Graphics context)
 372   {
 373     if( context instanceof Graphics2D )
 374       return font.getMaxCharBounds(((Graphics2D)context).getFontRenderContext());
 375     return font.getMaxCharBounds( gRC );
 376   }
 377
 378   /**
 379    * Returns a {@link LineMetrics} object constructed with the
 380    * specified text and the {@link FontRenderContext} of the Graphics
 381    * object when it is an instance of Graphics2D or a generic
 382    * FontRenderContext with a null transform, not anti-aliased and not
 383    * using fractional metrics.
 384    *
 385    * @param ci An iterator over the string to calculate metrics from.
 386    * @param begin Index of first character in <code>text</code> to measure.
 387    * @param limit Index of last character in <code>text</code> to measure.
 388    * @param g The Graphics object that will be used.
 389    *
 390    * @return A new {@link LineMetrics} object.
 391    *
 392    * @throws IndexOutOfBoundsException if the range [begin, limit] is
 393    * invalid in <code>text</code>.
 394    */
 395   public LineMetrics getLineMetrics(CharacterIterator ci, int begin,
 396                                     int limit, Graphics g)
 397   {
 398     FontRenderContext rc;
 399     if (g instanceof Graphics2D)
 400       rc = ((Graphics2D) g).getFontRenderContext();
 401     else
 402       rc = gRC;
 403     return font.getLineMetrics(ci, begin, limit, rc);
 404   }
 405
 406   public Rectangle2D getStringBounds(String str, Graphics context)
 407   {
 408     return font.getStringBounds(str, getFontRenderContext(context));
 409   }
 410
 411   public Rectangle2D getStringBounds(String str, int beginIndex, int limit,
 412                                      Graphics context)
 413   {
 414     return font.getStringBounds(str, beginIndex, limit,
 415                                 getFontRenderContext(context));
 416   }
 417
 418   public Rectangle2D getStringBounds(char[] chars, int beginIndex, int limit,
 419                                      Graphics context)
 420   {
 421     return font.getStringBounds(chars, beginIndex, limit,
 422                                 getFontRenderContext(context));
 423   }
 424
 425   public Rectangle2D getStringBounds(CharacterIterator ci, int beginIndex,
 426                                      int limit, Graphics context)
 427   {
 428     return font.getStringBounds(ci, beginIndex, limit,
 429                                 getFontRenderContext(context));
 430   }
 431
 432   private FontRenderContext getFontRenderContext(Graphics context)
 433   {
 434     if (context instanceof Graphics2D)
 435       return ((Graphics2D) context).getFontRenderContext();
 436
 437     return gRC;
 438   }
 439
 440   /**
 441    * Returns if the font has uniform line metrics.
 442    * @see Font#hasUniformLineMetrics()
 443    */
 444   public boolean hasUniformLineMetrics()
 445   {
 446     return font.hasUniformLineMetrics();
 447   }
 448 }