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

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

import type Viewpoint from "../Viewpoint.js";
import type Widget from "./Widget.js";
import type HomeViewModel from "./Home/HomeViewModel.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 { HomeViewModelEvents, HomeViewModelProperties } from "./Home/HomeViewModel.js";
import type { GoToOverride } from "./support/types.js";
import type { ViewpointProperties } from "../Viewpoint.js";

export interface HomeProperties extends WidgetProperties, Partial<Pick<Home, "goToOverride" | "uiStrings" | "view">> {
  /**
   * Icon displayed in the widget's button.
   *
   * @default "home"
   * @since 4.28
   * @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
   * [HomeViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Home/HomeViewModel/) class to access
   * all properties and methods on the widget.
   */
  viewModel?: HomeViewModelProperties;
  /**
   * The [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/), or point of view, to zoom to when
   * going home. The initial value is determined a few different ways:
   *
   * If no [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) is provided, the value is `null`.
   * If the [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) is ready, but the [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/) is not defined, the initial
   * value of the [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/) is determined when the [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) became ready.
   * If the [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) is ready and the [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/) is defined by the user, the initial viewpoint value is the user-defined [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/).
   *
   * @example
   * // Creates a viewpoint centered on the extent of a polygon geometry
   * let vp = new Viewpoint({
   *   targetGeometry: geom.extent
   * });
   *
   * // Sets the model's viewpoint to the Viewpoint based on a polygon geometry
   * home.viewpoint = vp;
   */
  viewpoint?: ViewpointProperties | null;
}

export interface HomeEvents extends HomeViewModelEvents {}

/**
 * Provides a simple widget that switches the [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) to its
 * initial [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/) or a previously defined [viewpoint](https://developers.arcgis.com/javascript/latest/references/core/widgets/Home/#viewpoint).
 * By default this button looks like the following:
 *
 * ![home-button](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/widgets-home.png)
 *
 * You can use the view's [DefaultUI](https://developers.arcgis.com/javascript/latest/references/core/views/ui/DefaultUI/) to add widgets
 * to the view's user interface via the `ui` property on the view.
 * See the example below.
 *
 * @deprecated since version 4.32. Use the [Home component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-home/) 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 [HomeViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Home/HomeViewModel/)
 * @see [DefaultUI](https://developers.arcgis.com/javascript/latest/references/core/views/ui/DefaultUI/)
 * @example
 * let homeWidget = new Home({
 *   view: view
 * });
 *
 * // adds the home widget to the top left corner of the MapView
 * view.ui.add(homeWidget, "top-left");
 */
export default class Home extends Widget {
  /**
   * @deprecated
   * Do not directly reference this property.
   * Use EventNames and EventTypes helpers from \@arcgis/core/Evented
   */
  "@eventTypes": HomeEvents;
  /**
   * @example
   * // typical usage
   * let homeButton = new Home({
   *   view: view,
   *   viewpoint: new Viewpoint()
   * });
   */
  constructor(properties?: HomeProperties);
  /**
   * 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 "home"
   * @since 4.28
   * @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);
  /**
   * Overwrite localized strings for this widget.
   *
   * @since 4.27
   */
  accessor uiStrings: Record<string, unknown> | null | undefined;
  /** A reference to the [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/) or [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). Set this to link the widget to a specific view. */
  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
   * [HomeViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Home/HomeViewModel/) class to access
   * all properties and methods on the widget.
   */
  get viewModel(): HomeViewModel;
  set viewModel(value: HomeViewModelProperties);
  /**
   * The [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/), or point of view, to zoom to when
   * going home. The initial value is determined a few different ways:
   *
   * If no [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) is provided, the value is `null`.
   * If the [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) is ready, but the [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/) is not defined, the initial
   * value of the [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/) is determined when the [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) became ready.
   * If the [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) is ready and the [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/) is defined by the user, the initial viewpoint value is the user-defined [Viewpoint](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/).
   *
   * @example
   * // Creates a viewpoint centered on the extent of a polygon geometry
   * let vp = new Viewpoint({
   *   targetGeometry: geom.extent
   * });
   *
   * // Sets the model's viewpoint to the Viewpoint based on a polygon geometry
   * home.viewpoint = vp;
   */
  get viewpoint(): Viewpoint | null | undefined;
  set viewpoint(value: ViewpointProperties | null | undefined);
  /**
   * This function provides the ability to interrupt and cancel the process
   * of navigating the view back to the view's initial extent.
   *
   * @since 4.9
   */
  cancelGo(): void;
  /**
   * Animates the view to the initial Viewpoint of the view or the
   * value of [viewpoint](https://developers.arcgis.com/javascript/latest/references/core/widgets/Home/#viewpoint).
   *
   * @see [Event: go](https://developers.arcgis.com/javascript/latest/references/core/widgets/Home/#event-go)
   */
  go(): Promise<void>;
}