java.awt.font
类 TextLayout

java.lang.Object
  java.awt.font.TextLayout

所有已实现的接口：

Cloneable

public final class TextLayout
     

      extends 
      Object
     
     

      implements 
      Cloneable
     

TextLayout 是样式字符数据的不可变图形表示形式。

它提供以下功能：

• 隐式双向分析和重排序
• 光标定位和移动，包括针对混向文本的拆分光标
• ，包括针对混向文本的逻辑和可视高亮显示
• 多个基线（罗马字体、悬挂和居中）
• 命中测试
• 调整
• 默认字体替换
• 规格信息，如 ascent、descent 和 advance
• 呈现

TextLayout 对象可以使用其 draw 方法呈现。

可以直接或通过使用 LineBreakMeasurer 构造 TextLayout。直接构造时，源文本表示一个段落。LineBreakMeasurer 允许带样式的文本断行，以适应特定的宽度。有关更多信息，请参阅 LineBreakMeasurer 文档。

TextLayout 的逻辑构造过程如下：

• 提取并检查段落属性
• 对文本进行双向重排分析，并在需要时计算重排信息
• 根据样式排列对文本进行分段
• 为样式排列选择的字体，如果存在 TextAttribute.FONT 属性，则首先使用该字体，否则，通过使用已定义的属性计算默认字体
• 如果文本位于多个基线上，则排列或子排列被进一步拆分为共享公共基线的子排列
• 使用所选字体为每个排列生成字形向量
• 对字形向量执行最后的双向重排

从 TextLayout 对象的方法返回的所有图形信息都相对于 TextLayout 的原点，它是 TextLayout 对象的基线与其左边缘的交叉点。同样，假定传递到 TextLayout 对象方法的坐标也相对于 TextLayout 对象的原点。客户端通常需要在 TextLayout 对象的坐标系和另一对象（如 Graphics 对象）中的坐标系之间进行转换。

根据样式文本创建 TextLayout 对象，但它们不保留对其源文本的引用。因此，对先前用来生成 TextLayout 文本的改动不会影响 TextLayout。

TextLayout 对象的三个方法（getNextRightHit、getNextLeftHit 和 hitTestChar）都返回 TextHitInfo 实例。这些 TextHitInfo 对象中的偏移量相对于 TextLayout 的起始处，而不是相对于用来创建 TextLayout 的文本。同样，接受 TextHitInfo 实例作为参数的 TextLayout 方法将 TextHitInfo 对象的偏移量看做相对于 TextLayout，而不是其他任何基础文本存储模型。

示例：

构造并绘制 TextLayout 及其边界矩形：

   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);
 

对 TextLayout 进行命中测试（确定哪个字符位于特定图形位置上）：

   Point2D click = ...;
   TextHitInfo hit = layout.hitTestChar(
                         (float) (click.getX() - loc.getX()),
                         (float) (click.getY() - loc.getY()));
 

对按下向右方向键进行响应：

   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]);
       }
   }
 

绘制一个对应于源文本中子字符串的选择范围。选择的区域在视觉上可能是不连续的：

   // 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);
 

绘制一个视觉上连续的选择范围。选择范围可能对应源文本中的多个子字符串。通过 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.
 

注：字体旋转可能导致文本基线旋转，多次进行不同的旋转可能够导致基线弯曲或出现 Z 形转角。为了处理好这种（少有的）可能性，需要指定一些 API 返回规格，并采用“相对于基线的坐标中”的参数（比如 ascent 和 advance），以及其他一些“标准坐标中”的规格和参数（比如 getBounds）。相对于基线的坐标中的值将 'x' 坐标映射到沿基线的某段距离处（正 x 表示沿基线的正方向），将 'y' 坐标映射到 'x' 坐标处基线垂直方向的某段距离处（正 y 表示从基线向量顺时针旋转 90 度）。标准坐标中的值是沿 x 轴和 y 轴进行测量的，0,0 是 TextLayout 的原点。用于每个相关 API 的文档都将指示哪些值位于坐标系中。通常，与测量有关的 API 位于与相对于基线的坐标中，而与显示有关的 API 则位于标准坐标中。

另请参见：

LineBreakMeasurer, TextAttribute, TextHitInfo, LayoutPath

DEFAULT_CARET_POLICY

public static final TextLayout.CaretPolicy DEFAULT_CARET_POLICY

客户端未指定策略时使用此 CaretPolicy。使用此策略，方向与行方向相同的字符的命中要强于对反方向字符的命中。如果字符的方向相同，则对字符开始边的命中要强于对字符结尾边的命中。

TextLayout

public TextLayout(String string,
                  Font font,
                  FontRenderContext frc)

根据 String 和 Font 构造一个 TextLayout。使用指定的 Font 样式化所有文本。

String 必须指定单个文本段，因为双向算法需要整个段落。

参数：

