@itwin/core-common

/** @packageDocumentation * @module Annotation */ import { DeepReadonlyObject, DeepRequiredObject } from "@itwin/core-bentley"; import { ColorDefProps } from "../ColorDef"; import { FontFamilySelector } from "../Fonts"; /** Predefined markers for list items in text annotations. * These values control the appearance of list item markers (e.g., bullet, circle, square, dash, number) that denote the start of a list item in a list. * @beta */ export declare enum ListMarkerEnumerator { /** English Alphabet */ Letter = "A", RomanNumeral = "I", Number = "1", Bullet = "\u2022", Circle = "\u25CB", Square = "\u25A0", /** EM Dash */ Dash = "\u2013" } /** A settings to specify how to mark or denote the start of a list item in a [[List]]. * @beta */ export interface ListMarker { /** This can be either one of the predefined markers in [[ListMarkerEnumerator]], or any arbitrary string. */ enumerator: ListMarkerEnumerator | string; /** The punctuation to follow the enumerator. */ terminator?: "parenthesis" | "period"; /** Whether to use upper or lower case for alphabetic or roman numeral enumerators. Ignored if [[enumerator]] is not alphabetic or roman numeral. */ case?: "upper" | "lower"; } /** Set of predefined shapes that can be computed and drawn around the margins of a [[TextBlock]] * @beta */ export declare const textAnnotationFrameShapes: readonly ["none", "line", "rectangle", "circle", "equilateralTriangle", "diamond", "square", "pentagon", "hexagon", "octagon", "capsule", "roundedRectangle"]; /** Describes a predefined shape that can be computed and drawn around the margins of a [[TextBlock]] * @beta */ export type TextAnnotationFrameShape = typeof textAnnotationFrameShapes[number]; /** Set of predefined shapes that can be used as terminators for leaders in a [[TextAnnotation]] * @beta */ export declare const terminatorShapes: readonly ["openArrow", "closedArrow", "closedArrowFilled", "circle", "circleFilled", "slash", "none"]; /** Describes a predefined shape that can be used as a terminator for leaders in a [[TextAnnotation]] * @beta */ export type TerminatorShape = typeof terminatorShapes[number]; /** * Describes what color to use when filling the frame around a [[TextBlock]]. * If `background` is specified, [[GeometryParams.BackgroundFill]] will be set to `BackgroundFill.Outline`. * If `none` is specified, no fill will be applied. * @beta */ export type TextAnnotationFillColor = TextStyleColor | "background" | "none"; /** Describes the margins around the content inside a [[TextBlock]], measured in meters. * All margins default to zero if `undefined`. * @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; } /** Describes the relative alignment of text. * @beta */ export type TextJustification = "left" | "center" | "right"; /** Specifies how to separate the numerator and denominator of a [[FractionRun]], by either a horizontal or diagonal bar. * @see [[TextStyleSettingsProps.stackedFractionType]] and [[TextStyleSettings.stackedFractionType]]. * @beta */ export type StackedFractionType = "horizontal" | "diagonal"; /** Describes the color in which to draw the text in a [[TextRun]]. * "subcategory" indicates that the text should be drawn using the color of the [SubCategory]($backend) specified by the [GeometryStream]($docs/learning/common/GeometryStream.md) hosting the * text. * @beta */ export type TextStyleColor = ColorDefProps | "subcategory"; /** * Describes how to draw the frame around a [[TextAnnotation]]. * The frame can be a simple line, a filled shape, or both. * If only a subset of properties are specified, the others will be set to their default value. * @beta */ export interface TextFrameStyleProps { /** Shape of the frame. Default: "none" */ shape?: TextAnnotationFrameShape; /** The color to fill the shape of the text frame. This fill is applied using [[FillDisplay.Blanking]]. Default: "none" */ fillColor?: TextAnnotationFillColor; /** The color of the text frame's outline. Default: black */ borderColor?: TextStyleColor; /** This will be used to set the [[GeometryParams.weight]] property of the frame (in pixels). Default: 1px */ borderWeight?: number; } /** Properties describing the appearance of [[TextAnnotationLeader]] in a [[TextAnnotation]]. * Used when producing geometry for [[TextAnnotation]]. * @beta */ export interface TextLeaderStyleProps { /** The color of the leader. * If `inherit` is specified, the [[TextAnnotationLeader]] will use the color specified in the parent [[TextStyleSettings]]`. * Default: "inherit". */ color?: TextStyleColor | "inherit"; /** Whether to use an elbow in the leader. * Default: false */ wantElbow?: boolean; /** Multiplier used to compute length of the elbow in the leader. * The elbowLength is computed in meters as elbowLength * [[textHeight]]. * Default: 1.0 */ elbowLength?: number; /** * The shape of the leader terminator. * Default:"openArrow" */ terminatorShape?: TerminatorShape; /** Multiplier to compute height of the leader terminator. * The terminator height is computed in meters as terminatorHeight * [[textHeight]]. * Default: 1.0 */ terminatorHeightFactor?: number; /** Multiplier to compute width of the leader terminator. * The terminator width is computed in meters as terminatorWidth * [[textHeight]]. * Default: 1.0 */ terminatorWidthFactor?: number; } /** Serves both as the JSON representation of a [[TextStyleSettings]], and a way for a [[TextBlockComponent]] to selectively override aspects of a [AnnotationTextStyle]($backend)'s properties. * @beta */ export interface TextStyleSettingsProps { /** The color of the text. * Default: "subcategory". */ color?: TextStyleColor; /** The font stored in an iModel, used to draw the contents of a [[TextRun]]. * Default: { name: "" } (an invalid font name). */ font?: FontFamilySelector; /** The height of the text, in meters. Many other settings use the text height as the basis for computing their own values. * For example, the height and offset from baseline of a subscript [[TextRun]] are computed as textHeight * [[subScriptScale]] and * textHeight * [[subScriptOffsetFactor]], respectively. * Default: 1.0. */ textHeight?: number; /** Multiplier used to compute the vertical distance between two lines of text. * The distance is computed in meters as lineSpacingFactor * [[textHeight]]. * Default: 0.5. */ lineSpacingFactor?: number; /** Multiplier used to compute the vertical distance between two paragraphs of text. * The distance is computed in meters as paragraphSpacingFactor * [[textHeight]]. * Default: 0.5. */ paragraphSpacingFactor?: number; /** Specifies whether the content of a [[TextRun]] should be rendered **bold**. * Default: false. */ isBold?: boolean; /** Specifies whether the content of a [[TextRun]] should be rendered in *italics*. * Default: false. */ isItalic?: boolean; /** Specifies whether the content of a [[TextRun]] should be underlined. * Default: false. */ isUnderlined?: boolean; /** Multiplier used to compute the height of both the numerator and denominator of a [[FractionRun]]. * The height is computed in meters as stackedFractionScale * [[textHeight]]. * Default: 0.7. */ stackedFractionScale?: number; /** Specifies how to separate the numerator and denominator of a [[FractionRun]]. * Default: "horizontal". */ stackedFractionType?: StackedFractionType; /** Multiplier used to compute the vertical offset from the baseline for a subscript [[TextRun]]. * The offset is computed in meters as subScriptOffsetFactor * [[textHeight]]. * Default: -0.15. */ subScriptOffsetFactor?: number; /** Multiplier used to compute the height of a subscript [[TextRun]]. * The height is computed as subScriptScale * [[textHeight]]. * Default: 2/3 */ subScriptScale?: number; /** Multiplier used to compute the vertical offset from the baseline for a super [[TextRun]]. * The offset is computed in meters as superScriptOffsetFactor * [[textHeight]]. * Default: -0.5. */ superScriptOffsetFactor?: number; /** Multiplier used to compute the height of a superscript [[TextRun]]. * The height is computed as superScriptScale * [[textHeight]]. * Default: 2/3 */ superScriptScale?: number; /** A scale applied to the width of each glyph. * Default: 1.0 */ widthFactor?: number; /** Properties describing appearance of leaders in a [[TextAnnotation]] * Used when producing geometry for [[TextAnnotation]] * Default: {color:"subcategory", wantElbow:"false",elbowLength:1, terminatorShape:"openArrow",terminatorWidthFactor:1, terminatorHeightFactor:1}. */ leader?: TextLeaderStyleProps; /** The size (in meters) used to calculate the tab stops in a run. * These are equally spaced from the left edge of the TextBlock. * [[tabInterval]] is also used in lists to compute the offset of each child or [[Paragraph]]. * The [[listMarker]] is right justified on [[indentation]] + [[tabInterval]]*(depth - 1/2). * [[Paragraph]]s will start at [[indentation]] + [[tabInterval]]*depth. * Default: 4 meters. */ tabInterval?: number; /** * A description of the frame around the text annotation. * Used when producing geometry for [[TextAnnotation]]s. * Default: {shape: "none", fill: "none", border: black, borderWeight: 1} for no frame. */ frame?: TextFrameStyleProps; /** The margins to surround the document content. * Default: 0 margins on all sides */ margins?: TextBlockMargins; /** The offset (in meters) from the left edge of the text block to the start of the line of text. * In lists, the indentation is added to offset of list items. * The [[listMarker]] is right justified on [[indentation]] + [[tabInterval]]*(depth - 1/2). * [[Paragraph]]s will start at [[indentation]] + [[tabInterval]]*depth. * Default: 0 meters. */ indentation?: number; /** The marker used to indicate the start of a list item. * Default: "1.". */ listMarker?: ListMarker; /** The alignment of the text content. * Default: "left". */ justification?: TextJustification; } /** A description of the formatting to be applied to a [[TextBlockComponent]]. * Named instances of these settings can be stored as [AnnotationTextStyle]($backend)s in an iModel. * @note This is an immutable type. Use [[clone]] to create a modified copy. * @see [[TextStyleSettingsProps]] for documentation of each of the settings. * @beta */ export declare class TextStyleSettings { /** The color of the text. */ readonly color: TextStyleColor; /** The font stored in an iModel, used to draw the contents of a [[TextRun]]. */ readonly font: Readonly<Required<FontFamilySelector>>; /** The height of the text, in meters. Many other settings use the text height as the basis for computing their own values. * For example, the height and offset from baseline of a subscript [[TextRun]] are computed as textHeight * [[subScriptScale]] and * textHeight * [[subScriptOffsetFactor]], respectively. */ readonly textHeight: number; /** Multiplier used to compute the vertical distance between two lines of text. * The distance is computed in meters as lineSpacingFactor * [[textHeight]] of the [[TextBlock]]. */ readonly lineSpacingFactor: number; /** Multiplier used to compute the vertical distance between two paragraphs of text. * The distance is computed in meters as paragraphSpacingFactor * the [[TextBlock]]'s [[textHeight]]. */ readonly paragraphSpacingFactor: number; /** Specifies whether the content of a [[TextRun]] should be rendered **bold**. */ readonly isBold: boolean; /** Specifies whether the content of a [[TextRun]] should be rendered in *italics*. */ readonly isItalic: boolean; /** Specifies whether the content of a [[TextRun]] should be underlined. */ readonly isUnderlined: boolean; /** Multiplier used to compute the height of both the numerator and denominator of a [[FractionRun]]. * The height is computed in meters as stackedFractionScale * [[textHeight]]. */ readonly stackedFractionScale: number; /** Specifies how to separate the numerator and denominator of a [[FractionRun]]. */ readonly stackedFractionType: StackedFractionType; /** Multiplier used to compute the vertical offset from the baseline for a subscript [[TextRun]]. * The offset is computed in meters as subScriptOffsetFactor * [[textHeight]]. */ readonly subScriptOffsetFactor: number; /** Multiplier used to compute the height of a subscript [[TextRun]]. * The height is computed as subScriptScale * [[textHeight]]. */ readonly subScriptScale: number; /** Multiplier used to compute the vertical offset from the baseline for a super [[TextRun]]. * The offset is computed in meters as superScriptOffsetFactor * [[textHeight]]. */ readonly superScriptOffsetFactor: number; /** Multiplier used to compute the height of a superscript [[TextRun]]. * The height is computed as superScriptScale * [[textHeight]]. */ readonly superScriptScale: number; /** Multiplier used to compute the width of each glyph, relative to [[textHeight]]. */ readonly widthFactor: number; /** Properties describing appearance of leaders in a [[TextAnnotation]]. * Used when producing geometry for [[TextAnnotation]]. */ readonly leader: Readonly<Required<TextLeaderStyleProps>>; /** The size (in meters) used to calculate the tab stops in a run. * These are equally spaced from the left edge of the TextBlock. * [[tabInterval]] is also used in lists to compute the offset of each child or [[Paragraph]]. * The [[listMarker]] is right justified on [[indentation]] + [[tabInterval]]*(depth - 1/2). * [[Paragraph]]s will start at [[indentation]] + [[tabInterval]]*depth. */ readonly tabInterval: number; /** The offset (in meters) from the left edge of the text block to the start of the line of text. * In lists, the indentation is added to offset of list items. * The [[listMarker]] is right justified on [[indentation]] + [[tabInterval]]*(depth - 1/2). * [[Paragraph]]s will start at [[indentation]] + [[tabInterval]]*depth. */ readonly indentation: number; /** The marker used to indicate the start of a list item. * Default: [[ListMarkerEnumerator.Number]]. */ readonly listMarker: ListMarker; /** The frame settings of the [[TextAnnotation]]. */ readonly frame: Readonly<Required<TextFrameStyleProps>>; /** The margins to surround the document content. */ readonly margins: Readonly<Required<TextBlockMargins>>; /** The alignment of the text content. */ readonly justification: TextJustification; /** A fully-populated JSON representation of the default settings. A real `font` must be provided before use. */ static defaultProps: DeepReadonlyObject<DeepRequiredObject<TextStyleSettingsProps>>; /** Settings initialized to all default values. */ static defaults: TextStyleSettings; private constructor(); /** Create a copy of these settings, modified according to the properties defined by `alteredProps`. */ clone(alteredProps?: TextStyleSettingsProps): TextStyleSettings; /** Create settings from their JSON representation. */ static fromJSON(props?: TextStyleSettingsProps): TextStyleSettings; toJSON(): TextStyleSettingsProps; /** Compare two [[TextLeaderStyleProps]] for equality. * @param other The other leader style properties to compare against. * @returns true if the two leader styles are equal, false otherwise. */ leaderEquals(other: TextLeaderStyleProps): boolean; frameEquals(other: TextFrameStyleProps): boolean; marginsEqual(other: TextBlockMargins): boolean; equals(other: TextStyleSettings): boolean; /** * Returns a list of validation errors for this instance. * * A TextStyleSettings object may contain values that are invalid in all contexts. * If this method returns any error strings, using the settings will likely result in rendering failures or runtime exceptions. * * This method only checks for universally invalid values. Additional domain-specific validation may be required depending on the context in which these settings are used. * * @returns An array of error strings describing the invalid values, or an empty array if the settings are valid. */ getValidationErrors(): string[]; } //# sourceMappingURL=TextStyle.d.ts.map