@itwin/core-common

/** @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