UNPKG

@arcgis/map-components

Version:
613 lines (612 loc) • 27.1 kB
/// <reference path="../../index.d.ts" /> import type GraphicsLayer from "@arcgis/core/layers/GraphicsLayer.js"; import type Sketch from "@arcgis/core/widgets/Sketch.js"; import type Graphic from "@arcgis/core/Graphic.js"; import type SketchLabelOptions from "@arcgis/core/views/interactive/sketch/SketchLabelOptions.js"; import type MapNotesLayer from "@arcgis/core/layers/MapNotesLayer.js"; import type SnappingOptions from "@arcgis/core/views/interactive/snapping/SnappingOptions.js"; import type TextSymbol from "@arcgis/core/symbols/TextSymbol.js"; import type SketchTooltipOptions from "@arcgis/core/views/interactive/sketch/SketchTooltipOptions.js"; import type Collection from "@arcgis/core/core/Collection.js"; import type { SketchGroupName } from "@arcgis/core/applications/ExperienceBuilder/sketchUtils.js"; import type { PublicLitElement as LitElement } from "@arcgis/lumina"; import type { ArcgisReferenceElement, IconName } from "../types.js"; import type { CreateOptions, CreateTool, UpdateEvent, UndoEvent, DuplicateEvent, RedoEvent, DeleteEvent, CreateEvent, CustomToolOptions, CustomActionProperties, SketchTool, SelectionTool, CreationMode, UpdateOptions, Layout, SketchPointSymbol, SketchPolygonSymbol, SketchPolylineSymbol, State, ToolbarKind } from "@arcgis/core/widgets/Sketch/types.js"; import type { MapViewOrSceneView } from "@arcgis/core/views/MapViewOrSceneView.js"; import type { Icon } from "@esri/calcite-components/components/calcite-icon"; import type { Button as Button } from "@esri/calcite-components/components/calcite-button"; /** * The Sketch component provides a simple UI for creating and updating graphics on a [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/) or a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). * * @since 4.28 */ export abstract class ArcgisSketch extends LitElement { /** * When creating new graphics (for example after [create()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/#create) has been called), * this property reflects the create tool being used. When updating graphics * (for example after [update()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/#update) has been called), this property reflects the * update tool being used. If no create or update operation is in progress, this is `null`. * * Prior to 4.32, creation tools were modeled as a combination of a geometry type (point, line, polygon) * and an interaction mode (click, freehand, hybrid). * At 4.32, the available create tools were expanded to include "freehandPolyline" and "freehandPolygon". * These tools are made available to enable interoperability with other components of the ArcGIS system, * where freehand polyline is a distinct create tool from polyline. * * To minimize compatibility issues, if "freehandPolyline" and "freehandPolygon" are not in the list * of available create tools, they will not be returned by this property, even if the user is drawing a * polygon in freehand mode. * * To opt in to freehandPolyline and freehandPolygon tools, include them when setting availableCreateTools, * and hideCreateTools* properties */ get activeTool(): SketchTool | SelectionTool | null; /** * 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-sketch/#destroy) method when you are done to * prevent memory leaks. * * @default false */ accessor autoDestroyDisabled: boolean; /** * Property controlling the visibility and order of create tool buttons. * Create tool buttons will only be rendered if they are in this collections and the * matching hide/show property or attribute is configured to show the tool. * * @default ["point", "polyline", "freehandPolyline", "polygon", "freehandPolygon", "rectangle", "circle"] */ accessor availableCreateTools: Array<CreateTool> | null | undefined; /** The graphic that is being created. */ get createGraphic(): Graphic | null | undefined; /** * Defines the default behavior once the [create()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/#create) operation is completed. By default, the user will be * able to continuously create graphics with same geometry types. * * **Possible Values** * * Value | Description | * ----- | ----------- | * continuous | This is the default. Users can continue creating graphics with same geometry types. * single | User can create a single graphic with the specified geometry type. User must choose an operation once the graphic is created. * update | The graphic will be selected for an [update()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/#update) operation once the `create` operation is completed. * * @default "continuous" * @since 4.14 */ accessor creationMode: CreationMode; /** * Default create options set for the Sketch component. * * @since 4.14 */ accessor defaultCreateOptions: CreateOptions; /** * By default, sketch will auto-create a new graphics layer if none was * provided. Set this prop to true to disable this behavior. * * @default false */ accessor defaultGraphicsLayerDisabled: boolean; /** * Default update options set for the Sketch component. Update options set on this property will be overwritten if the update options are changed * when [update()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/#update) method is called. * * @since 4.11 * @example * // Turn off highlights for update operations * const sketch = new Sketch({ * view, * defaultUpdateOptions: { * highlightOptions: { * enabled: false * } * } * }); * // Turn off highlights from the update() method * const updateOptions = { tool: "reshape", highlightOptions: { enabled: false }}; * sketch.update(graphic, updateOptions); */ accessor defaultUpdateOptions: UpdateOptions; /** * Indicates whether to hide the circle sketch tool. * * @default false * @since 5.0 */ accessor hideCreateToolsCircle: boolean; /** * Indicates whether to hide the multipoint tool. Regardless of setting, multipoint is not available when working with a scene view. * * The multipoint tool is excluded from `availableCreateTools` by default. Even if this property is false, * multipoint will not be available until it is added to `availableCreateTools`. * * @default false */ accessor hideCreateToolsMultipoint: boolean; /** * Indicates whether to hide the point sketch tool. * * @default false * @since 5.0 */ accessor hideCreateToolsPoint: boolean; /** * Indicates whether to hide the polygon sketch tool. * * @default false * @since 5.0 */ accessor hideCreateToolsPolygon: boolean; /** * Indicates whether to hide the polyline sketch tool. * * @default false * @since 5.0 */ accessor hideCreateToolsPolyline: boolean; /** * Indicates whether to hide the rectangle sketch tool. * * @default false * @since 5.0 */ accessor hideCreateToolsRectangle: boolean; /** * Indicates whether to hide the 'delete' button while a graphic is selected. Do not hide this button without giving users on touch devices another way to delete selected geometries. * * @default false * @since 5.0 */ accessor hideDeleteButton: boolean; /** * Indicates whether to hide the 'duplicate' button while a graphic is selected. * * @default false * @since 5.0 */ accessor hideDuplicateButton: boolean; /** * Indicates whether to hide the sketch labels toggle`. * * @default false * @since 5.0 */ accessor hideLabelsToggle: boolean; /** * Indicates whether to hide a label indicating the length of the currently selected feature set. * * @default false * @since 5.0 */ accessor hideSelectionCountLabel: boolean; /** @default false */ accessor hideSelectionToolsLassoSelection: boolean; /** @default false */ accessor hideSelectionToolsRectangleSelection: boolean; /** * Indicates whether to hide the settings menu. Currently this menu contains snapping options`. * * @default false * @since 5.0 */ accessor hideSettingsMenu: boolean; /** * Indicates whether to hide the `SnappingControls` component. * * @default false * @since 5.0 */ accessor hideSnappingControls: boolean; /** * Indicates whether to hide the `enabledToggle` (Enable snapping). This toggles * the [SnappingOptions#enabled](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#enabled) property. * > [!WARNING] * > * > **Note** * > * > It is recommended to set `SnappingControls.snappingOptions.enabled = true` if `enabledToggle` is set to `false`. * > This is because `selfEnabledToggle` and `featureEnabledToggle` require snapping globally to be enabled in order to be interactive. Otherwise, these toggles will not be responsive. * * @default false * @since 5.0 */ accessor hideSnappingControlsElementsEnabledToggle: boolean; /** * Indicates whether to hide the `featureEnabledToggle` (Feature to feature). This toggles * the [SnappingOptions#featureEnabled](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#featureEnabled) property. * * @default false * @since 5.0 */ accessor hideSnappingControlsElementsFeatureEnabledToggle: boolean; /** * Indicates whether to hide the `gridControls` (configuration of the snapping grid). * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridControls: boolean; /** * Indicates whether to hide the `colorSelection` within the snapping grid controls. * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridControlsElementsColorSelection: boolean; /** * Indicates whether to hide the `dynamicScaleToggle` within the snapping grid controls. * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridControlsElementsDynamicScaleToggle: boolean; /** * Indicates whether to hide the `lineIntervalInput` within the snapping grid controls. * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridControlsElementsLineIntervalInput: boolean; /** * Indicates whether to hide the `numericInputs` within the snapping grid controls. * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridControlsElementsNumericInputs: boolean; /** * Indicates whether to hide the `outOfScaleWarning` within the snapping grid controls. * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridControlsElementsOutOfScaleWarning: boolean; /** * Indicates whether to hide the `placementButtons` within the snapping grid controls. * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridControlsElementsPlacementButtons: boolean; /** * Indicates whether to hide the `rotateWithMapToggle` within the snapping grid controls. * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridControlsElementsRotateWithMapToggle: boolean; /** * Indicates whether to hide the `gridEnabledToggle` (snap-to-grid). * * @default false * @since 5.1 */ accessor hideSnappingControlsElementsGridEnabledToggle: boolean; /** * Indicates whether to hide the [FeatureSnappingLayerSource](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/FeatureSnappingLayerSource/) layerList. The layerlist provides the available layer sources supported for snapping. * * @default false * @since 5.0 */ accessor hideSnappingControlsElementsLayerList: boolean; /** * Indicates whether to hide the `selfEnabledToggle` (Geometry guides). This toggles * the [SnappingOptions#selfEnabled](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#selfEnabled) property. * * @default false * @since 5.0 */ accessor hideSnappingControlsElementsSelfEnabledToggle: boolean; /** * Indicates whether to hide the tooltips toggle`. * * @default false * @since 5.0 */ accessor hideTooltipsToggle: boolean; /** * Indicates whether to hide the undo/redo menu within the component. * * @default false * @since 5.0 */ accessor hideUndoRedoMenu: boolean; /** * Icon which represents the component. * Typically used when the component is controlled by another component (e.g. by the Expand component). * * @default "pencil" * @since 4.27 * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/) */ get icon(): Icon["icon"]; set icon(value: IconName); /** * The component's default label. * * @since 4.11 */ accessor label: string; /** * Options to configure the sketch labels shown next to each segment of the geometry being created or updated. * * > [!WARNING] * > * > **Known Limitation** * > * > Sketch labels are currently only supported when working with a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). * * @since 4.24 */ accessor labelOptions: SketchLabelOptions; /** * The [GraphicsLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GraphicsLayer/) associated with the Sketch component. The Sketch component adds new [graphics](https://developers.arcgis.com/javascript/latest/references/core/Graphic/) to this layer or can only update graphics * stored in this layer. */ accessor layer: GraphicsLayer | MapNotesLayer | null | undefined; /** * Determines the layout/orientation of the Sketch component. * * @default "horizontal" * @since 4.10 */ accessor layout: Layout; /** * A [SimpleMarkerSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleMarkerSymbol/), [PictureMarkerSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/PictureMarkerSymbol/), [PointSymbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/PointSymbol3D/), [TextSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/TextSymbol/), [CIMSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/), or [WebStyleSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/WebStyleSymbol/) used for representing the point geometry that is being drawn. [SimpleMarkerSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleMarkerSymbol/) may also be used to symbolize point features in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). However, it is recommended you use [PointSymbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/PointSymbol3D/) instead. * * > [!WARNING] * > * > **Known Limitation** * > To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance. * * The default value is the following: * ```js * { * type: "simple-marker", * style: "circle", * size: 6, * color: [255, 255, 255], * outline: { * color: [50, 50, 50], * width: 1 * } * } * ``` */ accessor pointSymbol: SketchPointSymbol; /** * A [SimpleFillSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleFillSymbol/), [PolygonSymbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/PolygonSymbol3D/), or [CIMSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/) used for representing the polygon geometry that is being drawn. [SimpleFillSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleFillSymbol/) may also be used to symbolize polygon features in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). However, it is recommended you use [PolygonSymbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/PolygonSymbol3D/) instead. * * > [!WARNING] * > * > **Known Limitation** * > To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance. * * The default value is the following: * ```js * { * type: "simple-fill", * color: [150, 150, 150, 0.2], * outline: { * color: [50, 50, 50], * width: 2 * } * } * ``` */ accessor polygonSymbol: SketchPolygonSymbol; /** * A [SimpleLineSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleLineSymbol/), [LineSymbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/LineSymbol3D/), or [CIMSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/) used for representing the polyline geometry that is being drawn. [SimpleLineSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleLineSymbol/) may also be used to symbolize polyline features in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). However, it is recommended you use [LineSymbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/LineSymbol3D/) instead. * * > [!WARNING] * > * > **Known Limitation** * > To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance. * * The default value is the following: * ```js * { * type: "simple-line", * color: [130, 130, 130], * width: 2 * } * ``` */ accessor polylineSymbol: SketchPolylineSymbol; /** * 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 the size of component elements. * * @deprecated since 5.0, use `element.visualScale` instead. * @default "m" * @since 4.32 */ accessor scale: Button["scale"]; /** * Indicates whether to display the freehandPolygon tool. * * @default false * @since 5.0 */ accessor showCreateToolsFreehandPolygon: boolean; /** * Indicates whether to display the freehandPolyline tool. * * @default false * @since 5.0 */ accessor showCreateToolsFreehandPolyline: boolean; /** * Indicates whether to display the text tool. * * @default false * @since 5.0 */ accessor showCreateToolsText: boolean; /** * Indicates whether to display the header. * * @default false * @since 5.0 */ accessor showSnappingControlsElementsHeader: boolean; /** The [SnappingOptions](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/) for sketching. It supports [self](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#selfEnabled) and [feature](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#featureEnabled) snapping. */ accessor snappingOptions: SnappingOptions; /** The current state of the component. */ get state(): State; /** * A [TextSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/TextSymbol/) used for representing the geometry that is being drawn. * * > [!WARNING] * > * > **Known Limitation** * > To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance. * * The default value is the following: * ```js * { * type: "text", * text: "hello world" * } * ``` * * @since 5.0 */ accessor textSymbol: TextSymbol; /** * Controls the appearance of the sketch component, allowing the toolbar to adapt its appearance appropriately based on context. * * Set this to `docked` for use within the Expand component, or any other situation * where Sketch is not floating within a large canvas. * * @default "floating" * @since 4.32 */ accessor toolbarKind: ToolbarKind; /** Options to configure the tooltip shown next to the cursor when creating or updating graphics. */ accessor tooltipOptions: SketchTooltipOptions; /** An array of [graphics](https://developers.arcgis.com/javascript/latest/references/core/Graphic/) that are being updated by the Sketch component. */ get updateGraphics(): Collection<Graphic>; /** * Controls whether the user can click a graphic in the layer to start updating it. * * @default false * @since 5.1 */ accessor updateOnGraphicClickDisabled: boolean; /** * Starting at version 5.0, `arcgis-sketch` is transitioning to a next generation geometry * creation experience. This new experience provides advanced curve creation tools * and allows multiple tools to be used in combination to define a single geometry. * * As of 5.0, this experience is only available in 2D (e.g. [`arcgis-map`](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-map)). * * This property is available to allow 2D applications to temporarily * opt out of this experience. * * > [!CAUTION] * > * > This option will be removed in an upcoming release. * * @deprecated * @default false * @since 5.0 */ accessor useLegacyCreateTools: boolean; /** * 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-sketch component will be associated with a map or scene component rather than using the `view` property. */ accessor view: MapViewOrSceneView | null | undefined; /** * Specifies the size of the component. * * @since 5.0 */ accessor visualScale: Button["scale"]; cancel(): Promise<void>; complete(): Promise<void>; /** * @param tool * @param createOptions */ create(tool: CreateTool, createOptions?: CreateOptions): Promise<void>; delete(): Promise<void>; /** Permanently destroy the component. */ destroy(): Promise<void>; /** * @internal * @since 5.1 */ dismissFloatingElements(): Promise<void>; duplicate(): Promise<void>; redo(): Promise<void>; /** * @param location * @internal * @since 5.1 */ setContextualToolLocation(location: "inline-end" | "inline" | "separate"): Promise<void>; /** * @param createToolOptions * @param customActionOptions * @internal * @since 5.1 */ setCustomTools(createToolOptions?: CustomToolOptions[] | null, customActionOptions?: CustomActionProperties[] | null): Promise<void>; /** * @param options * @internal * @since 5.1 */ setGroupAllowCollapseOptions(options: Map<SketchGroupName, boolean>): Promise<void>; /** * @param priorities * @internal * @since 5.1 */ setGroupCollapsePriorities(priorities: Map<SketchGroupName, number> | null): Promise<void>; /** * @param graphic * @param updateOptions */ triggerUpdate(graphic: Parameters<Sketch["update"]>[0], updateOptions?: Parameters<Sketch["update"]>[1]): Promise<void>; undo(): Promise<void>; "@setterTypes": { icon?: IconName; }; /** Fires when a user starts sketching a graphic, is actively sketching a graphic and completes sketching a graphic. */ readonly arcgisCreate: import("@arcgis/lumina").TargetedEvent<this, CreateEvent>; /** Fires when a user deletes selected graphics by clicking the Delete feature button on the Sketch widget or when the `delete()` method is called. */ readonly arcgisDelete: import("@arcgis/lumina").TargetedEvent<this, DeleteEvent>; /** Fires when the user duplicates selected graphics. */ readonly arcgisDuplicate: import("@arcgis/lumina").TargetedEvent<this, DuplicateEvent>; /** 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: "state"; }>; /** 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>; /** Fires in response to redo action during creation of a new graphic or updating existing graphics. The undo/redo stack is for an individual sketch operation, meaning you can undo/redo actions while creating or updating a graphic. */ readonly arcgisRedo: import("@arcgis/lumina").TargetedEvent<this, RedoEvent>; /** Fires in response to undo action during creation of a new graphic or updating existing graphics. The undo/redo stack is for an individual sketch operation, meaning you can undo/redo actions while creating or updating a graphic. */ readonly arcgisUndo: import("@arcgis/lumina").TargetedEvent<this, UndoEvent>; /** Fires when the user starts updating graphics, is actively updating graphics, and completes updating graphics. */ readonly arcgisUpdate: import("@arcgis/lumina").TargetedEvent<this, UpdateEvent>; readonly "@eventTypes": { arcgisCreate: ArcgisSketch["arcgisCreate"]["detail"]; arcgisDelete: ArcgisSketch["arcgisDelete"]["detail"]; arcgisDuplicate: ArcgisSketch["arcgisDuplicate"]["detail"]; arcgisPropertyChange: ArcgisSketch["arcgisPropertyChange"]["detail"]; arcgisReady: ArcgisSketch["arcgisReady"]["detail"]; arcgisRedo: ArcgisSketch["arcgisRedo"]["detail"]; arcgisUndo: ArcgisSketch["arcgisUndo"]["detail"]; arcgisUpdate: ArcgisSketch["arcgisUpdate"]["detail"]; }; }