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