@arcgis/map-components
Version:
ArcGIS Map Components
342 lines (341 loc) • 15.2 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type Color from "@arcgis/core/Color.js";
import type MapView from "@arcgis/core/views/MapView.js";
import type SnappingOptions from "@arcgis/core/views/interactive/snapping/SnappingOptions.js";
import type { ArcgisReferenceElement } from "../types.js";
import type { GridTheme } from "./types.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { LengthUnit } from "@arcgis/core/core/units.js";
import type { GridPlacementState as GridPlacementState2 } from "@arcgis/core/widgets/support/GridControls/types.js";
/**
* The Grid Controls component provides a user interface (UI) for configuring and displaying a two-dimensional grid.
* The grid displayed provides a network of horizontal and vertical lines used to divide the view into equal cells.
* With support for snapping, the grid lines can be used as a reference when drawing features.
* Note: grid controls are embedded in snapping controls for Sketch and Editor by default.
*
* **Known limitations**
*
* - Grid Controls is only supported in a 2D Map component.
* - The grid spacing does not correspond to real world measurements. Distortion will be minimized when used in conjunction with an equal area basemap.
* - The grid spacing input will be hidden when working with Web Mercator and Geographic Coordinate Systems.
*/
export abstract class ArcgisGridControls extends LitElement {
/** @internal */
protected _messages: Partial<{
componentLabel: string;
placementOptions: string;
gridLineColorPopoverLabel: string;
switchLabel: {
rotateWithMap: string;
scaling: string;
display: string;
snap: string;
};
inputLabel: {
spacing: string;
interval: string;
angle: string;
theme: string;
};
gridTheme: {
light: string;
dark: string;
custom: string;
};
placementState: {
interactive: string;
place: string;
scale: string;
rotate: string;
};
warnings: {
dynamicSpacing: string;
outOfScale: string;
interactivePlaceDisabled: string;
};
}> & T9nMeta<{
componentLabel: string;
placementOptions: string;
gridLineColorPopoverLabel: string;
switchLabel: {
rotateWithMap: string;
scaling: string;
display: string;
snap: string;
};
inputLabel: {
spacing: string;
interval: string;
angle: string;
theme: string;
};
gridTheme: {
light: string;
dark: string;
custom: string;
};
placementState: {
interactive: string;
place: string;
scale: string;
rotate: string;
};
warnings: {
dynamicSpacing: string;
outOfScale: string;
interactivePlaceDisabled: string;
};
}>;
/**
* 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-grid-controls/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/** The custom color used for drawing the grid, if any. */
accessor customColor: Color | undefined;
/**
* Returns `true` if the grid is enabled for display.
* Use [trySetDisplayEnabled()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-grid-controls/#trySetDisplayEnabled) to enable or disable grid display.
*
* @default false
*/
get displayEnabled(): boolean;
/**
* Returns `true` if the grid is set to scale dynamically. When dynamic scaling is enabled,
* grid cells are added or removed to ensure that grid cells are a reasonable size on screen as the user zooms.
* The way additional grid lines are shown is controlled by the [majorLineInterval](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-grid-controls/#majorLineInterval) property.
*
* @default false
*/
accessor dynamicScaling: boolean;
/** Returns the actual spacing of grid lines after dynamic scaling has been applied at the current scale. */
get effectiveSpacingAfterDynamicScaling(): number | null;
/** Controls the color of the major grid lines. Minor grid lines are a slightly transparent version of this color. */
accessor gridColor: Color | null | undefined;
/**
* Returns `true` if the grid is in a valid state for manually setting grid properties or starting an interactive placement.
*
* @default false
*/
get gridControlsEnabled(): boolean;
/**
* True if the grid is currently not displayed (and therefore also not a valid snap target),
* because [dynamicScaling](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-grid-controls/#dynamicScaling) is off and the grid cells are too small
* to render at the current scale.
*
* @default false
*/
get gridOutOfScale(): boolean;
/**
* Controls display of the color and theme selection options.
*
* @default false
*/
accessor hideColorSelection: boolean;
/**
* Controls display of the dynamic scaling toggle. Dynamic scaling adjusts the size of the grid to work
* well regardless of view scale.
*
* @default false
*/
accessor hideDynamicScaleToggle: boolean;
/**
* Controls display of the grid enabled toggle. This toggle controls whether the grid is displayed.
*
* @default false
*/
accessor hideGridEnabledToggle: boolean;
/**
* Controls display of the grid snapping enabled toggle. This toggle controls whether snapping is enabled.
*
* @default false
*/
accessor hideGridSnapEnabledToggle: boolean;
/**
* Controls display of the line interval input field for setting the interval between major grid lines.
*
* @default false
*/
accessor hideLineIntervalInput: boolean;
/**
* Controls display of the numeric input fields for setting grid spacing and rotation.
*
* @default false
*/
accessor hideNumericInputs: boolean;
/**
* Controls display of the out of scale warning. This warning is displayed when the grid is not shown
* because it would be too small at the current scale and dynamic scaling is disabled.
*
* @default false
*/
accessor hideOutOfScaleWarning: boolean;
/**
* Controls display of the grid placement buttons. These buttons allow the user to start interactive
* configuration of the grid.
*
* @default false
*/
accessor hidePlacementButtons: boolean;
/**
* Controls display of the rotate with map toggle. This toggle controls whether the grid rotates with the map.
*
* @default false
*/
accessor hideRotateWithMapToggle: boolean;
/**
* Icon which represents the component.
* Typically used when the component is controlled by another component (e.g. by the Expand component).
*
* @default "grid-unit"
* @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
*/
accessor icon: string | undefined;
/**
* Sets the interactive placement state, either starting or ending a draw operation that implicitly adjusts the grid.
* Interactive placement allows the user to define the center of the grid, then the scale and rotation of the grid by
* drawing a second point. Setting this to "place" allows the user to move the grid center only. Setting this to "rotate"
* keeps the scale and center of the grid constant while rotating the grid by defining a second point.
*
* @default null
*/
accessor interactivePlacementState: GridPlacementState2 | null | undefined;
/** The component's default label. */
accessor label: string | undefined;
/**
* Controls the number of grid cells shown between major grid lines. Can be anything between 1 and 15.
* No minor grid lines are shown when this is set to 1.
*
* @default 10
*/
accessor majorLineInterval: number;
/**
* Replace localized message strings with your own strings.
*
* _**Note**: Individual message keys may change between releases._
*/
accessor messageOverrides: {
componentLabel?: string | undefined;
placementOptions?: string | undefined;
gridLineColorPopoverLabel?: string | undefined;
switchLabel?: {
rotateWithMap?: string | undefined;
scaling?: string | undefined;
display?: string | undefined;
snap?: string | undefined;
} | undefined;
inputLabel?: {
spacing?: string | undefined;
interval?: string | undefined;
angle?: string | undefined;
theme?: string | undefined;
} | undefined;
gridTheme?: {
light?: string | undefined;
dark?: string | undefined;
custom?: string | undefined;
} | undefined;
placementState?: {
interactive?: string | undefined;
place?: string | undefined;
scale?: string | undefined;
rotate?: string | undefined;
} | undefined;
warnings?: {
dynamicSpacing?: string | undefined;
outOfScale?: string | undefined;
interactivePlaceDisabled?: string | undefined;
} | undefined;
};
/**
* Use this property to disable the interactive grid placement buttons as needed.
* An example use case might be to block interaction while another interactive operation
* (e.g. sketching) is in progress.
*
* @default false
* @since 4.33
*/
accessor placementDisabled: boolean;
/**
* 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;
/**
* Controls whether the grid rotates with the map, or stays fixed to the screen.
*
* @default false
*/
accessor rotateWithMap: boolean;
/** Rotation of the grid in radians. NOTE: UI controls convert to and from degrees automatically. */
accessor rotation: number;
/**
* Controls snapping behavior if [snappingOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-grid-controls/#snappingOptions) has been defined.
* If [snappingOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-grid-controls/#snappingOptions) have been defined, disabling or enabling grid snapping will
* also disable or enable grid display.
*
* @default false
*/
accessor snappingEnabled: boolean;
/**
* The [SnappingOptions](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/)
* that will be controlled by this component if the snapping toggle is enabled for display.
* If SnappingOptions are provided, grid display will be automatically enabled or disabled to match snapping state.
*/
accessor snappingOptions: SnappingOptions | null | undefined;
/**
* Length of a grid cell. Grid cells are always square. Defined in [unit](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-grid-controls/#unit).
*
* @default 1
*/
accessor spacing: number;
/**
* The color scheme used to display the grid. This will be light, dark, or custom. When theme is set to custom,
* the [customColor](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-grid-controls/#customColor) is shown, otherwise a default light or dark theme color is used.
*
* @default "dark"
*/
accessor theme: GridTheme | null | undefined;
/**
* Unit of measure (foot, meter, etc) used when defining the [spacing](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-grid-controls/#spacing) grid cell.
* Note that units are defined relatively to the map's spatial reference length unit,
* which will not correspond to geographic distance unless using a special-purpose basemap
* within a supported target area.
*
* When using Web Mercator, the projection defines the length of a meter in projection system units;
* this length is equal to a geographic meter only at the equator. On screen, the size of the grid cells is constant
* from the equator to the poles, but the real-world size of the grid cell is much larger further from the equator.
*
* The length of the grid cells can usefully correspond to a geographic length when the Grid is used with an
* appropriate spatial reference (for example a local system or a State Plane system) within the reference's area of interest.
*/
accessor unit: LengthUnit | undefined;
/**
* 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-grid-controls component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: MapView | null | undefined;
/** Permanently destroy the component. */
destroy(): Promise<void>;
/**
* Call this to turn the grid on/off.
*
* @param enabled - Desired end state for grid display.
*/
trySetDisplayEnabled(enabled: boolean): 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: "customColor" | "theme" | "spacing" | "rotation" | "majorLineInterval" | "rotateWithMap" | "dynamicScaling" | "snappingEnabled" | "interactivePlacementState" | "displayEnabled" | "gridOutOfScale" | "effectiveSpacingAfterDynamicScaling" | "gridControlsEnabled" | "gridColor"; }>;
/** 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": {
arcgisPropertyChange: ArcgisGridControls["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisGridControls["arcgisReady"]["detail"];
};
}