@itwin/core-frontend/lib/esm/Marker.d.ts

iTwin.js frontend components

/** @packageDocumentation
 * @module Views
 */
import { Matrix4d, Point2d, Point3d, Range1d, Range1dProps, XAndY, XYAndZ } from "@itwin/core-geometry";
import { ColorDef } from "@itwin/core-common";
import { ViewRect } from "./common/ViewRect";
import { ToolTipOptions } from "./NotificationManager";
import { CanvasDecoration } from "./render/CanvasDecoration";
import { BeButtonEvent } from "./tools/Tool";
import { DecorateContext } from "./ViewContext";
import { ScreenViewport, Viewport } from "./Viewport";
/** The types that may be used for Markers
 * @public
 * @extensions
 */
export type MarkerImage = HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageBitmap;
/**
 * @public
 * @extensions
 */
export type MarkerFillStyle = string | CanvasGradient | CanvasPattern;
/**
 * @public
 * @extensions
 */
export type MarkerTextAlign = "left" | "right" | "center" | "start" | "end";
/**
 * @public
 * @extensions
 */
export type MarkerTextBaseline = "top" | "hanging" | "middle" | "alphabetic" | "ideographic" | "bottom";
/** A Marker is a [[CanvasDecoration]], whose position follows a fixed location in world space.
 * Markers draw on top of all scene graphics, and show visual cues about locations of interest.
 * @see [Markers]($docs/learning/frontend/Markers)
 * @public
 * @extensions
 */
export declare class Marker implements CanvasDecoration {
    protected _scaleFactor?: Point2d;
    protected _scaleFactorRange?: Range1d;
    /** Whether this marker is currently enabled. If false, this Marker is not displayed. */
    visible: boolean;
    /** Whether this marker is currently hilited or not. */
    protected _isHilited: boolean;
    /** The color for the shadowBlur when this Marker is hilited */
    protected _hiliteColor?: ColorDef;
    /** The location of this Marker in world coordinates. */
    worldLocation: Point3d;
    /** The size of this Marker, in pixels. */
    size: Point2d;
    /** The current position for the marker, in view coordinates (pixels). This value will be updated by calls to [[setPosition]]. */
    position: Point3d;
    /** The current rectangle for the marker, in view coordinates (pixels). This value will be updated by calls to [[setPosition]]. */
    readonly rect: ViewRect;
    /** An image to draw for this Marker. If undefined, no image is shown. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage.  */
    image?: MarkerImage;
    /** The offset for [[image]], in pixels, from the *center* of this Marker. If undefined, (0,0). */
    imageOffset?: XAndY;
    /** The size of [[image]], in pixels. If undefined, use [[size]]. */
    imageSize?: XAndY;
    /** A text Label for this Marker. If undefined, no label is displayed. */
    label?: string;
    /** The offset for [[label]], in pixels, from the *center* of this Marker. If undefined, (0,0). */
    labelOffset?: XAndY;
    /** The maximum with for [[label]], in pixels. If undefined label will not be condensed or use a smaller font size. */
    labelMaxWidth?: number;
    /** The color for [[label]]. See  https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/fillStyle. If undefined, "white". */
    labelColor?: MarkerFillStyle;
    /** The text alignment for [[label]]. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign. If undefined, "center" */
    labelAlign?: MarkerTextAlign;
    /** The text baseline for [[label]]. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline. If undefined, "middle" */
    labelBaseline?: MarkerTextBaseline;
    /** The font for [[label]]. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/font. */
    labelFont?: string;
    /** The title string, or HTMLElement, to show (only) in the ToolTip when the pointer is over this Marker. See [[NotificationManager.openToolTip]] */
    title?: HTMLElement | string;
    /** The ToolTipOptions to use for [[title]]. */
    tooltipOptions?: ToolTipOptions;
    /** An Optional (unique) HTMLElement to display with this Marker. Generally, HTMLElements are more expensive than
     * images and labels, since they are added/removed from the DOM every frame. But, some types of markers are more convenient to construct
     * as HTMLElements, and if there aren't too many of them performance is fine.
     * @note HTMLElements may only appear in the DOM one time. Therefore, they *may not be shared* by more than one Marker.
     * You must ensure that each marker has its own HTMLElement. For this reason, you should probably only use HTMLElements in Markers if
     * each one is meant to be unique. For shared content, use images.
     */
    htmlElement?: HTMLElement;
    /** Return true to display [[image]], if present. */
    get wantImage(): boolean;
    /** Implement this function to draw onto the CanvasRenderingContext2D when this Marker is displayed. The [0,0] point will be the center of the Marker. */
    drawFunc?(ctx: CanvasRenderingContext2D): void;
    /** Called when the mouse pointer enters this Marker. */
    onMouseEnter(ev: BeButtonEvent): void;
    /** Called when the mouse pointer leaves this Marker. */
    onMouseLeave(): void;
    /** Called when the mouse pointer moves over this Marker */
    onMouseMove(ev: BeButtonEvent): void;
    /** Called when a mouse button is pressed over this Marker. */
    onMouseButton?(_ev: BeButtonEvent): boolean;
    /** Determine whether the point is within this Marker.  */
    pick(pt: XAndY): boolean;
    /** Establish a range of scale factors to increases and decrease the size of this Marker based on its distance from the camera.
     * @param range The minimum and maximum scale factors to be applied to the size of this Marker based on its distance from the camera. `range.Low` is the scale factor
     * for Markers at the back of the view frustum and `range.high` is the scale factor at the front of the view frustum.
     * @note Marker size scaling is only applied in views with the camera enabled. It has no effect on orthographic views.
     */
    setScaleFactor(range: Range1dProps): void;
    /** Constructor for Marker
     * @param worldLocation The location of this Marker in world coordinates.
     * @param size The size of this Marker in pixels.
     */
    constructor(worldLocation: XYAndZ, size: XAndY);
    /** Make a new Marker at the same position and size as this Marker.
     * The new Marker will share the world location and size, but will be otherwise blank.
     */
    static makeFrom<T extends Marker>(other: Marker, ...args: any[]): T;
    /** When a Marker is displayed in its hilited state, this method is called first. If it returns true, no further action is taken.
     * Otherwise the Marker's normal drawing operations are also called. By default, this method adds a shadowBlur effect and increases
     * the size of the Marker by 25%.
     * @return true to stop drawing this Marker
     */
    protected drawHilited(ctx: CanvasRenderingContext2D): boolean;
    /** Called during frame rendering to display this Marker onto the supplied context. */
    drawDecoration(ctx: CanvasRenderingContext2D): void;
    /** Set the [[image]] for this marker.
     * @param image Either a [[MarkerImage]] or a Promise for a [[MarkerImage]]. If a Promise is supplied, the [[image]] member is set
     * when the Promise resolves.
     */
    setImage(image: MarkerImage | Promise<MarkerImage>): void;
    /** Set the image for this Marker from a URL. */
    setImageUrl(url: string): void;
    /** Set the position (in pixels) for this Marker in the supplied Viewport, based on its worldLocation.
     * @param markerSet The MarkerSet if this Marker is included in a set.
     * @return true if the Marker is visible and its new position is inside the Viewport.
     */
    setPosition(vp: Viewport, markerSet?: MarkerSet<Marker>): boolean;
    /** Position the HTMLElement for this Marker relative to the Marker's position in the view.
     * The default implementation centers the HTMLElement (using its boundingClientRect) on the Marker.
     * Override this method to provide an alternative positioning approach.
     */
    protected positionHtml(): void;
    /** Add this Marker to the supplied DecorateContext. */
    addMarker(context: DecorateContext): void;
    /** Set the position and add this Marker to the supplied DecorateContext, if it's visible.
     * This method should be called from your implementation of [[Decorator.decorate]]. It will set this Marker's position based on the
     * Viewport from the context, and add this this Marker to the supplied DecorateContext.
     * @param context The DecorateContext for the Marker
     */
    addDecoration(context: DecorateContext): void;
}
/** A cluster of one or more Markers that overlap one another in the view. The cluster's screen position is taken from its first entry.
 * Clusters also have a Marker themselves, that represents the whole group. The cluster marker isn't created until all entries have been added.
 * @public
 * @extensions
 */
