FontMetrics


1   /*
2    * @(#)FontMetrics.java 1.53 04/05/18
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt;
9   
10  import java.awt.Graphics2D  ;
11  import java.awt.font.FontRenderContext  ;
12  import java.awt.font.LineMetrics  ;
13  import java.awt.geom.Rectangle2D  ;
14  import java.text.CharacterIterator  ;
15  
16  /**
17   * The <code>FontMetrics</code> class defines a font metrics object, which
18   * encapsulates information about the rendering of a particular font on a
19   * particular screen. 
20   * <p>
21   * <b>Note to subclassers</b>: Since many of these methods form closed,
22   * mutually recursive loops, you must take care that you implement
23   * at least one of the methods in each such loop to prevent
24   * infinite recursion when your subclass is used.
25   * In particular, the following is the minimal suggested set of methods
26   * to override in order to ensure correctness and prevent infinite
27   * recursion (though other subsets are equally feasible):
28   * <ul>
29   * <li>{@link #getAscent()}
30   * <li>{@link #getLeading()}
31   * <li>{@link #getMaxAdvance()}
32   * <li>{@link #charWidth(char)}
33   * <li>{@link #charsWidth(char[], int, int)}
34   * </ul>
35   * <p>
36   * <img SRC="doc-files/FontMetrics-1.gif" alt="The letter 'p' showing its 'reference point'" border=15 align
37   * ALIGN=right HSPACE=10 VSPACE=7>
38   * Note that the implementations of these methods are
39   * inefficient, so they are usually overridden with more efficient
40   * toolkit-specific implementations.
41   * <p>
42   * When an application asks AWT to place a character at the position
43   * (<i>x</i>,&nbsp;<i>y</i>), the character is placed so that its
44   * reference point (shown as the dot in the accompanying image) is
45   * put at that position. The reference point specifies a horizontal
46   * line called the <i>baseline</i> of the character. In normal
47   * printing, the baselines of characters should align.
48   * <p>
49   * In addition, every character in a font has an <i>ascent</i>, a
50   * <i>descent</i>, and an <i>advance width</i>. The ascent is the
51   * amount by which the character ascends above the baseline. The
52   * descent is the amount by which the character descends below the
53   * baseline. The advance width indicates the position at which AWT
54   * should place the next character.
55   * <p>
56   * An array of characters or a string can also have an ascent, a
57   * descent, and an advance width. The ascent of the array is the
58   * maximum ascent of any character in the array. The descent is the
59   * maximum descent of any character in the array. The advance width
60   * is the sum of the advance widths of each of the characters in the
61   * character array.  The advance of a <code>String</code> is the
62   * distance along the baseline of the <code>String</code>.  This 
63   * distance is the width that should be used for centering or 
64   * right-aligning the <code>String</code>.
65   * Note that the advance of a <code>String</code> is not necessarily 
66   * the sum of the advances of its characters measured in isolation 
67   * because the width of a character can vary depending on its context.  
68   * For example, in Arabic text, the shape of a character can change 
69   * in order to connect to other characters.  Also, in some scripts, 
70   * certain character sequences can be represented by a single shape, 
71   * called a <em>ligature</em>.  Measuring characters individually does
72   * not account for these transformations.
73   *
74   * @version     1.53 05/18/04
75   * @author  Jim Graham
76   * @see         java.awt.Font
77   * @since       JDK1.0
78   */
79  public abstract class FontMetrics implements java.io.Serializable   {
80  
81      static {
82          /* ensure that the necessary native libraries are loaded */
83      Toolkit.loadLibraries();
84          if (!GraphicsEnvironment.isHeadless()) {
85              initIDs();
86          }
87      }
88  
89      /**
90       * The actual {@link Font} from which the font metrics are
91       * created. 
92       * This cannot be null.
93       *
94       * @serial
95       * @see #getFont()
96       */
97      protected Font   font;
98  
99      /*
100      * JDK 1.1 serialVersionUID
101      */
102     private static final long serialVersionUID = 1681126225205050147L;
103 
104     /**
105      * Creates a new <code>FontMetrics</code> object for finding out
106      * height and width information about the specified <code>Font</code> 
107      * and specific character glyphs in that <code>Font</code>.
108      * @param     font the <code>Font</code>
109      * @see       java.awt.Font
110      */
111     protected FontMetrics(Font   font) {
112     this.font = font;
113     }
114 
115     /**
116      * Gets the <code>Font</code> described by this
117      * <code>FontMetrics</code> object.
118      * @return    the <code>Font</code> described by this 
119      * <code>FontMetrics</code> object.
120      */
121     public Font   getFont() {
122     return font;
123     }
124 
125     /**
126      * Determines the <em>standard leading</em> of the 
127      * <code>Font</code> described by this <code>FontMetrics</code>
128      * object.  The standard leading, or
129      * interline spacing, is the logical amount of space to be reserved
130      * between the descent of one line of text and the ascent of the next
131      * line. The height metric is calculated to include this extra space.
132      * @return    the standard leading of the <code>Font</code>.
133      * @see   #getHeight()
134      * @see   #getAscent()
135      * @see   #getDescent()
136      */
137     public int getLeading() {
138     return 0;
139     }
140 
141     /**
142      * Determines the <em>font ascent</em> of the <code>Font</code> 
143      * described by this <code>FontMetrics</code> object. The font ascent
144      * is the distance from the font's baseline to the top of most
145      * alphanumeric characters. Some characters in the <code>Font</code> 
146      * might extend above the font ascent line.
147      * @return     the font ascent of the <code>Font</code>.
148      * @see        #getMaxAscent()
149      */
150     public int getAscent() {
151     return font.getSize();
152     }
153 
154     /**
155      * Determines the <em>font descent</em> of the <code>Font</code> 
156      * described by this
157      * <code>FontMetrics</code> object. The font descent is the distance
158      * from the font's baseline to the bottom of most alphanumeric
159      * characters with descenders. Some characters in the
160      * <code>Font</code> might extend
161      * below the font descent line.
162      * @return     the font descent of the <code>Font</code>.
163      * @see        #getMaxDescent()
164      */
165     public int getDescent() {
166     return 0;
167     }
168 
169     /**
170      * Gets the standard height of a line of text in this font.  This
171      * is the distance between the baseline of adjacent lines of text.
172      * It is the sum of the leading + ascent + descent. Due to rounding
173      * this may not be the same as getAscent() + getDescent() + getLeading().
174      * There is no guarantee that lines of text spaced at this distance are
175      * disjoint; such lines may overlap if some characters overshoot
176      * either the standard ascent or the standard descent metric.
177      * @return    the standard height of the font.
178      * @see       #getLeading()
179      * @see       #getAscent()
180      * @see       #getDescent()
181      */
182     public int getHeight() {
183     return getLeading() + getAscent() + getDescent();
184     }
185 
186     /**
187      * Determines the maximum ascent of the <code>Font</code> 
188      * described by this <code>FontMetrics</code> object.  No character 
189      * extends further above the font's baseline than this height.
190      * @return    the maximum ascent of any character in the 
191      * <code>Font</code>.
192      * @see       #getAscent()
193      */
194     public int getMaxAscent() {
195     return getAscent();
196     }
197 
198     /**
199      * Determines the maximum descent of the <code>Font</code> 
200      * described by this <code>FontMetrics</code> object.  No character 
201      * extends further below the font's baseline than this height.
202      * @return    the maximum descent of any character in the
203      * <code>Font</code>.
204      * @see       #getDescent()
205      */
206     public int getMaxDescent() {
207     return getDescent();
208     }
209 
210     /**
211      * For backward compatibility only.
212      * @return    the maximum descent of any character in the
213      * <code>Font</code>.
214      * @see #getMaxDescent()
215      * @deprecated As of JDK version 1.1.1,
216      * replaced by <code>getMaxDescent()</code>.
217      */
218     @Deprecated  
219     public int getMaxDecent() {
220     return getMaxDescent();
221     }
222 
223     /**
224      * Gets the maximum advance width of any character in this 
225      * <code>Font</code>.  The advance is the
226      * distance from the leftmost point to the rightmost point on the
227      * string's baseline.  The advance of a <code>String</code> is    
228      * not necessarily the sum of the advances of its characters.
229      * @return    the maximum advance width of any character
230      *            in the <code>Font</code>, or <code>-1</code> if the
231      *            maximum advance width is not known.
232      */
233     public int getMaxAdvance() {
234     return -1;
235     }
236 
237     /**
238      * Returns the advance width of the specified character in this 
239      * <code>Font</code>.  The advance is the
240      * distance from the leftmost point to the rightmost point on the
241      * character's baseline.  Note that the advance of a
242      * <code>String</code> is not necessarily the sum of the advances 
243      * of its characters.
244      * 
245      * <p>This method doesn't validate the specified character to be a
246      * valid Unicode code point. The caller must validate the
247      * character value using {@link
248      * java.lang.Character#isValidCodePoint(int)
249      * Character.isValidCodePoint} if necessary.
250      *
251      * @param codePoint the character (Unicode code point) to be measured
252      * @return    the advance width of the specified character
253      *            in the <code>Font</code> described by this
254      *        <code>FontMetrics</code> object.
255      * @see   #charsWidth(char[], int, int)
256      * @see   #stringWidth(String)
257      */
258     public int charWidth(int codePoint) {
259     if (!Character.isValidCodePoint(codePoint)) {
260         codePoint = 0xffff; // substitute missing glyph width
261     }
262 
263     if (codePoint < 256) {
264         return getWidths()[codePoint];
265     } else {
266         char[] buffer = new char[2];
267         int len = Character.toChars(codePoint, buffer, 0);
268         return charsWidth(buffer, 0, len);
269     }
270     }
271 
272     /**
273      * Returns the advance width of the specified character in this 
274      * <code>Font</code>.  The advance is the
275      * distance from the leftmost point to the rightmost point on the
276      * character's baseline.  Note that the advance of a
277      * <code>String</code> is not necessarily the sum of the advances 
278      * of its characters.
279      *
280      * <p><b>Note:</b> This method cannot handle <a
281      * HREF="../../lang/Character.html#supplementary"> supplementary
282      * characters</a>. To support all Unicode characters, including
283      * supplementary characters, use the {@link #charWidth(int)} method.
284      *
285      * @param ch the character to be measured
286      * @return     the advance width of the specified character
287      *                  in the <code>Font</code> described by this 
288      *          <code>FontMetrics</code> object.
289      * @see        #charsWidth(char[], int, int)
290      * @see        #stringWidth(String)
291      */
292     public int charWidth(char ch) {
293     if (ch < 256) {
294         return getWidths()[ch];
295     }
296     char data[] = {ch};
297     return charsWidth(data, 0, 1);
298     }
299 
300     /**
301      * Returns the total advance width for showing the specified 
302      * <code>String</code> in this <code>Font</code>.  The advance
303      * is the distance from the leftmost point to the rightmost point
304      * on the string's baseline.  
305      * <p>
306      * Note that the total advance width returned from this method
307      * does not take into account the rendering context.  Therefore, 
308      * the anti-aliasing and fractional metrics hints can affect the
309      * value of the advance.  When enabling the anti-aliasing and 
310      * fractional metrics hints, use 
311      * <code>getStringBounds(String, Graphics)</code> 
312      * instead of this method.  The advance of a <code>String</code> is
313      * not necessarily the sum of the advances of its characters.
314      * <p>
315      * @param str the <code>String</code> to be measured
316      * @return    the advance width of the specified <code>String</code>
317      *                  in the <code>Font</code> described by this
318      *          <code>FontMetrics</code>.
319      * @see       #bytesWidth(byte[], int, int)
320      * @see       #charsWidth(char[], int, int)
321      * @see       #getStringBounds(String, Graphics)
322      */
323     public int stringWidth(String   str) {
324     int len = str.length();
325     char data[] = new char[len];
326     str.getChars(0, len, data, 0);
327     return charsWidth(data, 0, len);
328     }
329 
330     /**
331      * Returns the total advance width for showing the specified array
332      * of characters in this <code>Font</code>.  The advance is the
333      * distance from the leftmost point to the rightmost point on the
334      * string's baseline.  The advance of a <code>String</code>
335      * is not necessarily the sum of the advances of its characters.
336      * This is equivalent to measuring a <code>String</code> of the
337      * characters in the specified range.
338      * @param data the array of characters to be measured
339      * @param off the start offset of the characters in the array
340      * @param len the number of characters to be measured from the array
341      * @return    the advance width of the subarray of the specified
342      *               <code>char</code> array in the font described by
343      *               this <code>FontMetrics</code> object.
344      * @see       #charWidth(int)
345      * @see       #charWidth(char)
346      * @see       #bytesWidth(byte[], int, int)
347      * @see       #stringWidth(String)
348      */
349     public int charsWidth(char data[], int off, int len) {
350     return stringWidth(new String  (data, off, len));
351     }
352 
353     /**
354      * Returns the total advance width for showing the specified array
355      * of bytes in this <code>Font</code>.  The advance is the
356      * distance from the leftmost point to the rightmost point on the
357      * string's baseline.  The advance of a <code>String</code>
358      * is not necessarily the sum of the advances of its characters.  
359      * This is equivalent to measuring a <code>String</code> of the
360      * characters in the specified range.
361      * @param data the array of bytes to be measured
362      * @param off the start offset of the bytes in the array
363      * @param len the number of bytes to be measured from the array
364      * @return    the advance width of the subarray of the specified
365      *               <code>byte</code> array in the <code>Font</code> 
366      *          described by
367      *               this <code>FontMetrics</code> object.
368      * @see       #charsWidth(char[], int, int)
369      * @see       #stringWidth(String)
370      */
371     public int bytesWidth(byte data[], int off, int len) {
372     return stringWidth(new String  (data, 0, off, len));
373     }
374 
375     /**
376      * Gets the advance widths of the first 256 characters in the 
377      * <code>Font</code>.  The advance is the
378      * distance from the leftmost point to the rightmost point on the
379      * character's baseline.  Note that the advance of a
380      * <code>String</code> is not necessarily the sum of the advances 
381      * of its characters.
382      * @return    an array storing the advance widths of the
383      *                 characters in the <code>Font</code>
384      *                 described by this <code>FontMetrics</code> object.
385      */
386     public int[] getWidths() {
387     int widths[] = new int[256];
388     for (char ch = 0 ; ch < 256 ; ch++) {
389         widths[ch] = charWidth(ch);
390     }
391     return widths;
392     }
393 
394     /**
395      * Checks to see if the <code>Font</code> has uniform line metrics.  A 
396      * composite font may consist of several different fonts to cover
397      * various character sets.  In such cases, the 
398      * <code>FontLineMetrics</code> objects are not uniform.  
399      * Different fonts may have a different ascent, descent, metrics and
400      * so on.  This information is sometimes necessary for line 
401      * measuring and line breaking.
402      * @return <code>true</code> if the font has uniform line metrics;
403      * <code>false</code> otherwise.
404      * @see java.awt.Font#hasUniformLineMetrics()
405      */
406     public boolean hasUniformLineMetrics() {
407         return font.hasUniformLineMetrics();
408     }
409 
410     /**
411      * Returns the {@link LineMetrics} object for the specified
412      * <code>String</code> in the specified {@link Graphics} context.
413      * @param str the specified <code>String</code>
414      * @param context the specified <code>Graphics</code> context
415      * @return a <code>LineMetrics</code> object created with the
416      * specified <code>String</code> and <code>Graphics</code> context.
417      * @see java.awt.Font#getLineMetrics(String, FontRenderContext)
418      */
419     public LineMetrics   getLineMetrics( String   str, Graphics   context) {
420         return font.getLineMetrics(str, myFRC(context));
421     }
422 
423     /**
424      * Returns the {@link LineMetrics} object for the specified
425      * <code>String</code> in the specified {@link Graphics} context.
426      * @param str the specified <code>String</code>
427      * @param beginIndex the initial offset of <code>str</code>
428      * @param limit the length of <code>str</code>
429      * @param context the specified <code>Graphics</code> context
430      * @return a <code>LineMetrics</code> object created with the
431      * specified <code>String</code> and <code>Graphics</code> context.
432      * @see java.awt.Font#getLineMetrics(String, int, int, FontRenderContext)
433      */
434     public LineMetrics   getLineMetrics( String   str,
435                                             int beginIndex, int limit,
436                                             Graphics   context) {
437         return font.getLineMetrics(str, beginIndex, limit, myFRC(context));
438     }
439 
440     /**
441      * Returns the {@link LineMetrics} object for the specified
442      * character array in the specified {@link Graphics} context.
443      * @param chars the specified character array
444      * @param beginIndex the initial offset of <code>chars</code>
445      * @param limit the length of <code>chars</code>
446      * @param context the specified <code>Graphics</code> context
447      * @return a <code>LineMetrics</code> object created with the
448      * specified character array and <code>Graphics</code> context.
449      * @see java.awt.Font#getLineMetrics(char[], int, int, FontRenderContext)
450      */
451     public LineMetrics   getLineMetrics(char [] chars,
452                                             int beginIndex, int limit,
453                                             Graphics   context) {
454         return font.getLineMetrics(
455                                 chars, beginIndex, limit, myFRC(context));
456     }
457 
458     /**
459      * Returns the {@link LineMetrics} object for the specified
460      * {@link CharacterIterator} in the specified {@link Graphics} 
461      * context.
462      * @param ci the specified <code>CharacterIterator</code>
463      * @param beginIndex the initial offset in <code>ci</code>
464      * @param limit the end index of <code>ci</code>
465      * @param context the specified <code>Graphics</code> context
466      * @return a <code>LineMetrics</code> object created with the
467      * specified arguments.
468      * @see java.awt.Font#getLineMetrics(CharacterIterator, int, int, FontRenderContext)
469      */
470     public LineMetrics   getLineMetrics(CharacterIterator   ci,
471                                             int beginIndex, int limit,
472                                             Graphics   context) {
473         return font.getLineMetrics(ci, beginIndex, limit, myFRC(context));
474     }
475 
476     /**
477      * Returns the bounds of the specified <code>String</code> in the
478      * specified <code>Graphics</code> context.  The bounds is used
479      * to layout the <code>String</code>.
480      * @param str the specified <code>String</code>   
481      * @param context the specified <code>Graphics</code> context
482      * @return a {@link Rectangle2D} that is the bounding box of the
483      * specified <code>String</code> in the specified
484      * <code>Graphics</code> context.
485      * @see java.awt.Font#getStringBounds(String, FontRenderContext)
486      */
487     public Rectangle2D   getStringBounds( String   str, Graphics   context) {
488         return font.getStringBounds(str, myFRC(context));
489     }
490 
491     /**
492      * Returns the bounds of the specified <code>String</code> in the
493      * specified <code>Graphics</code> context.  The bounds is used
494      * to layout the <code>String</code>.
495      * @param str the specified <code>String</code>
496      * @param beginIndex the offset of the beginning of <code>str</code>
497      * @param limit the length of <code>str</code>
498      * @param context the specified <code>Graphics</code> context
499      * @return a <code>Rectangle2D</code> that is the bounding box of the
500      * specified <code>String</code> in the specified
501      * <code>Graphics</code> context.
502      * @see java.awt.Font#getStringBounds(String, int, int, FontRenderContext)
503      */
504     public Rectangle2D   getStringBounds( String   str,
505                                         int beginIndex, int limit,
506                                         Graphics   context) {
507         return font.getStringBounds(str, beginIndex, limit,
508                                         myFRC(context));
509     }
510 
511    /**
512      * Returns the bounds of the specified array of characters
513      * in the specified <code>Graphics</code> context.
514      * The bounds is used to layout the <code>String</code>
515      * created with the specified array of characters,
516      * <code>beginIndex</code> and <code>limit</code>.
517      * @param chars an array of characters
518      * @param beginIndex the initial offset of the array of
519      * characters
520      * @param limit the length of the array of characters
521      * @param context the specified <code>Graphics</code> context
522      * @return a <code>Rectangle2D</code> that is the bounding box of the
523      * specified character array in the specified
524      * <code>Graphics</code> context. 
525      * @see java.awt.Font#getStringBounds(char[], int, int, FontRenderContext)
526      */ 
527     public Rectangle2D   getStringBounds( char [] chars,
528                                         int beginIndex, int limit,
529                                         Graphics   context) {
530         return font.getStringBounds(chars, beginIndex, limit,
531                                         myFRC(context));
532     }
533 
534    /**
535      * Returns the bounds of the characters indexed in the specified
536      * <code>CharacterIterator</code> in the
537      * specified <code>Graphics</code> context.  
538      * @param ci the specified <code>CharacterIterator</code> 
539      * @param beginIndex the initial offset in <code>ci</code>
540      * @param limit the end index of <code>ci</code>
541      * @param context the specified <code>Graphics</code> context
542      * @return a <code>Rectangle2D</code> that is the bounding box of the
543      * characters indexed in the specified <code>CharacterIterator</code>
544      * in the specified <code>Graphics</code> context.
545      * @see java.awt.Font#getStringBounds(CharacterIterator, int, int, FontRenderContext)
546      */
547     public Rectangle2D   getStringBounds(CharacterIterator   ci,
548                                         int beginIndex, int limit,
549                                         Graphics   context) {
550         return font.getStringBounds(ci, beginIndex, limit,
551                                         myFRC(context));
552     }
553 
554     /**
555      * Returns the bounds for the character with the maximum bounds
556      * in the specified <code>Graphics</code> context.
557      * @param context the specified <code>Graphics</code> context
558      * @return a <code>Rectangle2D</code> that is the 
559      * bounding box for the character with the maximum bounds.
560      * @see java.awt.Font#getMaxCharBounds(FontRenderContext)
561      */       
562     public Rectangle2D   getMaxCharBounds(Graphics   context) {
563         return font.getMaxCharBounds(myFRC(context));
564     }
565 
566     private FontRenderContext   myFRC(Graphics   context) {
567         if (context instanceof Graphics2D  ) {
568             return ((Graphics2D  )context).getFontRenderContext();
569         }
570         return new FontRenderContext  (null, false, false);
571     }
572 
573 
574     /**
575      * Returns a representation of this <code>FontMetrics</code>
576      * object's values as a <code>String</code>.
577      * @return    a <code>String</code> representation of this 
578      * <code>FontMetrics</code> object.
579      * @since     JDK1.0.
580      */
581     public String   toString() {
582     return getClass().getName() +
583         "[font=" + getFont() +
584         "ascent=" + getAscent() +
585         ", descent=" + getDescent() +
586         ", height=" + getHeight() + "]";
587     }
588 
589     /**
590      * Initialize JNI field and method IDs
591      */
592     private static native void initIDs();
593 }
594
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags