@itwin/core-backend 5.0.0-dev.9 → 5.0.0-dev.92

package/lib/esm/TextAnnotationLayout.d.ts

@@ -0,0 +1,177 @@
+/** @packageDocumentation
+ * @module ElementGeometry
+ */
+import { BaselineShift, FontId, FontType, FractionRun, LineLayoutResult, Paragraph, Run, RunLayoutResult, TextBlock, TextBlockLayoutResult, TextRun, TextStyleSettings } from "@itwin/core-common";
+import { Range2d } from "@itwin/core-geometry";
+import { IModelDb } from "./IModelDb";
+/** @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 */
+export type FindTextStyle = (name: string) => 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 [TextStyle]($common)s when laying out glyphs. */
+    iModel: IModelDb;
+    /** @internal chiefly for tests, by default uses IModelJsNative.DgnDb.computeRangesForText. */
+    computeTextRange?: ComputeRangesForTextLayout;
+    /** @internal chiefly for tests, by default looks up styles from a workspace. */
+    findTextStyle?: FindTextStyle;
+    /** @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]]
+ * @internal
+ */
+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 [TextStyle]($common)s, fonts, and [TextBlock.width]($common). It applies word-wrapping if needed.
+ * The layout returned matches the visual layout of the geometry produced by [[produceTextAnnotationGeometry]].
+ * @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[];
+declare class LayoutContext {
+    private readonly _computeTextRange;
+    private readonly _findTextStyle;
+    private readonly _findFontId;
+    private readonly _textStyles;
+    private readonly _fontIds;
+    readonly blockSettings: TextStyleSettings;
+    constructor(block: TextBlock, _computeTextRange: ComputeRangesForTextLayout, _findTextStyle: FindTextStyle, _findFontId: FindFontId);
+    findFontId(name: string): FontId;
+    findTextStyle(name: string): TextStyleSettings;
+    createRunSettings(run: Run): TextStyleSettings;
+    computeRangeForText(chars: string, style: TextStyleSettings, baselineShift: BaselineShift): TextLayoutRanges;
+    computeRangeForTextRun(style: TextStyleSettings, run: TextRun, charOffset: number, numChars: number): TextLayoutRanges;
+    computeRangeForFractionRun(style: TextStyleSettings, source: FractionRun): {
+        layout: Range2d;
+        numerator: Range2d;
+        denominator: Range2d;
+    };
+}
+/** @internal */
+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): 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;
+}
+/** @internal */
+export declare class LineLayout {
+    source: Paragraph;
+    range: Range2d;
+    justificationRange: Range2d;
+    offsetFromDocument: {
+        x: number;
+        y: 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.
+ * @internal
+ */
+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=TextAnnotationLayout.d.ts.map

package/lib/esm/TextAnnotationLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextAnnotationLayout.d.ts","sourceRoot":"","sources":["../../src/TextAnnotationLayout.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,GAAG,EAAE,eAAe,EAAE,SAAS,EAAE,qBAAqB,EAAoB,OAAO,EAAE,iBAAiB,EAA0B,MAAM,oBAAoB,CAAC;AAC7O,OAAO,EAAY,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC,gBAAgB;AAChB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,IAAI,EAAE,8BAA8B,KAAK,gBAAgB,CAAC;AAEpG;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,KAAK,MAAM,CAAC;AAEnE,gBAAgB;AAChB,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,iBAAiB,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,SAAS,EAAE,SAAS,CAAC;IACrB,8FAA8F;IAC9F,MAAM,EAAE,QAAQ,CAAC;IACjB,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;IAC9C,gFAAgF;IAChF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,qEAAqE;IACrE,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAQ1E;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,qBAAqB,CAG7F;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACrE,wGAAwG;IACxG,cAAc,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,eAAe,EAAE,eAAe,CAAC;IACjC,sIAAsI;IACtI,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,0BAA0B,GAAG,OAAO,EAAE,CAqBlF;AAuBD,cAAM,aAAa;IAKoB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAA8B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAAiB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAJjL,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwC;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,SAAgB,aAAa,EAAE,iBAAiB,CAAC;gBAE9B,KAAK,EAAE,SAAS,EAAmB,iBAAiB,EAAE,0BAA0B,EAAmB,cAAc,EAAE,aAAa,EAAmB,WAAW,EAAE,UAAU;IAKtL,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAShC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB;IAS9C,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,iBAAiB;IAS9C,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,GAAG,gBAAgB;IAmC5G,sBAAsB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAItH,0BAA0B,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,WAAW,GAAG;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE;CA+BhJ;AA2BD,gBAAgB;AAChB,qBAAa,SAAS;IACb,MAAM,EAAE,GAAG,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IAEtB,OAAO;WAaO,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,GAAG,SAAS;IAmCpE,yEAAyE;IAClE,SAAS,IAAI,MAAM;IAInB,OAAO,IAAI,IAAI,IAAI;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE;IAI7C,OAAO,CAAC,YAAY;IAab,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,EAAE;IAsB1C,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe;CAyBvD;AAED,gBAAgB;AAChB,qBAAa,UAAU;IACd,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,UAA2B;IAChC,kBAAkB,UAA2B;IAC7C,kBAAkB;;;MAAkB;IAC3C,OAAO,CAAC,KAAK,CAAmB;gBAEb,MAAM,EAAE,SAAS;IAIpC,yEAAyE;IAClE,SAAS,IAAI,MAAM;IAK1B,IAAW,IAAI,IAAI,aAAa,CAAC,SAAS,CAAC,CAAuB;IAClE,IAAW,OAAO,YAAsC;IACxD,IAAW,IAAI,IAAI,SAAS,CAG3B;IAEM,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAKnC,6CAA6C;IAC7C,OAAO,CAAC,aAAa;IA0Bd,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,gBAAgB;CASxD;AAED;;;GAGG;AACH,qBAAa,eAAe;IACnB,MAAM,EAAE,SAAS,CAAC;IAEzB,8FAA8F;IACvF,SAAS,UAAiB;IAEjC,wDAAwD;IACjD,KAAK,UAAiB;IACtB,KAAK,EAAE,UAAU,EAAE,CAAM;IAChC,OAAO,CAAC,QAAQ,CAAgB;gBAEb,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa;IAcrD,QAAQ,IAAI,qBAAqB;IAOxC,yEAAyE;IAClE,SAAS,IAAI,MAAM;IAI1B,OAAO,KAAK,KAAK,GAGhB;IAED,OAAO,CAAC,aAAa;IAqDrB,OAAO,CAAC,YAAY;IA6BpB,OAAO,CAAC,SAAS;IAqCjB,OAAO,CAAC,YAAY;CAoBrB"}