fvtt-types/src/foundry/client/canvas/placeables/template.d.mts

TypeScript type definitions for Foundry VTT

import type { FixedInstanceType, HandleEmptyObject } from "#utils";
import type { Canvas } from "#client/canvas/_module.d.mts";
import type { PlaceableObject } from "#client/canvas/placeables/_module.d.mts";
import type { ConfiguredObjectClassOrDefault } from "../../config.d.mts";
import type { PreciseText } from "#client/canvas/containers/_module.mjs";
import { RenderFlagsMixin, RenderFlags, RenderFlag } from "#client/canvas/interaction/_module.mjs";

declare module "#configuration" {
  namespace Hooks {
    interface PlaceableObjectConfig {
      MeasuredTemplate: MeasuredTemplate.Implementation;
    }
  }
}

/**
 * A type of Placeable Object which highlights an area of the grid as covered by some area of effect.
 * @see {@linkcode MeasuredTemplateDocument}
 * @see {@linkcode TemplateLayer}
 */
declare class MeasuredTemplate extends PlaceableObject<MeasuredTemplateDocument.Implementation> {
  /**
   * The geometry shape used for testing point intersection
   * @defaultValue `undefined`
   * @remarks Only `undefined` prior to {@link MeasuredTemplate._refreshShape | `MeasuredTemplate#_refreshShape`} being called
   *
   * @privateRemarks Foundry also types this as `| PIXI.Ellipse | PIXI.RoundedRectangle`, but {@link MeasuredTemplate._computeShape | `MeasuredTemplate#_computeShape`}
   * never returns either in v12
   */
  shape: PIXI.Circle | PIXI.Polygon | PIXI.Rectangle | undefined;

  /**
   * The tiling texture used for this template, if any
   * @defaultValue `undefined`
   * @remarks Only `undefined` prior to first draw. Set `null` if the template's document has no `texture` set
   */
  texture: PIXI.Texture | null | undefined;

  /**
   * The template graphics
   * @defaultValue `undefined`
   * @remarks Only `undefined` prior to first draw.
   */
  template: PIXI.Graphics | undefined;

  /**
   * The measurement ruler label
   * @defaultValue `undefined`
   * @remarks Only `undefined` prior to first draw.
   */
  ruler: PreciseText | undefined;

  /**
   * Internal property used to configure the control border thickness
   * @defaultValue `3`
   */
  protected _borderThickness: number;

  static override embeddedName: "MeasuredTemplate";

  static override RENDER_FLAGS: MeasuredTemplate.RENDER_FLAGS;

  // Note: This isn't a "real" override but `renderFlags` is set corresponding to the
  // `RENDER_FLAGS` and so it has to be adjusted here.
  renderFlags: RenderFlags<MeasuredTemplate.RENDER_FLAGS>;

  /**
   * A convenient reference for whether the current User is the author of the MeasuredTemplate document.
   */
  get isAuthor(): boolean;

  override get bounds(): PIXI.Rectangle;

  /**
   * Is this MeasuredTemplate currently visible on the Canvas?
   */
  get isVisible(): boolean;

  /**
   * A unique identifier which is used to uniquely identify related objects like a template effect or grid highlight.
   */
  get highlightId(): string;

  protected override _draw(options: HandleEmptyObject<MeasuredTemplate.DrawOptions>): Promise<void>;

  protected override _destroy(options: PIXI.IDestroyOptions | boolean | undefined): void;

  // fake override; super has to account for misbehaving siblings returning void
  override clear(): this;

  protected _applyRenderFlags(flags: MeasuredTemplate.RenderFlags): void;

  /**
   * Refresh the displayed state of the MeasuredTemplate.
   * This refresh occurs when the user interaction state changes.
   */
  protected _refreshState(): void;

  /**
   * Refresh the elevation of the control icon.
   */
  protected _refreshElevation(): void;

  protected override _getTargetAlpha(): number;

  /**
   * Refresh the position of the MeasuredTemplate
   */
  protected _refreshPosition(): void;

