Class TextLayout
- All Implemented Interfaces:
Cloneable
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
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:
- 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 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 translated 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.
Note: Font rotations can cause text baselines to be rotated, and multiple runs with different rotations can cause the baseline to bend or zig-zag. In order to account for this (rare) possibility, some APIs are specified to return metrics and take parameters 'in baseline-relative coordinates' (e.g. ascent, advance), and others are in 'in standard coordinates' (e.g. getBounds). Values in baseline-relative coordinates map the 'x' coordinate to the distance along the baseline, (positive x is forward along the baseline), and the 'y' coordinate to a distance along the perpendicular to the baseline at 'x' (positive y is 90 degrees clockwise from the baseline vector). Values in standard coordinates are measured along the x and y axes, with 0,0 at the origin of the TextLayout. Documentation for each relevant API indicates what values are in what coordinate system. In general, measurement-related APIs are in baseline-relative coordinates, while display-related APIs are in standard coordinates.
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Defines a policy for determining the strong caret location. -
Field Summary
Modifier and TypeFieldDescriptionstatic final TextLayout.CaretPolicy
ThisCaretPolicy
is used when a policy is not specified by the client. -
Constructor Summary
ConstructorDescriptionTextLayout
(String string, Font font, FontRenderContext frc) TextLayout
(String string, Map<? extends AttributedCharacterIterator.Attribute, ?> attributes, FontRenderContext frc) Constructs aTextLayout
from aString
and an attribute set.Constructs aTextLayout
from an iterator over styled text. -
Method Summary
Modifier and TypeMethodDescriptionprotected Object
clone()
Creates a copy of thisTextLayout
.void
draw
(Graphics2D g2, float x, float y) Renders thisTextLayout
at the specified location in the specifiedGraphics2D
context.boolean
equals
(TextLayout rhs) Returnstrue
if the two layouts are equal.float
Returns the advance of thisTextLayout
.float
Returns the ascent of thisTextLayout
.byte
Returns the baseline for thisTextLayout
.float[]
Returns the offsets array for the baselines used for thisTextLayout
.getBlackBoxBounds
(int firstEndpoint, int secondEndpoint) Returns the black box bounds of the characters in the specified range.Returns the bounds of thisTextLayout
.float[]
getCaretInfo
(TextHitInfo hit) Returns information about the caret corresponding tohit
.float[]
getCaretInfo
(TextHitInfo hit, Rectangle2D bounds) Returns information about the caret corresponding tohit
.getCaretShape
(TextHitInfo hit) Returns aShape
representing the caret at the specified hit inside the natural bounds of thisTextLayout
.getCaretShape
(TextHitInfo hit, Rectangle2D bounds) Returns aShape
representing the caret at the specified hit inside the specified bounds.Shape[]
getCaretShapes
(int offset) Returns two paths corresponding to the strong and weak caret.Shape[]
getCaretShapes
(int offset, Rectangle2D bounds) Returns two paths corresponding to the strong and weak caret.Shape[]
getCaretShapes
(int offset, Rectangle2D bounds, TextLayout.CaretPolicy policy) Returns two paths corresponding to the strong and weak caret.int
Returns the number of characters represented by thisTextLayout
.byte
getCharacterLevel
(int index) Returns the level of the character atindex
.float
Returns the descent of thisTextLayout
.getJustifiedLayout
(float justificationWidth) Creates a copy of thisTextLayout
justified to the specified width.Return the LayoutPath, or null if the layout path is the default path (x maps to advance, y maps to offset).float
Returns the leading of theTextLayout
.getLogicalHighlightShape
(int firstEndpoint, int secondEndpoint) Returns aShape
enclosing the logical selection in the specified range, extended to the natural bounds of thisTextLayout
.getLogicalHighlightShape
(int firstEndpoint, int secondEndpoint, Rectangle2D bounds) Returns aShape
enclosing the logical selection in the specified range, extended to the specifiedbounds
.int[]
getLogicalRangesForVisualSelection
(TextHitInfo firstEndpoint, TextHitInfo secondEndpoint) Returns the logical ranges of text corresponding to a visual selection.getNextLeftHit
(int offset) Returns the hit for the next caret to the left (top); if no such hit, returnsnull
.getNextLeftHit
(int offset, TextLayout.CaretPolicy policy) Returns the hit for the next caret to the left (top); if no such hit, returnsnull
.Returns the hit for the next caret to the left (top); if no such hit, returnsnull
.getNextRightHit
(int offset) Returns the hit for the next caret to the right (bottom); if no such hit, returnsnull
.getNextRightHit
(int offset, TextLayout.CaretPolicy policy) Returns the hit for the next caret to the right (bottom); if no such hit, returnsnull
.Returns the hit for the next caret to the right (bottom); if there is no such hit, returnsnull
.Returns aShape
representing the outline of thisTextLayout
.getPixelBounds
(FontRenderContext frc, float x, float y) Returns the pixel bounds of thisTextLayout
when rendered in a graphics with the givenFontRenderContext
at the given location.float
Returns the advance of thisTextLayout
, minus trailing whitespace.getVisualHighlightShape
(TextHitInfo firstEndpoint, TextHitInfo secondEndpoint) Returns aShape
enclosing the visual selection in the specified range, extended to the bounds.getVisualHighlightShape
(TextHitInfo firstEndpoint, TextHitInfo secondEndpoint, Rectangle2D bounds) Returns a path enclosing the visual selection in the specified range, extended tobounds
.Returns the hit on the opposite side of the specified hit's caret.protected void
handleJustify
(float justificationWidth) Justify this layout.hitTestChar
(float x, float y) Returns aTextHitInfo
corresponding to the specified point.hitTestChar
(float x, float y, Rectangle2D bounds) Returns aTextHitInfo
corresponding to the specified point.void
hitToPoint
(TextHitInfo hit, Point2D point) Convert a hit to a point in standard coordinates.boolean
Returnstrue
if thisTextLayout
has a left-to-right base direction orfalse
if it has a right-to-left base direction.boolean
Returnstrue
if thisTextLayout
is vertical.toString()
Returns debugging information for thisTextLayout
.
-
Field Details
-
DEFAULT_CARET_POLICY
ThisCaretPolicy
is used when a policy is not specified by the client. With this policy, a hit on a character whose direction is the same as the line direction is stronger than a hit on a counterdirectional character. If the characters' directions are the same, a hit on the leading edge of a character is stronger than a hit on the trailing edge of a character.
-
-
Constructor Details
-
TextLayout
Constructs aTextLayout
from aString
and aFont
. 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.- Parameters:
string
- the text to displayfont
- aFont
used to style the textfrc
- 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.
-
TextLayout
public TextLayout(String string, Map<? extends AttributedCharacterIterator.Attribute, ?> attributes, FontRenderContext frc) Constructs aTextLayout
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.- Parameters:
string
- the text to displayattributes
- the attributes used to style the textfrc
- 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.
-
TextLayout
Constructs aTextLayout
from an iterator over styled text.The iterator must specify a single paragraph of text because an entire paragraph is required for the bidirectional algorithm.
- Parameters:
text
- the styled text to displayfrc
- 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.
-
-
Method Details
-
clone
-
getJustifiedLayout
Creates a copy of thisTextLayout
justified to the specified width.If this
TextLayout
has already been justified, an exception is thrown. If thisTextLayout
object's justification ratio is zero, aTextLayout
identical to thisTextLayout
is returned.- Parameters:
justificationWidth
- the width to use when justifying the line. For best results, it should not be too different from the current advance of the line.- Returns:
- a
TextLayout
justified to the specified width. - Throws:
Error
- if this layout has already been justified, an Error is thrown.
-
handleJustify
protected void handleJustify(float justificationWidth) Justify this layout. Overridden by subclassers to control justification (if there were subclassers, that is...) The layout will only justify if the paragraph attributes (from the source text, possibly defaulted by the layout attributes) indicate a non-zero justification ratio. The text will be justified to the indicated width. The current implementation also adjusts hanging punctuation and trailing whitespace to overhang the justification width. Once justified, the layout may not be rejustified.Some code may rely on immutability of layouts. Subclassers should not call this directly, but instead should call getJustifiedLayout, which will call this method on a clone of this layout, preserving the original.
- Parameters:
justificationWidth
- the width to use when justifying the line. For best results, it should not be too different from the current advance of the line.- See Also:
-
getBaseline
public byte getBaseline()Returns the baseline for thisTextLayout
. The baseline is one of the values defined inFont
, which are roman, centered and hanging. Ascent and descent are relative to this baseline. ThebaselineOffsets
are also relative to this baseline.- Returns:
- the baseline of this
TextLayout
. - See Also:
-
getBaselineOffsets
public float[] getBaselineOffsets()Returns the offsets array for the baselines used for thisTextLayout
.The array is indexed by one of the values defined in
Font
, which are roman, centered and hanging. The values are relative to thisTextLayout
object's baseline, so thatgetBaselineOffsets[getBaseline()] == 0
. Offsets are added to the position of theTextLayout
object's baseline to get the position for the new baseline.- Returns:
- the offsets array containing the baselines used for this
TextLayout
. - See Also:
-
getAdvance
public float getAdvance()Returns the advance of thisTextLayout
. The advance is the distance from the origin to the advance of the rightmost (bottommost) character. This is in baseline-relative coordinates.- Returns:
- the advance of this
TextLayout
.
-
getVisibleAdvance
public float getVisibleAdvance()Returns the advance of thisTextLayout
, minus trailing whitespace. This is in baseline-relative coordinates.- Returns:
- the advance of this
TextLayout
without the trailing whitespace. - See Also:
-
getAscent
public float getAscent()Returns the ascent of thisTextLayout
. The ascent is the distance from the top (right) of theTextLayout
to the baseline. It is always either positive or zero. The ascent is sufficient to accommodate superscripted text and is the maximum of the sum of the ascent, offset, and baseline of each glyph. The ascent is the maximum ascent from the baseline of all the text in the TextLayout. It is in baseline-relative coordinates.- Returns:
- the ascent of this
TextLayout
.
-
getDescent
public float getDescent()Returns the descent of thisTextLayout
. The descent is the distance from the baseline to the bottom (left) of theTextLayout
. It is always either positive or zero. The descent is sufficient to accommodate subscripted text and is the maximum of the sum of the descent, offset, and baseline of each glyph. This is the maximum descent from the baseline of all the text in the TextLayout. It is in baseline-relative coordinates.- Returns:
- the descent of this
TextLayout
.
-
getLeading
public float getLeading()Returns the leading of theTextLayout
. The leading is the suggested interline spacing for thisTextLayout
. This is in baseline-relative coordinates.The leading is computed from the leading, descent, and baseline of all glyphvectors in the
TextLayout
. The algorithm is roughly as follows:maxD = 0; maxDL = 0; for (GlyphVector g in all glyphvectors) { maxD = max(maxD, g.getDescent() + offsets[g.getBaseline()]); maxDL = max(maxDL, g.getDescent() + g.getLeading() + offsets[g.getBaseline()]); } return maxDL - maxD;
- Returns:
- the leading of this
TextLayout
.
-
getBounds
Returns the bounds of thisTextLayout
. The bounds are in standard coordinates.Due to rasterization effects, this bounds might not enclose all of the pixels rendered by the TextLayout.
It might not coincide exactly with the ascent, descent, origin or advance of theTextLayout
.- Returns:
- a
Rectangle2D
that is the bounds of thisTextLayout
.
-
getPixelBounds
Returns the pixel bounds of thisTextLayout
when rendered in a graphics with the givenFontRenderContext
at the given location. The graphics render context need not be the same as theFontRenderContext
used to create thisTextLayout
, and can be null. If it is null, theFontRenderContext
of thisTextLayout
is used.- Parameters:
frc
- theFontRenderContext
of theGraphics
.x
- the x-coordinate at which to render thisTextLayout
.y
- the y-coordinate at which to render thisTextLayout
.- Returns:
- a
Rectangle
bounding the pixels that would be affected. - Since:
- 1.6
- See Also:
-
isLeftToRight
public boolean isLeftToRight()Returnstrue
if thisTextLayout
has a left-to-right base direction orfalse
if it has a right-to-left base direction. TheTextLayout
has a base direction of either left-to-right (LTR) or right-to-left (RTL). The base direction is independent of the actual direction of text on the line, which may be either LTR, RTL, or mixed. Left-to-right layouts by default should position flush left. If the layout is on a tabbed line, the tabs run left to right, so that logically successive layouts position left to right. The opposite is true for RTL layouts. By default they should position flush left, and tabs run right-to-left.- Returns:
true
if the base direction of thisTextLayout
is left-to-right;false
otherwise.
-
isVertical
public boolean isVertical()Returnstrue
if thisTextLayout
is vertical.- Returns:
true
if thisTextLayout
is vertical;false
otherwise.
-
getCharacterCount
public int getCharacterCount()Returns the number of characters represented by thisTextLayout
.- Returns:
- the number of characters in this
TextLayout
.
-
getCaretInfo
Returns information about the caret corresponding tohit
. The first element of the array is the intersection of the caret with the baseline, as a distance along the baseline. The second element of the array is the inverse slope (run/rise) of the caret, measured with respect to the baseline at that point.This method is meant for informational use. To display carets, it is better to use
getCaretShapes
.- Parameters:
hit
- a hit on a character in thisTextLayout
bounds
- the bounds to which the caret info is constructed. The bounds is in baseline-relative coordinates.- Returns:
- a two-element array containing the position and slope of the caret. The returned caret info is in baseline-relative coordinates.
- See Also:
-
getCaretInfo
Returns information about the caret corresponding tohit
. This method is a convenience overload ofgetCaretInfo
and uses the natural bounds of thisTextLayout
.- Parameters:
hit
- a hit on a character in thisTextLayout
- Returns:
- the information about a caret corresponding to a hit. The returned caret info is in baseline-relative coordinates.
-
getNextRightHit
Returns the hit for the next caret to the right (bottom); if there is no such hit, returnsnull
. If the hit character index is out of bounds, anIllegalArgumentException
is thrown.- Parameters:
hit
- a hit on a character in this layout- Returns:
- a hit whose caret appears at the next position to the
right (bottom) of the caret of the provided hit or
null
.
-
getNextRightHit
Returns the hit for the next caret to the right (bottom); if no such hit, returnsnull
. The hit is to the right of the strong caret at the specified offset, as determined by the specified policy. The returned hit is the stronger of the two possible hits, as determined by the specified policy.- Parameters:
offset
- an insertion offset in thisTextLayout
. Cannot be less than 0 or greater than thisTextLayout
object's character count.policy
- the policy used to select the strong caret- Returns:
- a hit whose caret appears at the next position to the
right (bottom) of the caret of the provided hit, or
null
.
-
getNextRightHit
Returns the hit for the next caret to the right (bottom); if no such hit, returnsnull
. The hit is to the right of the strong caret at the specified offset, as determined by the default policy. The returned hit is the stronger of the two possible hits, as determined by the default policy.- Parameters:
offset
- an insertion offset in thisTextLayout
. Cannot be less than 0 or greater than theTextLayout
object's character count.- Returns:
- a hit whose caret appears at the next position to the
right (bottom) of the caret of the provided hit, or
null
.
-
getNextLeftHit
Returns the hit for the next caret to the left (top); if no such hit, returnsnull
. If the hit character index is out of bounds, anIllegalArgumentException
is thrown.- Parameters:
hit
- a hit on a character in thisTextLayout
.- Returns:
- a hit whose caret appears at the next position to the
left (top) of the caret of the provided hit, or
null
.
-
getNextLeftHit
Returns the hit for the next caret to the left (top); if no such hit, returnsnull
. The hit is to the left of the strong caret at the specified offset, as determined by the specified policy. The returned hit is the stronger of the two possible hits, as determined by the specified policy.- Parameters:
offset
- an insertion offset in thisTextLayout
. Cannot be less than 0 or greater than thisTextLayout
object's character count.policy
- the policy used to select the strong caret- Returns:
- a hit whose caret appears at the next position to the
left (top) of the caret of the provided hit, or
null
.
-
getNextLeftHit
Returns the hit for the next caret to the left (top); if no such hit, returnsnull
. The hit is to the left of the strong caret at the specified offset, as determined by the default policy. The returned hit is the stronger of the two possible hits, as determined by the default policy.- Parameters:
offset
- an insertion offset in thisTextLayout
. Cannot be less than 0 or greater than thisTextLayout
object's character count.- Returns:
- a hit whose caret appears at the next position to the
left (top) of the caret of the provided hit, or
null
.
-
getVisualOtherHit
Returns the hit on the opposite side of the specified hit's caret.- Parameters:
hit
- the specified hit- Returns:
- a hit that is on the opposite side of the specified hit's caret.
-
getCaretShape
Returns aShape
representing the caret at the specified hit inside the specified bounds.- Parameters:
hit
- the hit at which to generate the caretbounds
- the bounds of theTextLayout
to use in generating the caret. The bounds is in baseline-relative coordinates.- Returns:
- a
Shape
representing the caret. The returned shape is in standard coordinates.
-
getCaretShape
Returns aShape
representing the caret at the specified hit inside the natural bounds of thisTextLayout
.- Parameters:
hit
- the hit at which to generate the caret- Returns:
- a
Shape
representing the caret. The returned shape is in standard coordinates.
-
getCharacterLevel
public byte getCharacterLevel(int index) Returns the level of the character atindex
. Indices -1 andcharacterCount
are assigned the base level of thisTextLayout
.- Parameters:
index
- the index of the character from which to get the level- Returns:
- the level of the character at the specified index.
-
getCaretShapes
Returns two paths corresponding to the strong and weak caret.- Parameters:
offset
- an offset in thisTextLayout
bounds
- the bounds to which to extend the carets. The bounds is in baseline-relative coordinates.policy
- the specifiedCaretPolicy
- Returns:
- an array of two paths. Element zero is the strong
caret. If there are two carets, element one is the weak caret,
otherwise it is
null
. The returned shapes are in standard coordinates.
-
getCaretShapes
Returns two paths corresponding to the strong and weak caret. This method is a convenience overload ofgetCaretShapes
that uses the default caret policy.- Parameters:
offset
- an offset in thisTextLayout
bounds
- the bounds to which to extend the carets. This is in baseline-relative coordinates.- Returns:
- two paths corresponding to the strong and weak caret as
defined by the
DEFAULT_CARET_POLICY
. These are in standard coordinates.
-
getCaretShapes
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.- Parameters:
offset
- an offset in thisTextLayout
- Returns:
- two paths corresponding to the strong and weak caret as
defined by the
DEFAULT_CARET_POLICY
. These are in standard coordinates.
-
getLogicalRangesForVisualSelection
public int[] getLogicalRangesForVisualSelection(TextHitInfo firstEndpoint, TextHitInfo secondEndpoint) Returns the logical ranges of text corresponding to a visual selection.- Parameters:
firstEndpoint
- an endpoint of the visual rangesecondEndpoint
- the other endpoint of the visual range. This endpoint can be less thanfirstEndpoint
.- Returns:
- an array of integers representing start/limit pairs for the selected ranges.
- See Also:
-
getVisualHighlightShape
public Shape getVisualHighlightShape(TextHitInfo firstEndpoint, TextHitInfo secondEndpoint, Rectangle2D bounds) Returns a path enclosing the visual selection in the specified range, extended tobounds
.If the selection includes the leftmost (topmost) position, the selection is extended to the left (top) of
bounds
. If the selection includes the rightmost (bottommost) position, the selection is extended to the right (bottom) of the bounds. The height (width on vertical lines) of the selection is always extended tobounds
.Although the selection is always contiguous, the logically selected text can be discontiguous on lines with mixed-direction text. The logical ranges of text selected can be retrieved using
getLogicalRangesForVisualSelection
. For example, consider the text 'ABCdef' where capital letters indicate right-to-left text, rendered on a right-to-left line, with a visual selection from 0L (the leading edge of 'A') to 3T (the trailing edge of 'd'). The text appears as follows, with bold underlined areas representing the selection:defCBA
The logical selection ranges are 0-3, 4-6 (ABC, ef) because the visually contiguous text is logically discontiguous. Also note that since the rightmost position on the layout (to the right of 'A') is selected, the selection is extended to the right of the bounds.- Parameters:
firstEndpoint
- one end of the visual selectionsecondEndpoint
- the other end of the visual selectionbounds
- the bounding rectangle to which to extend the selection. This is in baseline-relative coordinates.- Returns:
- a
Shape
enclosing the selection. This is in standard coordinates. - See Also:
-
getVisualHighlightShape
Returns aShape
enclosing the visual selection in the specified range, extended to the bounds. This method is a convenience overload ofgetVisualHighlightShape
that uses the natural bounds of thisTextLayout
.- Parameters:
firstEndpoint
- one end of the visual selectionsecondEndpoint
- the other end of the visual selection- Returns:
- a
Shape
enclosing the selection. This is in standard coordinates.
-
getLogicalHighlightShape
Returns aShape
enclosing the logical selection in the specified range, extended to the specifiedbounds
.If the selection range includes the first logical character, the selection is extended to the portion of
bounds
before the start of thisTextLayout
. If the range includes the last logical character, the selection is extended to the portion ofbounds
after the end of thisTextLayout
. The height (width on vertical lines) of the selection is always extended tobounds
.The selection can be discontiguous on lines with mixed-direction text. Only those characters in the logical range between start and limit appear selected. For example, consider the text 'ABCdef' where capital letters indicate right-to-left text, rendered on a right-to-left line, with a logical selection from 0 to 4 ('ABCd'). The text appears as follows, with bold standing in for the selection, and underlining for the extension:
defCBA
The selection is discontiguous because the selected characters are visually discontiguous. Also note that since the range includes the first logical character (A), the selection is extended to the portion of thebounds
before the start of the layout, which in this case (a right-to-left line) is the right portion of thebounds
.- Parameters:
firstEndpoint
- an endpoint in the range of characters to selectsecondEndpoint
- the other endpoint of the range of characters to select. Can be less thanfirstEndpoint
. The range includes the character at min(firstEndpoint, secondEndpoint), but excludes max(firstEndpoint, secondEndpoint).bounds
- the bounding rectangle to which to extend the selection. This is in baseline-relative coordinates.- Returns:
- an area enclosing the selection. This is in standard coordinates.
- See Also:
-
getLogicalHighlightShape
Returns aShape
enclosing the logical selection in the specified range, extended to the natural bounds of thisTextLayout
. This method is a convenience overload ofgetLogicalHighlightShape
that uses the natural bounds of thisTextLayout
.- Parameters:
firstEndpoint
- an endpoint in the range of characters to selectsecondEndpoint
- the other endpoint of the range of characters to select. Can be less thanfirstEndpoint
. The range includes the character at min(firstEndpoint, secondEndpoint), but excludes max(firstEndpoint, secondEndpoint).- Returns:
- a
Shape
enclosing the selection. This is in standard coordinates.
-
getBlackBoxBounds
Returns the black box bounds of the characters in the specified range. The black box bounds is an area consisting of the union of the bounding boxes of all the glyphs corresponding to the characters between start and limit. This area can be disjoint.- Parameters:
firstEndpoint
- one end of the character rangesecondEndpoint
- the other end of the character range. Can be less thanfirstEndpoint
.- Returns:
- a
Shape
enclosing the black box bounds. This is in standard coordinates.
-
hitTestChar
Returns aTextHitInfo
corresponding to the specified point. Coordinates outside the bounds of theTextLayout
map to hits on the leading edge of the first logical character, or the trailing edge of the last logical character, as appropriate, regardless of the position of that character in the line. Only the direction along the baseline is used to make this evaluation.- Parameters:
x
- the x offset from the origin of thisTextLayout
. This is in standard coordinates.y
- the y offset from the origin of thisTextLayout
. This is in standard coordinates.bounds
- the bounds of theTextLayout
. This is in baseline-relative coordinates.- Returns:
- a hit describing the character and edge (leading or trailing) under the specified point.
-
hitTestChar
Returns aTextHitInfo
corresponding to the specified point. This method is a convenience overload ofhitTestChar
that uses the natural bounds of thisTextLayout
.- Parameters:
x
- the x offset from the origin of thisTextLayout
. This is in standard coordinates.y
- the y offset from the origin of thisTextLayout
. This is in standard coordinates.- Returns:
- a hit describing the character and edge (leading or trailing) under the specified point.
-
equals
Returnstrue
if the two layouts are equal. Obeys the general contract ofequals(Object)
.- Parameters:
rhs
- theTextLayout
to compare to thisTextLayout
- Returns:
true
if the specifiedTextLayout
equals thisTextLayout
.
-
toString
-
draw
Renders thisTextLayout
at the specified location in the specifiedGraphics2D
context. The origin of the layout is placed at x, y. Rendering may touch any point withingetBounds()
of this position. This leaves theg2
unchanged. Text is rendered along the baseline path.- Parameters:
g2
- theGraphics2D
context into which to render the layoutx
- the X coordinate of the origin of thisTextLayout
y
- the Y coordinate of the origin of thisTextLayout
- See Also:
-
getOutline
Returns aShape
representing the outline of thisTextLayout
.- Parameters:
tx
- an optionalAffineTransform
to apply to the outline of thisTextLayout
.- Returns:
- a
Shape
that is the outline of thisTextLayout
. This is in standard coordinates.
-
getLayoutPath
Return the LayoutPath, or null if the layout path is the default path (x maps to advance, y maps to offset).- Returns:
- the layout path
- Since:
- 1.6
-
hitToPoint
Convert a hit to a point in standard coordinates. The point is on the baseline of the character at the leading or trailing edge of the character, as appropriate. If the path is broken at the side of the character represented by the hit, the point will be adjacent to the character.- Parameters:
hit
- the hit to check. This must be a valid hit on the TextLayout.point
- the returned point. The point is in standard coordinates.- Throws:
IllegalArgumentException
- if the hit is not valid for the TextLayout.NullPointerException
- if hit or point is null.- Since:
- 1.6
-