@itwin/core-backend/lib/cjs/annotations/TextBlockLayout.d.ts

iTwin.js backend components

/** @packageDocumentation
 * @module ElementGeometry
 */
import { BaselineShift, FieldRun, FontId, FontType, FractionRun, LineLayoutResult, Paragraph, Run, RunLayoutResult, TabRun, TextAnnotationLeader, TextBlock, TextBlockLayoutResult, TextRun, TextStyleSettings } from "@itwin/core-common";
import { Range2d } from "@itwin/core-geometry";
import { IModelDb } from "../IModelDb";
import { Id64String } from "@itwin/core-bentley";
/** @internal */
export interface TextLayoutRanges {
    layout: Range2d;
    justification: Range2d;
}
/** Arguments to [[ComputeRangesForTextLayout]].
 * @internal
 */
export interface ComputeRangesForTextLayoutArgs {
    chars: string;
    bold: boolean;
    italic: boolean;
    baselineShift: BaselineShift;
    fontId: FontId;
    widthFactor: number;
    lineHeight: number;
}
/** A function that uses a font to compute the layout and justification ranges of a string of text.
 * @internal
 */
export type ComputeRangesForTextLayout = (args: ComputeRangesForTextLayoutArgs) => TextLayoutRanges;
/** A function that looks up the font Id corresponding to a [FontFamilyDescriptor]($common).
 * If no type is provided, the function can return a font of any type matching `name` (there may be more than one, of different types).
 * @internal
 */
export type FindFontId = (name: string, type?: FontType) => FontId;
/** @internal chiefly for tests. */
export type FindTextStyle = (id: Id64String) => TextStyleSettings;
/**
 * Arguments supplied to [[computeLayoutTextBlockResult]].
 * @beta
 */
export interface LayoutTextBlockArgs {
    /** The text block whose extents are to be computed. */
    textBlock: TextBlock;
    /** The iModel from which to obtain fonts and [[AnnotationTextStyle]]s when laying out glyphs. */
    iModel: IModelDb;
    /** The text style resolver used to resolve effective text styles during layout. */
    textStyleResolver: TextStyleResolver;
    /** @internal chiefly for tests, by default uses IModelJsNative.DgnDb.computeRangesForText. */
    computeTextRange?: ComputeRangesForTextLayout;
    /** @internal chiefly for tests, by default uses IModelDb.fontMap. */
    findFontId?: FindFontId;
}
/**
 * Lays out the contents of a TextBlock into a series of lines containing runs.
 * Each paragraph is decomposed into a series of lines.
 * Each series of consecutive non-linebreak runs within a paragraph is concatenated into one line.
 * If the document specifies a width > 0, individual lines are split to try to avoid exceeding that width.
 * Individual TextRuns can be split onto multiple lines at word boundaries if necessary. Individual FractionRuns are never split.
 * @see [[computeLayoutTextBlockResult]]
 * @beta
 */
export declare function layoutTextBlock(args: LayoutTextBlockArgs): TextBlockLayout;
/**
 * Gets the result of laying out the the contents of a TextBlock into a series of lines containing runs.
 * The visual layout accounts for the [[AnnotationTextStyle]]s, fonts, and [TextBlock.width]($common). It applies word-wrapping if needed.
 * The layout returned matches the visual layout of the geometry produced by [[appendTextAnnotationGeometry]].
 * @beta
 */
export declare function computeLayoutTextBlockResult(args: LayoutTextBlockArgs): TextBlockLayoutResult;
/**
 * Arguments supplied to [[computeGraphemeOffsets]].
 * @beta
 */
export interface ComputeGraphemeOffsetsArgs extends LayoutTextBlockArgs {
    /** The index of the [Paragraph]($common) in the text block that contains the run layout result text. */
    paragraphIndex: number;
    /** The run layout result for which grapheme ranges will be computed. */
    runLayoutResult: RunLayoutResult;
    /** An array of starting character indexes for each grapheme. Each entry represents the index of the first character in a grapheme. */
    graphemeCharIndexes: number[];
}
/**
 * Computes the range from the start of a [RunLayoutResult]($common) to the trailing edge of each grapheme.
 * It is the responsibility of the caller to determine the number and character indexes of the graphemes.
 * @returns If the [RunLayoutResult]($common)'s source is a [TextRun]($common), it returns an array containing the range of each grapheme.
 * Otherwise, it returns and empty array.
 * @beta
 */
export declare function computeGraphemeOffsets(args: ComputeGraphemeOffsetsArgs): Range2d[];
/**
 * Arguments used when constructing a [[TextStyleResolver]].
 * @beta
 */
export interface TextStyleResolverArgs {
    /** The text block whose styles are being resolved. */
    textBlock: TextBlock;
    /** The iModel from which to obtain [[AnnotationTextStyle]]s when resolving styles. */
    iModel: IModelDb;
    /** The ID of the model containing the text block, used to compute the scale factor. */
    modelId?: Id64String;
    /** @internal chiefly for tests, by default looks up an [[AnnotationTextStyle]] in the iModel by ID. */
    findTextStyle?: FindTextStyle;
}
/**
 * Resolves the effective style of TextBlockComponents and Leaders, taking into account overrides/style of the instance and its parent(s).
 * @beta
 */
