home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / Chip_1998-11_cd.bin / tema / Cafe / main.bin / FontMetrics.java < prev    next >
Text File  |  1997-10-01  |  14KB  |  346 lines
  1. /*
  2.  * @(#)FontMetrics.java    1.17 97/06/13
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.awt;
  24.  
  25. /** 
  26.  * A font metrics object, which gives information about the rendering 
  27.  * of a particular font on a particular screen. Note that the 
  28.  * implementations of these methods are inefficient, they are usually 
  29.  * overridden with more efficient toolkit-specific implementations.
  30.  * <p>
  31.  * <b>Note to subclassers</b>: Since many of these methods form closed
  32.  * mutually recursive loops, you must take care that you implement
  33.  * at least one of the methods in each such loop in order to prevent
  34.  * infinite recursion when your subclass is used.
  35.  * In particular, the following is the minimal suggested set of methods
  36.  * to override in order to ensure correctness and prevent infinite
  37.  * recursion (though other subsets are equally feasible):
  38.  * <ul>
  39.  * <li><a href=#getAscent>getAscent</a>()
  40.  * <li><a href=#getAscent>getDescent</a>()
  41.  * <li><a href=#getLeading>getLeading</a>()
  42.  * <li><a href=#getMaxAdvance>getMaxAdvance</a>()
  43.  * <li><a href="#charWidth(char)">charWidth</a>(char ch)
  44.  * <li><a href="#charsWidth(char[], int, int)">charsWidth</a>(char data[], int off, int len)
  45.  * </ul>
  46.  * <p>
  47.  * <img src="images-awt/FontMetrics-1.gif" border=15 align
  48.  * ALIGN=right HSPACE=10 VSPACE=7>
  49.  * When an application asks AWT to place a character at the position 
  50.  * (<i>x</i>, <i>y</i>), the character is placed so that its 
  51.  * reference point (shown as the dot in the accompanying image) is 
  52.  * put at that position. The reference point specifies a horizontal 
  53.  * line called the <i>baseline</i> of the character. In normal 
  54.  * printing, the baselines of characters should align. 
  55.  * <p> 
  56.  * In addition, every character in a font has an <i>ascent</i>, a 
  57.  * <i>descent</i>, and an <i>advance width</i>. The ascent is the 
  58.  * amount by which the character ascends above the baseline. The 
  59.  * descent is the amount by which the character descends below the 
  60.  * baseline. The advance width indicates the position at which AWT  
  61.  * should place the next character. 
  62.  * <p>
  63.  * If the current character is placed with its reference point 
  64.  * at the position (<i>x</i>, <i>y</i>), and 
  65.  * the character's advance width is <i>w</i>, then the following 
  66.  * character is placed with its reference point at the position 
  67.  * (<i>x </i><code>+</code><i> w</i>, <i>y</i>). 
  68.  * The advance width is often the same as the width of character's 
  69.  * bounding box, but need not be so. In particular, oblique and 
  70.  * italic fonts often have characters whose top-right corner extends 
  71.  * slightly beyond the advance width. 
  72.  * <p>
  73.  * An array of characters or a string can also have an ascent, a 
  74.  * descent, and an advance width. The ascent of the array is the 
  75.  * maximum ascent of any character in the array. The descent is the 
  76.  * maximum descent of any character in the array. The advance width 
  77.  * is the sum of the advance widths of each of the characters in the 
  78.  * array. 
  79.  * @version     1.17 06/13/97
  80.  * @author     Jim Graham
  81.  * @see         java.awt.Font
  82.  * @since       JDK1.0
  83.  */
  84. public abstract class FontMetrics implements java.io.Serializable {
  85.     /**
  86.      * The actual font.
  87.      * @see #getFont
  88.      * @since JDK1.0
  89.      */
  90.     protected Font font;
  91.  
  92.     /*
  93.      * JDK 1.1 serialVersionUID 
  94.      */
  95.     private static final long serialVersionUID = 1681126225205050147L;
  96.  
  97.     /**
  98.      * Creates a new <code>FontMetrics</code> object for finding out 
  99.      * height and width information about the specified font and  
  100.      * specific character glyphs in that font. 
  101.      * @param     font the font
  102.      * @see       java.awt.Font
  103.      * @since     JDK1.0
  104.      */
  105.     protected FontMetrics(Font font) {
  106.     this.font = font;
  107.     }
  108.  
  109.     /**
  110.      * Gets the font described by this font metric.
  111.      * @return    the font described by this font metric.
  112.      * @since     JDK1.0
  113.      */
  114.     public Font getFont() {
  115.     return font;
  116.     }
  117.  
  118.     /**
  119.      * Determines the <em>standard leading</em> of the font described by 
  120.      * this font metric. The standard leading (interline spacing) is the 
  121.      * logical amount of space to be reserved between the descent of one 
  122.      * line of text and the ascent of the next line. The height metric is 
  123.      * calculated to include this extra space. 
  124.      * @return    the standard leading of the font.
  125.      * @see       java.awt.FontMetrics#getHeight
  126.      * @see       java.awt.FontMetrics#getAscent
  127.      * @see       java.awt.FontMetrics#getDescent
  128.      * @since     JDK1.0
  129.      */
  130.     public int getLeading() {
  131.     return 0;
  132.     }
  133.  
  134.     /**
  135.      * Determines the <em>font ascent</em> of the font described by this 
  136.      * font metric. The font ascent is the distance from the font's 
  137.      * baseline to the top of most alphanumeric characters. Some 
  138.      * characters in the font may extend above the font ascent line. 
  139.      * @return     the font ascent of the font.
  140.      * @see        java.awt.FontMetrics#getMaxAscent
  141.      * @since      JDK1.0
  142.      */
  143.     public int getAscent() {
  144.     return font.getSize();
  145.     }
  146.  
  147.     /**
  148.      * Determines the <em>font descent</em> of the font described by this 
  149.      * font metric. The font descent is the distance from the font's 
  150.      * baseline to the bottom of most alphanumeric characters with 
  151.      * descenders. Some characters in the font may extend below the font 
  152.      * descent line. 
  153.      * @return     the font descent of the font.
  154.      * @see        java.awt.FontMetrics#getMaxDescent
  155.      * @since      JDK1.0
  156.      */
  157.     public int getDescent() {
  158.     return 0;
  159.     }
  160.  
  161.     /**
  162.      * Gets the standard height of a line of text in this font.  This
  163.      * is the distance between the baseline of adjacent lines of text.
  164.      * It is the sum of the leading + ascent + descent.  There is no
  165.      * guarantee that lines of text spaced at this distance will be
  166.      * disjoint; such lines may overlap if some characters overshoot
  167.      * either the standard ascent or the standard descent metric.
  168.      * @return    the standard height of the font.
  169.      * @see       java.awt.FontMetrics#getLeading
  170.      * @see       java.awt.FontMetrics#getAscent
  171.      * @see       java.awt.FontMetrics#getDescent
  172.      * @since     JDK1.0
  173.      */
  174.     public int getHeight() {
  175.     return getLeading() + getAscent() + getDescent();
  176.     }
  177.  
  178.     /**
  179.      * Determines the maximum ascent of the font described by this font 
  180.      * metric. No character extends further above the font's baseline 
  181.      * than this height. 
  182.      * @return    the maximum ascent of any character in the font.
  183.      * @see       java.awt.FontMetrics#getAscent
  184.      * @since     JDK1.0
  185.      */
  186.     public int getMaxAscent() {
  187.     return getAscent();
  188.     }
  189.  
  190.     /**
  191.      * Determines the maximum descent of the font described by this font 
  192.      * metric. No character extends further below the font's baseline 
  193.      * than this height. 
  194.      * @return    the maximum descent of any character in the font.
  195.      * @see       java.awt.FontMetrics#getDescent
  196.      * @since     JDK1.0
  197.      */
  198.     public int getMaxDescent() {
  199.     return getDescent();
  200.     }
  201.  
  202.     /**
  203.      * For backward compatibility only.
  204.      * @see #getMaxDescent
  205.      * @deprecated As of JDK version 1.1.1,
  206.      * replaced by <code>getMaxDescent()</code>.
  207.      */
  208.     public int getMaxDecent() {
  209.     return getMaxDescent();
  210.     }
  211.  
  212.     /**
  213.      * Gets the maximum advance width of any character in this Font. 
  214.      * The advance width is the amount by which the current point is
  215.      * moved from one character to the next in a line of text.
  216.      * @return    the maximum advance width of any character 
  217.      *            in the font, or <code>-1</code> if the 
  218.      *            maximum advance width is not known.
  219.      * @since     JDK1.0
  220.      */
  221.     public int getMaxAdvance() {
  222.     return -1;
  223.     }
  224.  
  225.     /** 
  226.      * Returns the advance width of the specified character in this Font.
  227.      * The advance width is the amount by which the current point is
  228.      * moved from one character to the next in a line of text.
  229.      * @param ch the character to be measured
  230.      * @return    the advance width of the specified <code>char</code> 
  231.      *                 in the font described by this font metric.
  232.      * @see       java.awt.FontMetrics#charsWidth
  233.      * @see       java.awt.FontMetrics#stringWidth
  234.      * @since     JDK1.0
  235.      */
  236.     public int charWidth(int ch) {
  237.     return charWidth((char)ch);
  238.     }
  239.  
  240.     /** 
  241.      * Returns the advance width of the specified character in this Font.
  242.      * The advance width is the amount by which the current point is
  243.      * moved from one character to the next in a line of text.
  244.      * @param ch the character to be measured
  245.      * @return     the advance width of the specified <code>char</code> >
  246.      *                  in the font described by this font metric.
  247.      * @see        java.awt.FontMetrics#charsWidth
  248.      * @see        java.awt.FontMetrics#stringWidth
  249.      * @since      JDK1.0
  250.      */
  251.     public int charWidth(char ch) {
  252.     if (ch < 256) {
  253.         return getWidths()[ch];
  254.     }
  255.     char data[] = {ch};
  256.     return charsWidth(data, 0, 1);
  257.     }
  258.  
  259.     /** 
  260.      * Returns the total advance width for showing the specified String
  261.      * in this Font.
  262.      * The advance width is the amount by which the current point is
  263.      * moved from one character to the next in a line of text.
  264.      * @param str the String to be measured
  265.      * @return    the advance width of the specified string 
  266.      *                  in the font described by this font metric.
  267.      * @see       java.awt.FontMetrics#bytesWidth
  268.      * @see       java.awt.FontMetrics#charsWidth
  269.      * @since     JDK1.0
  270.      */
  271.     public int stringWidth(String str) {
  272.     int len = str.length();
  273.     char data[] = new char[len];
  274.     str.getChars(0, len, data, 0);
  275.     return charsWidth(data, 0, len);
  276.     }
  277.  
  278.     /** 
  279.      * Returns the total advance width for showing the specified array
  280.      * of characters in this Font.
  281.      * The advance width is the amount by which the current point is
  282.      * moved from one character to the next in a line of text.
  283.      * @param data the array of characters to be measured
  284.      * @param off the start offset of the characters in the array
  285.      * @param len the number of characters to be measured from the array
  286.      * @return    the advance width of the subarray of the specified 
  287.      *               <code>char</code> array in the font described by 
  288.      *               this font metric.
  289.      * @see       java.awt.FontMetrics#charWidth(int)
  290.      * @see       java.awt.FontMetrics#charWidth(char)
  291.      * @see       java.awt.FontMetrics#bytesWidth
  292.      * @see       java.awt.FontMetrics#stringWidth
  293.      * @since     JDK1.0
  294.      */
  295.     public int charsWidth(char data[], int off, int len) {
  296.     return stringWidth(new String(data, off, len));
  297.     }
  298.  
  299.     /** 
  300.      * Returns the total advance width for showing the specified array
  301.      * of bytes in this Font.
  302.      * The advance width is the amount by which the current point is
  303.      * moved from one character to the next in a line of text.
  304.      * @param data the array of bytes to be measured
  305.      * @param off the start offset of the bytes in the array
  306.      * @param len the number of bytes to be measured from the array
  307.      * @return    the advance width of the subarray of the specified 
  308.      *               <code>byte</code> array in the font described by 
  309.      *               this font metric.
  310.      * @see       java.awt.FontMetrics#charsWidth
  311.      * @see       java.awt.FontMetrics#stringWidth
  312.      * @since     JDK1.0
  313.      */
  314.     public int bytesWidth(byte data[], int off, int len) {
  315.     return stringWidth(new String(data, 0, off, len));
  316.     }
  317.  
  318.     /**
  319.      * Gets the advance widths of the first 256 characters in the Font.
  320.      * The advance width is the amount by which the current point is
  321.      * moved from one character to the next in a line of text.
  322.      * @return    an array giving the advance widths of the 
  323.      *                 characters in the font 
  324.      *                 described by this font metric.
  325.      * @since     JDK1.0
  326.      */
  327.     public int[] getWidths() {
  328.     int widths[] = new int[256];
  329.     for (char ch = 0 ; ch < 256 ; ch++) {
  330.         widths[ch] = charWidth(ch);
  331.     }
  332.     return widths;
  333.     }
  334.  
  335.     /** 
  336.      * Returns a representation of this <code>FontMetric</code> 
  337.      * object's values as a string.
  338.      * @return    a string representation of this font metric.
  339.      * @since     JDK1.0.
  340.      */
  341.     public String toString() {
  342.     return getClass().getName() + "[font=" + getFont() + "ascent=" +
  343.         getAscent() + ", descent=" + getDescent() + ", height=" + getHeight() + "]";
  344.     }
  345. }
  346.