- java.lang.Object
-
- java.awt.font.GlyphVector
-
- All Implemented Interfaces:
Cloneable
public abstract class GlyphVector extends Object implements Cloneable
AGlyphVector
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 theGlyphVector
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 aFont
.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 oneFont
, and can provide data useful only in relation to thisFont
. In addition, metrics obtained from aGlyphVector
are not generally geometrically scalable since the pixelization and spacing are dependent on grid-fitting algorithms within aFont
. To facilitate accurate measurement of aGlyphVector
and its component glyphs, you must specify a scaling transform, anti-alias mode, and fractional metrics mode when creating theGlyphVector
. These characteristics can be derived from the destination device.For each glyph in the
GlyphVector
, you can obtain:- the position of the glyph
- the transform associated with the glyph
- the metrics of the glyph in the context of the
GlyphVector
. The metrics of the glyph may be different under different transforms, application specified rendering hints, and the specific instance of the glyph within theGlyphVector
.
Altering the data used to create the
GlyphVector
does not alter the state of theGlyphVector
.Methods are provided to adjust the positions of 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 transform individual glyphs within the
GlyphVector
. These methods are primarily useful for special effects.Methods are provided to return both the visual, logical, and pixel bounds of the entire
GlyphVector
or of individual glyphs within theGlyphVector
.Methods are provided to return a
Shape
for theGlyphVector
, and for individual glyphs within theGlyphVector
.- See Also:
Font
,GlyphMetrics
,TextLayout
-
-
Field Summary
Fields Modifier and Type Field Description static int
FLAG_COMPLEX_GLYPHS
A flag used with getLayoutFlags that indicates that thisGlyphVector
has a complex glyph-to-char mapping (one that does not map glyphs to chars one-to-one in strictly ascending or descending order matching the run direction).static int
FLAG_HAS_POSITION_ADJUSTMENTS
A flag used with getLayoutFlags that indicates that thisGlyphVector
has position adjustments.static int
FLAG_HAS_TRANSFORMS
A flag used with getLayoutFlags that indicates that thisGlyphVector
has per-glyph transforms.static int
FLAG_MASK
A mask for supported flags from getLayoutFlags.static int
FLAG_RUN_RTL
A flag used with getLayoutFlags that indicates that thisGlyphVector
has a right-to-left run direction.
-
Constructor Summary
Constructors Constructor Description GlyphVector()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract boolean
equals(GlyphVector set)
Tests if the specifiedGlyphVector
exactly equals thisGlyphVector
.abstract Font
getFont()
Returns theFont
associated with thisGlyphVector
.abstract FontRenderContext
getFontRenderContext()
Returns theFontRenderContext
associated with thisGlyphVector
.int
getGlyphCharIndex(int glyphIndex)
Returns the character index of the specified glyph.int[]
getGlyphCharIndices(int beginGlyphIndex, int numEntries, int[] codeReturn)
Returns the character indices of the specified glyphs.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 thisGlyphVector
.abstract Shape
getGlyphLogicalBounds(int glyphIndex)
Returns the logical bounds of the specified glyph within thisGlyphVector
.abstract GlyphMetrics
getGlyphMetrics(int glyphIndex)
Returns the metrics of the glyph at the specified index into thisGlyphVector
.abstract Shape
getGlyphOutline(int glyphIndex)
Returns aShape
whose interior corresponds to the visual representation of the specified glyph within thisGlyphVector
.Shape
getGlyphOutline(int glyphIndex, float x, float y)
Returns aShape
whose interior corresponds to the visual representation of the specified glyph within thisGlyphVector
, offset to x, y.Rectangle
getGlyphPixelBounds(int index, FontRenderContext renderFRC, float x, float y)
Returns the pixel bounds of the glyph at index when thisGlyphVector
is rendered in aGraphics
with the givenFontRenderContext
at the given location.abstract Point2D
getGlyphPosition(int glyphIndex)
Returns the position of the specified glyph relative to the origin of thisGlyphVector
.abstract float[]
getGlyphPositions(int beginGlyphIndex, int numEntries, float[] positionReturn)
Returns an array of glyph positions for the specified glyphs.abstract AffineTransform
getGlyphTransform(int glyphIndex)
Returns the transform of the specified glyph within thisGlyphVector
.abstract Shape
getGlyphVisualBounds(int glyphIndex)
Returns the visual bounds of the specified glyph within theGlyphVector
.int
getLayoutFlags()
Returns flags describing the global state of the GlyphVector.abstract Rectangle2D
getLogicalBounds()
Returns the logical bounds of thisGlyphVector
.abstract int
getNumGlyphs()
Returns the number of glyphs in thisGlyphVector
.abstract Shape
getOutline()
Returns aShape
whose interior corresponds to the visual representation of thisGlyphVector
.abstract Shape
getOutline(float x, float y)
Returns aShape
whose interior corresponds to the visual representation of thisGlyphVector
when rendered at x, y.Rectangle
getPixelBounds(FontRenderContext renderFRC, float x, float y)
Returns the pixel bounds of thisGlyphVector
when rendered in a graphics with the givenFontRenderContext
at the given location.abstract Rectangle2D
getVisualBounds()
Returns the visual bounds of thisGlyphVector
The visual bounds is the bounding box of the outline of thisGlyphVector
.abstract void
performDefaultLayout()
Assigns default positions to each glyph in thisGlyphVector
.abstract void
setGlyphPosition(int glyphIndex, Point2D newPos)
Sets the position of the specified glyph within thisGlyphVector
.abstract void
setGlyphTransform(int glyphIndex, AffineTransform newTX)
Sets the transform of the specified glyph within thisGlyphVector
.
-
-
-
Field Detail
FLAG_HAS_TRANSFORMS
public static final int FLAG_HAS_TRANSFORMS
A flag used with getLayoutFlags that indicates that thisGlyphVector
has per-glyph transforms.- Since:
- 1.4
- See Also:
- Constant Field Values
FLAG_HAS_POSITION_ADJUSTMENTS
public static final int FLAG_HAS_POSITION_ADJUSTMENTS
A flag used with getLayoutFlags that indicates that thisGlyphVector
has position adjustments. When this is true, the glyph positions don't match the accumulated default advances of the glyphs (for example, if kerning has been done).- Since:
- 1.4
- See Also:
- Constant Field Values
FLAG_RUN_RTL
public static final int FLAG_RUN_RTL
A flag used with getLayoutFlags that indicates that thisGlyphVector
has a right-to-left run direction. This refers to the glyph-to-char mapping and does not imply that the visual locations of the glyphs are necessarily in this order, although generally they will be.- Since:
- 1.4
- See Also:
- Constant Field Values
FLAG_COMPLEX_GLYPHS
public static final int FLAG_COMPLEX_GLYPHS
A flag used with getLayoutFlags that indicates that thisGlyphVector
has a complex glyph-to-char mapping (one that does not map glyphs to chars one-to-one in strictly ascending or descending order matching the run direction).- Since:
- 1.4
- See Also:
- Constant Field Values
FLAG_MASK
public static final int FLAG_MASK
A mask for supported flags from getLayoutFlags. Only bits covered by the mask should be tested.- Since:
- 1.4
- See Also:
- Constant Field Values
-
Method Detail
getFont
public abstract Font getFont()
Returns theFont
associated with thisGlyphVector
.- Returns:
Font
used to create thisGlyphVector
.- See Also:
Font
getFontRenderContext
public abstract FontRenderContext getFontRenderContext()
Returns theFontRenderContext
associated with thisGlyphVector
.- Returns:
FontRenderContext
used to create thisGlyphVector
.- See Also:
FontRenderContext
,Font
performDefaultLayout
public abstract void performDefaultLayout()
Assigns default positions to each glyph in thisGlyphVector
. This can destroy information generated during initial layout of thisGlyphVector
.
getNumGlyphs
public abstract int getNumGlyphs()
Returns the number of glyphs in thisGlyphVector
.- 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 theFont
object that created thisGlyphVector
.- Parameters:
glyphIndex
- the index into thisGlyphVector
that corresponds to the glyph from which to retrieve the glyphcode.- Returns:
-
the glyphcode of the glyph at the specified
glyphIndex
. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
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 theFont
used to create thisGlyphVector
. This method is used for convenience and performance when processing glyphcodes. If no array is passed in, a new array is created.- Parameters:
beginGlyphIndex
- the index into thisGlyphVector
at which to start retrieving glyphcodesnumEntries
- the number of glyphcodes to retrievecodeReturn
- the array that receives the glyphcodes and is then returned- Returns:
- an array of glyphcodes for the specified glyphs.
- Throws:
IllegalArgumentException
- ifnumEntries
is less than 0IndexOutOfBoundsException
- ifbeginGlyphIndex
is less than 0IndexOutOfBoundsException
- if the sum ofbeginGlyphIndex
andnumEntries
is greater than the number of glyphs in thisGlyphVector
getGlyphCharIndex
public int getGlyphCharIndex(int glyphIndex)
Returns the character index of the specified glyph. The character index is the index of the first logical character represented by the glyph. The default implementation assumes a one-to-one, left-to-right mapping of glyphs to characters.- Parameters:
glyphIndex
- the index of the glyph- Returns:
- the index of the first character represented by the glyph
- Since:
- 1.4
getGlyphCharIndices
public int[] getGlyphCharIndices(int beginGlyphIndex, int numEntries, int[] codeReturn)
Returns the character indices of the specified glyphs. The character index is the index of the first logical character represented by the glyph. Indices are returned in glyph order. The default implementation invokes getGlyphCharIndex for each glyph, and subclassers will probably want to override this implementation for performance reasons. Use this method for convenience and performance in processing of glyphcodes. If no array is passed in, a new array is created.- Parameters:
beginGlyphIndex
- the index of the first glyphnumEntries
- the number of glyph indicescodeReturn
- the array into which to return the character indices- Returns:
- an array of character indices, one per glyph.
- Since:
- 1.4
getLogicalBounds
public abstract Rectangle2D getLogicalBounds()
Returns the logical bounds of thisGlyphVector
. This method is used when positioning thisGlyphVector
in relation to visually adjacentGlyphVector
objects.- Returns:
-
a
Rectangle2D
that is the logical bounds of thisGlyphVector
.
getVisualBounds
public abstract Rectangle2D getVisualBounds()
Returns the visual bounds of thisGlyphVector
The visual bounds is the bounding box of the outline of thisGlyphVector
. Because of rasterization and alignment of pixels, it is possible that this box does not enclose all pixels affected by rendering thisGlyphVector
.- Returns:
-
a
Rectangle2D
that is the bounding box of thisGlyphVector
.
getPixelBounds
public Rectangle getPixelBounds(FontRenderContext renderFRC, float x, float y)
Returns the pixel bounds of thisGlyphVector
when rendered in a graphics with the givenFontRenderContext
at the given location. The renderFRC need not be the same as theFontRenderContext
of thisGlyphVector
, and can be null. If it is null, theFontRenderContext
of thisGlyphVector
is used. The default implementation returns the visual bounds, offset to x, y and rounded out to the next integer value (i.e. returns an integer rectangle which encloses the visual bounds) and ignores the FRC. Subclassers should override this method.- Parameters:
renderFRC
- theFontRenderContext
of theGraphics
.x
- the x-coordinate at which to render thisGlyphVector
.y
- the y-coordinate at which to render thisGlyphVector
.- Returns:
-
a
Rectangle
bounding the pixels that would be affected. - Since:
- 1.4
getOutline
public abstract Shape getOutline()
Returns aShape
whose interior corresponds to the visual representation of thisGlyphVector
.- Returns:
-
a
Shape
that is the outline of thisGlyphVector
.
getOutline
public abstract Shape getOutline(float x, float y)
Returns aShape
whose interior corresponds to the visual representation of thisGlyphVector
when rendered at x, y.- Parameters:
x
- the X coordinate of thisGlyphVector
.y
- the Y coordinate of thisGlyphVector
.- Returns:
-
a
Shape
that is the outline of thisGlyphVector
when rendered at the specified coordinates.
getGlyphOutline
public abstract Shape getGlyphOutline(int glyphIndex)
Returns aShape
whose interior corresponds to the visual representation of the specified glyph within thisGlyphVector
. The outline returned by this method is positioned around the origin of each individual glyph.- Parameters:
glyphIndex
- the index into thisGlyphVector
- Returns:
-
a
Shape
that is the outline of the glyph at the specifiedglyphIndex
of thisGlyphVector
. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
getGlyphOutline
public Shape getGlyphOutline(int glyphIndex, float x, float y)
Returns aShape
whose interior corresponds to the visual representation of the specified glyph within thisGlyphVector
, offset to x, y. The outline returned by this method is positioned around the origin of each individual glyph.- Parameters:
glyphIndex
- the index into thisGlyphVector
x
- the X coordinate of the location of thisGlyphVector
y
- the Y coordinate of the location of thisGlyphVector
- Returns:
-
a
Shape
that is the outline of the glyph at the specifiedglyphIndex
of thisGlyphVector
when rendered at the specified coordinates. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
- Since:
- 1.4
getGlyphPosition
public abstract Point2D getGlyphPosition(int glyphIndex)
Returns the position of the specified glyph relative to the origin of thisGlyphVector
. IfglyphIndex
equals the number of glyphs in thisGlyphVector
, this method returns the position after the last glyph. This position is used to define the advance of the entireGlyphVector
.- Parameters:
glyphIndex
- the index into thisGlyphVector
- Returns:
-
a
Point2D
object that is the position of the glyph at the specifiedglyphIndex
. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than the number of glyphs in thisGlyphVector
- See Also:
setGlyphPosition(int, java.awt.geom.Point2D)
setGlyphPosition
public abstract void setGlyphPosition(int glyphIndex, Point2D newPos)
Sets the position of the specified glyph within thisGlyphVector
. IfglyphIndex
equals the number of glyphs in thisGlyphVector
, this method sets the position after the last glyph. This position is used to define the advance of the entireGlyphVector
.- Parameters:
glyphIndex
- the index into thisGlyphVector
newPos
- thePoint2D
at which to position the glyph at the specifiedglyphIndex
- Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than the number of glyphs in thisGlyphVector
- See Also:
getGlyphPosition(int)
getGlyphTransform
public abstract AffineTransform getGlyphTransform(int glyphIndex)
Returns the transform of the specified glyph within thisGlyphVector
. The transform is relative to the glyph position. If no special transform has been applied,null
can be returned. A null return indicates an identity transform.- Parameters:
glyphIndex
- the index into thisGlyphVector
- Returns:
-
an
AffineTransform
that is the transform of the glyph at the specifiedglyphIndex
. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
- See Also:
setGlyphTransform(int, java.awt.geom.AffineTransform)
setGlyphTransform
public abstract void setGlyphTransform(int glyphIndex, AffineTransform newTX)
Sets the transform of the specified glyph within thisGlyphVector
. The transform is relative to the glyph position. Anull
argument fornewTX
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 significant performance changes.- Parameters:
glyphIndex
- the index into thisGlyphVector
newTX
- the new transform of the glyph atglyphIndex
- Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
- See Also:
getGlyphTransform(int)
getLayoutFlags
public int getLayoutFlags()
Returns flags describing the global state of the GlyphVector. Flags not described below are reserved. The default implementation returns 0 (meaning false) for the position adjustments, transforms, rtl, and complex flags. Subclassers should override this method, and make sure it correctly describes the GlyphVector and corresponds to the results of related calls.- Returns:
- an int containing the flags describing the state
- Since:
- 1.4
- See Also:
FLAG_HAS_POSITION_ADJUSTMENTS
,FLAG_HAS_TRANSFORMS
,FLAG_RUN_RTL
,FLAG_COMPLEX_GLYPHS
,FLAG_MASK
getGlyphPositions
public abstract float[] getGlyphPositions(int beginGlyphIndex, int numEntries, float[] positionReturn)
Returns an array of glyph positions for the specified glyphs. 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 numberedbeginGlyphIndex + position/2
. Odd numbered array entries beginning with position one are the Y coordinates of the glyph numberedbeginGlyphIndex + (position-1)/2
. IfbeginGlyphIndex
equals the number of glyphs in thisGlyphVector
, this method gets the position after the last glyph and this position is used to define the advance of the entireGlyphVector
.- Parameters:
beginGlyphIndex
- the index at which to begin retrieving glyph positionsnumEntries
- the number of glyphs to retrievepositionReturn
- the array that receives the glyph positions and is then returned.- Returns:
-
an array of glyph positions specified by
beginGlyphIndex
andnumEntries
. - Throws:
IllegalArgumentException
- ifnumEntries
is less than 0IndexOutOfBoundsException
- ifbeginGlyphIndex
is less than 0IndexOutOfBoundsException
- if the sum ofbeginGlyphIndex
andnumEntries
is greater than the number of glyphs in thisGlyphVector
plus one
getGlyphLogicalBounds
public abstract Shape getGlyphLogicalBounds(int glyphIndex)
Returns the logical bounds of the specified glyph within thisGlyphVector
. 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 thisGlyphVector
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 specifiedglyphIndex
. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
- See Also:
getGlyphVisualBounds(int)
getGlyphVisualBounds
public abstract Shape getGlyphVisualBounds(int glyphIndex)
Returns the visual bounds of the specified glyph within theGlyphVector
. The bounds returned by this method is positioned around the origin of each individual glyph.- Parameters:
glyphIndex
- the index into thisGlyphVector
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 specifiedglyphIndex
. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
- See Also:
getGlyphLogicalBounds(int)
getGlyphPixelBounds
public Rectangle getGlyphPixelBounds(int index, FontRenderContext renderFRC, float x, float y)
Returns the pixel bounds of the glyph at index when thisGlyphVector
is rendered in aGraphics
with the givenFontRenderContext
at the given location. The renderFRC need not be the same as theFontRenderContext
of thisGlyphVector
, and can be null. If it is null, theFontRenderContext
of thisGlyphVector
is used. The default implementation returns the visual bounds of the glyph, offset to x, y and rounded out to the next integer value, and ignores the FRC. Subclassers should override this method.- Parameters:
index
- the index of the glyph.renderFRC
- theFontRenderContext
of theGraphics
.x
- the X position at which to render thisGlyphVector
.y
- the Y position at which to render thisGlyphVector
.- Returns:
-
a
Rectangle
bounding the pixels that would be affected. - Since:
- 1.4
getGlyphMetrics
public abstract GlyphMetrics getGlyphMetrics(int glyphIndex)
Returns the metrics of the glyph at the specified index into thisGlyphVector
.- Parameters:
glyphIndex
- the index into thisGlyphVector
that corresponds to the glyph from which to retrieve its metrics- Returns:
-
a
GlyphMetrics
object that represents the metrics of the glyph at the specifiedglyphIndex
into thisGlyphVector
. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
getGlyphJustificationInfo
public abstract GlyphJustificationInfo getGlyphJustificationInfo(int glyphIndex)
Returns the justification information for the glyph at the specified index into thisGlyphVector
.- Parameters:
glyphIndex
- the index into thisGlyphVector
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 specifiedglyphIndex
into thisGlyphVector
. - Throws:
IndexOutOfBoundsException
- ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
equals
public abstract boolean equals(GlyphVector set)
Tests if the specifiedGlyphVector
exactly equals thisGlyphVector
.- Parameters:
set
- the specifiedGlyphVector
to test- Returns:
true
if the specifiedGlyphVector
equals thisGlyphVector
;false
otherwise.
-