@arcgis/core/widgets/Compass.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type Widget from "./Widget.js";
import type CompassViewModel from "./Compass/CompassViewModel.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { MapViewOrSceneView } from "../views/MapViewOrSceneView.js";
import type { WidgetProperties } from "./Widget.js";
import type { GoToOverride } from "./support/types.js";
import type { CompassViewModelProperties } from "./Compass/CompassViewModel.js";

export interface CompassProperties extends WidgetProperties, Partial<Pick<Compass, "goToOverride" | "view">> {
  /**
   * Icon displayed in the widget's button.
   *
   * @default "compass-needle"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  icon?: Icon["icon"] | null;
  /**
   * The widget's default label.
   *
   * @since 4.7
   */
  label?: string | null;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [CompassViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Compass/CompassViewModel/) class to access
   * all properties and methods on the widget.
   */
  viewModel?: CompassViewModelProperties;
}

/**
 * The Compass widget indicates where north is in relation to the current view
 * [MapView.rotation](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#rotation)
 * or [camera heading](https://developers.arcgis.com/javascript/latest/references/core/Camera/#heading). Clicking the Compass widget
 * rotates the view to face north (heading = 0). This widget is added to a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/)
 * by default. The icon for the Compass widget is determined based upon the view's
 * [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#spatialReference).
 * If the spatial reference is Web Mercator or WGS84, the icon will be a compass needle.
 * For all other spatial references, the icon will be an arrow. For more information, see the
 * [Reference topic on Spatial references](https://developers.arcgis.com/documentation/spatial-references/).
 *
 * ![Compass for Web Mercator and WGS84](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/compass.png)
 * ![Compass for other spatial references](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/compass-other-sr.png)
 *
 * You can use the view's [DefaultUI](https://developers.arcgis.com/javascript/latest/references/core/views/ui/DefaultUI/) to add the compass widget
 * to a 2D application via the [MapView.ui](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#ui) property on the view.
 *
 * @deprecated since version 4.32. Use the [Compass component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-compass/) instead. For information on widget deprecation, read about [Esri's move to web components](https://developers.arcgis.com/javascript/latest/components-transition-plan/).
 * @since 4.0
 * @see [CompassViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Compass/CompassViewModel/)
 * @see [DefaultUI](https://developers.arcgis.com/javascript/latest/references/core/views/ui/DefaultUI/)
 * @see [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/)
 * @see [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/)
 * @see [Camera](https://developers.arcgis.com/javascript/latest/references/core/Camera/)
 * @example
 * let view = new MapView({
 *   container: "viewDiv",
 *   map: map
 * });
 *
 * let compass = new Compass({
 *   view: view
 * });
 *
 * // Add the compass to the top left corner of the MapView
 * view.ui.add(compass, "top-left");
 */
export default class Compass extends Widget {
  constructor(properties?: CompassProperties);
  /**
   * This function provides the ability to override either the
   * [MapView goTo()](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#goTo) or
   * [SceneView goTo()](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#goTo) methods.
   *
   * @since 4.8
   * @see [MapView.goTo()](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#goTo)
   * @see [SceneView.goTo()](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#goTo)
   * @example
   * // The following snippet uses Search but can be applied to any
   * // widgets that support the goToOverride property.
   * search.goToOverride = function(view, goToParams) {
   *   goToParams.options = {
   *     duration: updatedDuration
   *   };
   *   return view.goTo(goToParams.target, goToParams.options);
   * };
   */
  accessor goToOverride: GoToOverride | null | undefined;
  /**
   * Icon displayed in the widget's button.
   *
   * @default "compass-needle"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: Icon["icon"] | null | undefined);
  /**
   * The widget's default label.
   *
   * @since 4.7
   */
  get label(): string;
  set label(value: string | null | undefined);
  /**
   * The view in which the Compass obtains and indicates camera
   * [Camera.heading](https://developers.arcgis.com/javascript/latest/references/core/Camera/#heading), using a (SceneView) or
   * [MapView.rotation](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#rotation) (MapView).
   */
  accessor view: MapViewOrSceneView | null | undefined;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [CompassViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Compass/CompassViewModel/) class to access
   * all properties and methods on the widget.
   */
  get viewModel(): CompassViewModel;
  set viewModel(value: CompassViewModelProperties);
  /**
   * If working in a [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/), sets the view's
   * [MapView.rotation](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#rotation) to `0`. If working in a
   * [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/), sets the camera's
   * [Camera.heading](https://developers.arcgis.com/javascript/latest/references/core/Camera/#heading) to `0`. This method is executed each
   * time the [Compass](https://developers.arcgis.com/javascript/latest/references/core/widgets/Compass/) is clicked.
   */
  reset(): void;
}