@itwin/core-common/lib/esm/annotation/TextBlock.d.ts

iTwin.js components common to frontend and backend

/** @packageDocumentation
 * @module Annotation
 */
import { ListMarker, TextStyleSettingsProps } from "./TextStyle";
import { FieldFormatOptions, FieldPropertyHost, FieldPropertyPath } from "./TextField";
/** Options supplied to [[TextBlockComponent.clearStyleOverrides]] to control how the style overrides are cleared on the component and its child components.
 * @beta
 */
export interface ClearTextStyleOptions {
    /** Controls whether the styleOverrides of any child components are retained.
     * By default, all overrides are cleared.
     */
    preserveChildrenOverrides?: boolean;
}
/** The JSON representation of a [[TextBlockComponent]].
 * @beta
 */
export interface TextBlockComponentProps {
    /** Deviations from the base [[TextStyleSettings]] defined by the [AnnotationTextStyle]($backend) applied to this component.
     * This permits you to, e.g., create a [[TextBlock]] using "Arial" font and override one of its [[TextRun]]s to use "Comic Sans" instead.
     */
    styleOverrides?: TextStyleSettingsProps;
}
/** Options supplied to [[TextBlockComponent.stringify]] to control how the content is formatted.
 * @beta
 */
export interface TextBlockStringifyOptions {
    /** A string to insert in between each [[Paragraph]].
     * Default: " " - a single space.
     */
    paragraphBreak?: string;
    /** A string to insert for each [[LineBreakRun]].
     * Default: " " - a single space.
     */
    lineBreak?: string;
    /** A string to insert between the numerator and denominator of each [[FractionRun]].
     * Default: "/"
     */
    fractionSeparator?: string;
    /** The number of spaces to use for tabs. If not provided, tabs will be represented by a tab character: "\t".
     * Default: "undefined" - use "\t".
     */
    tabsAsSpaces?: number;
    /** A string to insert in between the list marker and the list item.
     * Default: " " - a single space.
     */
    listMarkerBreak?: string;
}
/**
 * Context information that may be useful when converting a [[TextBlock]] to a string.
 * @beta
 */
export interface TextBlockStringifyContext {
    /** The current depth of the text block in the document structure. */
    depth: number;
}
/**
 * Abstract representation of any of the building blocks that make up a [[TextBlock]] document - namely [[Run]]s and [[StructuralTextBlockComponent]]s.
 * The [[TextBlock]] can specify an [AnnotationTextStyle]($backend) that formats its contents.
 * Each component can specify an optional [[styleOverrides]] to customize that formatting.
 * @beta
 */
export declare abstract class TextBlockComponent {
    private _styleOverrides;
    /** @internal */
    protected constructor(props?: TextBlockComponentProps);
    /** Deviations in individual properties of the [[TextStyleSettings]] in the [AnnotationTextStyle]($backend).
     * For example, if the style uses the "Arial" font, you can override that by settings `styleOverrides.font.name` to "Comic Sans".
     * @see [[clearStyleOverrides]] to reset this to an empty object.
     */
    get styleOverrides(): TextStyleSettingsProps;
    set styleOverrides(overrides: TextStyleSettingsProps);
    /** Reset any [[styleOverrides]] applied to this component. */
    clearStyleOverrides(_options?: ClearTextStyleOptions): void;
    /** Returns true if [[styleOverrides]] specifies any deviations from the [[TextBlock]]'s [AnnotationTextStyle]($backend). */
    get overridesStyle(): boolean;
    /** Create a deep copy of this component. */
    abstract clone(): TextBlockComponent;
    /** Compute a string representation of the contents of this component and all of its sub-components. */
    abstract stringify(options?: TextBlockStringifyOptions, context?: TextBlockStringifyContext): string;
    /** Returns true if this component has no content or children. */
    abstract get isEmpty(): boolean;
    /**
    * Returns true if the string representation of this component consists only of whitespace characters.
    * Useful for checking if the component is visually empty (producing no graphics) or contains only spaces, tabs, or line breaks.
    */
    get isWhitespace(): boolean;
    /** Convert this component to its JSON representation. */
    toJSON(): TextBlockComponentProps;
    /** Returns true if `this` is equivalent to `other`. */
    equals(other: TextBlockComponent): boolean;
}
/** [[TextBlockComponent]]s contained within a [[Paragraph]].
 * @beta
 */
export type Run = TextRun | FractionRun | TabRun | LineBreakRun | FieldRun;
/** The JSON representation of a [[Run]].
 * Use the `type` field to discriminate between the different kinds of runs.
 * @beta
 */
export type RunProps = TextRunProps | FractionRunProps | TabRunProps | LineBreakRunProps | FieldRunProps;
/** A sequence of characters within a [[Paragraph]] that share a single style. Runs are the leaf nodes of a [[TextBlock]] document. When laid out for display, a single run may span
 * multiple lines, but it will never contain different styling.
 * Use the `type` field to discriminate between the different kinds of runs.
 * @beta
 */
