JavaTM 2 Platform
Standard Edition

java.awt.font
Class GlyphVector

java.lang.Object
  |
  +--java.awt.font.GlyphVector

public abstract class GlyphVector
extends Object
implements Cloneable

A GlyphVector object is a collection of glyphs containing geometric information for the placement of each glyph in a transformed coordinate space which corresponds to the device on which the GlyphVector is ultimately displayed.

The GlyphVector does not attempt any interpretation of the sequence of glyphs it contains. Relationships between adjacent glyphs in sequence are solely used to determine the placement of the glyphs in the visual coordinate space.

Instances of GlyphVector are created by a Font.

In a text processing application that can cache intermediate representations of text, creation and subsequent caching of a GlyphVector for use during rendering is the fastest method to present the visual representation of characters to a user.

A GlyphVector is associated with exactly one Font, and can provide data useful only in relation to this Font. In addition, metrics obtained from a GlyphVector are not generally geometrically scaleable since the pixelization and spacing are dependent on grid-fitting algorithms within a Font. To facilitate accurate measurement of a GlyphVector and its component glyphs, you must specify a scaling transform, anti-alias mode, and fractional metrics mode when creating the GlyphVector. These characteristics can be derived from the destination device.

For each glyph in the GlyphVector, you can obtain:

Altering the data used to create the GlyphVector does not alter the state of the GlyphVector.

Methods are provided to create new GlyphVector objects which are the result of editing operations on the GlyphVector, such as glyph insertion and deletion. These methods are most appropriate for applications that are forming combinations such as ligatures from existing glyphs or are breaking such combinations into their component parts for visual presentation.

Methods are provided to create new GlyphVector objects that are the result of specifying new positions for the glyphs within the GlyphVector. These methods are most appropriate for applications that are performing justification operations for the presentation of the glyphs.

Methods are provided to return both the visual and logical bounds of the entire GlyphVector or of individual glyphs within the GlyphVector.

Methods are provided to return a Shape for the GlyphVector, and for individual glyphs within the GlyphVector.

See Also:
Font, GlyphMetrics, TextLayout

Constructor Summary
GlyphVector()
           
 
Method Summary
abstract  boolean equals(GlyphVector set)
          Tests if the specified GlyphVector exactly equals this GlyphVector.
abstract  Font getFont()
          Returns the Font associated with this GlyphVector.
abstract  FontRenderContext getFontRenderContext()
          Returns the FontRenderContext associated with this GlyphVector.
abstract  int getGlyphCode(int glyphIndex)
          Returns the glyphcode of the specified glyph.
abstract  int[] getGlyphCodes(int beginGlyphIndex, int numEntries, int[] codeReturn)
          Returns an array of glyphcodes for the specified glyphs.
abstract  GlyphJustificationInfo getGlyphJustificationInfo(int glyphIndex)
          Returns the justification information for the glyph at the specified index into this GlyphVector.
abstract  Shape getGlyphLogicalBounds(int glyphIndex)
          Returns the logical bounds of the specified glyph within this GlyphVector.
abstract  GlyphMetrics getGlyphMetrics(int glyphIndex)
          Returns the metrics of the glyph at the specified index into this GlyphVector.
abstract  Shape getGlyphOutline(int glyphIndex)
          Returns a Shape whose interior corresponds to the visual representation of the specified glyph within this GlyphVector.
abstract  Point2D getGlyphPosition(int glyphIndex)
          Returns the position of the specified glyph within this GlyphVector.
abstract  float[] getGlyphPositions(int beginGlyphIndex, int numEntries, float[] positionReturn)
          Returns an array of glyph positions for the specified glyphs.
abstract  AffineTransform getGlyphTransform(int glyphIndex)
          Gets the transform of the specified glyph within this GlyphVector.
abstract  Shape getGlyphVisualBounds(int glyphIndex)
          Returns the visual bounds of the specified glyph within the GlyphVector.
abstract  Rectangle2D getLogicalBounds()
          Returns the logical bounds of this GlyphVector.
abstract  int getNumGlyphs()
          Returns the number of glyphs in this GlyphVector.
abstract  Shape getOutline()
          Returns a Shape whose interior corresponds to the visual representation of this GlyphVector.
abstract  Shape getOutline(float x, float y)
          Returns a Shape whose interior corresponds to the visual representation of this GlyphVector, offset to x, y.
abstract  Rectangle2D getVisualBounds()
          Returns the visual bounds of this GlyphVector The visual bounds is the tightest rectangle enclosing all non-background pixels in the rendered representation of this GlyphVector.
abstract  void performDefaultLayout()
          Assigns default positions to each glyph in this GlyphVector.
abstract  void setGlyphPosition(int glyphIndex, Point2D newPos)
          Sets the position of the specified glyph within this GlyphVector.
abstract  void setGlyphTransform(int glyphIndex, AffineTransform newTX)
          Sets the transform of the specified glyph within this GlyphVector.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GlyphVector

