001 /*
002 * Copyright 1995-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt;
027
028 import java.awt.Graphics2D;
029 import java.awt.font.FontRenderContext;
030 import java.awt.font.LineMetrics;
031 import java.awt.geom.Rectangle2D;
032 import java.text.CharacterIterator;
033
034 /**
035 * The <code>FontMetrics</code> class defines a font metrics object, which
036 * encapsulates information about the rendering of a particular font on a
037 * particular screen.
038 * <p>
039 * <b>Note to subclassers</b>: Since many of these methods form closed,
040 * mutually recursive loops, you must take care that you implement
041 * at least one of the methods in each such loop to prevent
042 * infinite recursion when your subclass is used.
043 * In particular, the following is the minimal suggested set of methods
044 * to override in order to ensure correctness and prevent infinite
045 * recursion (though other subsets are equally feasible):
046 * <ul>
047 * <li>{@link #getAscent()}
048 * <li>{@link #getLeading()}
049 * <li>{@link #getMaxAdvance()}
050 * <li>{@link #charWidth(char)}
051 * <li>{@link #charsWidth(char[], int, int)}
052 * </ul>
053 * <p>
054 * <img src="doc-files/FontMetrics-1.gif" alt="The letter 'p' showing its 'reference point'" border=15 align
055 * ALIGN=right HSPACE=10 VSPACE=7>
056 * Note that the implementations of these methods are
057 * inefficient, so they are usually overridden with more efficient
058 * toolkit-specific implementations.
059 * <p>
060 * When an application asks to place a character at the position
061 * (<i>x</i>, <i>y</i>), the character is placed so that its
062 * reference point (shown as the dot in the accompanying image) is
063 * put at that position. The reference point specifies a horizontal
064 * line called the <i>baseline</i> of the character. In normal
065 * printing, the baselines of characters should align.
066 * <p>
067 * In addition, every character in a font has an <i>ascent</i>, a
068 * <i>descent</i>, and an <i>advance width</i>. The ascent is the
069 * amount by which the character ascends above the baseline. The
070 * descent is the amount by which the character descends below the
071 * baseline. The advance width indicates the position at which AWT
072 * should place the next character.
073 * <p>
074 * An array of characters or a string can also have an ascent, a
075 * descent, and an advance width. The ascent of the array is the
076 * maximum ascent of any character in the array. The descent is the
077 * maximum descent of any character in the array. The advance width
078 * is the sum of the advance widths of each of the characters in the
079 * character array. The advance of a <code>String</code> is the
080 * distance along the baseline of the <code>String</code>. This
081 * distance is the width that should be used for centering or
082 * right-aligning the <code>String</code>.
083 * <p>Note that the advance of a <code>String</code> is not necessarily
084 * the sum of the advances of its characters measured in isolation
085 * because the width of a character can vary depending on its context.
086 * For example, in Arabic text, the shape of a character can change
087 * in order to connect to other characters. Also, in some scripts,
088 * certain character sequences can be represented by a single shape,
089 * called a <em>ligature</em>. Measuring characters individually does
090 * not account for these transformations.
091 * <p>Font metrics are baseline-relative, meaning that they are
092 * generally independent of the rotation applied to the font (modulo
093 * possible grid hinting effects). See {@link java.awt.Font Font}.
094 *
095 * @version 1.65 05/05/07
096 * @author Jim Graham
097 * @see java.awt.Font
098 * @since JDK1.0
099 */
100 public abstract class FontMetrics implements java.io.Serializable {
101
102 static {
103 /* ensure that the necessary native libraries are loaded */
104 Toolkit.loadLibraries();
105 if (!GraphicsEnvironment.isHeadless()) {
106 initIDs();
107 }
108 }
109
110 private static final FontRenderContext DEFAULT_FRC = new FontRenderContext(
111 null, false, false);
112
113 /**
114 * The actual {@link Font} from which the font metrics are
115 * created.
116 * This cannot be null.
117 *
118 * @serial
119 * @see #getFont()
120 */
121 protected Font font;
122
123 /*
124 * JDK 1.1 serialVersionUID
125 */
126 private static final long serialVersionUID = 1681126225205050147L;
127
128 /**
129 * Creates a new <code>FontMetrics</code> object for finding out
130 * height and width information about the specified <code>Font</code>
131 * and specific character glyphs in that <code>Font</code>.
132 * @param font the <code>Font</code>
133 * @see java.awt.Font
134 */
135 protected FontMetrics(Font font) {
136 this .font = font;
137 }
138
139 /**
140 * Gets the <code>Font</code> described by this
141 * <code>FontMetrics</code> object.
142 * @return the <code>Font</code> described by this
143 * <code>FontMetrics</code> object.
144 */
145 public Font getFont() {
146 return font;
147 }
148
149 /**
150 * Gets the <code>FontRenderContext</code> used by this
151 * <code>FontMetrics</code> object to measure text.
152 * <p>
153 * Note that methods in this class which take a <code>Graphics</code>
154 * parameter measure text using the <code>FontRenderContext</code>
155 * of that <code>Graphics</code> object, and not this
156 * <code>FontRenderContext</code>
157 * @return the <code>FontRenderContext</code> used by this
158 * <code>FontMetrics</code> object.
159 * @since 1.6
160 */
161 public FontRenderContext getFontRenderContext() {
162 return DEFAULT_FRC;
163 }
164
165 /**
166 * Determines the <em>standard leading</em> of the
167 * <code>Font</code> described by this <code>FontMetrics</code>
168 * object. The standard leading, or
169 * interline spacing, is the logical amount of space to be reserved
170 * between the descent of one line of text and the ascent of the next
171 * line. The height metric is calculated to include this extra space.
172 * @return the standard leading of the <code>Font</code>.
173 * @see #getHeight()
174 * @see #getAscent()
175 * @see #getDescent()
176 */
177 public int getLeading() {
178 return 0;
179 }
180
181 /**
182 * Determines the <em>font ascent</em> of the <code>Font</code>
183 * described by this <code>FontMetrics</code> object. The font ascent
184 * is the distance from the font's baseline to the top of most
185 * alphanumeric characters. Some characters in the <code>Font</code>
186 * might extend above the font ascent line.
187 * @return the font ascent of the <code>Font</code>.
188 * @see #getMaxAscent()
189 */
190 public int getAscent() {
191 return font.getSize();
192 }
193
194 /**
195 * Determines the <em>font descent</em> of the <code>Font</code>
196 * described by this
197 * <code>FontMetrics</code> object. The font descent is the distance
198 * from the font's baseline to the bottom of most alphanumeric
199 * characters with descenders. Some characters in the
200 * <code>Font</code> might extend
201 * below the font descent line.
202 * @return the font descent of the <code>Font</code>.
203 * @see #getMaxDescent()
204 */
205 public int getDescent() {
206 return 0;
207 }
208
209 /**
210 * Gets the standard height of a line of text in this font. This
211 * is the distance between the baseline of adjacent lines of text.
212 * It is the sum of the leading + ascent + descent. Due to rounding
213 * this may not be the same as getAscent() + getDescent() + getLeading().
214 * There is no guarantee that lines of text spaced at this distance are
215 * disjoint; such lines may overlap if some characters overshoot
216 * either the standard ascent or the standard descent metric.
217 * @return the standard height of the font.
218 * @see #getLeading()
219 * @see #getAscent()
220 * @see #getDescent()
221 */
222 public int getHeight() {
223 return getLeading() + getAscent() + getDescent();
224 }
225
226 /**
227 * Determines the maximum ascent of the <code>Font</code>
228 * described by this <code>FontMetrics</code> object. No character
229 * extends further above the font's baseline than this height.
230 * @return the maximum ascent of any character in the
231 * <code>Font</code>.
232 * @see #getAscent()
233 */
234 public int getMaxAscent() {
235 return getAscent();
236 }
237
238 /**
239 * Determines the maximum descent of the <code>Font</code>
240 * described by this <code>FontMetrics</code> object. No character
241 * extends further below the font's baseline than this height.
242 * @return the maximum descent of any character in the
243 * <code>Font</code>.
244 * @see #getDescent()
245 */
246 public int getMaxDescent() {
247 return getDescent();
248 }
249
250 /**
251 * For backward compatibility only.
252 * @return the maximum descent of any character in the
253 * <code>Font</code>.
254 * @see #getMaxDescent()
255 * @deprecated As of JDK version 1.1.1,
256 * replaced by <code>getMaxDescent()</code>.
257 */
258 @Deprecated
259 public int getMaxDecent() {
260 return getMaxDescent();
261 }
262
263 /**
264 * Gets the maximum advance width of any character in this
265 * <code>Font</code>. The advance is the
266 * distance from the leftmost point to the rightmost point on the
267 * string's baseline. The advance of a <code>String</code> is
268 * not necessarily the sum of the advances of its characters.
269 * @return the maximum advance width of any character
270 * in the <code>Font</code>, or <code>-1</code> if the
271 * maximum advance width is not known.
272 */
273 public int getMaxAdvance() {
274 return -1;
275 }
276
277 /**
278 * Returns the advance width of the specified character in this
279 * <code>Font</code>. The advance is the
280 * distance from the leftmost point to the rightmost point on the
281 * character's baseline. Note that the advance of a
282 * <code>String</code> is not necessarily the sum of the advances
283 * of its characters.
284 *
285 * <p>This method doesn't validate the specified character to be a
286 * valid Unicode code point. The caller must validate the
287 * character value using {@link
288 * java.lang.Character#isValidCodePoint(int)
289 * Character.isValidCodePoint} if necessary.
290 *
291 * @param codePoint the character (Unicode code point) to be measured
292 * @return the advance width of the specified character
293 * in the <code>Font</code> described by this
294 * <code>FontMetrics</code> object.
295 * @see #charsWidth(char[], int, int)
296 * @see #stringWidth(String)
297 */
298 public int charWidth(int codePoint) {
299 if (!Character.isValidCodePoint(codePoint)) {
300 codePoint = 0xffff; // substitute missing glyph width
301 }
302
303 if (codePoint < 256) {
304 return getWidths()[codePoint];
305 } else {
306 char[] buffer = new char[2];
307 int len = Character.toChars(codePoint, buffer, 0);
308 return charsWidth(buffer, 0, len);
309 }
310 }
311
312 /**
313 * Returns the advance width of the specified character in this
314 * <code>Font</code>. The advance is the
315 * distance from the leftmost point to the rightmost point on the
316 * character's baseline. Note that the advance of a
317 * <code>String</code> is not necessarily the sum of the advances
318 * of its characters.
319 *
320 * <p><b>Note:</b> This method cannot handle <a
321 * href="../lang/Character.html#supplementary"> supplementary
322 * characters</a>. To support all Unicode characters, including
323 * supplementary characters, use the {@link #charWidth(int)} method.
324 *
325 * @param ch the character to be measured
326 * @return the advance width of the specified character
327 * in the <code>Font</code> described by this
328 * <code>FontMetrics</code> object.
329 * @see #charsWidth(char[], int, int)
330 * @see #stringWidth(String)
331 */
332 public int charWidth(char ch) {
333 if (ch < 256) {
334 return getWidths()[ch];
335 }
336 char data[] = { ch };
337 return charsWidth(data, 0, 1);
338 }
339
340 /**
341 * Returns the total advance width for showing the specified
342 * <code>String</code> in this <code>Font</code>. The advance
343 * is the distance from the leftmost point to the rightmost point
344 * on the string's baseline.
345 * <p>
346 * Note that the advance of a <code>String</code> is
347 * not necessarily the sum of the advances of its characters.
348 * @param str the <code>String</code> to be measured
349 * @return the advance width of the specified <code>String</code>
350 * in the <code>Font</code> described by this
351 * <code>FontMetrics</code>.
352 * @throws NullPointerException if str is null.
353 * @see #bytesWidth(byte[], int, int)
354 * @see #charsWidth(char[], int, int)
355 * @see #getStringBounds(String, Graphics)
356 */
357 public int stringWidth(String str) {
358 int len = str.length();
359 char data[] = new char[len];
360 str.getChars(0, len, data, 0);
361 return charsWidth(data, 0, len);
362 }
363
364 /**
365 * Returns the total advance width for showing the specified array
366 * of characters in this <code>Font</code>. The advance is the
367 * distance from the leftmost point to the rightmost point on the
368 * string's baseline. The advance of a <code>String</code>
369 * is not necessarily the sum of the advances of its characters.
370 * This is equivalent to measuring a <code>String</code> of the
371 * characters in the specified range.
372 * @param data the array of characters to be measured
373 * @param off the start offset of the characters in the array
374 * @param len the number of characters to be measured from the array
375 * @return the advance width of the subarray of the specified
376 * <code>char</code> array in the font described by
377 * this <code>FontMetrics</code> object.
378 * @throws NullPointerException if <code>data</code> is null.
379 * @throws IndexOutOfBoundsException if the <code>off</code>
380 * and <code>len</code> arguments index characters outside
381 * the bounds of the <code>data</code> array.
382 * @see #charWidth(int)
383 * @see #charWidth(char)
384 * @see #bytesWidth(byte[], int, int)
385 * @see #stringWidth(String)
386 */
387 public int charsWidth(char data[], int off, int len) {
388 return stringWidth(new String(data, off, len));
389 }
390
391 /**
392 * Returns the total advance width for showing the specified array
393 * of bytes in this <code>Font</code>. The advance is the
394 * distance from the leftmost point to the rightmost point on the
395 * string's baseline. The advance of a <code>String</code>
396 * is not necessarily the sum of the advances of its characters.
397 * This is equivalent to measuring a <code>String</code> of the
398 * characters in the specified range.
399 * @param data the array of bytes to be measured
400 * @param off the start offset of the bytes in the array
401 * @param len the number of bytes to be measured from the array
402 * @return the advance width of the subarray of the specified
403 * <code>byte</code> array in the <code>Font</code>
404 * described by
405 * this <code>FontMetrics</code> object.
406 * @throws NullPointerException if <code>data</code> is null.
407 * @throws IndexOutOfBoundsException if the <code>off</code>
408 * and <code>len</code> arguments index bytes outside
409 * the bounds of the <code>data</code> array.
410 * @see #charsWidth(char[], int, int)
411 * @see #stringWidth(String)
412 */
413 public int bytesWidth(byte data[], int off, int len) {
414 return stringWidth(new String(data, 0, off, len));
415 }
416
417 /**
418 * Gets the advance widths of the first 256 characters in the
419 * <code>Font</code>. The advance is the
420 * distance from the leftmost point to the rightmost point on the
421 * character's baseline. Note that the advance of a
422 * <code>String</code> is not necessarily the sum of the advances
423 * of its characters.
424 * @return an array storing the advance widths of the
425 * characters in the <code>Font</code>
426 * described by this <code>FontMetrics</code> object.
427 */
428 public int[] getWidths() {
429 int widths[] = new int[256];
430 for (char ch = 0; ch < 256; ch++) {
431 widths[ch] = charWidth(ch);
432 }
433 return widths;
434 }
435
436 /**
437 * Checks to see if the <code>Font</code> has uniform line metrics. A
438 * composite font may consist of several different fonts to cover
439 * various character sets. In such cases, the
440 * <code>FontLineMetrics</code> objects are not uniform.
441 * Different fonts may have a different ascent, descent, metrics and
442 * so on. This information is sometimes necessary for line
443 * measuring and line breaking.
444 * @return <code>true</code> if the font has uniform line metrics;
445 * <code>false</code> otherwise.
446 * @see java.awt.Font#hasUniformLineMetrics()
447 */
448 public boolean hasUniformLineMetrics() {
449 return font.hasUniformLineMetrics();
450 }
451
452 /**
453 * Returns the {@link LineMetrics} object for the specified
454 * <code>String</code> in the specified {@link Graphics} context.
455 * @param str the specified <code>String</code>
456 * @param context the specified <code>Graphics</code> context
457 * @return a <code>LineMetrics</code> object created with the
458 * specified <code>String</code> and <code>Graphics</code> context.
459 * @see java.awt.Font#getLineMetrics(String, FontRenderContext)
460 */
461 public LineMetrics getLineMetrics(String str, Graphics context) {
462 return font.getLineMetrics(str, myFRC(context));
463 }
464
465 /**
466 * Returns the {@link LineMetrics} object for the specified
467 * <code>String</code> in the specified {@link Graphics} context.
468 * @param str the specified <code>String</code>
469 * @param beginIndex the initial offset of <code>str</code>
470 * @param limit the end offset of <code>str</code>
471 * @param context the specified <code>Graphics</code> context
472 * @return a <code>LineMetrics</code> object created with the
473 * specified <code>String</code> and <code>Graphics</code> context.
474 * @see java.awt.Font#getLineMetrics(String, int, int, FontRenderContext)
475 */
476 public LineMetrics getLineMetrics(String str, int beginIndex,
477 int limit, Graphics context) {
478 return font.getLineMetrics(str, beginIndex, limit,
479 myFRC(context));
480 }
481
482 /**
483 * Returns the {@link LineMetrics} object for the specified
484 * character array in the specified {@link Graphics} context.
485 * @param chars the specified character array
486 * @param beginIndex the initial offset of <code>chars</code>
487 * @param limit the end offset of <code>chars</code>
488 * @param context the specified <code>Graphics</code> context
489 * @return a <code>LineMetrics</code> object created with the
490 * specified character array and <code>Graphics</code> context.
491 * @see java.awt.Font#getLineMetrics(char[], int, int, FontRenderContext)
492 */
493 public LineMetrics getLineMetrics(char[] chars, int beginIndex,
494 int limit, Graphics context) {
495 return font.getLineMetrics(chars, beginIndex, limit,
496 myFRC(context));
497 }
498
499 /**
500 * Returns the {@link LineMetrics} object for the specified
501 * {@link CharacterIterator} in the specified {@link Graphics}
502 * context.
503 * @param ci the specified <code>CharacterIterator</code>
504 * @param beginIndex the initial offset in <code>ci</code>
505 * @param limit the end index of <code>ci</code>
506 * @param context the specified <code>Graphics</code> context
507 * @return a <code>LineMetrics</code> object created with the
508 * specified arguments.
509 * @see java.awt.Font#getLineMetrics(CharacterIterator, int, int, FontRenderContext)
510 */
511 public LineMetrics getLineMetrics(CharacterIterator ci,
512 int beginIndex, int limit, Graphics context) {
513 return font.getLineMetrics(ci, beginIndex, limit,
514 myFRC(context));
515 }
516
517 /**
518 * Returns the bounds of the specified <code>String</code> in the
519 * specified <code>Graphics</code> context. The bounds is used
520 * to layout the <code>String</code>.
521 * <p>Note: The returned bounds is in baseline-relative coordinates
522 * (see {@link java.awt.FontMetrics class notes}).
523 * @param str the specified <code>String</code>
524 * @param context the specified <code>Graphics</code> context
525 * @return a {@link Rectangle2D} that is the bounding box of the
526 * specified <code>String</code> in the specified
527 * <code>Graphics</code> context.
528 * @see java.awt.Font#getStringBounds(String, FontRenderContext)
529 */
530 public Rectangle2D getStringBounds(String str, Graphics context) {
531 return font.getStringBounds(str, myFRC(context));
532 }
533
534 /**
535 * Returns the bounds of the specified <code>String</code> in the
536 * specified <code>Graphics</code> context. The bounds is used
537 * to layout the <code>String</code>.
538 * <p>Note: The returned bounds is in baseline-relative coordinates
539 * (see {@link java.awt.FontMetrics class notes}).
540 * @param str the specified <code>String</code>
541 * @param beginIndex the offset of the beginning of <code>str</code>
542 * @param limit the end offset of <code>str</code>
543 * @param context the specified <code>Graphics</code> context
544 * @return a <code>Rectangle2D</code> that is the bounding box of the
545 * specified <code>String</code> in the specified
546 * <code>Graphics</code> context.
547 * @see java.awt.Font#getStringBounds(String, int, int, FontRenderContext)
548 */
549 public Rectangle2D getStringBounds(String str, int beginIndex,
550 int limit, Graphics context) {
551 return font.getStringBounds(str, beginIndex, limit,
552 myFRC(context));
553 }
554
555 /**
556 * Returns the bounds of the specified array of characters
557 * in the specified <code>Graphics</code> context.
558 * The bounds is used to layout the <code>String</code>
559 * created with the specified array of characters,
560 * <code>beginIndex</code> and <code>limit</code>.
561 * <p>Note: The returned bounds is in baseline-relative coordinates
562 * (see {@link java.awt.FontMetrics class notes}).
563 * @param chars an array of characters
564 * @param beginIndex the initial offset of the array of
565 * characters
566 * @param limit the end offset of the array of characters
567 * @param context the specified <code>Graphics</code> context
568 * @return a <code>Rectangle2D</code> that is the bounding box of the
569 * specified character array in the specified
570 * <code>Graphics</code> context.
571 * @see java.awt.Font#getStringBounds(char[], int, int, FontRenderContext)
572 */
573 public Rectangle2D getStringBounds(char[] chars, int beginIndex,
574 int limit, Graphics context) {
575 return font.getStringBounds(chars, beginIndex, limit,
576 myFRC(context));
577 }
578
579 /**
580 * Returns the bounds of the characters indexed in the specified
581 * <code>CharacterIterator</code> in the
582 * specified <code>Graphics</code> context.
583 * <p>Note: The returned bounds is in baseline-relative coordinates
584 * (see {@link java.awt.FontMetrics class notes}).
585 * @param ci the specified <code>CharacterIterator</code>
586 * @param beginIndex the initial offset in <code>ci</code>
587 * @param limit the end index of <code>ci</code>
588 * @param context the specified <code>Graphics</code> context
589 * @return a <code>Rectangle2D</code> that is the bounding box of the
590 * characters indexed in the specified <code>CharacterIterator</code>
591 * in the specified <code>Graphics</code> context.
592 * @see java.awt.Font#getStringBounds(CharacterIterator, int, int, FontRenderContext)
593 */
594 public Rectangle2D getStringBounds(CharacterIterator ci,
595 int beginIndex, int limit, Graphics context) {
596 return font.getStringBounds(ci, beginIndex, limit,
597 myFRC(context));
598 }
599
600 /**
601 * Returns the bounds for the character with the maximum bounds
602 * in the specified <code>Graphics</code> context.
603 * @param context the specified <code>Graphics</code> context
604 * @return a <code>Rectangle2D</code> that is the
605 * bounding box for the character with the maximum bounds.
606 * @see java.awt.Font#getMaxCharBounds(FontRenderContext)
607 */
608 public Rectangle2D getMaxCharBounds(Graphics context) {
609 return font.getMaxCharBounds(myFRC(context));
610 }
611
612 private FontRenderContext myFRC(Graphics context) {
613 if (context instanceof Graphics2D) {
614 return ((Graphics2D) context).getFontRenderContext();
615 }
616 return DEFAULT_FRC;
617 }
618
619 /**
620 * Returns a representation of this <code>FontMetrics</code>
621 * object's values as a <code>String</code>.
622 * @return a <code>String</code> representation of this
623 * <code>FontMetrics</code> object.
624 * @since JDK1.0.
625 */
626 public String toString() {
627 return getClass().getName() + "[font=" + getFont() + "ascent="
628 + getAscent() + ", descent=" + getDescent()
629 + ", height=" + getHeight() + "]";
630 }
631
632 /**
633 * Initialize JNI field and method IDs
634 */
635 private static native void initIDs();
636 }
|