001: /*
002: * @(#)FontMetrics.java 1.9 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.awt;
029:
030: /**
031: * A font metrics object, which gives information about the rendering
032: * of a particular font on a particular screen. Note that the
033: * implementations of these methods are inefficient, they are usually
034: * overridden with more efficient toolkit-specific implementations.
035: * <p>
036: * <b>Note to subclassers</b>: Since many of these methods form closed
037: * mutually recursive loops, you must take care that you implement
038: * at least one of the methods in each such loop in order to prevent
039: * infinite recursion when your subclass is used.
040: * In particular, the following is the minimal suggested set of methods
041: * to override in order to ensure correctness and prevent infinite
042: * recursion (though other subsets are equally feasible):
043: * <ul>
044: * <li><a href=#getAscent>getAscent</a>()
045: * <li><a href=#getDescent>getDescent</a>()
046: * <li><a href=#getLeading>getLeading</a>()
047: * <li><a href=#getMaxAdvance>getMaxAdvance</a>()
048: * <li><a href="#charWidth(char)">charWidth</a>(char ch)
049: * <li><a href="#charsWidth(char[], int, int)">charsWidth</a>(char data[], int off, int len)
050: * </ul>
051: * <p>
052: * <img src="images-awt/FontMetrics-1.gif" border=15 align
053: * ALIGN=right HSPACE=10 VSPACE=7>
054: * When an application asks AWT to place a character at the position
055: * (<i>x</i>, <i>y</i>), the character is placed so that its
056: * reference point (shown as the dot in the accompanying image) is
057: * put at that position. The reference point specifies a horizontal
058: * line called the <i>baseline</i> of the character. In normal
059: * printing, the baselines of characters should align.
060: * <p>
061: * In addition, every character in a font has an <i>ascent</i>, a
062: * <i>descent</i>, and an <i>advance width</i>. The ascent is the
063: * amount by which the character ascends above the baseline. The
064: * descent is the amount by which the character descends below the
065: * baseline. The advance width indicates the position at which AWT
066: * should place the next character.
067: * <p>
068: * If the current character is placed with its reference point
069: * at the position (<i>x</i>, <i>y</i>), and
070: * the character's advance width is <i>w</i>, then the following
071: * character is placed with its reference point at the position
072: * (<i>x </i><code>+</code><i> w</i>, <i>y</i>).
073: * The advance width is often the same as the width of character's
074: * bounding box, but need not be so. In particular, oblique and
075: * italic fonts often have characters whose top-right corner extends
076: * slightly beyond the advance width.
077: * <p>
078: * An array of characters or a string can also have an ascent, a
079: * descent, and an advance width. The ascent of the array is the
080: * maximum ascent of any character in the array. The descent is the
081: * maximum descent of any character in the array. The advance width
082: * is the sum of the advance widths of each of the characters in the
083: * array.
084: * @version 1.19 01/05/01
085: * @author Jim Graham
086: * @see java.awt.Font
087: * @since JDK1.0
088: */
089: public abstract class FontMetrics implements java.io.Serializable {
090: /**
091: * The actual font.
092: * @see #getFont
093: * @since JDK1.0
094: */
095: protected Font font;
096: /*
097: * JDK 1.1 serialVersionUID
098: */
099: private static final long serialVersionUID = 1681126225205050147L;
100:
101: /**
102: * Creates a new <code>FontMetrics</code> object for finding out
103: * height and width information about the specified font and
104: * specific character glyphs in that font.
105: * @param font the font
106: * @see java.awt.Font
107: * @since JDK1.0
108: */
109: protected FontMetrics(Font font) {
110: this .font = font;
111: }
112:
113: /**
114: * Gets the font described by this font metric.
115: * @return the font described by this font metric.
116: * @since JDK1.0
117: */
118: public Font getFont() {
119: return font;
120: }
121:
122: /**
123: * Determines the <em>standard leading</em> of the font described by
124: * this font metric. The standard leading (interline spacing) is the
125: * logical amount of space to be reserved between the descent of one
126: * line of text and the ascent of the next line. The height metric is
127: * calculated to include this extra space.
128: * @return the standard leading of the font.
129: * @see java.awt.FontMetrics#getHeight
130: * @see java.awt.FontMetrics#getAscent
131: * @see java.awt.FontMetrics#getDescent
132: * @since JDK1.0
133: */
134: public int getLeading() {
135: return 0;
136: }
137:
138: /**
139: * Determines the <em>font ascent</em> of the font described by this
140: * font metric. The font ascent is the distance from the font's
141: * baseline to the top of most alphanumeric characters. Some
142: * characters in the font may extend above the font ascent line.
143: * @return the font ascent of the font.
144: * @see java.awt.FontMetrics#getMaxAscent
145: * @since JDK1.0
146: */
147: public int getAscent() {
148: return font.getSize();
149: }
150:
151: /**
152: * Determines the <em>font descent</em> of the font described by this
153: * font metric. The font descent is the distance from the font's
154: * baseline to the bottom of most alphanumeric characters with
155: * descenders. Some characters in the font may extend below the font
156: * descent line.
157: * @return the font descent of the font.
158: * @see java.awt.FontMetrics#getMaxDescent
159: * @since JDK1.0
160: */
161: public int getDescent() {
162: return 0;
163: }
164:
165: /**
166: * Gets the standard height of a line of text in this font. This
167: * is the distance between the baseline of adjacent lines of text.
168: * It is the sum of the leading + ascent + descent. There is no
169: * guarantee that lines of text spaced at this distance will be
170: * disjoint; such lines may overlap if some characters overshoot
171: * either the standard ascent or the standard descent metric.
172: * @return the standard height of the font.
173: * @see java.awt.FontMetrics#getLeading
174: * @see java.awt.FontMetrics#getAscent
175: * @see java.awt.FontMetrics#getDescent
176: * @since JDK1.0
177: */
178: public int getHeight() {
179: return getLeading() + getAscent() + getDescent();
180: }
181:
182: /**
183: * Determines the maximum ascent of the font described by this font
184: * metric. No character extends further above the font's baseline
185: * than this height.
186: * @return the maximum ascent of any character in the font.
187: * @see java.awt.FontMetrics#getAscent
188: * @since JDK1.0
189: */
190: public int getMaxAscent() {
191: return getAscent();
192: }
193:
194: /**
195: * Determines the maximum descent of the font described by this font
196: * metric. No character extends further below the font's baseline
197: * than this height.
198: * @return the maximum descent of any character in the font.
199: * @see java.awt.FontMetrics#getDescent
200: * @since JDK1.0
201: */
202: public int getMaxDescent() {
203: return getDescent();
204: }
205:
206: /**
207: * For backward compatibility only.
208: * @see #getMaxDescent
209: * @deprecated As of JDK version 1.1.1,
210: * replaced by <code>getMaxDescent()</code>.
211: */
212: public int getMaxDecent() {
213: return getMaxDescent();
214: }
215:
216: /**
217: * Gets the maximum advance width of any character in this Font.
218: * The advance width is the amount by which the current point is
219: * moved from one character to the next in a line of text.
220: * @return the maximum advance width of any character
221: * in the font, or <code>-1</code> if the
222: * maximum advance width is not known.
223: * @since JDK1.0
224: */
225: public int getMaxAdvance() {
226: return -1;
227: }
228:
229: /**
230: * Returns the advance width of the specified character in this Font.
231: * The advance width is the amount by which the current point is
232: * moved from one character to the next in a line of text.
233: * @param ch the character to be measured
234: * @return the advance width of the specified <code>char</code>
235: * in the font described by this font metric.
236: * @see java.awt.FontMetrics#charsWidth
237: * @see java.awt.FontMetrics#stringWidth
238: * @since JDK1.0
239: */
240: public int charWidth(int ch) {
241: return charWidth((char) ch);
242: }
243:
244: /**
245: * Returns the advance width of the specified character in this Font.
246: * The advance width is the amount by which the current point is
247: * moved from one character to the next in a line of text.
248: * @param ch the character to be measured
249: * @return the advance width of the specified <code>char</code> >
250: * in the font described by this font metric.
251: * @see java.awt.FontMetrics#charsWidth
252: * @see java.awt.FontMetrics#stringWidth
253: * @since JDK1.0
254: */
255: public int charWidth(char ch) {
256: char data[] = { ch };
257: return charsWidth(data, 0, 1);
258: }
259:
260: /**
261: * Returns the total advance width for showing the specified String
262: * in this Font.
263: * The advance width is the amount by which the current point is
264: * moved from one character to the next in a line of text.
265: * @param str the String to be measured
266: * @return the advance width of the specified string
267: * in the font described by this font metric.
268: * @see java.awt.FontMetrics#bytesWidth
269: * @see java.awt.FontMetrics#charsWidth
270: * @since JDK1.0
271: */
272: public int stringWidth(String str) {
273: int len = str.length();
274: char data[] = new char[len];
275: str.getChars(0, len, data, 0);
276: return charsWidth(data, 0, len);
277: }
278:
279: /**
280: * Returns the total advance width for showing the specified array
281: * of characters in this Font.
282: * The advance width is the amount by which the current point is
283: * moved from one character to the next in a line of text.
284: * @param data the array of characters to be measured
285: * @param off the start offset of the characters in the array
286: * @param len the number of characters to be measured from the array
287: * @return the advance width of the subarray of the specified
288: * <code>char</code> array in the font described by
289: * this font metric.
290: * @see java.awt.FontMetrics#charWidth(int)
291: * @see java.awt.FontMetrics#charWidth(char)
292: * @see java.awt.FontMetrics#bytesWidth
293: * @see java.awt.FontMetrics#stringWidth
294: * @since JDK1.0
295: */
296: public int charsWidth(char data[], int off, int len) {
297: return stringWidth(new String(data, off, len));
298: }
299:
300: /**
301: * Returns the total advance width for showing the specified array
302: * of bytes in this Font.
303: * The advance width is the amount by which the current point is
304: * moved from one character to the next in a line of text.
305: * @param data the array of bytes to be measured
306: * @param off the start offset of the bytes in the array
307: * @param len the number of bytes to be measured from the array
308: * @return the advance width of the subarray of the specified
309: * <code>byte</code> array in the font described by
310: * this font metric.
311: * @see java.awt.FontMetrics#charsWidth
312: * @see java.awt.FontMetrics#stringWidth
313: * @since JDK1.0
314: */
315: public int bytesWidth(byte data[], int off, int len) {
316: return stringWidth(new String(data, off, len));
317: }
318:
319: /**
320: * Gets the advance widths of the first 256 characters in the Font.
321: * The advance width is the amount by which the current point is
322: * moved from one character to the next in a line of text.
323: * @return an array giving the advance widths of the
324: * characters in the font
325: * described by this font metric.
326: * @since JDK1.0
327: */
328: public int[] getWidths() {
329: int widths[] = new int[256];
330: for (char ch = 0; ch < 256; ch++) {
331: widths[ch] = charWidth(ch);
332: }
333: return widths;
334: }
335:
336: /**
337: * Returns a representation of this <code>FontMetric</code>
338: * object's values as a string.
339: * @return a string representation of this font metric.
340: * @since JDK1.0.
341: */
342: public String toString() {
343: return getClass().getName() + "[font=" + getFont() + "ascent="
344: + getAscent() + ", descent=" + getDescent()
345: + ", height=" + getHeight() + "]";
346: }
347: }
|