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

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

import type MapView from "../views/MapView.js";
import type Widget from "./Widget.js";
import type ScaleBarViewModel from "./ScaleBar/ScaleBarViewModel.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { MeasurementSystem } from "../core/units.js";
import type { WidgetProperties } from "./Widget.js";
import type { ScaleBarViewModelProperties } from "./ScaleBar/ScaleBarViewModel.js";

export interface ScaleBarProperties extends WidgetProperties, Partial<Pick<ScaleBar, "style" | "view">> {
  /**
   * Icon which represents the widget.
   * Typically used when the widget is controlled by another widget (e.g. by the Expand widget).
   *
   * @default "actual-size"
   * @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.11
   */
  label?: string | null;
  /**
   * Units to use for the scale bar.
   * When using `dual`, the scale bar displays both metric and imperial units.
   * When metric, distances will be shown in either kilometers, meters, centimeters, or millimeters depending on the scale. Similarly, imperial
   * units will be shown in either miles, feet, or inches.
   */
  unit?: ScaleBarUnit | 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
   * [ScaleBarViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/ScaleBar/ScaleBarViewModel/) class to access
   * all properties and methods on the widget.
   */
  viewModel?: ScaleBarViewModelProperties;
}

export type ScaleBarStyle = "line" | "ruler";

export type ScaleBarUnit = MeasurementSystem | "dual";

/**
 * The ScaleBar widget displays a scale bar on the map or in a specified HTML node.
 * The widget respects various coordinate systems and displays units in metric or imperial values.
 * Metric values show either kilometers, meters, centimeters, or millimeters depending on the scale, and likewise, imperial values show miles, feet, or inches depending on the scale.
 * When working with Web Mercator or geographic coordinate systems the scale bar takes into account projection distortion and dynamically adjusts the scale bar.
 *
 * When the scale bar is inside the map, the actual location of the scale bar is used to calculate the scale.
 * Otherwise, the center of the map is used to calculate the scale.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > ScaleBar only works with [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/).
 *
 * @deprecated since version 4.32. Use the [Scale Bar component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scale-bar/) 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.3
 * @see [ScaleBarViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/ScaleBar/ScaleBarViewModel/)
 * @example
 * let scaleBar = new ScaleBar({
 *   view: view
 * });
 * // Add widget to the bottom left corner of the view
 * view.ui.add(scaleBar, {
 *   position: "bottom-left"
 * });
 */
export default class ScaleBar extends Widget {
  /**
   * @example
   * // typical usage
   * let scalebar = new ScaleBar({
   *   view: view
   * });
   */
  constructor(properties?: ScaleBarProperties);
  /**
   * Icon which represents the widget.
   * Typically used when the widget is controlled by another widget (e.g. by the Expand widget).
   *
   * @default "actual-size"
   * @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.11
   */
  get label(): string;
  set label(value: string | null | undefined);
  /**
   * The style for the scale bar.
   * When `unit` is set to `dual`, the style will always be `line`.
   *
   * @default "line"
   */
  accessor style: ScaleBarStyle;
  /**
   * Units to use for the scale bar.
   * When using `dual`, the scale bar displays both metric and imperial units.
   * When metric, distances will be shown in either kilometers, meters, centimeters, or millimeters depending on the scale. Similarly, imperial
   * units will be shown in either miles, feet, or inches.
   */
  get unit(): ScaleBarUnit;
  set unit(value: ScaleBarUnit | null | undefined);
  /**
   * A reference to the [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/). Set this to link
   * the widget to a specific view.
   */
  accessor view: MapView | 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
   * [ScaleBarViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/ScaleBar/ScaleBarViewModel/) class to access
   * all properties and methods on the widget.
   */
  get viewModel(): ScaleBarViewModel;
  set viewModel(value: ScaleBarViewModelProperties);
}