Класс TextLayout

public final class TextLayout
extends Object
implements Cloneable

TextLayout — это неизменяемое графическое представление стилизованных данных символов.

Он предоставляет следующие возможности:

• неявный анализ и переупорядочение в соответствии с направлением письма,
• позиционирование и перемещение курсора, включая разделение курсора для текста с смешанным направлением,
• выделение, включая логическое и визуальное выделение для текста со смешанным направлением,
• несколько базовых линий (римская, подвешенная и центрированная),
• проверка попадания,
• выравнивание,
• замена шрифтов по умолчанию,
• метрическая информация, такая как восходящая, нисходящая и продвижение, и
• отображение

Объект TextLayout может быть отображён с помощью его метода draw.

Объект TextLayout может быть создан либо напрямую, либо с помощью LineBreakMeasurer. При прямом создании исходный текст представляет собой один абзац. LineBreakMeasurer позволяет разбивать стилизованный текст на строки, которые помещаются в определённую ширину. Дополнительную информацию см. в документации LineBreakMeasurer.

Создание объекта TextLayout логически происходит следующим образом:

• экстрагируются и анализируются атрибуты абзаца,
• текст анализируется на переупорядочение в соответствии с направлением письма, и информация о переупорядочении вычисляется, если необходимо,
• текст сегментируется на блоки стиля,
• для блоков стиля выбираются шрифты, сначала используется шрифт, если присутствует атрибут TextAttribute.FONT, в противном случае вычисляется шрифт по умолчанию с использованием определённых атрибутов,
• если текст находится на нескольких базовых линиях, блоки или подблоки разбиваются на подблоки, которые используют общую базовую линию,
• для каждого блока генерируются векторы глифов с использованием выбранного шрифта,
• выполняется окончательное переупорядочение в соответствии с направлением письма для векторов глифов

Вся графическая информация, возвращаемая методами объекта TextLayout, относится к началу системы координат объекта TextLayout, которая является пересечением базовой линии объекта TextLayout с его левым краем. Кроме того, координаты, передаваемые в методы объекта TextLayout, предполагается относительными к началу системы координат объекта TextLayout. Клиентам обычно необходимо выполнять преобразование между системой координат объекта TextLayout и системой координат другого объекта (например, объекта Graphics).

Объекты TextLayout создаются на основе стилизованного текста, но они не сохраняют ссылку на исходный текст. Таким образом, изменения в тексте, ранее использованном для генерации объекта TextLayout, не влияют на объект TextLayout.

Три метода объекта TextLayout (getNextRightHit, getNextLeftHit, и hitTestChar) возвращают экземпляры TextHitInfo. Смещения, содержащиеся в этих объектах TextHitInfo, относительны к началу объекта TextLayout, а не к тексту, используемому для создания объекта TextLayout. Аналогично, методы TextLayout, принимающие объекты TextHitInfo в качестве параметров, ожидают, что смещения объекта 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 translated 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.

Примечание: Поворот шрифта может вызвать поворот базовых линий текста, а несколько блоков с различными поворотами могут привести к искривлению или зигзагообразности базовой линии. Чтобы учесть эту (редкую) возможность, некоторые API разработаны для возвращения метрик и использования параметров «в координатах, относительных к базовой линии» (например, восходящая, продвижение), а другие — в «стандартных координатах» (например, getBounds). Значения в координатах, относительных к базовой линии, отображают координату «x» как расстояние вдоль базовой линии (положительная x — вперёд вдоль базовой линии), а координату «y» — как расстояние вдоль перпендикуляра к базовой линии в точке «x» (положительная y — на 90 градусов по часовой стрелке от вектора базовой линии). Значения в стандартных координатах измеряются вдоль осей x и y, причём 0,0 находится в начале координат объекта TextLayout. Документация для каждого соответствующего API указывает, какие значения находятся в какой системе координат. В целом, API, связанные с измерениями, находятся в координатах, относительных к базовой линии, а API, связанные с отображением, — в стандартных координатах.