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

iTwin.js components common to frontend and backend

/** @packageDocumentation
 * @module Annotation
 */
import { TextStyleSettingsProps } from "./TextStyle";
/** Options supplied to [[TextBlockComponent.applyStyle]] to control how the style is applied to the component and its child components.
 * @beta
 */
export interface ApplyTextStyleOptions {
    /** Controls whether any deviations from the style's settings stored in [[TextBlockComponent.styleOverrides]] are retained.
     * By default, all overrides are cleared.
     */
    preserveOverrides?: boolean;
    /** Controls whether the style should be recursively applied to the [[Paragraph]]s belonging to a [[TextBlock]] and the [[Run]]s belonging to a [[Paragraph]].
     * By default, the style change propagates to child components.
     */
    preventPropagation?: boolean;
}
/** The JSON representation of a [[TextBlockComponent]].
 * @beta
 */
export interface TextBlockComponentProps {
    /** The name of a [[TextStyle]] stored in a [Workspace]($backend) from which the base [[TextStyleSettings]] applied to the component originates. */
    styleName: string;
    /** Deviations from the base [[TextStyleSettings]] defined by the [[TextStyle]] applied to this component.
     * This permits you to, e.g., create a [[TextRun]] using "Arial" font and override it 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;
}
/** Abstract representation of any of the building blocks that make up a [[TextBlock]] document - namely [[Run]]s, [[Paragraph]]s, and [[TextBlock]] itself.
 * Each component can specify a [[TextStyle]] that formats its contents and optional [[styleOverrides]] to customize that formatting.
 * @beta
 */
export declare abstract class TextBlockComponent {
    private _styleName;
    private _styleOverrides;
    /** @internal */
    protected constructor(props: TextBlockComponentProps);
    /** The name of the [[TextStyle]] that provides the base formatting for the contents of this component.
     * @note Assigning to this property is equivalent to calling [[applyStyle]] with default [[ApplyTextStyleOptions]], which propagates the style change to all of
     * the components sub-components and clears any [[styleOverrides]].
     */
    get styleName(): string;
    set styleName(styleName: string);
    /** Deviations in individual properties of the [[TextStyle]] specified by [[styleName]].
     * For example, if the style uses the "Arial" font, you can override that by settings `styleOverrides.fontName` 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's [[TextStyle]]. */
    clearStyleOverrides(): void;
    /** Apply the [[TextStyle]] specified by `styleName` to this component, optionally preserving [[styleOverrides]] and/or preventing propagation to sub-components. */
    applyStyle(styleName: string, options?: ApplyTextStyleOptions): void;
    /** Returns true if [[styleOverrides]] specifies any deviations from this component's base [[TextStyle]]. */
    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): string;
    /** Convert this component to its JSON representation. */
    toJSON(): TextBlockComponentProps;
    /** Returns true if `this` is equivalent to `other`. */
    equals(other: TextBlockComponent): boolean;
}
/**
 * @beta
 */
export type Run = TextRun | FractionRun | LineBreakRun;
/** The JSON representation of a [[Run]].
 * Use the `type` field to discriminate between the different kinds of runs.
 * @beta
 */
export type RunProps = TextRunProps | FractionRunProps | LineBreakRunProps;
/** 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]], 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;
    /** 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 [[TextStyle.stackedFractionType]]. Default: an empty string. */
    numerator?: string;
    /** The text displayed after or below the fraction separator, depending on [[TextStyle.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;
    /** 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: TextBlockComponentProps): LineBreakRun;
    clone(): LineBreakRun;
    /** Simply returns [[TextBlockStringifyOptions.lineBreak]]. */
    stringify(options?: TextBlockStringifyOptions): string;
    equals(other: TextBlockComponent): boolean;
}
/** JSON representation of a [[Paragraph]].
 * @beta
 */
