libjava/classpath/gnu/java/awt/font/FontDelegate.java

   1 /* FontDelegate.java -- Interface implemented by all font delegates.
   2    Copyright (C) 2006 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package gnu.java.awt.font;
  40
  41 import java.awt.Font;
  42 import java.awt.font.FontRenderContext;
  43 import java.awt.font.GlyphVector;
  44 import java.awt.geom.AffineTransform;
  45 import java.awt.geom.GeneralPath;
  46 import java.awt.geom.Point2D;
  47 import java.text.CharacterIterator;
  48 import java.util.Locale;
  49
  50
  51 /**
  52  * The interface that all font delegate objects implement,
  53  * irrespective of where they get their information from.
  54  *
  55  * <p><b>Thread Safety:</b> All classes that implement the
  56  * <code>FontDelegate</code> interface must allow calling these
  57  * methods from multiple concurrent threads. The delegates are
  58  * responsible for performing the necessary synchronization.
  59  *
  60  * @author Sascha Brawer (brawer@dandelis.ch)
  61  */
  62 public interface FontDelegate
  63 {
  64   public static final int FLAG_FITTED = 1 << 0;
  65   public static final int FLAG_NO_HINT_HORIZONTAL = 1 << 1;
  66   public static final int FLAG_NO_HINT_VERTICAL = 1 << 2;
  67   public static final int FLAG_NO_HINT_EDGE_POINTS = 1 << 3;
  68   public static final int FLAG_NO_HINT_STRONG_POINTS = 1 << 4;
  69   public static final int FLAG_NO_HINT_WEAK_POINTS = 1 << 5;
  70
  71   /**
  72    * Returns the full name of this font face in the specified
  73    * locale, for example <i>&#x201c;Univers Light&#x201d;</i>.
  74    *
  75    * @param locale the locale for which to localize the name.
  76    *
  77    * @return the face name.
  78    */
  79   public String getFullName(Locale locale);
  80
  81
  82   /**
  83    * Returns the name of the family to which this font face belongs,
  84    * for example <i>&#x201c;Univers&#x201d;</i>.
  85    *
  86    * @param locale the locale for which to localize the name.
  87    *
  88    * @return the family name.
  89    */
  90   public String getFamilyName(Locale locale);
  91
  92
  93   /**
  94    * Returns the name of this font face inside the family, for example
  95    * <i>&#x201c;Light&#x201d;</i>.
  96    *
  97    * @param locale the locale for which to localize the name.
  98    *
  99    * @return the name of the face inside its family.
 100    */
 101   public String getSubFamilyName(Locale locale);
 102
 103
 104   /**
 105    * Returns the PostScript name of this font face, for example
 106    * <i>&#x201c;Helvetica-Bold&#x201d;</i>.
 107    *
 108    * @return the PostScript name, or <code>null</code> if the font
 109    * does not provide a PostScript name.
 110    */
 111   public String getPostScriptName();
 112
 113
 114   /**
 115    * Returns the number of glyphs in this font face.
 116    */
 117   public int getNumGlyphs();
 118
 119   /**
 120    * Returns the glyph code for the specified character.
 121    *
 122    * @param c the character to map
 123    *
 124    * @return the glyph code
 125    */
 126   public int getGlyphIndex(int c);
 127
 128   /**
 129    * Returns the index of the glyph which gets displayed if the font
 130    * cannot map a Unicode code point to a glyph. Many fonts show this
 131    * glyph as an empty box.
 132    */
 133   public int getMissingGlyphCode();
 134
 135
 136   /**
 137    * Creates a GlyphVector by mapping each character in a
 138    * CharacterIterator to the corresponding glyph.
 139    *
 140    * <p>The mapping takes only the font&#x2019;s <code>cmap</code>
 141    * tables into consideration. No other operations (such as glyph
 142    * re-ordering, composition, or ligature substitution) are
 143    * performed. This means that the resulting GlyphVector will not be
 144    * correct for text in languages that have complex
 145    * character-to-glyph mappings, such as Arabic, Hebrew, Hindi, or
 146    * Thai.
 147    *
 148    * @param font the font object that the created GlyphVector
 149    * will return when it gets asked for its font. This argument is
 150    * needed because the public API works with java.awt.Font,
 151    * not with some private delegate like OpenTypeFont.
 152    *
 153    * @param frc the font rendering parameters that are used for
 154    * measuring glyphs. The exact placement of text slightly depends on
 155    * device-specific characteristics, for instance the device
 156    * resolution or anti-aliasing. For this reason, any measurements
 157    * will only be accurate if the passed
 158    * <code>FontRenderContext</code> correctly reflects the relevant
 159    * parameters. Hence, <code>frc</code> should be obtained from the
 160    * same <code>Graphics2D</code> that will be used for drawing, and
 161    * any rendering hints should be set to the desired values before
 162    * obtaining <code>frc</code>.
 163    *
 164    * @param ci a CharacterIterator for iterating over the
 165    * characters to be displayed.
 166    */
 167   public GlyphVector createGlyphVector(Font font,
 168                                        FontRenderContext frc,
 169                                        CharacterIterator ci);
 170
 171
 172   /**
 173    * Determines the advance width and height for a glyph.
 174    *
 175    * @param glyphIndex the glyph whose advance width is to be
 176    * determined.
 177    *
 178    * @param pointSize the point size of the font.
 179    *
 180    * @param transform a transform that is applied in addition to
 181    * scaling to the specified point size. This is often used for
 182    * scaling according to the device resolution. Those who lack any
 183    * aesthetic sense may also use the transform to slant or stretch
 184    * glyphs.
 185    *
 186    * @param antialias <code>true</code> for anti-aliased rendering,
 187    * <code>false</code> for normal rendering. For hinted fonts,
 188    * this parameter may indeed affect the result.
 189    *
 190    * @param fractionalMetrics <code>true</code> for fractional metrics,
 191    * <code>false</code> for rounding the result to a pixel boundary.
 192    *
 193    * @param horizontal <code>true</code> for horizontal line layout,
 194    * <code>false</code> for vertical line layout.
 195    *
 196    * @param advance a point whose <code>x</code> and <code>y</code>
 197    * fields will hold the advance in each direction. It is well
 198    * possible that both values are non-zero, for example for rotated
 199    * text or for Urdu fonts.
 200    */
 201   public void getAdvance(int glyphIndex,
 202                          float pointSize,
 203                          AffineTransform transform,
 204                          boolean antialias,
 205                          boolean fractionalMetrics,
 206                          boolean horizontal,
 207                          Point2D advance);
 208
 209
 210   /**
 211    * Returns the shape of a glyph.
 212    *
 213    * @param glyphIndex the glyph whose advance width is to be
 214    * determined.
 215    *
 216    * @param pointSize the point size of the font.
 217    *
 218    * @param transform a transform that is applied in addition to
 219    * scaling to the specified point size. This is often used for
 220    * scaling according to the device resolution. Those who lack any
 221    * aesthetic sense may also use the transform to slant or stretch
 222    * glyphs.
 223    *
 224    * @param antialias <code>true</code> for anti-aliased rendering,
 225    * <code>false</code> for normal rendering. For hinted fonts, this
 226    * parameter may indeed affect the result.
 227    *
 228    * @param fractionalMetrics <code>true</code> for fractional
 229    * metrics, <code>false</code> for rounding the result to a pixel
 230    * boundary.
 231    *
 232    * @return the scaled and grid-fitted outline of the specified
 233    * glyph, or <code>null</code> for bitmap fonts.
 234    */
 235   public GeneralPath getGlyphOutline(int glyphIndex,
 236                                      float pointSize,
 237                                      AffineTransform transform,
 238                                      boolean antialias,
 239                                      boolean fractionalMetrics,
 240                                      int type);
 241
 242
 243   /**
 244    * Returns a name for the specified glyph. This is useful for
 245    * generating PostScript or PDF files that embed some glyphs of a
 246    * font.
 247    *
 248    * <p><b>Names are not unique:</b> Under some rare circumstances,
 249    * the same name can be returned for different glyphs. It is
 250    * therefore recommended that printer drivers check whether the same
 251    * name has already been returned for antoher glyph, and make the
 252    * name unique by adding the string ".alt" followed by the glyph
 253    * index.</p>
 254    *
 255    * <p>This situation would occur for an OpenType or TrueType font
 256    * that has a <code>post</code> table of format 3 and provides a
 257    * mapping from glyph IDs to Unicode sequences through a
 258    * <code>Zapf</code> table. If the same sequence of Unicode
 259    * codepoints leads to different glyphs (depending on contextual
 260    * position, for example, or on typographic sophistication level),
 261    * the same name would get synthesized for those glyphs.
 262    *
 263    * @param glyphIndex the glyph whose name the caller wants to
 264    * retrieve.
 265    */
 266   public String getGlyphName(int glyphIndex);
 267
 268
 269   /**
 270    * Determines the distance between the base line and the highest
 271    * ascender.
 272    *
 273    * @param pointSize the point size of the font.
 274    *
 275    * @param transform a transform that is applied in addition to
 276    * scaling to the specified point size. This is often used for
 277    * scaling according to the device resolution. Those who lack any
 278    * aesthetic sense may also use the transform to slant or stretch
 279    * glyphs.
 280    *
 281    * @param antialiased <code>true</code> for anti-aliased rendering,
 282    * <code>false</code> for normal rendering. For hinted fonts,
 283    * this parameter may indeed affect the result.
 284    *
 285    * @param fractionalMetrics <code>true</code> for fractional metrics,
 286    * <code>false</code> for rounding the result to a pixel boundary.
 287    *
 288    * @param horizontal <code>true</code> for horizontal line layout,
 289    * <code>false</code> for vertical line layout.
 290    *
 291    * @return the ascent, which usually is a positive number.
 292    */
 293   public float getAscent(float pointSize,
 294                          AffineTransform transform,
 295                          boolean antialiased,
 296                          boolean fractionalMetrics,
 297                          boolean horizontal);
 298
 299
 300   /**
 301    * Determines the distance between the base line and the lowest
 302    * descender.
 303    *
 304    * @param pointSize the point size of the font.
 305    *
 306    * @param transform a transform that is applied in addition to
 307    * scaling to the specified point size. This is often used for
 308    * scaling according to the device resolution. Those who lack any
 309    * aesthetic sense may also use the transform to slant or stretch
 310    * glyphs.
 311    *
 312    * @param antialiased <code>true</code> for anti-aliased rendering,
 313    * <code>false</code> for normal rendering. For hinted fonts,
 314    * this parameter may indeed affect the result.
 315    *
 316    * @param fractionalMetrics <code>true</code> for fractional metrics,
 317    * <code>false</code> for rounding the result to a pixel boundary.
 318    *
 319    * @param horizontal <code>true</code> for horizontal line layout,
 320    * <code>false</code> for vertical line layout.
 321    *
 322    * @return the descent, which usually is a nagative number.
 323    */
 324   public float getDescent(float pointSize,
 325                           AffineTransform transform,
 326                           boolean antialiased,
 327                           boolean fractionalMetrics,
 328                           boolean horizontal);
 329 }