@itwin/core-common

/** @packageDocumentation * @module Annotation */ import { Id64String } from "@itwin/core-bentley"; import { TextStyleSettingsProps } from "./TextStyle"; /** 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; } /** Abstract representation of any of the building blocks that make up a [[TextBlock]] document - namely [[Run]]s, [[Paragraph]]s, and [[TextBlock]] itself. * 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) specified by `styleId` on the [[TextBlock]]. * 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. */ 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): string; /** * 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]], 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 [[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; /** 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 [[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; /** * 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; } /** A chain of property accesses that resolves to a primitive value that forms the basis of the displayed content * of a [[FieldRun]]. * The simplest property paths consist of a [[propertyName]] and nothing else, where `propertyName` identifies * a primitive property. * If `propertyName` identifies a struct or array property, then additional [[accessors]] are required to identify the specific value. * If `propertyName` (including any [[accessors]]) resolves to a JSON property, then additional [[jsonAccessors]] are required to identify a specific value within the JSON. * Some examples: * ``` * | Access String | propertyName | accessors | jsonAccessors | * | ------------- | ------------ | --------- | ------------- | * | name | "name" | undefined | undefined | * | spouse.name | "spouse" | [name] | undefined | * | colors[2] | "colors" | [2] | undefined | * | spouse.favoriteRestaurants[1].address | "spouse" | ["favoriteRestaurants", 1, "address"] | undefined | * | jsonProperties.contactInfo.email | "jsonProperties" | undefined | ["contactInfo", "email"] | * | spouse.jsonProperties.contactInfo.phoneNumbers[0].areaCode | "spouse" | ["jsonProperties"] | ["contactInfo", "phoneNumbers", 0, "areaCode"] | * ``` * @beta */ export interface FieldPropertyPath { /** The name of the BIS property of the [[FieldPropertyHost]] that serves as the root of the path. */ propertyName: string; /** Property names and/or array indices describing the path from [[propertyName]] to the ultimate BIS property. */ accessors?: Array<string | number>; /** If [[propertyName]] and [[accessors]] (if defined) resolve to a BIS property of extended type `Json`, property names and/or * array indices for selecting a primitive value within the JSON. */ jsonAccessors?: Array<string | number>; } /** Describes the source of the property value against which a [[FieldPropertyPath]] is evaluated. * A field property is always hosted by an [Element]($backend). It may be a property of the element's BIS class itself, * or that of one of its [ElementAspect]($backend)s. * The [[schemaName]] and [[className]] should always identify the exact class that contains [[FieldPropertyPath.propertyName]] - not a subclass thereof. * @beta */ export interface FieldPropertyHost { /** The Id of the [Element]($backend) that hosts the property. */ elementId: Id64String; /** The name of the schema containing the class identified by [[className]]. */ schemaName: string; /** The name of the exact class (not a subclass) containing the property identified by [[FieldPropertyPath.propertyName]]. */ className: string; } /** Placeholder type for a description of how to format the raw property value resolved by a [[FieldPropertyPath]] into a [[FieldRun]]'s display string. * *** COMING SOON *** * @beta */ export interface FieldFormatter { [k: string]: any; } /** 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]]. */ formatter?: FieldFormatter; /** The field's most recently evaluated display string. */ 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, 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]]. */ readonly propertyHost: Readonly<FieldPropertyHost>; /** Describes how to obtain the property value from [[propertyHost]]. */ readonly propertyPath: Readonly<FieldPropertyPath>; /** Specifies how to format the property value obtained from [[propertyPath]] into a string to be stored in [[cachedContent]]. */ readonly formatter?: FieldFormatter; 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; /** 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 { /** 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; /** * Clears any [[styleOverrides]] applied to this Paragraph. * Will also clear [[styleOverrides]] from all child components unless [[ClearTextStyleOptions.preserveChildrenOverrides]] is `true`. */ clearStyleOverrides(options?: ClearTextStyleOptions): 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 ID of an [AnnotationTextStyle]($backend) stored in the iModel from which the base [[TextStyleSettings]] applied to the [[TextBlock]] originates. */ styleId: Id64String; /** 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 ID of the [AnnotationTextStyle]($backend) that provides the base formatting for the contents of this TextBlock. * @note Assigning to this property retains all style overrides on the TextBlock and its child components. * Call [[clearStyleOverrides]] to clear the TextBlock's and optionally all children's style overrides. */ styleId: Id64String; /** 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 [[styleId]]. */ static createEmpty(): TextBlock; /** Returns true if every paragraph in this text block is empty. */ get isEmpty(): boolean; clone(): TextBlock; /** * Clears any [[styleOverrides]] applied to this TextBlock. * Will also clear [[styleOverrides]] from all child components unless [[ClearTextStyleOptions.preserveChildrenOverrides]] is `true`. */ clearStyleOverrides(options?: ClearTextStyleOptions): 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. * By default, the paragraph will be created with no [[styleOverrides]], so that it inherits the style of this block. * @param seedFromLast If true and [[paragraphs]] is not empty, the new paragraph will inherit the style overrides of the last [[Paragraph]] in this block. */ appendParagraph(seedFromLast?: boolean): 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