export interface ParagraphProps extends TextBlockComponentProps {
    /** The collection of [[Run]]s within the paragraph.
     * Default: an empty array.
     */
    runs?: RunProps[];
}
/** A collection of [[Run]]s within a [[TextBlock]]. Each paragraph within a text block is laid out on a separate line.
 * @beta
 */
export declare class Paragraph extends TextBlockComponent {
    /** The runs within the paragraph. You can modify the contents of this array to change the content of the paragraph. */
    readonly runs: Run[];
    private constructor();
    toJSON(): ParagraphProps;
    /** Create a paragraph from its JSON representation. */
    static create(props: ParagraphProps): Paragraph;
    clone(): Paragraph;
    /** Apply the specified style to this [[Paragraph]], and - unless [[ApplyTextStyleOptions.preventPropagation]] is `true` - to all of its [[runs]]. */
    applyStyle(styleName: string, options?: ApplyTextStyleOptions): void;
    /** Compute a string representation of this paragraph by concatenating the string representations of all of its [[runs]]. */
    stringify(options?: TextBlockStringifyOptions): string;
    equals(other: TextBlockComponent): boolean;
}
/** Describes the relative alignment of the content of a [[TextBlock]].
 * @beta
 */
export type TextBlockJustification = "left" | "center" | "right";
/** Describes the margins around the content inside a [[TextBlock]]. It's measured in meters.
 * @beta
 */
export interface TextBlockMargins {
    /** The left margin measured in meters. Must be a positive number >= 0. Negative values are disregarded */
    left: number;
    /** The right margin measured in meters. Must be a positive number >= 0. Negative values are disregarded */
    right: number;
    /** The top margin measured in meters. Must be a positive number >= 0. Negative values are disregarded */
    top: number;
    /** The bottom margin measured in meters. Must be a positive number >= 0. Negative values are disregarded */
    bottom: number;
}
/** 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;
    /** The alignment of the document content. Default: "left". */
    justification?: TextBlockJustification;
    /** The margins to surround the document content. Default: 0 margins on all sides */
    margins?: Partial<TextBlockMargins>;
    /** The paragraphs within the text block. Default: an empty array. */
    paragraphs?: 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 in the form of [[Run]]s.
 * You can change the content of the document by directly modifying the contents of its [[paragraphs]], or via [[appendParagraph]] and [[appendRun]].
 * 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 {
    /** 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;
    /** The alignment of the document's content. */
    justification: TextBlockJustification;
    /** The margins of the document. */
    margins: TextBlockMargins;
    /** The ordered list of paragraphs within the document. */
    readonly paragraphs: Paragraph[];
    private constructor();
    toJSON(): TextBlockProps;
    /** Create a text block from its JSON representation. */
    static create(props: TextBlockProps): TextBlock;
    /** Create an empty text block containing no [[paragraphs]] and an empty [[styleName]]. */
    static createEmpty(): TextBlock;
    /** Returns true if every paragraph in this text block is empty. */
    get isEmpty(): boolean;
    clone(): TextBlock;
    /** Apply the specified style to this block and - unless [[ApplyTextStyleOptions.preventPropagation]] is `true` - to all of its [[paragraphs]]. */
    applyStyle(styleName: string, options?: ApplyTextStyleOptions): void;
    /** Compute a string representation of the document's contents by concatenating the string representations of each of its [[paragraphs]], separated by [[TextBlockStringifyOptions.paragraphBreak]]. */
    stringify(options?: TextBlockStringifyOptions): string;
    /** Add and return a new paragraph.
     * If [[paragraphs]] is not empty, the style and overrides of the last [[Paragraph]] in the block will be applied to the new paragraph; otherwise,
     * the paragraph will inherit this block's style with no overrides.
     */
    appendParagraph(): Paragraph;
    /** Append a run to the last [[Paragraph]] in this block.
     * If the block contains no [[paragraphs]], a new one will first be created using [[appendParagraph]].
     */
    appendRun(run: Run): void;
    equals(other: TextBlockComponent): boolean;
}
//# sourceMappingURL=TextBlock.d.ts.map