001 /* FontMetrics.java -- Information about about a fonts display characteristics
002 Copyright (C) 1999, 2002, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath 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 for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.awt;
040
041 import java.awt.font.FontRenderContext;
042 import java.awt.font.LineMetrics;
043 import java.awt.geom.Rectangle2D;
044 import java.text.CharacterIterator;
045
046 // FIXME: I leave many methods basically unimplemented. This
047 // should be reviewed.
048
049 /**
050 * This class returns information about the display characteristics of
051 * a font. It is abstract, and concrete subclasses should implement at
052 * least the following methods:
053 *
054 * <ul>
055 * <li>getAscent()</li>
056 * <li>getDescent()</li>
057 * <li>getLeading()</li>
058 * <li>getMaxAdvance()</li>
059 * <li>charWidth(char)</li>
060 * <li>charsWidth(char[], int, int)</li>
061 * </ul>
062 *
063 * @author Aaron M. Renn (arenn@urbanophile.com)
064 */
065 public abstract class FontMetrics implements java.io.Serializable
066 {
067 // Serialization constant.
068 private static final long serialVersionUID = 1681126225205050147L;
069
070 /**
071 * This is the font for which metrics will be returned.
072 */
073 protected Font font;
074
075 /**
076 * Initializes a new instance of <code>FontMetrics</code> for the
077 * specified font.
078 *
079 * @param font The font to return metric information for.
080 */
081 protected FontMetrics(Font font)
082 {
083 this.font = font;
084 }
085
086 /**
087 * Returns the font that this object is creating metric information fo.
088 *
089 * @return The font for this object.
090 */
091 public Font getFont()
092 {
093 return font;
094 }
095
096 /**
097 * Returns the leading, or spacing between lines, for this font.
098 *
099 * @return The font leading.
100 */
101 public int getLeading()
102 {
103 return 0;
104 }
105
106 /**
107 * Returns the ascent of the font, which is the distance from the base
108 * to the top of the majority of characters in the set. Some characters
109 * can exceed this value however.
110 *
111 * @return The font ascent.
112 */
113 public int getAscent()
114 {
115 return 1;
116 }
117
118 /**
119 * Returns the descent of the font, which is the distance from the base
120 * to the bottom of the majority of characters in the set. Some characters
121 * can exceed this value however.
122 *
123 * @return The font descent.
124 */
125 public int getDescent()
126 {
127 return 1;
128 }
129
130 /**
131 * Returns the height of a line in this font. This will be the sum
132 * of the leading, the ascent, and the descent.
133 *
134 * @return The height of the font.
135 */
136 public int getHeight()
137 {
138 return getAscent() + getDescent() + getLeading();
139 }
140
141 /**
142 * Returns the maximum ascent value. This is the maximum distance any
143 * character in the font rised above the baseline.
144 *
145 * @return The maximum ascent for this font.
146 */
147 public int getMaxAscent()
148 {
149 return getAscent();
150 }
151
152 /**
153 * Returns the maximum descent value. This is the maximum distance any
154 * character in the font extends below the baseline.
155 *
156 * @return The maximum descent for this font.
157 */
158 public int getMaxDescent()
159 {
160 return getMaxDecent();
161 }
162
163 /**
164 * Returns the maximum descent value. This is the maximum distance any
165 * character in the font extends below the baseline.
166 *
167 * @return The maximum descent for this font.
168 *
169 * @deprecated This method is deprecated in favor of
170 * <code>getMaxDescent()</code>.
171 */
172 public int getMaxDecent()
173 {
174 return getDescent();
175 }
176
177 /**
178 * Returns the width of the widest character in the font.
179 *
180 * @return The width of the widest character in the font.
181 */
182 public int getMaxAdvance()
183 {
184 return -1;
185 }
186
187 /**
188 * Returns the width of the specified character.
189 *
190 * @param ch The character to return the width of.
191 *
192 * @return The width of the specified character.
193 */
194 public int charWidth(int ch)
195 {
196 char[] chars = Character.toChars(ch);
197 return charsWidth(chars, 0, chars.length);
198 }
199
200 /**
201 * Returns the width of the specified character.
202 *
203 * @param ch The character to return the width of.
204 *
205 * @return The width of the specified character.
206 */
207 public int charWidth(char ch)
208 {
209 return 1;
210 }
211
212 /**
213 * Returns the total width of the specified string
214 *
215 * @param str The string to return the width of.
216 *
217 * @return The width of the string.
218 */
219 public int stringWidth(String str)
220 {
221 char[] buf = new char[str.length()];
222 str.getChars(0, str.length(), buf, 0);
223
224 return charsWidth(buf, 0, buf.length);
225 }
226
227 /**
228 * Returns the total width of the specified character array.
229 *
230 * @param buf The character array containing the data.
231 * @param offset The offset into the array to start calculating from.
232 * @param len The total number of bytes to process.
233 *
234 * @return The width of the requested characters.
235 */
236 public int charsWidth(char[] buf, int offset, int len)
237 {
238 int total_width = 0;
239 int endOffset = offset + len;
240 for (int i = offset; i < endOffset; i++)
241 total_width += charWidth(buf[i]);
242 return total_width;
243 }
244
245 /**
246 * Returns the total width of the specified byte array.
247 *
248 * @param buf The byte array containing the data.
249 * @param offset The offset into the array to start calculating from.
250 * @param len The total number of bytes to process.
251 *
252 * @return The width of the requested characters.
253 */
254 public int bytesWidth(byte[] buf, int offset, int len)
255 {
256 int total_width = 0;
257 for (int i = offset; i < len; i++)
258 total_width = charWidth((char) buf[i]);
259
260 return total_width;
261 }
262
263 /**
264 * Returns the widths of the first 256 characters in the font.
265 *
266 * @return The widths of the first 256 characters in the font.
267 */
268 public int[] getWidths()
269 {
270 int[] result = new int[256];
271 for (char i = 0; i < 256; i++)
272 result[i] = charWidth(i);
273 return result;
274 }
275
276 /**
277 * Returns a string representation of this object.
278 *
279 * @return A string representation of this object.
280 */
281 public String toString()
282 {
283 return (this.getClass() + "[font=" + font + ",ascent=" + getAscent()
284 + ",descent=" + getDescent() + ",height=" + getHeight() + "]");
285 }
286
287 // Generic FontRenderContext used when getLineMetrics is called with a
288 // plain Graphics object.
289 private static final FontRenderContext gRC = new FontRenderContext(null,
290 false,
291 false);
292
293 /**
294 * Returns a {@link LineMetrics} object constructed with the
295 * specified text and the {@link FontRenderContext} of the Graphics
296 * object when it is an instance of Graphics2D or a generic
297 * FontRenderContext with a null transform, not anti-aliased and not
298 * using fractional metrics.
299 *
300 * @param text The string to calculate metrics from.
301 * @param g The Graphics object that will be used.
302 *
303 * @return A new {@link LineMetrics} object.
304 */
305 public LineMetrics getLineMetrics(String text, Graphics g)
306 {
307 return getLineMetrics(text, 0, text.length(), g);
308 }
309
310 /**
311 * Returns a {@link LineMetrics} object constructed with the
312 * specified text and the {@link FontRenderContext} of the Graphics
313 * object when it is an instance of Graphics2D or a generic
314 * FontRenderContext with a null transform, not anti-aliased and not
315 * using fractional metrics.
316 *
317 * @param text The string to calculate metrics from.
318 * @param begin Index of first character in <code>text</code> to measure.
319 * @param limit Index of last character in <code>text</code> to measure.
320 * @param g The Graphics object that will be used.
321 *
322 * @return A new {@link LineMetrics} object.
323 *
324 * @throws IndexOutOfBoundsException if the range [begin, limit] is
325 * invalid in <code>text</code>.
326 */
327 public LineMetrics getLineMetrics(String text, int begin, int limit,
328 Graphics g)
329 {
330 FontRenderContext rc;
331 if (g instanceof Graphics2D)
332 rc = ((Graphics2D) g).getFontRenderContext();
333 else
334 rc = gRC;
335 return font.getLineMetrics(text, begin, limit, rc);
336 }
337
338 /**
339 * Returns a {@link LineMetrics} object constructed with the
340 * specified text and the {@link FontRenderContext} of the Graphics
341 * object when it is an instance of Graphics2D or a generic
342 * FontRenderContext with a null transform, not anti-aliased and not
343 * using fractional metrics.
344 *
345 * @param chars The string to calculate metrics from.
346 * @param begin Index of first character in <code>text</code> to measure.
347 * @param limit Index of last character in <code>text</code> to measure.
348 * @param g The Graphics object that will be used.
349 *
350 * @return A new {@link LineMetrics} object.
351 *
352 * @throws IndexOutOfBoundsException if the range [begin, limit] is
353 * invalid in <code>text</code>.
354 */
355 public LineMetrics getLineMetrics(char[] chars, int begin, int limit,
356 Graphics g)
357 {
358 FontRenderContext rc;
359 if (g instanceof Graphics2D)
360 rc = ((Graphics2D) g).getFontRenderContext();
361 else
362 rc = gRC;
363 return font.getLineMetrics(chars, begin, limit, rc);
364 }
365
366 /**
367 * Returns the bounds of the largest character in a Graphics context.
368 * @param context the Graphics context object.
369 * @return a <code>Rectangle2D</code> representing the bounds
370 */
371 public Rectangle2D getMaxCharBounds(Graphics context)
372 {
373 if( context instanceof Graphics2D )
374 return font.getMaxCharBounds(((Graphics2D)context).getFontRenderContext());
375 return font.getMaxCharBounds( gRC );
376 }
377
378 /**
379 * Returns a {@link LineMetrics} object constructed with the
380 * specified text and the {@link FontRenderContext} of the Graphics
381 * object when it is an instance of Graphics2D or a generic
382 * FontRenderContext with a null transform, not anti-aliased and not
383 * using fractional metrics.
384 *
385 * @param ci An iterator over the string to calculate metrics from.
386 * @param begin Index of first character in <code>text</code> to measure.
387 * @param limit Index of last character in <code>text</code> to measure.
388 * @param g The Graphics object that will be used.
389 *
390 * @return A new {@link LineMetrics} object.
391 *
392 * @throws IndexOutOfBoundsException if the range [begin, limit] is
393 * invalid in <code>text</code>.
394 */
395 public LineMetrics getLineMetrics(CharacterIterator ci, int begin,
396 int limit, Graphics g)
397 {
398 FontRenderContext rc;
399 if (g instanceof Graphics2D)
400 rc = ((Graphics2D) g).getFontRenderContext();
401 else
402 rc = gRC;
403 return font.getLineMetrics(ci, begin, limit, rc);
404 }
405
406 public Rectangle2D getStringBounds(String str, Graphics context)
407 {
408 return font.getStringBounds(str, getFontRenderContext(context));
409 }
410
411 public Rectangle2D getStringBounds(String str, int beginIndex, int limit,
412 Graphics context)
413 {
414 return font.getStringBounds(str, beginIndex, limit,
415 getFontRenderContext(context));
416 }
417
418 public Rectangle2D getStringBounds(char[] chars, int beginIndex, int limit,
419 Graphics context)
420 {
421 return font.getStringBounds(chars, beginIndex, limit,
422 getFontRenderContext(context));
423 }
424
425 public Rectangle2D getStringBounds(CharacterIterator ci, int beginIndex,
426 int limit, Graphics context)
427 {
428 return font.getStringBounds(ci, beginIndex, limit,
429 getFontRenderContext(context));
430 }
431
432 private FontRenderContext getFontRenderContext(Graphics context)
433 {
434 if (context instanceof Graphics2D)
435 return ((Graphics2D) context).getFontRenderContext();
436
437 return gRC;
438 }
439
440 /**
441 * Returns if the font has uniform line metrics.
442 * @see Font#hasUniformLineMetrics()
443 */
444 public boolean hasUniformLineMetrics()
445 {
446 return font.hasUniformLineMetrics();
447 }
448 }