  /**
   * Refresh the underlying geometric shape of the MeasuredTemplate.
   */
  protected _refreshShape(): void;

  /**
   * Compute the geometry for the template using its document data.
   * Subclasses can override this method to take control over how different shapes are rendered.
   */
  protected _computeShape(): PIXI.Circle | PIXI.Rectangle | PIXI.Polygon;

  /**
   * Refresh the display of the template outline and shape.
   * Subclasses may override this method to take control over how the template is visually rendered.
   */
  protected _refreshTemplate(): void;

  /**
   * Get a Circular area of effect given a radius of effect
   * @param distance - The radius of the circle in grid units
   * @remarks Will return a `PIXI.Circle` unless the core `gridTemplates` setting is truthy,
   * in which case it returns a `PIXI.Polygon` with points generated by {@link foundry.grid.BaseGrid.getCircle | `canvas.grid.getCircle`}
   */
  static getCircleShape(distance: number): PIXI.Circle | PIXI.Polygon;

  /**
   * Get a Conical area of effect given a direction, angle, and distance
   * @param distance  - The radius of the cone in grid units
   * @param direction - The direction of the cone in degrees
   * @param angle     - The angle of the cone in degrees
   * @remarks Always returns a `PIXI.Polygon`, but if the core `gridTemplates` setting is truthy,
   * the points will come from {@link foundry.grid.BaseGrid.getCone | `canvas.grid.getCone`}
   */
  static getConeShape(distance: number, direction: number, angle: number): PIXI.Polygon;

  /**
   * Get a Rectangular area of effect given a width and height
   * @param distance  - The length of the diagonal in grid units
   * @param direction - The direction of the diagonal in degrees
   * @remarks Always returns a `PIXI.Rectangle`, but if the core `gridTemplates` setting is truthy,
   * the height and width will come from {@link foundry.grid.BaseGrid.getTranslatedPoint | `canvas.grid.getTranslatedPoint`}
   */
  static getRectShape(distance: number, direction: number): PIXI.Rectangle;

  /**
   * Get a rotated Rectangular area of effect given a width, height, and direction
   * @param distance  - The length of the ray in grid units
   * @param direction - The direction of the ray in degrees
   * @param width     - The width of the ray in grid units
   */
  static getRayShape(distance: number, direction: number, width: number): PIXI.Polygon;

  /**
   * Update the displayed ruler tooltip text
   */
  protected _refreshRulerText(): void;

  /**
   * Highlight the grid squares which should be shown under the area of effect
   */
  highlightGrid(): void;

  /**
   * Get the shape to highlight on a Scene which uses grid-less mode.
   */
  protected _getGridHighlightShape(): NonNullable<this["shape"]>;

  /**
   * Get an array of points which define top-left grid spaces to highlight for square or hexagonal grids.
   */
  protected _getGridHighlightPositions(): Canvas.Point[];

  // snap: not null (forwarded to _updateRotation with only a parameter default)
  override rotate(angle: number, snap?: number): Promise<this>;

  // _onUpdate is overridden but with no signature changes.
  // For type simplicity it is left off. These methods historically have been the source of a large amount of computation from tsc.

  protected override _canControl(user: User.Implementation, event?: Canvas.Event.Pointer): boolean;

  protected override _canHUD(user: User.Implementation, event?: Canvas.Event.Pointer): boolean;

  protected override _canConfigure(user: User.Implementation, event?: Canvas.Event.Pointer): boolean;

  protected override _canView(user: User.Implementation, event?: Canvas.Event.Pointer): boolean;

  // fake override to narrow the type from super, which had to account for this class's misbehaving siblings
  // options: not null (destructured)
  protected override _onHoverIn(event: Canvas.Event.Pointer, options?: PlaceableObject.HoverInOptions): void;

  protected override _onClickRight(event: Canvas.Event.Pointer): void;

