Source for gnu.java.awt.font.FontDelegate

   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:   /**
  65:    * Returns the full name of this font face in the specified
  66:    * locale, for example <i>&#x201c;Univers Light&#x201d;</i>.
  67:    *
  68:    * @param locale the locale for which to localize the name.
  69:    *
  70:    * @return the face name.
  71:    */
  72:   public String getFullName(Locale locale);
  73:   
  74:   
  75:   /**
  76:    * Returns the name of the family to which this font face belongs,
  77:    * for example <i>&#x201c;Univers&#x201d;</i>.
  78:    *
  79:    * @param locale the locale for which to localize the name.
  80:    *
  81:    * @return the family name.
  82:    */
  83:   public String getFamilyName(Locale locale);
  84: 
  85: 
  86:   /**
  87:    * Returns the name of this font face inside the family, for example
  88:    * <i>&#x201c;Light&#x201d;</i>.
  89:    *
  90:    * @param locale the locale for which to localize the name.
  91:    *
  92:    * @return the name of the face inside its family.
  93:    */
  94:   public String getSubFamilyName(Locale locale);
  95:   
  96:   
  97:   /**
  98:    * Returns the PostScript name of this font face, for example
  99:    * <i>&#x201c;Helvetica-Bold&#x201d;</i>.
 100:    *
 101:    * @return the PostScript name, or <code>null</code> if the font
 102:    * does not provide a PostScript name.
 103:    */
 104:   public String getPostScriptName();
 105: 
 106: 
 107:   /**
 108:    * Returns the number of glyphs in this font face.
 109:    */
 110:   public int getNumGlyphs();
 111:   
 112:   
 113:   /**
 114:    * Returns the index of the glyph which gets displayed if the font
 115:    * cannot map a Unicode code point to a glyph. Many fonts show this
 116:    * glyph as an empty box.
 117:    */
 118:   public int getMissingGlyphCode();
 119:   
 120: 
 121:   /**
 122:    * Creates a GlyphVector by mapping each character in a
 123:    * CharacterIterator to the corresponding glyph.
 124:    *
 125:    * <p>The mapping takes only the font&#x2019;s <code>cmap</code>
 126:    * tables into consideration. No other operations (such as glyph
 127:    * re-ordering, composition, or ligature substitution) are
 128:    * performed. This means that the resulting GlyphVector will not be
 129:    * correct for text in languages that have complex
 130:    * character-to-glyph mappings, such as Arabic, Hebrew, Hindi, or
 131:    * Thai.
 132:    *
 133:    * @param font the font object that the created GlyphVector
 134:    * will return when it gets asked for its font. This argument is
 135:    * needed because the public API works with java.awt.Font,
 136:    * not with some private delegate like OpenTypeFont.
 137:    *
 138:    * @param frc the font rendering parameters that are used for
 139:    * measuring glyphs. The exact placement of text slightly depends on
 140:    * device-specific characteristics, for instance the device
 141:    * resolution or anti-aliasing. For this reason, any measurements
 142:    * will only be accurate if the passed
 143:    * <code>FontRenderContext</code> correctly reflects the relevant
 144:    * parameters. Hence, <code>frc</code> should be obtained from the
 145:    * same <code>Graphics2D</code> that will be used for drawing, and
 146:    * any rendering hints should be set to the desired values before
 147:    * obtaining <code>frc</code>.
 148:    *
 149:    * @param ci a CharacterIterator for iterating over the
 150:    * characters to be displayed.
 151:    */
 152:   public GlyphVector createGlyphVector(Font font,
 153:                                        FontRenderContext frc,
 154:                                        CharacterIterator ci);
 155: 
 156: 
 157:   /**
 158:    * Determines the advance width and height for a glyph.
 159:    *
 160:    * @param glyphIndex the glyph whose advance width is to be
 161:    * determined.
 162:    *
 163:    * @param pointSize the point size of the font.
 164:    *
 165:    * @param transform a transform that is applied in addition to
 166:    * scaling to the specified point size. This is often used for
 167:    * scaling according to the device resolution. Those who lack any
 168:    * aesthetic sense may also use the transform to slant or stretch
 169:    * glyphs.
 170:    *
 171:    * @param antialias <code>true</code> for anti-aliased rendering,
 172:    * <code>false</code> for normal rendering. For hinted fonts,
 173:    * this parameter may indeed affect the result.
 174:    *
 175:    * @param fractionalMetrics <code>true</code> for fractional metrics,
 176:    * <code>false</code> for rounding the result to a pixel boundary.
 177:    *
 178:    * @param horizontal <code>true</code> for horizontal line layout,
 179:    * <code>false</code> for vertical line layout.
 180:    *
 181:    * @param advance a point whose <code>x</code> and <code>y</code>
 182:    * fields will hold the advance in each direction. It is well
 183:    * possible that both values are non-zero, for example for rotated
 184:    * text or for Urdu fonts.
 185:    */
 186:   public void getAdvance(int glyphIndex,
 187:                          float pointSize,
 188:                          AffineTransform transform,
 189:                          boolean antialias,
 190:                          boolean fractionalMetrics,
 191:                          boolean horizontal,
 192:                          Point2D advance);
 193:   
 194: 
 195:   /**
 196:    * Returns the shape of a glyph.
 197:    *
 198:    * @param glyphIndex the glyph whose advance width is to be
 199:    * determined.
 200:    *
 201:    * @param pointSize the point size of the font.
 202:    *
 203:    * @param transform a transform that is applied in addition to
 204:    * scaling to the specified point size. This is often used for
 205:    * scaling according to the device resolution. Those who lack any
 206:    * aesthetic sense may also use the transform to slant or stretch
 207:    * glyphs.
 208:    *
 209:    * @param antialias <code>true</code> for anti-aliased rendering,
 210:    * <code>false</code> for normal rendering. For hinted fonts, this
 211:    * parameter may indeed affect the result.
 212:    *
 213:    * @param fractionalMetrics <code>true</code> for fractional
 214:    * metrics, <code>false</code> for rounding the result to a pixel
 215:    * boundary.
 216:    *
 217:    * @return the scaled and grid-fitted outline of the specified
 218:    * glyph, or <code>null</code> for bitmap fonts.
 219:    */
 220:   public GeneralPath getGlyphOutline(int glyphIndex,
 221:                                      float pointSize,
 222:                                      AffineTransform transform,
 223:                                      boolean antialias,
 224:                                      boolean fractionalMetrics);
 225: 
 226: 
 227:   /**
 228:    * Returns a name for the specified glyph. This is useful for
 229:    * generating PostScript or PDF files that embed some glyphs of a
 230:    * font.
 231:    *
 232:    * <p><b>Names are not unique:</b> Under some rare circumstances,
 233:    * the same name can be returned for different glyphs. It is
 234:    * therefore recommended that printer drivers check whether the same
 235:    * name has already been returned for antoher glyph, and make the
 236:    * name unique by adding the string ".alt" followed by the glyph
 237:    * index.</p>
 238:    *
 239:    * <p>This situation would occur for an OpenType or TrueType font
 240:    * that has a <code>post</code> table of format 3 and provides a
 241:    * mapping from glyph IDs to Unicode sequences through a
 242:    * <code>Zapf</code> table. If the same sequence of Unicode
 243:    * codepoints leads to different glyphs (depending on contextual
 244:    * position, for example, or on typographic sophistication level),
 245:    * the same name would get synthesized for those glyphs.
 246:    *
 247:    * @param glyphIndex the glyph whose name the caller wants to
 248:    * retrieve.
 249:    */
 250:   public String getGlyphName(int glyphIndex);
 251: 
 252: 
 253:   /**
 254:    * Determines the distance between the base line and the highest
 255:    * ascender.
 256:    *
 257:    * @param pointSize the point size of the font.
 258:    *
 259:    * @param transform a transform that is applied in addition to
 260:    * scaling to the specified point size. This is often used for
 261:    * scaling according to the device resolution. Those who lack any
 262:    * aesthetic sense may also use the transform to slant or stretch
 263:    * glyphs.
 264:    *
 265:    * @param antialiased <code>true</code> for anti-aliased rendering,
 266:    * <code>false</code> for normal rendering. For hinted fonts,
 267:    * this parameter may indeed affect the result.
 268:    *
 269:    * @param fractionalMetrics <code>true</code> for fractional metrics,
 270:    * <code>false</code> for rounding the result to a pixel boundary.
 271:    *
 272:    * @param horizontal <code>true</code> for horizontal line layout,
 273:    * <code>false</code> for vertical line layout.
 274:    *
 275:    * @return the ascent, which usually is a positive number.
 276:    */
 277:   public float getAscent(float pointSize,
 278:                          AffineTransform transform,
 279:                          boolean antialiased,
 280:                          boolean fractionalMetrics,
 281:                          boolean horizontal);
 282: 
 283: 
 284:   /**
 285:    * Determines the distance between the base line and the lowest
 286:    * descender.
 287:    *
 288:    * @param pointSize the point size of the font.
 289:    *
 290:    * @param transform a transform that is applied in addition to
 291:    * scaling to the specified point size. This is often used for
 292:    * scaling according to the device resolution. Those who lack any
 293:    * aesthetic sense may also use the transform to slant or stretch
 294:    * glyphs.
 295:    *
 296:    * @param antialiased <code>true</code> for anti-aliased rendering,
 297:    * <code>false</code> for normal rendering. For hinted fonts,
 298:    * this parameter may indeed affect the result.
 299:    *
 300:    * @param fractionalMetrics <code>true</code> for fractional metrics,
 301:    * <code>false</code> for rounding the result to a pixel boundary.
 302:    *
 303:    * @param horizontal <code>true</code> for horizontal line layout,
 304:    * <code>false</code> for vertical line layout.
 305:    *
 306:    * @return the descent, which usually is a nagative number.
 307:    */
 308:   public float getDescent(float pointSize,
 309:                           AffineTransform transform,
 310:                           boolean antialiased,
 311:                           boolean fractionalMetrics,
 312:                           boolean horizontal);
 313: }