|
Generated by JDiff |
||||||||
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES |
This file contains all the changes in documentation in the packagejava.awt.font
as colored differences. Deletions are shownlike this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.
Gets the transform that is used to scale typographical points to pixels in thisClass FontRenderContext, int hashCode()FontRenderContext
. @returnsreturn theAffineTransform
of thisFontRenderContext
. @see AffineTransform
Class FontRenderContext, boolean isAntiAliased()ReturnsReturn ahashhashcodecode value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable. The general contract of hashCode is: Whenever it is invoked on the same object more than once during an execution of a Java application the hashCode method must consistently return the same integer provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the equals(Object) method then calling the hashCode method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the java.lang.Object#equals(java.lang.Object) method then calling the hashCode method on each of the two objects must produce distinct integer results. However the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables. As much as is reasonably practical the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer but this implementation technique is not required by the JavaTM programming language.) @return a hash code valuefor thisobject. @see java.lang.Object#equals(java.lang.Object) @see java.utilFontRenderContext.Hashtable
Gets the text anti-aliasing mode used in thisClass FontRenderContext, boolean usesFractionalMetrics()FontRenderContext
. @returnsreturntrue
if text is anti-aliased in thisFontRenderContext
;false
otherwise. @see java.awt.RenderingHints#KEY_TEXT_ANTIALIASING
Gets the text fractional metrics mode requested by the application for use in thisFontRenderContext
. @returnsreturntrue
if layout should be performed with fractional metrics;false
otherwise. in thisFontRenderContext
. @see java.awt.RenderingHints#KEY_FRACTIONALMETRICS
TheClass GlyphMetrics, constructor GlyphMetrics(float, Rectangle2D, byte)GlyphMetrics
class represents infomation for a single glyph. A glyph is the visual representation of one or more characters. Many different glyphs can be used to represent a single character or combination of characters.GlyphMetrics
instances are produced by Font and are applicable to a specific glyph in a particularFont
.Glyphs are either STANDARD LIGATURE COMBINING or COMPONENT.
- STANDARD glyphs are commonly used to represent single characters.
- LIGATURE glyphs are used to represent sequences of characters.
- COMPONENT glyphs in a GlyphVector do not correspond to a particular character in a text model. Instead COMPONENT glyphs are added for typographical reasons such as Arabic justification.
- COMBINING glyphs embellish STANDARD or LIGATURE glyphs such as accent marks. Carets do not appear before COMBINING glyphs.
Other metrics available through
GlyphMetrics
are the components of the advance the visual bounds and the left and right side bearings.Glyphs for a rotated font or obtained from a
GlyphVector
which has applied a rotation to the glyph can have advances that contain both X and Y components. Usually the advance only has one component.The advance of a glyph is the distance from the glyph's origin to the origin of the next glyph along the baseline which is either vertical or horizontal. Note that in a
GlyphVector
the distance from a glyph to its following glyph might not be the glyph's advance because of kerning or other positioning adjustments.The bounds is the smallest rectangle that completely contains the
visible portionoutline of the glyph. The bounds rectangle is relative to the glyph's origin. The left-side bearing is the distance from the glyph origin to the left of its bounds rectangle. If the left-side bearing is negative part of the glyph is drawn to the left of its origin. The right-side bearing is the distance from the right side of the bounds rectangle to the next glyph origin (the origin plus the advance). If negative part of the glyph is drawn to the right of the next glyph's origin. Note that the bounds does not necessarily enclose all the pixels affected when rendering the glyph because of rasterization and pixel adjustment effects.Although instances of
GlyphMetrics
can be directly constructed they are almost always obtained from aGlyphVector
. Once constructedGlyphMetrics
objects are immutable.Example:
Querying a
Font
for glyph information@see java.awt.Font @see GlyphVectorFont font = ...; int glyphIndex = ...; GlyphMetrics metrics = GlyphVector.getGlyphMetrics(glyphIndex); int isStandard = metrics.isStandard(); float glyphAdvance = metrics.getAdvance();
Constructs aClass GlyphMetrics, float getAdvance()GlyphMetrics
object. @param advance the advance widthor heightof the glyph @param bounds the black box bounds of the glyph @param glyphType the type of the glyph
Returns the advanceClass GlyphMetrics, Rectangle2D getBounds2D()width or height ofof the glyph along theglyphbaseline (either horizontal or vertical). @return the advance of the glyph.
Returns theblackbounds of the glyph. This is the bounding boxboundsof the glyph outline. Because of rasterization and pixel alignment effects it does not necessarily enclose the pixels that are affected when rendering the glyph. @return a Rectangle2D that is the bounds of the glyph.
AClass GlyphVector, Font getFont()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 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 a FontIn 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 scaleable 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
create new GlyphVector objectsadjustwhich aretheresultpositions ofeditingtheoperations onglyphs within theGlyphVector
such as glyph insertion and deletion. These methods are most appropriate for applications that areforming combinations such as ligatures from existing glyphs or are breaking suchperformingcombinations into their component parts for visual presentationjustification operations for the presentation of the glyphs.Methods are provided to
create new GlyphVector objects that are the result of specifying new positions fortransformtheindividual glyphs within theGlyphVector
. These methods aremost appropriate for applications that are performing justificationprimarilyoperationsuseful forthe presentation of thespecialglyphseffects.Methods are provided to return both the visual logical and
logicalpixel bounds of the entireGlyphVector
or of individual glyphs within theGlyphVector
.Methods are provided to return a Shape for the
GlyphVector
and for individual glyphs within theGlyphVector
. @see Font @see GlyphMetrics @see TextLayout @version 19 Mar 1998 @author Charlton Innovations Inc.
Returns theClass GlyphVector, int getGlyphCode(int)Font
associated with thisGlyphVector
. @returnsreturnFont
used to create thisGlyphVector
. @see Font
Returns the glyphcode of the specified glyph. This return value is meaningless to anything other thanClass GlyphVector, int[] getGlyphCodes(int, int, int[])atheFont
objectand can be used tothatask thecreated this
FontGlyphVectorobject about the existence of ligatures and other context sensitive information. @param glyphIndex the index into thisGlyphVector
that corresponds to the glyph from which to retrieve the glyphcode. @return the glyphcode of the glyphcorresponding theat the specifiedglyphIndex
. @throws IndexOutOfBoundsException ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
Returns an array of glyphcodes for the specified glyphs. The contents of this return value are meaningless to anything other thanClass GlyphVector, Shape getGlyphOutline(int)atheFont
and can beused toask thecreate this
FontGlyphVectorabout 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 inana new array is created. @param beginGlyphIndex the index into thisGlyphVector
at which to start retrieving glyphcodesfor the corresponding glyphs@param numEntries the number ofglyphsglyphcodes to retrieve @param codeReturn the array that receives the glyphcodes and is then returned @return an array of glyphcodes for the specified glyphs. @throws IllegalArgumentException ifnumEntries
is less than 0 @throws IndexOutOfBoundsException ifbeginGlyphIndex
is less than 0 @throws IndexOutOfBoundsException if the sum ofbeginGlyphIndex
andnumEntries
is greater than the number of glyphs in thisGlyphVector
Returns aClass GlyphVector, Point2D getGlyphPosition(int)Shape
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. @param glyphIndex the index into thisGlyphVector
@return aShape
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
Returns the position of the specified glyphClass GlyphVector, float[] getGlyphPositions(int, int, float[])withinrelativethis GlyphVector. This position correspondsto theleadingoriginedgeofthe baseline for thethisglyphGlyphVector
. IfglyphIndex
equals the number of of glyphs in thisGlyphVector
this methodgetsreturns the position after the last glyphand.thisThis position is used to define the advance of the entireGlyphVector
. @param glyphIndex the index into thisGlyphVector
@return 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 #setGlyphPosition
Returns an array of glyph positions for the specified glyphs.Class GlyphVector, AffineTransform getGlyphTransform(int)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 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 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
. @param beginGlyphIndex the index at which to begin retrieving glyph positions @param numEntries the number of glyphs to retrieve @param positionReturn the array that receives the glyph positions and is then returned. @return an array of glyph positions specified bybeginGlyphIndex
andnumEntries
. @throws IllegalArgumentException ifnumEntries
is less than 0 @throws IndexOutOfBoundsException ifbeginGlyphIndex
is less than 0 @throws IndexOutOfBoundsException if the sum ofbeginGlyphIndex
andnumEntries
is greater than the number of glyphs in thisGlyphVector
plus one
Class GlyphVector, Shape getGlyphVisualBounds(int)GetsReturns the transform of the specified glyph within thisGlyphVector
. The transform is relative to the glyph position. If no special transform has been appliednull
can be returned.SuchAa transformnullwould bereturn indicates an identity transform. @param glyphIndex the index into thisGlyphVector
@return 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 #setGlyphTransform
Returns the visual bounds of the specified glyph within theClass GlyphVector, int getNumGlyphs()GlyphVector
.TheseThevisualboundshave a total of four edges representing the tightest polygon enclosing non-background pixels in the renderedreturnedrepresentationbyof the glyph whose edges are parallelthisto the edges ofmethod is positioned around thelogical bounds. Useful for hit-testingorigin ofthe specifiedeach individual glyph. @param glyphIndex the index into thisGlyphVector
that corresponds to the glyph from which to retrieve its visual bounds @return aShape
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 #getGlyphLogicalBounds
Returns the number of glyphs in thisClass GlyphVector, Shape getOutline(float, float)GlyphVector
.This information is used to create arrays that are to be filled with results of other information retrieval operations.@return number of glyphs in thisGlyphVector
.
Returns aClass GlyphVector, Rectangle2D getVisualBounds()Shape
whose interior corresponds to the visual representation of thisGlyphVector
offsetwhentorendered at x y. @param x y the coordinates ofthe location of the outlinethis. @return a
ShapeGlyphVectorShape
that is the outline of thisGlyphVector
offsetwhentorendered at the specified coordinates.
Returns the visual bounds of thisClass GlyphVector, void performDefaultLayout()GlyphVector
The visual bounds is thetightest rectangle enclosing allbounding box of thenon-backgroundoutlinepixels inof thistheGlyphVector
. Because of rasterizationrendered representationand alignment of pixels it is possible that this box does not enclose all pixels affected by rendering thisGlyphVector
. @return aRectangle2D
that is thetightest boundsbounding box of thisGlyphVector
.
Assigns default positions to each glyph in thisClass GlyphVector, void setGlyphPosition(int, Point2D)GlyphVector
.No shaping reordering or contextual substitution isThis can destroy information generated during initialperformedlayout of thisGlyphVector
.
Sets the position of the specified glyph within thisClass GlyphVector, void setGlyphTransform(int, AffineTransform)GlyphVector
.This position corresponds to the leading edge of the baseline for the glyph.IfglyphIndex
equals the number of of glyphs in thisGlyphVector
this method sets the position after the last glyphand.thisThis position is used to define the advance of the entireGlyphVector
. @param glyphIndex the index into thisGlyphVector
@param 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 #getGlyphPosition
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 signifant performance changes. @param glyphIndex the index into thisGlyphVector
@paramnewTxnewTX thespecified transform that thenew transform of the glyph atthe specifiedglyphIndex
is set to@throws IndexOutOfBoundsException ifglyphIndex
is less than 0 or greater than or equal to the number of glyphs in thisGlyphVector
@see #getGlyphTransform
Constructs aGraphicAttribute
. Subclasses use this to define the alignment of the graphic. @param alignment an int representing one of theGraphicAttribute
alignment fields
Renders the graphic at the specified location. @param graphics the Graphics2D into which to render the graphic @param x y the user-space coordinates where the graphic is renderedClass ImageGraphicAttribute, float getDescent()
Returns the descent of thisImageGraphicAttribute
. The descent of anImageGraphicAttribute is the distance from the origin to the bottom of the image. @return the descent of this
ImageGraphicAttribute
.
TheClass LineBreakMeasurer, constructor LineBreakMeasurer(AttributedCharacterIterator, BreakIterator, FontRenderContext)LineBreakMeasurer
class allows styled text to be broken into lines (or segments) that fit within a particular visual advance. This is useful for clients who wish to display a paragraph of text that fits within a specific width called the wrapping width.
LineBreakMeasurer
is constructed with an iterator over styled text. The iterator's range should be a single paragraph in the text.LineBreakMeasurer
maintains a position in the text for the start of the next text segment. Initially this position is the start of text. Paragraphs are assigned an overall direction (either left-to-right or right-to-left) according to the bidirectional formatting rules. All segments obtained from a paragraph have the same direction as the paragraph.Segments of text are obtained by calling the method
nextLayout
which returns a TextLayout representing the text that fits within the wrapping width. ThenextLayout
method moves the current position to the end of the layout returned fromnextLayout
.
LineBreakMeasurer
implements the most commonly used line-breaking policy: Every word that fits within the wrapping width is placed on the line. If the first word does not fit then all of the characters that fit within the wrapping width are placed on the line. At least one character is placed on each line.The
TextLayout
instances returned byLineBreakMeasurer
treat tabs like 0-width spaces. Clients who wish to obtain tab-delimited segments for positioning should use the overload ofnextLayout
which takes a limiting offset in the text. The limiting offset should be the first character after the tab. TheTextLayout
objects returned from this method end at the limit provided (or before if the text between the current position and the limit won't fit entirely within the wrapping width).Clients who are laying out tab-delimited text need a slightly different line-breaking policy after the first segment has been placed on a line. Instead of fitting partial words in the remaining space they should place words which don't fit in the remaining space entirely on the next line. This change of policy can be requested in the overload of
nextLayout
which takes aboolean
parameter. If this parameter istrue
nextLayout
returnsnull
if the first word won't fit in the given space. See the tab sample below.In general if the text used to construct the
LineBreakMeasurer
changes a newLineBreakMeasurer
must be constructed to reflect the change. (The oldLineBreakMeasurer
continues to function properly but it won't be aware of the text change.) Nevertheless if the text change is the insertion or deletion of a single character an existingLineBreakMeasurer
can be 'updated' by callinginsertChar
ordeleteChar
. Updating an existingLineBreakMeasurer
is much faster than creating a new one. Clients who modify text based on user typing should take advantage of these methods.Examples:
Rendering a paragraph in a component
public void paint(Graphics graphics) { Point2D pen = new Point2D(10 20); Graphics2D g2d = (Graphics2D)graphics; FontRenderContext frc = g2d.getFontRenderContext(); // let styledText be an AttributedCharacterIterator containing at least // one character LineBreakMeasurer measurer = new LineBreakMeasurer(styledText frc); float wrappingWidth = getSize().width - 15; while (measurer.getPosition()Rendering text with tabs. For simplicity the overall text direction is assumed to be left-to-right
@see TextLayoutpublic void paint(Graphics graphics) { float leftMargin = 10 rightMargin = 310; float[] tabStops = { 100 250 }; // assume styledText is an AttributedCharacterIterator and the number // of tabs in styledText is tabCount int[] tabLocations = new int[tabCount+1]; int i = 0; for (char c = styledText.first(); c = styledText.DONE; c = styledText.next()) { if (c == '\t') { tabLocations[i++] = styledText.getIndex(); } } tabLocations[tabCount] = styledText.getEndIndex() - 1; // Now tabLocations has an entry for every tab's offset in // the text. For convenience the last entry is tabLocations // is the offset of the last character in the text. LineBreakMeasurer measurer = new LineBreakMeasurer(styledText); int currentTab = 0; float verticalPos = 20; while (measurer.getPosition()= tabStops[tabStops.length-1]) lineComplete = true; if ( lineComplete) { // move to next tab stop int j; for (j=0; horizontalPos >= tabStops[j]; j++) {} horizontalPos = tabStops[j]; } } verticalPos += maxAscent; Enumeration layoutEnum = layouts.elements(); Enumeration positionEnum = penPositions.elements(); // now iterate through layouts and draw them while (layoutEnum.hasMoreElements()) { TextLayout nextLayout = (TextLayout) layoutEnum.nextElement(); Float nextPosition = (Float) positionEnum.nextElement(); nextLayout.draw(graphics nextPosition.floatValue() verticalPos); } verticalPos += maxDescent; } }
Constructs aClass LineBreakMeasurer, constructor LineBreakMeasurer(AttributedCharacterIterator, FontRenderContext)LineBreakMeasurer
for the specified text. @param text the text for which thisLineBreakMeasurer
producesTextLayout
objects. The; the text must contain at least one character.;Ifif the text available throughiter
changes further calls to thisLineBreakMeasurer
instance are undefined (except in some cases wheninsertChar
ordeleteChar
are invoked afterward - see below).@param breakIter the BreakIterator which defines line breaks @param frc contains information about a graphics device which is needed to measure the text correctly. Text; text measurements can vary slightly depending on the device resolution and attributes such as antialiasing.;Thisthis parameter does not specify a translation between theLineBreakMeasurer
and user space.@throws IllegalArgumentException if the text has less than one character @see LineBreakMeasurer#insertChar @see LineBreakMeasurer#deleteChar
Constructs aClass LineBreakMeasurer, void deleteChar(AttributedCharacterIterator, int)LineBreakMeasurer
for the specified text. @param text the text for which thisLineBreakMeasurer
producesTextLayout
objects. The; the text must contain at least one character.;Ifif the text available throughiter
changes further calls to thisLineBreakMeasurer
instance are undefined (except in some cases wheninsertChar
ordeleteChar
are invoked afterward - see below).@param frc contains information about a graphics device which is needed to measure the text correctly. Text; text measurements can vary slightly depending on the device resolution and attributes such as antialiasing.;Thisthis parameter does not specify a translation between theLineBreakMeasurer
and user space.@see LineBreakMeasurer#insertChar @see LineBreakMeasurer#deleteChar
Updates thisClass LineBreakMeasurer, int getPosition()LineBreakMeasurer
after a single character is deleted from the text and sets the current position to the beginning of the paragraph. @param newParagraph the text after the deletion @param deletePos the position in the text at which the character is deleted @throws IndexOutOfBoundsException ifdeletePos
is less than the start ofnewParagraph
or greater than the end ofnewParagraph
@throws NullPointerException ifnewParagraph
isnull
@see #insertChar
Returns the current position of thisClass LineBreakMeasurer, void insertChar(AttributedCharacterIterator, int)LineBreakMeasurer
. @return the current position of thisLineBreakMeasurer
.@see #setPosition
Updates thisClass LineBreakMeasurer, TextLayout nextLayout(float)LineBreakMeasurer
after a single character is inserted into the text and sets the current position to the beginning of the paragraph. @param newParagraph the text after the insertion @param insertPos the position in the text at which the character is inserted @throws IndexOutOfBoundsException ifinsertPos
is less than the start ofnewParagraph
or greater than or equal to the end ofnewParagraph
@throws NullPointerException ifnewParagraph
isnull
@see #deleteChar
Returns the next layout and updates the current position. @param wrappingWidth the maximum visible advance permitted for the text in the next layout @return aClass LineBreakMeasurer, TextLayout nextLayout(float, int, boolean)TextLayout
beginning at the current position which represents the next line fitting withinwrappingWidth
.
Returns the next layout and updates the current position. @param wrappingWidth the maximum visible advance permitted for the text in the next layout @param offsetLimit the first character that can not be included in the next layout even if the text after the limit would fit within the wrapping widthClass LineBreakMeasurer, int nextOffset(float, int, boolean).;offsetLimit
must be greater than the current position.@param requireNextWord iftrue
and if the entire word at the current position does not fit within the wrapping widthnull
is returned. Iffalse
a valid layout is returned that includes at least the character at the current position.@return aTextLayout
beginning at the current position that represents the next line fitting withinwrappingWidth
. If the current position is at the end of the text used by thisLineBreakMeasurer
null
is returned.
Returns the position at the end of the next layout. Does NOT update the current position of thisClass LineBreakMeasurer, void setPosition(int)LineBreakMeasurer
. @param wrappingWidth the maximum visible advance permitted for the text in the next layout @param offsetLimit the first character that can not be included in the next layout even if the text after the limit would fit within the wrapping width.;offsetLimit
must be greater than the current position.@param requireNextWord iftrue
the current position that is returned if the entire next word does not fit withinwrappingWidth
. If; iffalse
the offset returned is at least one greater than the current position.@return an offset in the text representing the limit of the nextTextLayout
.
Sets the current position of thisLineBreakMeasurer
. @param newPosition the current position of thisLineBreakMeasurer
. The; the position should be within the text used to construct thisLineBreakMeasurer
(or in the text most recently passed toinsertChar
ordeleteChar
.@see #getPosition
Returns the table as an array of bytes for a specified tag. Tags for sfnt tables include items like cmap name and head. The byte array returned is a copy of the font data in memory. @paramClass OpenType, byte[] getFontTable(String, int, int)sfntTagstrSfntTag a four-character code as aString
@return abyte
array that is the table that contains the font data corresponding to the specified tag.
Returns a subset of the table as an array of bytes for a specified tag. Tags for sfnt tables include items like cmap name and head. Thebyte
array returned is a copy of the font data in memory. @paramsfntTagstrSfntTag a four-character code as aString
@param offset index of first byte to return from table @param count number of bytes to return from table @return a subset of the table corresponding tostrSfntTag
and containing the bytes starting atoffset
byte and includingcount
bytes.
TheClass TextAttribute, TextAttribute BIDI_EMBEDDINGTextAttribute
class defines attribute keys and attribute values used for text rendering.
TextAttribute
instances are used as attribute keys to identify attributes in AttributedCharacterIterator Font and other classes handling text attributes. Other constants defined in this class are used as attribute values.For each text attribute the documentation describes:
- the type of their values
- the valid values if there are limitations
- relevant constants
- the default effect if the attribute is absent (or has a
null
value).- a description of the effect.
- the fallback behavior if the exact attribute requested is not available.
Types of Values
- The values of attributes must always be immutable.
- Where a list of limitations is given any value outside of that set is reserved for future use and ignored at present.
- If the value is
null
or not of the proper type then it has the default effect. The effect of a particular value can be interpolated especially in the case of multiple master fonts. This interpolation is done based on the nearest defined constants above and below the request:
interpolation = (request - below)/(above - below);
Interpolation
@see java.text.AttributedCharacterIterator @see java.awt.Font
- Fonts should interpolate values in certain circumstances. For example when the WEIGHT value is 2.13. If the nearest surrounding values in the font are WEIGHT_BOLD = 2.0 and WEIGHT_HEAVY = 2.25 then font would then interpret the WEIGHT request as being 52% of the way between what it considers BOLD and what it considers HEAVY. If the nearest surrounding values are WEIGHT_SEMIBOLD = 1.25 and WEIGHT_ULTRABOLD = 2.75 then the WEIGHT request is interpreted as being 58.67% of the way between SEMIBOLD and ULTRABOLD.
- Where a font does not have enough capability to handle a given request such as superscript then it should simulate it to the best of its ability. To determine if simulation is being performed the client should query the font to see what actual attributes were used.
Attribute key for the embedding level for nested bidirectional runs.
Key
BIDI_EMBEDDING Value
Integer Limits
Positive values 1 through 1561 are embedding levels negative values
through -1561 are override levelsDefault
Use standard BIDI to compute levels from formatting characters in the text. Description
Specifies the bidi embedding level of the character. When this attribute is present anywhere in a paragraph then the Unicode characters RLO LRO RLE LRE PDF are disregarded in the BIDI analysis of that paragraph. See the Unicode Standard v. 2.0 section 3-11.
Class TextLayout, constructor TextLayout(String, Font, FontRenderContext)TextLayout
is an immutable graphical representation of styled character data.It provides the following capabilities:
- implicit bidirectional analysis and reordering
- cursor positioning and movement including split cursors for mixed directional text
- highlighting including both logical and visual highlighting for mixed directional text
- multiple baselines (roman hanging and centered)
- hit testing
- justification
- default font substitution
- metric information such as ascent descent and advance and
- rendering
A
TextLayout
object can be rendered using itsdraw
method.
TextLayout
can be constructed either directly or through the use of a LineBreakMeasurer When constructed directly the source text represents a single paragraph.LineBreakMeasurer
allows styled text to be broken into lines that fit within a particular width. See theLineBreakMeasurer
documentation for more information.
TextLayout
construction logically proceeds as follows:
- paragraph attributes are extracted and examined
- text is analyzed for bidirectional reordering and reordering information is computed if needed
- text is segmented into style runs
- fonts are chosen for style runs first by using a font if the attribute TextAttribute#FONT is present otherwise by computing a default font using the attributes that have been defined
- if text is on multiple baselines the runs or subruns are further broken into subruns sharing a common baseline
- glyphvectors are generated for each run using the chosen font
- final bidirectional reordering is performed on the glyphvectors
All graphical information returned from a
TextLayout
object's methods is relative to the origin of theTextLayout
which is the intersection of theTextLayout
object's baseline with its left edge. Also coordinates passed into aTextLayout
object's methods are assumed to be relative to theTextLayout
object's origin. Clients usually need to translate between aTextLayout
object's coordinate system and the coordinate system in another object (such as a Graphics object).
TextLayout
objects are constructed from styled text but they do not retain a reference to their source text. Thus changes in the text previously used to generate aTextLayout
do not affect theTextLayout
.Three methods on a
TextLayout
object (getNextRightHit
getNextLeftHit
andhitTestChar
) return instances of TextHitInfo The offsets contained in theseTextHitInfo
objects are relative to the start of theTextLayout
not to the text used to create theTextLayout
. SimilarlyTextLayout
methods that acceptTextHitInfo
instances as parameters expect theTextHitInfo
object's offsets to be relative to theTextLayout
not to any underlying text storage model.Examples:
Constructing and drawing a
TextLayout
and its bounding rectangle:Graphics2D g = ...; Point2D loc = ...; Font font = Font.getFont("Helvetica-bold-italic"); FontRenderContext frc = g.getFontRenderContext(); TextLayout layout = new TextLayout("This is a string" font frc); layout.draw(g (float)loc.getX() (float)loc.getY()); Rectangle2D bounds = layout.getBounds(); bounds.setRect(bounds.getX()+loc.getX() bounds.getY()+loc.getY() bounds.getWidth() bounds.getHeight()); g.draw(bounds);Hit-testing a
TextLayout
(determining which character is at a particular graphical location):Point2D click = ...; TextHitInfo hit = layout.hitTestChar( (float) (click.getX() - loc.getX()) (float) (click.getY() - loc.getY()));Responding to a right-arrow key press:
int insertionIndex = ...; TextHitInfo next = layout.getNextRightHit(insertionIndex); if (next = null) { // translate graphics to origin of layout on screen g.translate(loc.getX() loc.getY()); Shape[] carets = layout.getCaretShapes(next.getInsertionIndex()); g.draw(carets[0]); if (carets[1] = null) { g.draw(carets[1]); } }Drawing a selection range corresponding to a substring in the source text. The selected area may not be visually contiguous:
// selStart selLimit should be relative to the layout // not to the source text int selStart = ... selLimit = ...; Color selectionColor = ...; Shape selection = layout.getLogicalHighlightShape(selStart selLimit); // selection may consist of disjoint areas // graphics is assumed to be tranlated to origin of layout g.setColor(selectionColor); g.fill(selection);Drawing a visually contiguous selection range. The selection range may correspond to more than one substring in the source text. The ranges of the corresponding source text substrings can be obtained with
getLogicalRangesForVisualSelection()
:TextHitInfo selStart = ... selLimit = ...; Shape selection = layout.getVisualHighlightShape(selStart selLimit); g.setColor(selectionColor); g.fill(selection); int[] ranges = getLogicalRangesForVisualSelection(selStart selLimit); // ranges[0] ranges[1] is the first selection range // ranges[2] ranges[3] is the second selection range etc.@see LineBreakMeasurer @see TextAttribute @see TextHitInfo
Constructs aClass TextLayout, constructor TextLayout(String, Map, FontRenderContext)TextLayout
from aString
and a Font All the text is styled using the specifiedFont
.The
String
must specify a single paragraph of text because an entire paragraph is required for the bidirectional algorithm. @paramstrstring the text to display @param font aFont
used to style the text @param frc contains information about a graphics device which is needed to measure the text correctly. Text measurements can vary slightly depending on the device resolution and attributes such as antialiasing. This parameter does not specify a translation between theTextLayout
and user space.
Constructs aClass TextLayout, Shape[] getCaretShapes(int)TextLayout
from aString
and an attribute set.All the text is styled using the provided attributes.
string
must specify a single paragraph of text because an entire paragraph is required for the bidirectional algorithm. @paramstrstring the text to display @param attributes the attributes used to style the text @param frc contains information about a graphics device which is needed to measure the text correctly. Text measurements can vary slightly depending on the device resolution and attributes such as antialiasing. This parameter does not specify a translation between theTextLayout
and user space.
Returns two paths corresponding to the strong and weak caret. This method is a convenience overload ofgetCaretShapes
that uses the default caret policy and thisTextLayout
object's natural bounds. @param offset an offset in thisTextLayout
@param bounds the bounds to which to extend the carets @return two paths corresponding to the strong and weak caret as defined by theDEFAULT_CARET_POLICY
TheClass TextMeasurer, void deleteChar(AttributedCharacterIterator, int)TextMeasurer
class provides the primitive operations needed for line break: measuring up to a given advance determining the advance of a range of characters and generating aTextLayout
for a range of characters. It also provides methods for incremental editing of paragraphs.A
TextMeasurer
object is constructed with an AttributedCharacterIterator representing a single paragraph of text. The value returned by the getBeginIndex method ofAttributedCharacterIterator
defines the absolute index of the first character. The value returned by the getEndIndex method ofAttributedCharacterIterator
defines the index past the last character. These values define the range of indexes to use in calls to theTextMeasurer
. For example calls to get the advance of a range of text or the line break of a range of text must use indexes between the beginning and end index values. Calls to int insertChar} and int deleteChar} reset theTextMeasurer
to use the beginning index and end index of theAttributedCharacterIterator
passed in those calls.Most clients will use the more convenient
LineBreakMeasurer
which implements the standard line break policy (placing as many words as will fit on each line). @author John Raley @version 1.25 0231 04/0220/0001 @see LineBreakMeasurer @since 1.3
Updates theClass TextMeasurer, float getAdvanceBetween(int, int)TextMeasurer
after a single character has been deleted from the paragraph currently represented by thisTextMeasurer
. After this call thisTextMeasurer
is equivalent to a newTextMeasurer
created from the text; however it will usually be more efficient to update an existingTextMeasurer
than to create a new one from scratch. @param newParagraph the text of the paragraph after performing the deletion. Cannot be null. @param deletePos the position in the text where the character was removed. Must not be less than the start ofnewParagraph
and must not be greater than the end ofnewParagraph
. @throws IndexOutOfBoundsException ifdeletePos
is less than the start ofnewParagraph
or greater than the end ofnewParagraph
@throws NullPointerException ifnewParagraph
isnull
Returns the graphical width of a line beginning atClass TextMeasurer, TextLayout getLayout(int, int)start
and including characters up tolimit
.start
andlimit
are absolute indices not relative to the start of the paragraph. @param start the character index at which to start measuring @param limit the character index at which to stop measuring @return the graphical width of a line beginning atstart
and including characters up tolimit
@throws IndexOutOfBoundsException iflimit
is less thanstart
@throws IllegalArgumentException ifstart
orlimit
is not between the beginning of the paragraph and the end of the paragraph.
Returns aClass TextMeasurer, int getLineBreakIndex(int, float)TextLayout
on the given character range. @param start the index of the first character @param limit the index after the last character. Must be greater thanstart
@return aTextLayout
for the characters beginning atstart
up to (but not including)limit
@throws IndexOutOfBoundsException iflimit
is less thanstart
@throws IllegalArgumentException ifstart
orlimit
is not between the beginning of the paragraph and the end of the paragraph.
Returns the index of the first character which will not fit on on a lineClass TextMeasurer, void insertChar(AttributedCharacterIterator, int)which beginsbeginning atstart
andmay bepossible measuring up tomaxAdvance
in graphical width. @param start the character index at which to start measuring.start
is an absolute index not relative to the start of the paragraph @param maxAdvance the graphical width in which the line must fit @return the index after the last characterwhichthat will fit on a line beginning atstart
which is not longer thanmaxAdvance
in graphical width @throws IllegalArgumentException ifstart
is less than the beginning of the paragraph.
Updates theTextMeasurer
after a single character has been inserted into the paragraph currently represented by thisTextMeasurer
. After this call thisTextMeasurer
is equivalent to a newTextMeasurer
created from the text; however it will usually be more efficient to update an existingTextMeasurer
than to create a new one from scratch. @param newParagraph the text of the paragraph after performing the insertion. Cannot be null. @param insertPos the position in the text where the character was inserted. Must not be less than the start ofnewParagraph
and must be less than the end ofnewParagraph
. @throws IndexOutOfBoundsException ifinsertPos
is less than the start ofnewParagraph
or greater than or equal to the end ofnewParagraph
@throws NullPointerException ifnewParagraph
isnull