export declare class TextStyleResolver {
    private readonly _textStyles;
    private readonly _findTextStyle;
    /** The resolved style of the TextBlock. */
    readonly blockSettings: TextStyleSettings;
    /** The scale factor of the model containing the TextBlock. */
    readonly scaleFactor: number;
    constructor(args: TextStyleResolverArgs);
    private resolveParagraphSettingsImpl;
    /** Looks up an [[AnnotationTextStyle]] by ID. Uses caching. */
    findTextStyle(id: Id64String): TextStyleSettings;
    /** Resolves the effective style for a [TextAnnotationLeader]($common). The TextAnnotationLeader should be a sibling of the provided TextBlock. */
    resolveTextAnnotationLeaderSettings(leader: TextAnnotationLeader): TextStyleSettings;
    /** Resolves the effective style for a [Paragraph]($common). Paragraph should be child of provided TextBlock. */
    resolveParagraphSettings(paragraph: Paragraph): TextStyleSettings;
    /** Resolves the effective style for a [Run]($common). Run should be child of provided Paragraph and TextBlock. */
    resolveRunSettings(paragraph: Paragraph, run: Run): TextStyleSettings;
}
declare class LayoutContext {
    readonly textStyleResolver: TextStyleResolver;
    private readonly _computeTextRange;
    private readonly _findFontId;
    private readonly _fontIds;
    constructor(textStyleResolver: TextStyleResolver, _computeTextRange: ComputeRangesForTextLayout, _findFontId: FindFontId);
    findFontId(name: string): FontId;
    computeRangeForText(chars: string, style: TextStyleSettings, baselineShift: BaselineShift): TextLayoutRanges;
    computeRangeForTextRun(style: TextStyleSettings, run: TextRun | FieldRun, charOffset: number, numChars: number): TextLayoutRanges;
    computeRangeForFractionRun(style: TextStyleSettings, source: FractionRun): {
        layout: Range2d;
        numerator: Range2d;
        denominator: Range2d;
    };
    computeRangeForTabRun(style: TextStyleSettings, source: TabRun, length: number): Range2d;
}
/**
 * Represents the layout of a single run (text, fraction, or line break) within a line of text.
 * Stores information about the run's position, style, and font within the line.
 * Provides utilities for splitting text runs for word wrapping and converting to result objects.
 * @beta
 */
export declare class RunLayout {
    source: Run;
    charOffset: number;
    numChars: number;
    range: Range2d;
    justificationRange?: Range2d;
    denominatorRange?: Range2d;
    numeratorRange?: Range2d;
    offsetFromLine: {
        x: number;
        y: number;
    };
    style: TextStyleSettings;
    fontId: FontId;
    private constructor();
    static create(source: Run, parentParagraph: Paragraph, context: LayoutContext): RunLayout;
    /** Compute a string representation, primarily for debugging purposes. */
    stringify(): string;
    canWrap(): this is {
        source: TextRun;
    };
    private cloneForWrap;
    split(context: LayoutContext): RunLayout[];
    toResult(paragraph: Paragraph): RunLayoutResult;
}
/**
 * Represents the layout of a single line within a paragraph of a text block.
 * Contains a sequence of RunLayout objects, the computed range of the line, and its offset from the document origin.
 * Provides utilities for appending runs, computing ranges, and converting to result objects.
 * @beta
 */
export declare class LineLayout {
    source: Paragraph;
    range: Range2d;
    justificationRange: Range2d;
    offsetFromDocument: {
        x: number;
        y: number;
    };
    lengthFromLastTab: number;
    private _runs;
    constructor(source: Paragraph);
    /** Compute a string representation, primarily for debugging purposes. */
    stringify(): string;
    get runs(): ReadonlyArray<RunLayout>;
    get isEmpty(): boolean;
    get back(): RunLayout;
    append(run: RunLayout): void;
    /** Invoked every time a run is appended,. */
    private computeRanges;
    toResult(textBlock: TextBlock): LineLayoutResult;
}
/**
 * Describes the layout of a text block as a collection of lines containing runs.
 * Computes the visual layout of the text block, including word wrapping, justification, and margins.
 * Provides access to the computed lines, ranges, and utilities for converting to result objects.
 * @beta
 */
export declare class TextBlockLayout {
    source: TextBlock;
    /** @internal: This is primarily for debugging purposes. This is the range of text geometry */
    textRange: Range2d;
    /** The range including margins of the [[TextBlock]]. */
    range: Range2d;
    lines: LineLayout[];
    private _context;
    constructor(source: TextBlock, context: LayoutContext);
    toResult(): TextBlockLayoutResult;
    /** Compute a string representation, primarily for debugging purposes. */
    stringify(): string;
    private get _back();
    private populateLines;
    private justifyLines;
    private flushLine;
    private applyMargins;
}
export {};
//# sourceMappingURL=TextBlockLayout.d.ts.map