public GlyphVector()
Method Detail

getFont

public abstract Font getFont()
Returns the Font associated with this GlyphVector.
See Also:
Font

getFontRenderContext

public abstract FontRenderContext getFontRenderContext()
Returns the FontRenderContext associated with this GlyphVector.
Returns:
FontRenderContext used to create this GlyphVector.
See Also:
FontRenderContext, Font

performDefaultLayout

public abstract void performDefaultLayout()
Assigns default positions to each glyph in this GlyphVector. No shaping, reordering, or contextual substitution is performed.

getNumGlyphs

public abstract int getNumGlyphs()
Returns the number of glyphs in this GlyphVector. This information is used to create arrays that are to be filled with results of other information retrieval operations.
Returns:
number of glyphs in this GlyphVector.

getGlyphCode

public abstract int getGlyphCode(int glyphIndex)
Returns the glyphcode of the specified glyph. This return value is meaningless to anything other than a Font object and can be used to ask the Font object about the existence of ligatures and other context sensitive information.
Parameters:
glyphIndex - the index into this GlyphVector that corresponds to the glyph from which to retrieve the glyphcode.
Returns:
the glyphcode of the glyph corresponding the the specified glyphIndex.
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector

getGlyphCodes

public abstract int[] getGlyphCodes(int beginGlyphIndex,
                                    int numEntries,
                                    int[] codeReturn)
Returns an array of glyphcodes for the specified glyphs. The contents of this return value are meaningless to anything other than a Font and can be used to ask the Font about the existence of ligatures and other context sensitive information. This method is used for convenience and performance when processing glyphcodes. If no array is passed in, an array is created.
Parameters:
beginGlyphIndex - the index into this GlyphVector at which to start retrieving glyphcodes for the corresponding glyphs
numEntries - the offset from beginGlyphIndex at which to stop retrieving glyphcodes
codeReturn - the array that receives the glyphcodes and is then returned
Returns:
an array of glyphcodes for the specified glyphs.
Throws:
IllegalArgumentException - if numEntries is less than 0
IndexOutOfBoundsException - if beginGlyphIndex is less than 0
IndexOutOfBoundsException - if the sum of beginGlyphIndex and numEntries is greater than the number of glyphs in this GlyphVector

getLogicalBounds

public abstract Rectangle2D getLogicalBounds()
Returns the logical bounds of this GlyphVector. This method is used when positioning this GlyphVector in relation to visually adjacent GlyphVector objects.
Returns:
a Rectangle2D that is the logical bounds of this GlyphVector.

getVisualBounds

public abstract Rectangle2D getVisualBounds()
Returns the visual bounds of this GlyphVector The visual bounds is the tightest rectangle enclosing all non-background pixels in the rendered representation of this GlyphVector.
Returns:
a Rectangle2D that is the tightest bounds of this GlyphVector.

getOutline

public abstract Shape getOutline()
Returns a Shape whose interior corresponds to the visual representation of this GlyphVector.
Returns:
a Shape that is the outline of this GlyphVector.

getOutline

public abstract Shape getOutline(float x,
                                 float y)
Returns a Shape whose interior corresponds to the visual representation of this GlyphVector, offset to x, y.
Parameters:
x, y - the coordinates of the location of the outline Shape
Returns:
a Shape that is the outline of this GlyphVector, offset to the specified coordinates.

getGlyphOutline

public abstract Shape getGlyphOutline(int glyphIndex)
Returns a Shape whose interior corresponds to the visual representation of the specified glyph within this GlyphVector.
Parameters:
glyphIndex - the index into this GlyphVector
Returns:
a Shape that is the outline of the glyph at the specified glyphIndex of this GlyphVector.
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector

getGlyphPosition

public abstract Point2D getGlyphPosition(int glyphIndex)
Returns the position of the specified glyph within this GlyphVector. This position corresponds to the leading edge of the baseline for the glyph. If glyphIndex equals the number of of glyphs in this GlyphVector, this method gets the position after the last glyph and this position is used to define the advance of the entire GlyphVector.
Parameters:
glyphIndex - the index into this GlyphVector
Returns:
a Point2D object that is the position of the glyph at the specified glyphIndex.
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than the number of glyphs in this GlyphVector

setGlyphPosition

public abstract void setGlyphPosition(int glyphIndex,
                                      Point2D newPos)
Sets the position of the specified glyph within this GlyphVector. This position corresponds to the leading edge of the baseline for the glyph. If glyphIndex equals the number of of glyphs in this GlyphVector, this method sets the position after the last glyph and this position is used to define the advance of the entire GlyphVector.
Parameters:
glyphIndex - the index into this GlyphVector
newPos - the Point2D at which to position the glyph at the specified glyphIndex
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than the number of glyphs in this GlyphVector

getGlyphTransform