export declare namespace Run {
    /** Create a run from its JSON representation.
     * @see [[TextRun.create]], [[FractionRun.create]], [[FieldRun.create]], [[TabRun.create]], and [[LineBreakRun.create]] to create a run directly.
     */
    function fromJSON(props: RunProps): Run;
}
/** Describes whether the characters of a [[TextRun]] should be displayed normally, in subscript, or in superscript.
 * [[TextStyleSettings.superScriptScale]], [[TextStyleSettings.subScriptScale]], [[TextStyleSettings.superScriptOffsetFactor]], and [[TextStyleSettings.subScriptOffsetFactor]]
 * affect how the content is rendered.
 * @beta
 */
export type BaselineShift = "subscript" | "superscript" | "none";
/** JSON representation of a [[TextRun]].
 * @beta
 */
export interface TextRunProps extends TextBlockComponentProps {
    /** Discriminator field for the [[RunProps]] union. */
    readonly type: "text";
    /** The characters displayed by the run.
     * Default: an empty string.
     */
    content?: string;
    /** Whether to display [[content]] as a subscript, superscript, or normally.
     * Default: "none"
     */
    baselineShift?: BaselineShift;
}
/** The most common type of [[Run]], containing a sequence of characters to be displayed using a single style.
 * @beta
 */
export declare class TextRun extends TextBlockComponent {
    /** Discriminator field for the [[Run]] union. */
    readonly type = "text";
    /** The sequence of characters to be displayed by the run. */
    content: string;
    /** Whether to display [[content]] as a subscript, superscript, or normally. */
    baselineShift: BaselineShift;
    private constructor();
    clone(): TextRun;
    toJSON(): TextRunProps;
    static create(props?: Omit<TextRunProps, "type">): TextRun;
    get isEmpty(): boolean;
    /** Simply returns [[content]]. */
    stringify(): string;
    equals(other: TextBlockComponent): boolean;
}
/** JSON representation of a [[FractionRun]].
 * @beta
 */
export interface FractionRunProps extends TextBlockComponentProps {
    /** Discriminator field for the [[RunProps]] union. */
    readonly type: "fraction";
    /** The text displayed before or above the fraction separator, depending on [[TextStyleSettings.stackedFractionType]]. Default: an empty string. */
    numerator?: string;
    /** The text displayed after or below the fraction separator, depending on [[TextStyleSettings.stackedFractionType]]. Default: an empty string. */
    denominator?: string;
}
/** A [[Run]] containing a numeric ratio to be displayed as a numerator and denominator separated by a horizontal or diagonal bar.
 * @note The [[numerator]] and [[denominator]] are stored as strings. They are not technically required to contain a numeric representation.
 * @beta
 */
export declare class FractionRun extends TextBlockComponent {
    /** Discriminator field for the [[Run]] union. */
    readonly type = "fraction";
    /** The fraction's numerator. */
    numerator: string;
    /** The fraction's denominator. */
    denominator: string;
    private constructor();
    toJSON(): FractionRunProps;
    clone(): FractionRun;
    static create(props?: Omit<FractionRunProps, "type">): FractionRun;
    get isEmpty(): boolean;
    /** Formats the fraction as a string with the [[numerator]] and [[denominator]] separated by [[TextBlockStringifyOptions.fractionSeparator]]. */
    stringify(options?: TextBlockStringifyOptions): string;
    equals(other: TextBlockComponent): boolean;
}
/** JSON representation of a [[LineBreakRun]].
 * @beta
 */
export interface LineBreakRunProps extends TextBlockComponentProps {
    /** Discriminator field for the [[RunProps]] union. */
    readonly type: "linebreak";
}
/** A [[Run]] that represents the end of a line of text within a [[Paragraph]]. It contains no content of its own - it simply causes subsequent content to display on a new line.
 * @beta
 */
export declare class LineBreakRun extends TextBlockComponent {
    /** Discriminator field for the [[Run]] union. */
    readonly type = "linebreak";
    private constructor();
    toJSON(): LineBreakRunProps;
    static create(props?: Omit<LineBreakRunProps, "type">): LineBreakRun;
    clone(): LineBreakRun;
    get isEmpty(): boolean;
    /** Simply returns [[TextBlockStringifyOptions.lineBreak]]. */
    stringify(options?: TextBlockStringifyOptions): string;
    equals(other: TextBlockComponent): boolean;
}
/** JSON representation of a [[TabRun]].
 * @beta
 */
export interface TabRunProps extends TextBlockComponentProps {
    /** Discriminator field for the [[RunProps]] union. */
    readonly type: "tab";
}
/** A [[TabRun]] is used to shift the next tab stop.
 * @note Only left-justified tabs are supported at this tab.
 * @beta
 */
