Generated by
JDiff

java.awt.font Documentation Differences

This file contains all the changes in documentation in the package java.awt.font as colored differences. Deletions are shown like 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.

Class FontRenderContext, AffineTransform getTransform()

Gets the transform that is used to scale typographical points to pixels in this FontRenderContext. @returnsreturn the AffineTransform of this FontRenderContext. @see AffineTransform
Class FontRenderContext, int hashCode()

ReturnsReturn a hashhashcode code 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 value for this object. @see java.lang.Object#equals(java.lang.Object) @see java.utilFontRenderContext.Hashtable
Class FontRenderContext, boolean isAntiAliased()

Gets the text anti-aliasing mode used in this FontRenderContext. @returnsreturn true if text is anti-aliased in this FontRenderContext; false otherwise. @see java.awt.RenderingHints#KEY_TEXT_ANTIALIASING
Class FontRenderContext, boolean usesFractionalMetrics()

Gets the text fractional metrics mode requested by the application for use in this FontRenderContext. @returnsreturn true if layout should be performed with fractional metrics; false otherwise. in this FontRenderContext. @see java.awt.RenderingHints#KEY_FRACTIONALMETRICS

Class GlyphMetrics

The 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 particular Font.

Glyphs are either STANDARD LIGATURE COMBINING or COMPONENT.

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 a GlyphVector. Once constructed GlyphMetrics objects are immutable.

Example:

Querying a Font for glyph information

 Font font = ...; int glyphIndex = ...; GlyphMetrics metrics = GlyphVector.getGlyphMetrics(glyphIndex); int isStandard = metrics.isStandard(); float glyphAdvance = metrics.getAdvance(); 
@see java.awt.Font @see GlyphVector
Class GlyphMetrics, constructor GlyphMetrics(float, Rectangle2D, byte)

Constructs a GlyphMetrics object. @param advance the advance width or height of the glyph @param bounds the black box bounds of the glyph @param glyphType the type of the glyph
Class GlyphMetrics, float getAdvance()

Returns the advance width or height ofof the glyph along the glyphbaseline (either horizontal or vertical). @return the advance of the glyph.
Class GlyphMetrics, Rectangle2D getBounds2D()

Returns the blackbounds of the glyph. This is the bounding box boundsof 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.

Class GlyphVector

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 objectsadjust which are the resultpositions of editingthe operations onglyphs within 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 suchperforming combinations 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 fortransform theindividual glyphs within the GlyphVector. These methods are most appropriate for applications that are performing justificationprimarily operationsuseful for the presentation of thespecial glyphseffects.

Methods are provided to return both the visual logical and logicalpixel 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 Font @see GlyphMetrics @see TextLayout @version 19 Mar 1998 @author Charlton Innovations Inc.

Class GlyphVector, Font getFont()

Returns the Font associated with this GlyphVector. @returnsreturn Font used to create this GlyphVector. @see Font
Class GlyphVector, int getGlyphCode(int)

Returns the glyphcode of the specified glyph. This return value is meaningless to anything other than athe Font object and can be used tothat ask thecreated this FontGlyphVector object about the existence of ligatures and other context sensitive information. @param glyphIndex the index into this GlyphVector that corresponds to the glyph from which to retrieve the glyphcode. @return the glyphcode of the glyph corresponding theat the specified glyphIndex. @throws IndexOutOfBoundsException if glyphIndex is less than 0 or greater than or equal to the number of glyphs in this GlyphVector
Class GlyphVector, int[] getGlyphCodes(int, int, int[])

Returns an array of glyphcodes for the specified glyphs. The contents of this return value are meaningless to anything other than athe Font and can be used to ask thecreate this FontGlyphVector 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 ana new array is created. @param beginGlyphIndex the index into this GlyphVector at which to start retrieving glyphcodes for the corresponding glyphs @param numEntries the number of glyphsglyphcodes 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 if numEntries is less than 0 @throws IndexOutOfBoundsException if beginGlyphIndex is less than 0 @throws IndexOutOfBoundsException if the sum of beginGlyphIndex and numEntries is greater than the number of glyphs in this GlyphVector
Class GlyphVector, Shape getGlyphOutline(int)