string - 要显示的文本

font - 用于样式化文本的 Font

frc - 包含关于正确测量文本所需图形设备的信息。根据设备分辨率和属性（如抗锯齿）的不同，文本测量可能稍有变化。此参数未指定 TextLayout 和用户空间之间的转换。

TextLayout

public TextLayout(String string,
                  Map<? extends AttributedCharacterIterator.Attribute,?> attributes,
                  FontRenderContext frc)

根据 String 和属性集构造一个 TextLayout。

使用提供的属性样式化所有文本。

String 必须指定单个文本段，因为双向算法需要整个段落。

参数：

string - 要显示的文本

attributes - 用于样式化文本的属性

frc - 包含关于正确测量文本所需图形设备的信息。根据设备分辨率和属性（如抗锯齿）的不同，文本测量可能稍有变化。此参数未指定 TextLayout 和用户空间之间的转换。

TextLayout

public TextLayout(AttributedCharacterIterator text,
                  FontRenderContext frc)

根据样式文本上的迭代器构造一个 TextLayout。

该迭代器必须指定单个文本段，因为双向算法需要整个段落。

参数：

text - 要显示的样式文本

frc - 包含关于正确测量文本所需图形设备的信息。根据设备分辨率和属性（如抗锯齿）的不同，文本测量可能稍有变化。此参数未指定 TextLayout 和用户空间之间的转换。

clone

protected Object clone()

创建此 TextLayout 的副本。

覆盖：

类 Object 中的 clone

返回：

此实例的一个副本。

另请参见：

Cloneable

getJustifiedLayout

public TextLayout getJustifiedLayout(float justificationWidth)

创建调整到指定宽度的此 TextLayout 的一个副本。

如果已调整了此 TextLayout，则抛出异常。如果此 TextLayout 对象的调整率为零，将返回与此 TextLayout 相同的 TextLayout。

参数：

justificationWidth - 调整行时使用的宽度。要获得最佳结果，该宽度与行的当前 advance 不应有太大差别。

返回：

调整到指定宽度的 TextLayout。

抛出：

Error - 如果已调整了此布局，则抛出 Error。

handleJustify

protected void handleJustify(float justificationWidth)

调整此布局。子类重写该方法来控制调整（如果存在子类，即……）。 只在段落属性（来自源文本，可以是布局属性的默认值）指示一个非零调整率时才调整布局。将文本调整到指示的宽度。当前实现还调整标点和尾部空白，使其接近于调整宽度。调整布局之后将不会对其进行再调整。

某些代码依赖于布局的不可变性。因此子类不应直接调用该方法，而应调用 getJustifiedLayout，getJustifiedLayout 将在此布局的副本上调用此方法，并保留原始布局。

参数：

justificationWidth - 调整行时使用的宽度。要获得最佳结果，该宽度与行的当前 advance 不应有太大差别。

另请参见：

getJustifiedLayout(float)

getBaseline

public byte getBaseline()

返回此 TextLayout 的基线。基线是 Font 中定义的一个值，它可以是 roman、centered 或 hanging。Ascent 和 descent 相对于此基线。 baselineOffsets 也相对于此基线。

返回：

此 TextLayout 的基线。

另请参见：

getBaselineOffsets(), Font

getBaselineOffsets

public float[] getBaselineOffsets()

返回用于此 TextLayout 的基线偏移量数组。

该数组用 Font 中定义的 roman、centered 或 hanging 值之一进行索引。这些值相对于此 TextLayout 对象的基线，从而 getBaselineOffsets[getBaseline()] == 0。将偏移量添加到 TextLayout 对象基线所在的位置，以获取新基线的位置。

返回：

包含用于此 TextLayout 基线的偏移量数组。

另请参见：

getBaseline(), Font

getAdvance

public float getAdvance()

返回此 TextLayout 的 advance。该 advance 是从原点到最右边（最底部）字符的 advance 的距离。返回值位于相对于基线的坐标中。

返回：

此 TextLayout 的 advance。

getVisibleAdvance

public float getVisibleAdvance()

返回此 TextLayout 的 advance，减去结尾空格。返回值位于相对于基线的坐标中。

返回：

此 TextLayout 的 advance，不包括结尾的空格。

另请参见：

getAdvance()

getAscent

public float getAscent()

返回此 TextLayout 的 ascent。ascent 是从 TextLayout 的顶端（右端）到基线的距离。它始终为正数或零。ascent 足以容纳上标文本，它是每个字形的 ascent、偏移量和基线总和的最大值。该 ascent 是 TextLayout 中所有文本基线的最大 ascent。返回值位于相对于基线的坐标中。

返回：

此 TextLayout 的 ascent。

getDescent

public float getDescent()

