libjava/java/awt/FontMetrics.java

   1 /* FontMetrics.java -- Information about about a fonts display characteristics
   2    Copyright (C) 1999, 2002 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 // FIXME: I leave many methods basically unimplemented.  This
  42 // should be reviewed.
  43
  44 /**
  45   * This class returns information about the display characteristics of
  46   * a font.  It is abstract, and concrete subclasses should implement at
  47   * least the following methods:
  48   * <p>
  49   * <ul>
  50   * <li>getAscent
  51   * <li>getDescent
  52   * <li>getLeading()
  53   * <li>getMaxAdvance()
  54   * <li>charWidth(char)
  55   * <li>charsWidth(char[], int, int)
  56   * </ul>
  57   *
  58   * @author Aaron M. Renn (arenn@urbanophile.com)
  59   */
  60 public abstract class FontMetrics implements java.io.Serializable
  61 {
  62
  63 /*
  64  * Static Variables
  65  */
  66
  67 // Serialization constant
  68 private static final long serialVersionUID = 1681126225205050147L;
  69
  70 /*************************************************************************/
  71
  72 /*
  73  * Instance Variables
  74  */
  75
  76 /**
  77   * This is the font for which metrics will be returned.
  78   */
  79 protected Font font;
  80
  81 /*************************************************************************/
  82
  83 /*
  84  * Constructors
  85  */
  86
  87 /**
  88   * Initializes a new instance of <code>FontMetrics</code> for the
  89   * specified font.
  90   *
  91   * @param font The font to return metric information for.
  92   */
  93 protected
  94 FontMetrics(Font font)
  95 {
  96   this.font = font;
  97 }
  98
  99 /*************************************************************************/
 100
 101 /*
 102  * Instance Methods
 103  */
 104
 105 /**
 106   * Returns the font that this object is creating metric information fo.
 107   *
 108   * @return The font for this object.
 109   */
 110 public Font
 111 getFont()
 112 {
 113   return(font);
 114 }
 115
 116 /*************************************************************************/
 117
 118 /**
 119   * Returns the leading, or spacing between lines, for this font.
 120   *
 121   * @return The font leading.
 122   */
 123 public int
 124 getLeading()
 125 {
 126   return(0);
 127 }
 128
 129 /*************************************************************************/
 130
 131 /**
 132   * Returns the ascent of the font, which is the distance from the base
 133   * to the top of the majority of characters in the set.  Some characters
 134   * can exceed this value however.
 135   *
 136   * @return The font ascent.
 137   */
 138 public int
 139 getAscent()
 140 {
 141   return(1);
 142 }
 143
 144 /*************************************************************************/
 145
 146 /**
 147   * Returns the descent of the font, which is the distance from the base
 148   * to the bottom of the majority of characters in the set.  Some characters
 149   * can exceed this value however.
 150   *
 151   * @return The font descent.
 152   */
 153 public int
 154 getDescent()
 155 {
 156   return(1);
 157 }
 158
 159 /*************************************************************************/
 160
 161 /**
 162   * Returns the height of a line in this font.  This will be the sum
 163   * of the leading, the ascent, and the descent.
 164   *
 165   * @return The height of the font.
 166   */
 167 public int
 168 getHeight()
 169 {
 170   return(getAscent() + getDescent() + getLeading());
 171 }
 172
 173 /*************************************************************************/
 174
 175 /**
 176   * Returns the maximum ascent value.  This is the maximum distance any
 177   * character in the font rised above the baseline.
 178   *
 179   * @return The maximum ascent for this font.
 180   */
 181 public int
 182 getMaxAscent()
 183 {
 184   return(getAscent());
 185 }
 186
 187 /*************************************************************************/
 188
 189 /**
 190   * Returns the maximum descent value.  This is the maximum distance any
 191   * character in the font extends below the baseline.
 192   *
 193   * @return The maximum descent for this font.
 194   */
 195 public int
 196 getMaxDescent()
 197 {
 198   return(getDescent());
 199 }
 200
 201 /*************************************************************************/
 202
 203 /**
 204   * Returns the maximum descent value.  This is the maximum distance any
 205   * character in the font extends below the baseline.
 206   *
 207   * @return The maximum descent for this font.
 208   *
 209   * @deprecated This method is deprecated in favor of
 210   * <code>getMaxDescent()</code>.
 211   */
 212 public int
 213 getMaxDecent()
 214 {
 215   return(getMaxDescent());
 216 }
 217
 218 /*************************************************************************/
 219
 220 /**
 221   * Returns the width of the widest character in the font.
 222   *
 223   * @return The width of the widest character in the font.
 224   */
 225 public int
 226 getMaxAdvance()
 227 {
 228   return(-1);
 229 }
 230
 231 /*************************************************************************/
 232
 233 /**
 234   * Returns the width of the specified character.
 235   *
 236   * @param ch The character to return the width of.
 237   *
 238   * @return The width of the specified character.
 239   */
 240 public int
 241 charWidth(int ch)
 242 {
 243   return(charWidth((char)ch));
 244 }
 245
 246 /*************************************************************************/
 247
 248 /**
 249   * Returns the width of the specified character.
 250   *
 251   * @param ch The character to return the width of.
 252   *
 253   * @return The width of the specified character.
 254   */
 255 public int
 256 charWidth(char ch)
 257 {
 258   return(1);
 259 }
 260
 261 /*************************************************************************/
 262
 263 /**
 264   * Returns the total width of the specified string
 265   *
 266   * @param str The string to return the width of.
 267   *
 268   * @return The width of the string.
 269   */
 270 public int
 271 stringWidth(String str)
 272 {
 273   char[] buf = new char[str.length()];
 274   str.getChars(0, str.length(), buf, 0);
 275
 276   return(charsWidth(buf, 0, buf.length));
 277 }
 278
 279 /*************************************************************************/
 280
 281 /**
 282   * Returns the total width of the specified character array.
 283   *
 284   * @param buf The character array containing the data.
 285   * @param offset The offset into the array to start calculating from.
 286   * @param len The total number of bytes to process.
 287   *
 288   * @return The width of the requested characters.
 289   */
 290 public int
 291 charsWidth(char buf[], int offset, int len)
 292 {
 293   int total_width = 0;
 294   for (int i = offset; i < len; i++)
 295     total_width = charWidth(buf[i]);
 296
 297   return(total_width);
 298 }
 299
 300 /*************************************************************************/
 301
 302 /**
 303   * Returns the total width of the specified byte array.
 304   *
 305   * @param buf The byte array containing the data.
 306   * @param offset The offset into the array to start calculating from.
 307   * @param len The total number of bytes to process.
 308   *
 309   * @return The width of the requested characters.
 310   */
 311 public int
 312 bytesWidth(byte buf[], int offset, int len)
 313 {
 314   int total_width = 0;
 315   for (int i = offset; i < len; i++)
 316     total_width = charWidth((char)buf[i]);
 317
 318   return(total_width);
 319 }
 320
 321 /*************************************************************************/
 322
 323 /**
 324   * Returns the widths of the first 256 characters in the font.
 325   *
 326   * @return The widths of the first 256 characters in the font.
 327   */
 328 public int[]
 329 getWidths()
 330 {
 331   return(new int[256]);
 332 }
 333
 334 /*************************************************************************/
 335
 336 /**
 337   * Returns a string representation of this object.
 338   *
 339   * @return A string representation of this object.
 340   */
 341 public String
 342 toString()
 343 {
 344   return (this.getClass() + "[font=" + font + ",ascent=" + getAscent()
 345           + ",descent=" + getDescent() + ",height=" + getHeight() + "]");
 346 }
 347
 348 } // class FontMetrics
 349