Returns a Shape whose interior corresponds to the visual representation of the specified glyph within this GlyphVector. The outline returned by this method is positioned around the origin of each individual glyph. @param glyphIndex the index into this GlyphVector @return 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
Class GlyphVector, Point2D getGlyphPosition(int)

Returns the position of the specified glyph withinrelative this GlyphVector. This position corresponds to the leadingorigin edge of the baseline for thethis glyphGlyphVector. If glyphIndex equals the number of of glyphs in this GlyphVector this method getsreturns the position after the last glyph and. thisThis position is used to define the advance of the entire GlyphVector. @param glyphIndex the index into this GlyphVector @return 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 @see #setGlyphPosition
Class GlyphVector, float[] getGlyphPositions(int, int, float[])

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. @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 by beginGlyphIndex and numEntries. @throws IllegalArgumentException if numEntries is less than 0 @throws IndexOutOfBoundsException if beginGlyphIndex is less than 0 @throws IndexOutOfBoundsException if the sum of beginGlyphIndex and numEntries is greater than the number of glyphs in this GlyphVector plus one
Class GlyphVector, AffineTransform getGlyphTransform(int)

GetsReturns 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. SuchA a transformnull would bereturn indicates an identity transform. @param glyphIndex the index into this GlyphVector @return 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 @see #setGlyphTransform
Class GlyphVector, Shape getGlyphVisualBounds(int)

Returns the visual bounds of the specified glyph within the GlyphVector. TheseThe visual bounds have a total of four edges representing the tightest polygon enclosing non-background pixels in the renderedreturned representationby of the glyph whose edges are parallelthis to the edges ofmethod is positioned around the logical bounds. Useful for hit-testingorigin of the specifiedeach individual glyph. @param glyphIndex the index into this GlyphVector that corresponds to the glyph from which to retrieve its visual bounds @return 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 #getGlyphLogicalBounds
Class GlyphVector, 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. @return number of glyphs in this GlyphVector.
Class GlyphVector, Shape getOutline(float, float)

Returns a Shape whose interior corresponds to the visual representation of this GlyphVector offsetwhen torendered at x  y. @param x  y the coordinates of the location of the outlinethis ShapeGlyphVector. @return a Shape that is the outline of this GlyphVector offsetwhen torendered at the specified coordinates.
Class GlyphVector, Rectangle2D getVisualBounds()

Returns the visual bounds of this GlyphVector The visual bounds is the tightest rectangle enclosing allbounding box of the non-backgroundoutline pixels inof this theGlyphVector. Because of rasterization rendered representationand alignment of pixels it is possible that this box does not enclose all pixels affected by rendering this GlyphVector. @return a Rectangle2D that is the tightest boundsbounding box of this GlyphVector.
Class GlyphVector, void performDefaultLayout()

Assigns default positions to each glyph in this GlyphVector. No shaping reordering or contextual substitution isThis can destroy information generated during initial performedlayout of this GlyphVector.
Class GlyphVector, void setGlyphPosition(int, Point2D)

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. thisThis position is used to define the advance of the entire GlyphVector. @param glyphIndex the index into this GlyphVector @param 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 @see #getGlyphPosition
Class GlyphVector, void setGlyphTransform(int, AffineTransform)

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. @param glyphIndex the index into this GlyphVector @param newTxnewTX the specified transform that thenew 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 @see #getGlyphTransform

Class GraphicAttribute, constructor GraphicAttribute(int)

Constructs a GraphicAttribute. Subclasses use this to define the alignment of the graphic. @param alignment an int representing one of the GraphicAttribute alignment fields

Class ImageGraphicAttribute, void draw(Graphics2D, float, float)

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 rendered
Class ImageGraphicAttribute, float getDescent()

Returns the descent of this ImageGraphicAttribute. The descent of an ImageGraphicAttribute is the distance from the origin to the bottom of the image. @return the descent of this ImageGraphicAttribute.

Class LineBreakMeasurer