返回此 TextLayout 的 descent。descent 是从基线到 TextLayout 底部（左端）的距离。它始终为正数或零。descent 足以容纳下标文本，它是每个字形的 descent、偏移量和基线总和的最大值。该 ascent 是 TextLayout 中所有文本基线的最大 descent。返回值位于相对于基线的坐标中。

返回：

此 TextLayout 的 descent。

getLeading

public float getLeading()

返回 TextLayout 的行距。行距是此 TextLayout 的建议行间距。返回值位于相对于基线的坐标中。

行距通过 TextLayout 中所有字形向量的行距、descent 和基线计算。算法大致如下：

 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;
 

返回：

此 TextLayout 的行距。

getBounds

public Rectangle2D getBounds()

返回此 TextLayout 的边界。这些边界位于标准坐标中。因为光栅化效果，这些边界可能没有封装 TextLayout 呈现的所有像素。它可能与 TextLayout 的 ascent、descent、origin 或 advance 并不完全一致。

返回：

作为此 TextLayout 边界的 Rectangle2D。

getPixelBounds

public Rectangle getPixelBounds(FontRenderContext frc,
                                float x,
                                float y)

返回在图形中使用给定 FontRenderContext 在给定位置处呈现 TextLayout 时的像素边界。图形呈现上下文不必与用来创建此 TextLayout 的 FontRenderContext 相同，并且可以为 null。如果为 null，则使用此 TextLayout 的 FontRenderContext。

参数：

frc - Graphics 的 FontRenderContext。

x - 呈现此 TextLayout 处的 x 坐标。

y - 呈现此 TextLayout 处的 y 坐标。

返回：

封装受影响像素的 Rectangle。

从以下版本开始：

1.6

另请参见：

GlyphVector.getPixelBounds(java.awt.font.FontRenderContext, float, float)

isLeftToRight

public boolean isLeftToRight()

如果此 TextLayout 的基本方向是从左到右，则返回 true；如果基本方向是从右到左，则返回 false。 TextLayout 的基本方向是从左到右 (LTR) 或从右到左 (RTL)。基本方向与行中文本的实际方向无关，实际方向可以是 LTR、RTL 或混向。默认情况下，从左到右布局按左对齐来定位。如果布局在制表行上进行，那么制表符将从左到右，从而逻辑连续布局的定位将从左到右。对于 RTL 布局则相反。默认情况下，它们是按左对齐来定位的，制表符将从右到左。

返回：

如果此 TextLayout 的基本方向是从左到右，则返回 true；否则返回 false。

isVertical

public boolean isVertical()

如果此 TextLayout 是垂直的，则返回 true。

返回：

如果此 TextLayout 是垂直的，则返回 true；否则返回 false。

getCharacterCount

public int getCharacterCount()

返回由此 TextLayout 表示的字符数。

返回：

此 TextLayout 中的字符数。

getCaretInfo

public float[] getCaretInfo(TextHitInfo hit,
                            Rectangle2D bounds)

返回与对应于 hit 的插入符有关的信息。数组的第一个元素是插入符与基线的交集，它是沿基线的一段距离。数组的第二个元素是插入符的反斜面（排列/上升），它是根据位于该点的基线进行测量的。

此方法仅用于获取信息。要显示插入符，最好使用 getCaretShapes。

参数：

hit - 此 TextLayout 中的目标字符

bounds - 构造插入符位置的边界。这些边界位于相对于基线的坐标中。

返回：

包含插入符位置和斜面的两元素数组。返回的插入符信息位于相对于基线的坐标中。

另请参见：

getCaretShapes(int, Rectangle2D, TextLayout.CaretPolicy), Font.getItalicAngle()

getCaretInfo

public float[] getCaretInfo(TextHitInfo hit)

返回与对应于 hit 的插入符有关的信息。此方法是 getCaretInfo 的便捷用法，它使用了此 TextLayout 的自然边界。

参数：

hit - 此 TextLayout 中的目标字符

返回：

有关对应于目标字符的插入符的信息。返回的插入符信息位于相对于基线的坐标中。

getNextRightHit

public TextHitInfo getNextRightHit(TextHitInfo hit)

返回下一个插入符右侧（底部）的目标字符；如果没有这样的字符，则返回 null。如果目标字符索引超出范围，则抛出 IllegalArgumentException。

参数：

hit - 此布局中的目标字符

返回：

插入符显示在所提供目标字符的插入符右侧（底部）下一个位置的目标字符，或者返回 null。

getNextRightHit

public TextHitInfo getNextRightHit(int offset,
                                   TextLayout.CaretPolicy policy)

返回下一个插入符右侧（底部）的目标字符；如果没有这样的字符，则返回 null。目标字符位于指定偏移量处根据指定策略确定的强插入符右侧。返回的目标字符是根据指定策略确定的两个可能目标字符中较强的一个。

参数：

offset - 此 TextLayout 中的插入偏移量。不能小于 0 或大于此 TextLayout 对象的字符