public abstract AffineTransform getGlyphTransform(int glyphIndex)
Gets the transform of the specified glyph within this GlyphVector. The transform is relative to the glyph position. If no special transform has been applied, null can be returned. Such a transform would be an identity transform.
Parameters:
glyphIndex - the index into this GlyphVector
Returns:
an AffineTransform that is the transform of the glyph at the specified glyphIndex.
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector

setGlyphTransform

public abstract void setGlyphTransform(int glyphIndex,
                                       AffineTransform newTX)
Sets the transform of the specified glyph within this GlyphVector. The transform is relative to the glyph position. A null argument for newTX indicates that no special transform is applied for the specified glyph. This method can be used to rotate, mirror, translate and scale the glyph. Adding a transform can result in signifant performance changes.
Parameters:
glyphIndex - the index into this GlyphVector
newTx - the specified transform that the transform of the glyph at the specified glyphIndex is set to
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector

getGlyphPositions

public abstract float[] getGlyphPositions(int beginGlyphIndex,
                                          int numEntries,
                                          float[] positionReturn)
Returns an array of glyph positions for the specified glyphs. The position of each glyph corresponds to the leading edge of the baseline for that glyph. This method is used for convenience and performance when processing glyph positions. If no array is passed in, a new array is created. Even numbered array entries beginning with position zero are the X coordinates of the glyph numbered beginGlyphIndex + position/2. Odd numbered array entries beginning with position one are the Y coordinates of the glyph numbered beginGlyphIndex + (position-1)/2. If beginGlyphIndex equals the number of of glyphs in this GlyphVector, this method gets the position after the last glyph and this position is used to define the advance of the entire GlyphVector.
Parameters:
beginGlyphIndex - the index at which to begin retrieving glyph positions
numEntries - the offset from beginGlyphIndex at which to stop retrieving glyph positions
positionReturn - the array that receives the glyph positions and is then returned.
Returns:
an array of glyph positions specified by beginGlyphIndex and numEntries.
Throws:
IllegalArgumentException - if numEntries is less than 0
IndexOutOfBoundsException - if beginGlyphIndex is less than 0
IndexOutOfBoundsException - if the sum of beginGlyphIndex and numEntries is greater than the number of glyphs in this GlyphVector plus one

getGlyphLogicalBounds

public abstract Shape getGlyphLogicalBounds(int glyphIndex)
Returns the logical bounds of the specified glyph within this GlyphVector. These logical bounds have a total of four edges, with two edges parallel to the baseline under the glyph's transform and the other two edges are shared with adjacent glyphs if they are present. This method is useful for hit-testing of the specified glyph, positioning of a caret at the leading or trailing edge of a glyph, and for drawing a highlight region around the specified glyph.
Parameters:
glyphIndex - the index into this GlyphVector that corresponds to the glyph from which to retrieve its logical bounds
Returns:
a Shape that is the logical bounds of the glyph at the specified glyphIndex.
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector
See Also:
getGlyphVisualBounds(int)

getGlyphVisualBounds

public abstract Shape getGlyphVisualBounds(int glyphIndex)
Returns the visual bounds of the specified glyph within the GlyphVector. These visual bounds have a total of four edges, representing the tightest polygon enclosing non-background pixels in the rendered representation of the glyph whose edges are parallel to the edges of the logical bounds. Useful for hit-testing of the specified glyph.
Parameters:
glyphIndex - the index into this GlyphVector that corresponds to the glyph from which to retrieve its visual bounds
Returns:
a Shape that is the visual bounds of the glyph at the specified glyphIndex.
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector
See Also:
getGlyphLogicalBounds(int)

getGlyphMetrics

public abstract GlyphMetrics getGlyphMetrics(int glyphIndex)
Returns the metrics of the glyph at the specified index into this GlyphVector.
Parameters:
glyphIndex - the index into this GlyphVector that corresponds to the glyph from which to retrieve its metrics
Returns:
a GlyphMetrics object that represents the metrics of the glyph at the specified glyphIndex into this GlyphVector.
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector

getGlyphJustificationInfo

public abstract GlyphJustificationInfo getGlyphJustificationInfo(int glyphIndex)
Returns the justification information for the glyph at the specified index into this GlyphVector.
Parameters:
glyphIndex - the index into this GlyphVector that corresponds to the glyph from which to retrieve its justification properties
Returns:
a GlyphJustificationInfo object that represents the justification properties of the glyph at the specified glyphIndex into this GlyphVector.
Throws:
IndexOutOfBoundsException - if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector

equals

public abstract boolean equals(GlyphVector set)
Tests if the specified GlyphVector exactly equals this GlyphVector.
Parameters:
set - the specified GlyphVector to test
Returns:
true if the specified GlyphVector equals this GlyphVector; false otherwise.

JavaTM 2 Platform
Standard Edition

Submit a bug or feature
Java, Java 2D, and JDBC are a trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.