@arcgis/map-components/dist/components/arcgis-coordinate-conversion/customElement.d.ts

ArcGIS Map Components

/// <reference path="../../index.d.ts" />
import type Point from "@arcgis/core/geometry/Point.js";
import type Conversion from "@arcgis/core/widgets/CoordinateConversion/support/Conversion.js";
import type Format from "@arcgis/core/widgets/CoordinateConversion/support/Format.js";
import type Collection from "@arcgis/core/core/Collection.js";
import type PictureMarkerSymbol from "@arcgis/core/symbols/PictureMarkerSymbol.js";
import type SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol.js";
import type CIMSymbol from "@arcgis/core/symbols/CIMSymbol.js";
import type PointSymbol3D from "@arcgis/core/symbols/PointSymbol3D.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, IconName, HeadingLevel } from "../types.js";
import type { Orientation, StorageType } from "./types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { MapViewOrSceneView } from "@arcgis/core/views/MapViewOrSceneView.js";
import type { GoToOverride } from "@arcgis/core/widgets/support/types.js";
import type { Mode } from "@arcgis/core/widgets/types.js";
import type { CoordinateConversionViewModelState } from "@arcgis/core/widgets/CoordinateConversion/CoordinateConversionViewModel.js";

/**
 * > [!NOTE]
 * > In version 6.0, the implementation of [arcgis-coordinate-conversion](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion/) will be updated under the hood to that of [arcgis-coordinate-conversion-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion-next/) , and deprecated properties on this component will be removed. We encourage using the [arcgis-coordinate-conversion-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion-next/) component and providing feedback.
 *
 * The Coordinate Conversion component provides a way to display user cursor position either as map coordinates or
 * as any of several popular coordinate notations.  Additionally, the component provides a way to convert
 * user input coordinates into a [point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/).
 *
 *
 * Several common formats are included by default:
 * * XY - Longitude, Latitude (WGS84)
 * * MGRS - [Military Grid Reference System](https://earth-info.nga.mil/index.php?dir=coordsys&action=coordsys#mgrs)
 * * UTM - [Universal Transverse Mercator](https://earth-info.nga.mil/index.php?dir=coordsys&action=coordsys#utm)
 * * DD - Decimal Degrees
 * * DDM - Degrees Decimal Minutes
 * * DMS - Degrees Minutes Seconds
 * * Basemap - X, Y in the coordinate system used by the current basemap in the units used by the basemap.
 * Web Mercator is the standard for Esri-provided basemaps.
 *
 * Additional formats can be created by a developer and made available
 * through the component
 *
 * @example
 * ```html
 * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
 *   <arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion>
 * </arcgis-map>
 * ```
 */