export declare class TabRun extends TextBlockComponent {
    /** Discriminator field for the [[Run]] union. */
    readonly type = "tab";
    toJSON(): TabRunProps;
    clone(): TabRun;
    static create(props?: Omit<TabRunProps, "type">): TabRun;
    get isEmpty(): boolean;
    /**
   * Converts a [[TabRun]] to its string representation.
   * If the `tabsAsSpaces` option is provided, returns a string of spaces of the specified length.
   * Otherwise, returns a tab character ("\t").
   */
    stringify(options?: TextBlockStringifyOptions): string;
    equals(other: TextBlockComponent): boolean;
}
/** JSON representation of a [[FieldRun]].
 * @beta
 */
export interface FieldRunProps extends TextBlockComponentProps {
    /** Discriminator field for the [[RunProps]] union. */
    readonly type: "field";
    /** The element and BIS class containing the property described by [[propertyPath]]. */
    propertyHost: FieldPropertyHost;
    /** Describes how to obtain the property value from [[propertyHost]]. */
    propertyPath: FieldPropertyPath;
    /** Specifies how to format the property value obtained from [[propertyPath]] into a string to be stored in [[cachedContent]].
     * The specific options used depend upon the field's [[propertyType]].
     */
    formatOptions?: FieldFormatOptions;
    /** The field's most recently evaluated display string.
     * @note It is unnecessary to specify this when creating a field as part of an element like a [[TextAnnotation2d]], because
     * all of the element's fields will be re-evaluated when inserting or updating the element in the iModel.
     */
    cachedContent?: string;
}
/** A [[Run]] that displays the formatted value of a property of some [Element]($backend).
 * When a [[TextBlock]] containing a [[FieldRun]] is written into the iModel as an [ITextAnnotation]($backend) element,
 * a dependency is established between the two elements via the [ElementDrivesTextAnnotation]($backend) relationship such that
 * whenever the source element specified by [[propertyHost]] is modified or the `ITextAnnotation` element is inserted or updated in the iModel,
 * the field(s) in the `ITextAnnotation` element are automatically
 * recalculated, causing their [[cachedContent]] to update. If the field's display string cannot be evaluated (for example, because the specified element or
 * property does not exist), then its cached content is set to [[FieldRun.invalidContentIndicator]].
 * A [[FieldRun]] displays its [[cachedContent]] in the same way that [[TextRun]]s display their `content`, including word wrapping where appropriate.
 * @beta
 */
export declare class FieldRun extends TextBlockComponent {
    /** Display string used to signal an error in computing the field's value. */
    static invalidContentIndicator: string;
    /** Discriminator field for the [[Run]] union. */
    readonly type = "field";
    /** The element and BIS class containing the property described by [[propertyPath]]. */
    propertyHost: FieldPropertyHost;
    /** Describes how to obtain the property value from [[propertyHost]]. */
    propertyPath: FieldPropertyPath;
    /** Specifies how to format the property value obtained from [[propertyPath]] into a string to be stored in [[cachedContent]].
     * The specific options used depend upon the [[FieldPropertyType]].
     */
    formatOptions?: FieldFormatOptions;
    private _cachedContent;
    /** The field's most recently evaluated display string. */
    get cachedContent(): string;
    /** @internal Used by core-backend when re-evaluating field content. */
    setCachedContent(content: string | undefined): void;
    private constructor();
    /** Create a FieldRun from its JSON representation. */
    static create(props: Omit<FieldRunProps, "type">): FieldRun;
    /** Convert the FieldRun to its JSON representation. */
    toJSON(): FieldRunProps;
    /** Create a deep copy of this FieldRun. */
    clone(): FieldRun;
    get isEmpty(): boolean;
    /** Convert this FieldRun to a simple string representation. */
    stringify(): string;
    /** Returns true if `this` is equivalent to `other`. */
    equals(other: TextBlockComponent): boolean;
}
/** JSON representation of a [[Paragraph]].
 * @beta
 */
export interface ParagraphProps extends TextBlockComponentProps {
    children?: Array<ListProps | RunProps>;
}
/** A collection of [[Run]]s and [[List]]s. Paragraphs can be appended to [[List]]s and [[TextBlock]]s.
 * Each paragraph is laid out on a separate line. If included in a [[List]], the paragraph will be treated as a list item.
 * @beta
 */
export declare class Paragraph extends TextBlockComponent {
    readonly type = "paragraph";
    readonly children: Array<List | Run>;
    private constructor();
    /** Create a paragraph from its JSON representation. */
    static create(props?: Omit<ParagraphProps, "type">): Paragraph;
    clearStyleOverrides(options?: ClearTextStyleOptions): void;
    get isEmpty(): boolean;
    clone(): Paragraph;
    toJSON(): ParagraphProps;
    /** Compute a string representation of this paragraph by concatenating the string representations of all of its children. */
    stringify(options?: TextBlockStringifyOptions, context?: TextBlockStringifyContext): string;
    equals(other: TextBlockComponent): boolean;
}
/** JSON representation of a [[List]].
 * @beta
 */