The 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. The nextLayout method moves the current position to the end of the layout returned from nextLayout.

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 by LineBreakMeasurer treat tabs like 0-width spaces. Clients who wish to obtain tab-delimited segments for positioning should use the overload of nextLayout which takes a limiting offset in the text. The limiting offset should be the first character after the tab. The TextLayout 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 a boolean parameter. If this parameter is true nextLayout returns null 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 new LineBreakMeasurer must be constructed to reflect the change. (The old LineBreakMeasurer 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 existing LineBreakMeasurer can be 'updated' by calling insertChar or deleteChar. Updating an existing LineBreakMeasurer 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

 public 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; } } 
@see TextLayout
Class LineBreakMeasurer, constructor LineBreakMeasurer(AttributedCharacterIterator, BreakIterator, FontRenderContext)

Constructs a LineBreakMeasurer for the specified text. @param text the text for which this LineBreakMeasurer produces TextLayout objects. The; the text must contain at least one character.; Ifif the text available through iter changes further calls to this LineBreakMeasurer instance are undefined (except in some cases when insertChar or deleteChar 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 the LineBreakMeasurer and user space. @throws IllegalArgumentException if the text has less than one character @see LineBreakMeasurer#insertChar @see LineBreakMeasurer#deleteChar
Class LineBreakMeasurer, constructor LineBreakMeasurer(AttributedCharacterIterator, FontRenderContext)

Constructs a LineBreakMeasurer for the specified text. @param text the text for which this LineBreakMeasurer produces TextLayout objects. The; the text must contain at least one character.; Ifif the text available through iter changes further calls to this LineBreakMeasurer instance are undefined (except in some cases when insertChar or deleteChar 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 the LineBreakMeasurer and user space. @see LineBreakMeasurer#insertChar @see LineBreakMeasurer#deleteChar
Class LineBreakMeasurer, void deleteChar(AttributedCharacterIterator, int)

Updates this 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 if deletePos is less than the start of newParagraph or greater than the end of newParagraph @throws NullPointerException if newParagraph is null @see #insertChar
Class LineBreakMeasurer, int getPosition()

Returns the current position of this LineBreakMeasurer. @return the current position of this LineBreakMeasurer. @see #setPosition
Class LineBreakMeasurer, void insertChar(AttributedCharacterIterator, int)

Updates this 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 if insertPos is less than the start of newParagraph or greater than or equal to the end of newParagraph @throws NullPointerException if newParagraph is null @see #deleteChar
Class LineBreakMeasurer, TextLayout nextLayout(float)

Returns the next layout and updates the current position. @param wrappingWidth the maximum visible advance permitted for the text in the next layout @return a TextLayout beginning at the current position which represents the next line fitting within wrappingWidth.
Class LineBreakMeasurer, TextLayout nextLayout(float, int, boolean)

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 width.; offsetLimit must be greater than the current position. @param requireNextWord if true and if the entire word at the current position does not fit within the wrapping width null is returned. If false a valid layout is returned that includes at least the character at the current position. @return a TextLayout beginning at the current position that represents the next line fitting within wrappingWidth. If the current position is at the end of the text used by this LineBreakMeasurer null is returned.
Class LineBreakMeasurer, int nextOffset(float, int, boolean)

Returns the position at the end of the next layout. Does NOT update the current position of this 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 if true the current position that is returned if the entire next word does not fit within wrappingWidth. If; if false the offset returned is at least one greater than the current position. @return an offset in the text representing the limit of the next TextLayout.
Class LineBreakMeasurer, void setPosition(int)

Sets the current position of this LineBreakMeasurer. @param newPosition the current position of this LineBreakMeasurer. The; the position should be within the text used to construct this LineBreakMeasurer (or in the text most recently passed to insertChar or deleteChar. @see #getPosition

Class OpenType, byte[] getFontTable(String)

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. @param sfntTagstrSfntTag a four-character code as a String @return a byte array that is the table that contains the font data corresponding to the specified tag.
Class OpenType, byte[] getFontTable(String, int, int)

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. The byte array returned is a copy of the font data in memory. @param sfntTagstrSfntTag a four-character code as a String @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 to strSfntTag and containing the bytes starting at offset byte and including count bytes.

Class TextAttribute

The TextAttribute 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:

Types of Values

Interpolation

@see java.text.AttributedCharacterIterator @see java.awt.Font
Class TextAttribute, TextAttribute BIDI_EMBEDDING

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 levels

Default

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

TextLayout is an immutable graphical representation of styled character data.

It provides the following capabilities:

A TextLayout object can be rendered using its draw 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 the LineBreakMeasurer documentation for more information.

TextLayout construction logically proceeds as follows:

All graphical information returned from a TextLayout object's methods is relative to the origin of the TextLayout which is the intersection of the TextLayout object's baseline with its left edge. Also coordinates passed into a TextLayout object's methods are assumed to be relative to the TextLayout object's origin. Clients usually need to translate between a TextLayout 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 a TextLayout do not affect the TextLayout.

Three methods on a TextLayout object (getNextRightHit getNextLeftHit and hitTestChar) return instances of TextHitInfo The offsets contained in these TextHitInfo objects are relative to the start of the TextLayout not to the text used to create the TextLayout. Similarly TextLayout methods that accept TextHitInfo instances as parameters expect the TextHitInfo object's offsets to be relative to the TextLayout 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

Class TextLayout, constructor TextLayout(String, Font, FontRenderContext)

Constructs a TextLayout from a String and a Font All the text is styled using the specified Font.

The String must specify a single paragraph of text because an entire paragraph is required for the bidirectional algorithm. @param strstring the text to display @param font a Font 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 the TextLayout and user space.

Class TextLayout, constructor TextLayout(String, Map, FontRenderContext)

Constructs a TextLayout from a String 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. @param strstring 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 the TextLayout and user space.

Class TextLayout, Shape[] getCaretShapes(int)

Returns two paths corresponding to the strong and weak caret. This method is a convenience overload of getCaretShapes that uses the default caret policy and this TextLayout object's natural bounds. @param offset an offset in this TextLayout @param bounds the bounds to which to extend the carets @return two paths corresponding to the strong and weak caret as defined by the DEFAULT_CARET_POLICY

Class TextMeasurer

The 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 a TextLayout 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 of AttributedCharacterIterator defines the absolute index of the first character. The value returned by the getEndIndex method of AttributedCharacterIterator defines the index past the last character. These values define the range of indexes to use in calls to the TextMeasurer. 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 the TextMeasurer to use the beginning index and end index of the AttributedCharacterIterator 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

Class TextMeasurer, void deleteChar(AttributedCharacterIterator, int)

Updates the TextMeasurer after a single character has been deleted from the paragraph currently represented by this TextMeasurer. After this call this TextMeasurer is equivalent to a new TextMeasurer created from the text; however it will usually be more efficient to update an existing TextMeasurer 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 of newParagraph and must not be greater than the end of newParagraph. @throws IndexOutOfBoundsException if deletePos is less than the start of newParagraph or greater than the end of newParagraph @throws NullPointerException if newParagraph is null
Class TextMeasurer, float getAdvanceBetween(int, int)

Returns the graphical width of a line beginning at start and including characters up to limit. start and limit 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 at start and including characters up to limit @throws IndexOutOfBoundsException if limit is less than start @throws IllegalArgumentException if start or limit is not between the beginning of the paragraph and the end of the paragraph.
Class TextMeasurer, TextLayout getLayout(int, int)

Returns a 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 than start @return a TextLayout for the characters beginning at start up to (but not including) limit @throws IndexOutOfBoundsException if limit is less than start @throws IllegalArgumentException if start or limit is not between the beginning of the paragraph and the end of the paragraph.
Class TextMeasurer, int getLineBreakIndex(int, float)

Returns the index of the first character which will not fit on on a line which beginsbeginning at start and may bepossible measuring up to maxAdvance 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 character whichthat will fit on a line beginning at start which is not longer than maxAdvance in graphical width @throws IllegalArgumentException if start is less than the beginning of the paragraph.
Class TextMeasurer, void insertChar(AttributedCharacterIterator, int)

Updates the TextMeasurer after a single character has been inserted into the paragraph currently represented by this TextMeasurer. After this call this TextMeasurer is equivalent to a new TextMeasurer created from the text; however it will usually be more efficient to update an existing TextMeasurer 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 of newParagraph and must be less than the end of newParagraph. @throws IndexOutOfBoundsException if insertPos is less than the start of newParagraph or greater than or equal to the end of newParagraph @throws NullPointerException if newParagraph is null