export abstract class ArcgisCoordinateConversion extends LitElement {
  /**
   * If true, the component will not be destroyed automatically when it is
   * disconnected from the document. This is useful when you want to move the
   * component to a different place on the page, or temporarily hide it. If this
   * is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion/#destroy) method when you are done to
   * prevent memory leaks.
   *
   * @default false
   */
  accessor autoDestroyDisabled: boolean;
  /**
   * A [collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) of conversions
   * that the component is currently displaying. Each row in the component displaying a coordinate is a conversion.
   *
   * @example
   * Conversions can be set with an array of strings where each string is a format's name.
   * ```js
   * coordinateConversionComponent.conversions = ["mgrs"];
   * ```
   * @since 4.7
   */
  accessor conversions: Collection<Conversion>;
  /**
   * Describes the location of the coordinates currently displayed by the component as a [Point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/).
   * Setting this property will update all conversions.
   *
   * @example
   * Set the current location.
   * ```js
   * coordinateConversionComponent.currentLocation = { x: 77.0369, y: 38.9072, spatialReference: { wkid: 4326 } };
   * ```
   * @since 4.7
   */
  accessor currentLocation: Point | null | undefined;
  /**
   * Describes whether the component is expanded or not. If `true`, the component is expanded and all conversions are visible.
   *
   * @deprecated since 5.1. The expand/collapse functionality will be removed as part of migration to [arcgis-coordinate-conversion-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion-next/).
   * @default false
   * @example
   * Expand the component.
   * ```js
   * coordinateConversionComponent.expanded = true;
   * ```
   */
  accessor expanded: boolean;
  /**
   * A [collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) containing every coordinate format
   * that the component is capable of displaying.
   *
   * The default formats are `basemap`, `dd`, `ddm`, `dms`, `mgrs`, `usng`, `utm`, and `xy`.
   *
   * @example
   * Only show the "xy" format.
   * ```js
   * const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
   * const toRemove = coordinateConversionComponent.formats.filter(format => format.name !== "xy");
   * coordinateConversionComponent.formats.removeMany(toRemove);
   * ```
   * @example
   * Show every format except "xy".
   * ```js
   * const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
   * const toRemove = coordinateConversionComponent.formats.filter(format => format.name === "xy");
   * coordinateConversionComponent.formats.removeMany(toRemove);
   * ```
   */
  accessor formats: Collection<Format>;
  /**
   * This function provides the ability to override either the [arcgis-map.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#goTo) or [arcgis-scene.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#goTo) methods.
   *
   * @since 4.33
   * @example
   * ```js
   * component.goToOverride = function(view, goToParams) {
   *   goToParams.options = {
   *     duration: updatedDuration
   *   };
   *   return view.goTo(goToParams.target, goToParams.options);
   * };
   * ```
   */
  accessor goToOverride: GoToOverride | null | undefined;
  /**
   * Indicates the heading level to use for the coordinate input and coordinate settings headings. By default,
   * these headings are rendered as level 4 headings (e.g. `<h4>Input coordinate</h4>`). Depending on the coordinate conversion component's
   * placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting
   * accessibility standards.
   *
   * @default 4
   */
  accessor headingLevel: HeadingLevel;
  /**
   * Determines whether the capture button will be shown in the component. If `true`, the capture button will be hidden.
   *
   * @deprecated since 5.1. The capture button will be removed as part of migration to [arcgis-coordinate-conversion-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion-next/).
   * @default false
   * @example
   * Hide the capture button.
   * ```html
   * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
   *   <arcgis-coordinate-conversion hide-capture-button slot="bottom-left"></arcgis-coordinate-conversion>
   * </arcgis-map>
   * ```
   */
  accessor hideCaptureButton: boolean;
  /**
   * Determines whether the expand button will be shown in the component. If `true`, the expand button will be hidden.
   *
   * @deprecated since 5.1. The expand/collapse functionality will be removed as part of migration to [arcgis-coordinate-conversion-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion-next/).
   * @default false
   * @example
   * Hide the expand button.
   * ```html
   * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
   *   <arcgis-coordinate-conversion hide-expand-button slot="bottom-left"></arcgis-coordinate-conversion>
   * </arcgis-map>
   * ```
   */
  accessor hideExpandButton: boolean;
  /**
   * Determines whether the input coordinate button will be shown in the component. If `true`, the input button will be hidden.
   *
   * @deprecated since 5.1. The input button will be removed as part of migration to [arcgis-coordinate-conversion-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion-next/).
   * @default false
   * @example
   * Hide the input button.
   * ```html
   * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
   *   <arcgis-coordinate-conversion hide-input-button slot="bottom-left"></arcgis-coordinate-conversion>
   * </arcgis-map>
   * ```
   */
  accessor hideInputButton: boolean;
  /**
   * Determines whether the settings button will be shown in the component. If `true`, the settings button will be hidden.
   *
   * @deprecated since 5.1. The settings button will be removed as part of migration to [arcgis-coordinate-conversion-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion-next/).
   * @default false
   * @example
   * Hide the settings button.
   * ```html
   * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
   *   <arcgis-coordinate-conversion hide-settings-button slot="bottom-left"></arcgis-coordinate-conversion>
   * </arcgis-map>
   * ```
   */
  accessor hideSettingsButton: boolean;
  /**
   * Icon which represents the component.
   * Typically used when the component is controlled by another component (e.g. by the Expand component).
   * Search [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/) for possible values.
   *
   * @default "coordinate-system"
   */
  accessor icon: IconName;
  /**
   * If false, the component will estimate coordinate precision based on the current state of the
   * view. As the view is zoomed farther out, fewer decimal places will be shown. Only affects `DD`,
   * `DDM`, `DMS`, and `XY` formats.
   *
   * @default false
   * @since 5.1
   */
  accessor ignoreCoordinatePrecision: boolean;
  /**
   * The component's default label.
   *
   * @default "Coordinate conversion"
   */
  accessor label: string | undefined;
  /**
   * This symbol is used to visualize the location currently described by the component when `capture` mode
   * is active.
   *
   * This property should be set to a point symbol, typically a [Simple Marker Symbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleMarkerSymbol/).
   *
   * @example
   * Set the location symbol to be an 'x'.
   * ```js
   * const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
   * coordinateConversionComponent.locationSymbol = { type: "simple-marker", style: "x" };
   * ```
   */
  accessor locationSymbol: PictureMarkerSymbol | SimpleMarkerSymbol | CIMSymbol | PointSymbol3D;
  /** @internal */
  protected messages: Partial<{
      componentLabel: string;
      abbreviatedDirections: {
          north: string;
          south: string;
          east: string;
          west: string;
      };
      addConversion: string;
      alertLabel: string;
      back: string;
      captureMode: string;
      changeCoordinateDisplay: string;
      collapse: string;
      convert: string;
      conversionOutput: string;
      copy: string;
      copySuccessMessage: string;
      defaultPattern: string;
      expand: string;
      goTo: string;
      inputCoordTitle: string;
      invalidCoordinate: string;
      liveMode: string;
      locationOffBasemap: string;
      noBasemap: string;
      noLocation: string;
      preview: string;
      removeConversion: string;
      selectFormat: string;
      settingsTitle: string;
  }> & T9nMeta<{
      componentLabel: string;
      abbreviatedDirections: {
          north: string;
          south: string;
          east: string;
          west: string;
      };
      addConversion: string;
      alertLabel: string;
      back: string;
      captureMode: string;
      changeCoordinateDisplay: string;
      collapse: string;
      convert: string;
      conversionOutput: string;
      copy: string;
      copySuccessMessage: string;
      defaultPattern: string;
      expand: string;
      goTo: string;
      inputCoordTitle: string;
      invalidCoordinate: string;
      liveMode: string;
      locationOffBasemap: string;
      noBasemap: string;
      noLocation: string;
      preview: string;
      removeConversion: string;
      selectFormat: string;
      settingsTitle: string;
  }>;
  /**
   * Describes the current mode of the component.
   *
   * * While in `live` mode, the component will update as the cursor moves.
   * * While in `capture` mode, the component will update on mouse click and display a graphic
   * marking the current location.
   *
   * @default "live"
   * @example
   * Programmatically set the component to capture mode.
   * ```js
   * const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
   * coordinateConversionComponent.mode = "capture";
   * ```
   */
  accessor mode: Mode;
  /**
   * If this property is set to `true`, multiple conversions will be disabled, and only a single conversion will be displayed. Otherwise, multiple conversions will be shown.
   *
   * @default false
   */
  accessor multipleConversionsDisabled: boolean;
  /**
   * Determines whether the component should expand up or down.  If set to `auto`,
   * the component will be oriented based on its position in the view.
   *
   * @default "auto"
   */
  accessor orientation: Orientation;
  /**
   * By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
   *
   * @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
   */
  accessor referenceElement: ArcgisReferenceElement | string | undefined;
  /**
   * Determines whether leading zeros will be shown in `DD`, `DDM`, and `DMS` formats.
   * When false: 01.37°N, 008.71°E
   * When true: 1.37°N, 8.71°E
   *
   * @default false
   * @since 5.1
   */
  accessor removeLeadingZeros: boolean;
  /**
   * The current state of the component.
   *
   * @default "disabled"
   */
  get state(): CoordinateConversionViewModelState;
  /**
   * If this property is set to `true`, sessionStorage or localStorage (depending on [storageType](https://developers.arcgis.com/javascript/latest/references/core/widgets/CoordinateConversion/#storageType))
   * will not be used to hydrate and persist the component's state.
   *
   * @default false
   */
  accessor storageDisabled: boolean;
  /**
   * This property determines whether sessionStorage or localStorage will be used to store component's state.
   *
   * @default "session"
   * @see [Window.sessionStorage](https://developer.mozilla.org/docs/Web/API/Window/sessionStorage)
   * @see [Window.localStorage](https://developer.mozilla.org/docs/Web/API/Window/localStorage)
   * @since 4.23
   */
  accessor storageType: StorageType;
  /**
   * The view associated with the component. 
   *   > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-coordinate-conversion component will be associated with a map or scene component rather than using the `view` property.
   */
  accessor view: MapViewOrSceneView | null | undefined;
  /** Permanently destroy the component. */
  destroy(): Promise<void>;
  /**
   * Attempt to convert a string into a [point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/).  The format of the
   * string must be specified.  A [collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) of available formats can be
   * obtained from the [formats](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion/#formats) property.
   *
   * @param coordinate - The coordinate string.
   * @param format - Specifies the format of the input coordinate.
   * @returns When resolved, returns a [point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/).
   */
  reverseConvert(coordinate: string, format: Format): Promise<Point | null | undefined>;
  /**
   * Emitted when a conversion is added or removed, or when the order of conversions changes.
   *
   * @since 4.34
   */
  readonly arcgisConversionChange: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
  readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "currentLocation" | "state" | "expanded" | "mode"; }>;
  /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
  readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
  readonly "@eventTypes": {
    arcgisConversionChange: ArcgisCoordinateConversion["arcgisConversionChange"]["detail"];
    arcgisPropertyChange: ArcgisCoordinateConversion["arcgisPropertyChange"]["detail"];
    arcgisReady: ArcgisCoordinateConversion["arcgisReady"]["detail"];
  };
}