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

iTwin.js backend components

/** @packageDocumentation
 * @module ElementGeometry
 */
import { BaselineShift, FieldRun, FontId, FontType, FractionRun, LineLayoutResult, List, Paragraph, Run, RunLayoutResult, TabRun, TextBlock, TextBlockComponent, TextBlockLayoutResult, TextRun, TextStyleSettings, TextStyleSettingsProps } from "@itwin/core-common";
import { Range2d, WritableXAndY } 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;
    textHeight: 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;
/**
 * Base interface for arguments supplied to [[computeLayoutTextBlockResult]] and [[computeGraphemeOffsets]].
 * @beta
 */
export interface LayoutTextArgs {
    /** 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;
}
/**
 * Arguments supplied to [[computeLayoutTextBlockResult]].
 * @beta
 */
export interface LayoutTextBlockArgs extends LayoutTextArgs {
    /** The text block whose extents are to be computed. */
    textBlock: TextBlock;
}
/**
 * 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 LayoutTextArgs {
    /** The TextBlockComponent for which to compute grapheme offsets. */
    source: TextBlockComponent;
    /** 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 ID of the [[AnnotationTextStyle]] to apply. */
    textStyleId: Id64String;
    /** The iModel from which to obtain [[AnnotationTextStyle]]s when resolving styles. */
    iModel: IModelDb;
    /** @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 of the instance and its parent(s).
 * @beta
 */
export declare class TextStyleResolver {
    /** The resolved style of the TextBlock. */
    readonly blockSettings: TextStyleSettings;
    constructor(args: TextStyleResolverArgs);
    /**
     * Resolves the effective text style settings for a given TextBlockComponent, applying block-level overrides.
     */
    resolveSettings(overrides: TextStyleSettingsProps, isLeader?: boolean): TextStyleSettings;
    resolveMarkerText(overrides: TextStyleSettingsProps, index: number): string;
    /**
     * Computes the indentation based on its style and nesting depth.
     */
    resolveIndentation(styleOverrides: TextStyleSettingsProps, depth: number): number;
}
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, type?: FontType): 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, lengthFromLastTab: 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, context: LayoutContext, cumulativeOverrides: TextStyleSettingsProps): RunLayout;
    /** Compute a string representation, primarily for debugging purposes. */
    stringify(): string;
    canWrap(): this is {
        source: TextRun;
    };
    private cloneForWrap;
    split(context: LayoutContext): RunLayout[];
    toResult(): 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: List | Run | Paragraph;
    range: Range2d;
    runRange: Range2d;
    justificationRange: Range2d;
    offsetFromDocument: WritableXAndY;
    depth: number;
    lengthFromLastTab: number;
    private _runs;
    private _marker?;
    constructor(source: List | Run | Paragraph, style: TextStyleSettingsProps, context?: LayoutContext, depth?: number);
    /** Compute a string representation, primarily for debugging purposes. */
    stringify(): string;
    /** Gets the array of RunLayout objects contained in this line. */
    get runs(): ReadonlyArray<RunLayout>;
    /** Indicates whether this line contains any runs. */
    get isEmpty(): boolean;
    /** Gets the last RunLayout in this line. */
    get back(): RunLayout;
    /**
     * Gets or sets the marker RunLayout for this line, used for lists.
     * A marker is the symbol or character that appears before each list item in a list, bullets, numbers, etc.
     * */
    get marker(): RunLayout | undefined;
    set marker(value: RunLayout | undefined);
    append(run: RunLayout): void;
    /** Invoked every time a run is appended,. */
    private computeRanges;
    toResult(): 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 populateComponent;
    private populateRun;
    private flushLine;
    private justifyLines;
    private applyMargins;
}
export {};
//# sourceMappingURL=TextBlockLayout.d.ts.map