  // fake override to narrow the type from super, which had to account for this class's misbehaving siblings
  protected override _prepareDragLeftDropUpdates(event: Canvas.Event.Pointer): PlaceableObject.DragLeftDropUpdate[];

  /**
   * @deprecated since v12, until v14
   * @remarks "`MeasuredTemplate#borderColor` has been deprecated. Use {@link MeasuredTemplateDocument.borderColor | `MeasuredTemplate#document#borderColor`} instead."
   *
   * Returns the {@link Color.valueOf | `Color#valueOf()`} of the document's `borderColor`, not the `Color` itself
   */
  get borderColor(): number;

  /**
   * @deprecated since v12, until v14
   * @remarks "`MeasuredTemplate#fillColor` has been deprecated. Use {@link MeasuredTemplateDocument.fillColor | `MeasuredTemplate#document#fillColor`} instead."
   *
   * Returns the {@link Color.valueOf | `Color#valueOf()`} of the document's `fillColor`, not the `Color` itself
   */
  get fillColor(): number;

  /**
   * A flag for whether the current User has full ownership over the MeasuredTemplate document.
   * @deprecated since v12, until v14
   * @remarks "`MeasuredTemplate#owner` has been deprecated. Use {@link MeasuredTemplate.isOwner | `MeasuredTemplate#isOwner`} instead."
   */
  get owner(): this["isOwner"];
}

declare namespace MeasuredTemplate {
  /**
   * The implementation of the `MeasuredTemplate` placeable configured through `CONFIG.MeasuredTemplate.objectClass`
   * in Foundry and {@linkcode PlaceableObjectClassConfig} in fvtt-types.
   *
   * Not to be confused with {@linkcode MeasuredTemplateDocument.Implementation}
   * which refers to the implementation for the measured template document.
   */
  type Implementation = FixedInstanceType<ImplementationClass>;

  /**
   * The implementation of the `MeasuredTemplate` placeable configured through `CONFIG.MeasuredTemplate.objectClass`
   * in Foundry and {@linkcode PlaceableObjectClassConfig} in fvtt-types.
   *
   * Not to be confused with {@linkcode MeasuredTemplateDocument.ImplementationClass}
   * which refers to the implementation for the measured template document.
   */
  // eslint-disable-next-line no-restricted-syntax
  type ImplementationClass = ConfiguredObjectClassOrDefault<typeof MeasuredTemplate>;

  interface RENDER_FLAGS {
    /** @defaultValue `{ propagate: ["refresh"] }` */
    redraw: RenderFlag<this, "redraw">;

    /** @defaultValue `{ propagate: ["refreshState", "refreshPosition", "refreshShape", "refreshElevation"], alias: true }` */
    refresh: RenderFlag<this, "refresh">;

    /** @defaultValue `{}` */
    refreshState: RenderFlag<this, "refreshState">;

    /** @defaultValue `{ propagate: ["refreshGrid"] }` */
    refreshPosition: RenderFlag<this, "refreshPosition">;

    /** @defaultValue `{ propagate: ["refreshTemplate", "refreshGrid", "refreshText"] }` */
    refreshShape: RenderFlag<this, "refreshShape">;

    /** @defaultValue `{}` */
    refreshTemplate: RenderFlag<this, "refreshTemplate">;

    /** @defaultValue `{}` */
    refreshGrid: RenderFlag<this, "refreshGrid">;

    /** @defaultValue `{}` */
    refreshText: RenderFlag<this, "refreshText">;

    /** @defaultValue `{}` */
    refreshElevation: RenderFlag<this, "refreshElevation">;
  }

  interface RenderFlags extends RenderFlagsMixin.ToBooleanFlags<RENDER_FLAGS> {}

  interface DrawOptions extends PlaceableObject.DrawOptions {}

  interface RefreshOptions extends PlaceableObject.RefreshOptions {}

  interface ControlOptions extends PlaceableObject.ControlOptions {}

  interface ReleaseOptions extends PlaceableObject.ReleaseOptions {}
}

export default MeasuredTemplate;