@itwin/core-common
Version:
iTwin.js components common to frontend and backend
110 lines • 6.1 kB
TypeScript
/** @packageDocumentation
* @module Annotation
*/
import { Point3d, Range2d, Transform, XYZProps, YawPitchRollAngles, YawPitchRollProps } from "@itwin/core-geometry";
import { TextBlock, TextBlockProps } from "./TextBlock";
/** Describes how to compute the "anchor point" for a [[TextAnnotation]].
* The anchor point is a point on or inside of the 2d bounding box enclosing the contents of the annotation's [[TextBlock]].
* The annotation can be rotated and translated relative to the anchor point. The anchor point also serves as the snap point
* when [AccuSnap]($frontend) is set to [SnapMode.Origin]($frontend).
* [[TextAnnotation.computeTransform]] will align the anchor point with (0, 0).
* @see [[TextAnnotation]] for a description of how the anchor point is computed.
* @beta
*/
export interface TextAnnotationAnchor {
/**
* The vertical alignment of the anchor point.
* "top" aligns the anchor point with the top of the text's bounding box.
* "middle" aligns the anchor point with the middle of the text's bounding box.
* "bottom" aligns the anchor point with the bottom of the text's bounding box.
*/
vertical: "top" | "middle" | "bottom";
/**
* The horizontal alignment of the anchor point.
* "left" aligns the anchor point with left side of the text's bounding box.
* "center" aligns the anchor point with center of the text with's bounding box.
* "right" aligns the anchor point with right side of the text's bounding box.
*/
horizontal: "left" | "center" | "right";
}
/**
* JSON representation of a [[TextAnnotation]].
* @beta
*/
export interface TextAnnotationProps {
/** See [[TextAnnotation.offset]]. Default: [0, 0, 0]. */
offset?: XYZProps;
/** See [[TextAnnotation.orientation]]. Default: no rotation. */
orientation?: YawPitchRollProps;
/** See [[TextAnnotation.textBlock]]. Default: an empty text block. */
textBlock?: TextBlockProps;
/** See [[TextAnnotation.anchor]]. Default: top-left. */
anchor?: TextAnnotationAnchor;
}
/** Arguments supplied to [[TextAnnotation.create]].
* @beta
*/
export interface TextAnnotationCreateArgs {
/** See [[TextAnnotation.offset]]. Default: (0, 0, 0). */
offset?: Point3d;
/** See [[TextAnnotation.orientation]]. Default: no rotation. */
orientation?: YawPitchRollAngles;
/** See [[TextAnnotation.textBlock]]. Default: an empty text block. */
textBlock?: TextBlock;
/** See [[TextAnnotation.anchor]]. Default: top-left. */
anchor?: TextAnnotationAnchor;
}
/**
* Represents a formatted block of text positioned in 2d or 3d space.
* [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a single TextAnnotation from which their geometric representation is generated.
* Other types of elements may store multiple TextAnnotations, positioned relative to one another.
* The annotation's position and orientation relative to the host element's [Placement]($common) is determined as follows:
* - First, a bounding box is computed enclosing the contents of the [[textBlock].
* - Then, an "anchor point" is computed based on the bounding box and the [[anchor]] property. The anchor point can be at one of the four corners of the box, in the middle of one of its four
* edges, or in the center of the box.
* - The [[orientation]] is applied to rotate the box around the anchor point.
* - Finally, the [[offset]] is added to the anchor point to apply translation.
* @see [produceTextAnnotationGeometry]($backend) to decompose the annotation into a set of geometric primitives suitable for use with [[GeometryStreamBuilder.appendTextBlock]].
* @beta
*/
export declare class TextAnnotation {
/** The rotation of the annotation.
* @note When defining an annotation for a [TextAnnotation2d]($backend), only the `yaw` component (rotation around the Z axis) is used.
*/
orientation: YawPitchRollAngles;
/** The formatted document. */
textBlock: TextBlock;
/** Describes how to compute the [[textBlock]]'s anchor point. */
anchor: TextAnnotationAnchor;
/** An offset applied to the anchor point that can be used to position annotations within the same geometry stream relative to one another. */
offset: Point3d;
private constructor();
/** Creates a new TextAnnotation. */
static create(args?: TextAnnotationCreateArgs): TextAnnotation;
/**
* Creates a new TextAnnotation instance from its JSON representation.
*/
static fromJSON(props: TextAnnotationProps | undefined): TextAnnotation;
/**
* Converts this annotation to its JSON representation.
*/
toJSON(): TextAnnotationProps;
/** Compute the transform that positions and orients this annotation relative to its anchor point, based on the [[textBlock]]'s computed bounding box.
* The anchor point is computed as specified by this annotation's [[anchor]] setting. For example, if the text block is anchored
* at the bottom left, then the transform will be relative to the bottom-left corner of `textBlockExtents`.
* The text block will be rotated around the fixed anchor point according to [[orientation]], then translated by [[offset]].
* The anchor point will coincide with (0, 0, 0) unless an [[offset]] is present.
* @param boundingBox A box fully containing the [[textBlock]]. This range should include the margins.
* @see [[computeAnchorPoint]] to compute the transform's anchor point.
* @see [computeLayoutTextBlockResult]($backend) to lay out a `TextBlock`.
*/
computeTransform(boundingBox: Range2d): Transform;
/** Compute the anchor point of this annotation as specified by [[anchor]].
* @param boundingBox A box fully containing the [[textBlock]].
* @see [[computeTransform]] to compute the transform relative to the anchor point.
*/
computeAnchorPoint(boundingBox: Range2d): Point3d;
/** Returns true if this annotation is logically equivalent to `other`. */
equals(other: TextAnnotation): boolean;
}
//# sourceMappingURL=TextAnnotation.d.ts.map