Source for java.awt.FontMetrics

   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:     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: }