export declare class Cluster<T extends Marker> {
    readonly markers: T[];
    clusterMarker?: Marker;
    constructor(markers: T[]);
    get position(): Point3d;
    /**
     * Gets the location for the cluster
     * @returns The average of the cluster markers worldLocation.
     */
    getClusterLocation(): Point3d;
}
/** A *set* of Markers that are logically related, such that they *cluster* when they overlap one another in screen space.
 * In that case, a *cluster marker* is drawn instead of the overlapping Markers.
 * @public
 * @extensions
 */
export declare abstract class MarkerSet<T extends Marker> {
    private _viewport?;
    /** @internal */
    protected _entries: Array<T | Cluster<T>>;
    /** @internal */
    protected readonly _worldToViewMap: Matrix4d;
    /** @internal */
    protected _minScaleViewW?: number;
    private readonly _markers;
    /** The minimum number of Markers that must overlap before they are clustered. Otherwise they are each drawn individually. Default is 1 (always create a cluster.) */
    minimumClusterSize: number;
    /** The set of Markers in this MarkerSet. Add your [[Marker]]s into this. */
    get markers(): Set<T>;
    /** The radius (in pixels) representing the distance between the screen X,Y positions of two Markers to be clustered. When less than or equal to 0 (the default), the radius is calculated based on the first visible marker imageSize/size. */
    protected clusterRadius: number;
    /** Construct a new MarkerSet for a specific ScreenViewport.
     * @param viewport the ScreenViewport for this MarkerSet. If undefined, use [[IModelApp.viewManager.selectedView]]
     */
    constructor(viewport?: ScreenViewport);
    /** The ScreenViewport of this MarkerSet. */
    get viewport(): ScreenViewport | undefined;
    /** Change the ScreenViewport for this MarkerSet.
     * After this call, the markers from this MarkerSet will only appear in the supplied ScreenViewport.
     * @beta
     */
    changeViewport(viewport: ScreenViewport): void;
    /** Indicate that this MarkerSet has been changed and is now *dirty*.
     * This is necessary because [[addDecoration]] does not recreate the set of decoration graphics
     * if it can detect that the previously-created set remains valid.
     * The set becomes invalid when the view frustum changes, or the contents of [[markers]] changes.
     * If some other criterion affecting the graphics changes, invoke this method. This should not be necessary for most use cases.
     * @public
     */
    markDirty(): void;
    /** Implement this method to create a new Marker that is shown as a *stand-in* for a Cluster of Markers that overlap one another.
     * @param cluster The [[Cluster]] that the new Marker will represent.
     * @returns The Marker that will be displayed to represent the Cluster.
     * @note You must create a new Marker each time this method is called.
     */
    protected abstract getClusterMarker(cluster: Cluster<T>): Marker;
    /** Get weight value limit establishing the distance from camera for the back of view scale factor. */
    getMinScaleViewW(vp: Viewport): number;
    /** This method should be called from [[Decorator.decorate]]. It will add this this MarkerSet to the supplied DecorateContext.
     * This method implements the logic that turns overlapping Markers into a Cluster.
     * @param context The DecorateContext for the Markers
     */
    addDecoration(context: DecorateContext): void;
}
//# sourceMappingURL=Marker.d.ts.map