export interface ListProps extends TextBlockComponentProps {
    readonly type: "list";
    children?: ParagraphProps[];
}
/** A collection of list items ([[Paragraph]]s). Lists can be appended to [[Paragraph]]s.
 * Lists will be laid out on a new line. Each item in a list is laid out on a separate line.
 * @beta
 */
export declare class List extends TextBlockComponent {
    readonly type = "list";
    readonly children: Paragraph[];
    protected constructor(props?: ListProps);
    /** Create a list from its JSON representation. */
    static create(props?: Omit<ListProps, "type">): List;
    clearStyleOverrides(options?: ClearTextStyleOptions): void;
    get isEmpty(): boolean;
    clone(): List;
    toJSON(): ListProps;
    /** Compute a string representation of this list by concatenating the string representations of all of its [[children]]. */
    stringify(options?: TextBlockStringifyOptions, context?: TextBlockStringifyContext): string;
    equals(other: TextBlockComponent): boolean;
}
/** JSON representation of a [[TextBlock]].
 * @beta
 */
export interface TextBlockProps extends TextBlockComponentProps {
    /** The width of the document in meters. Lines that would exceed this width are instead wrapped around to the next line if possible.
     * A value less than or equal to zero indicates no wrapping is to be applied.
     * Default: 0
     */
    width?: number;
    children?: ParagraphProps[];
}
/** Represents a formatted text document consisting of a series of [[Paragraph]]s, each laid out on a separate line and containing their own content.
 * No word-wrapping is applied to the document unless a [[width]] greater than zero is specified.
 * @see [[TextAnnotation]] to position a text block as an annotation in 2d or 3d space.
 * @beta
 */
export declare class TextBlock extends TextBlockComponent {
    readonly children: Paragraph[];
    /** The width of the document in meters. Lines that would exceed this width are instead wrapped around to the next line if possible.
     * A value less than or equal to zero indicates no wrapping is to be applied.
     * Default: 0
     */
    width: number;
    private constructor();
    clearStyleOverrides(options?: ClearTextStyleOptions): void;
    toJSON(): TextBlockProps;
    /** Create a text block from its JSON representation. */
    static create(props?: Omit<TextBlockProps, "type">): TextBlock;
    /** Returns true if every paragraph in this text block is empty. */
    get isEmpty(): boolean;
    clone(): TextBlock;
    /** Compute a string representation of the document's contents by concatenating the string representations of each of its [[children]], separated by [[TextBlockStringifyOptions.paragraphBreak]]. */
    stringify(options?: TextBlockStringifyOptions): string;
    /** Add and return a new paragraph.
     * By default, the paragraph will be created with no [[styleOverrides]], so that it inherits the style of this block.
     * @param seedFromLast If true and [[children]] is not empty, the new paragraph will inherit the style overrides of the last child in this block.
     * @note Be sure you pass in [[ParagraphProps]] and not [[Paragraph]] or style overrides will be ignored.
     */
    appendParagraph(props?: ParagraphProps, seedFromLast?: boolean): Paragraph;
    /** Append a run to the last [[Paragraph]] in this block.
     * If the block contains no [[children]], a new [[Paragraph]] will first be created using [[appendParagraph]].
     */
    appendRun(run: Run): void;
    equals(other: TextBlockComponent): boolean;
}
/**
 * A union of all the [[TextBlockComponent]]s that can contain other components.
 * @beta
 */
export type StructuralTextBlockComponent = List | Paragraph | TextBlock;
/**
 * Recursively traverses a [[StructuralTextBlockComponent]] tree, yielding each child component along with its parent container.
 * This generator enables depth-first iteration over all components in a text block structure, including paragraphs, lists, and runs.
 *
 * @param parent The root container whose children should be traversed.
 * @returns An IterableIterator yielding objects with the child component and its parent container.
 * @beta
 */
export declare function traverseTextBlockComponent(parent: StructuralTextBlockComponent): IterableIterator<{
    parent: StructuralTextBlockComponent;
    child: List | Paragraph | Run;
}>;
/**
 * Returns the formatted marker text for a list item based on the marker type and item number.
 * Supports ordered and unordered list markers, including alphabetic, Roman numeral, and numeric formats.
 * @param marker The type of list marker to use.
 * @param num The item number in the list.
 * @returns The formatted marker string for the list item.
 * @beta
 */
export declare function getMarkerText(marker: ListMarker, num: number): string;
//# sourceMappingURL=TextBlock.d.ts.map