GeometryEditor Class

GeometryEditor

class Esri::ArcGISRuntime::GeometryEditor

Allows you to create new geometries, and change existing geometries, by interacting with a MapView. More...

Header:	#include <GeometryEditor.h>
Since:	Esri::ArcGISRuntime 200.1
Inherits:	Esri::ArcGISRuntime::Object

List of all members, including inherited members

Public Functions

	GeometryEditor(QObject *parent = nullptr)
virtual	~GeometryEditor() override
bool	canRedo() const
bool	canUndo() const
void	clearGeometry()
void	clearSelection()
void	deleteSelectedElement()
Esri::ArcGISRuntime::Geometry	geometry() const
void	insertVertex(const Esri::ArcGISRuntime::Point &point)
bool	isStarted() const
bool	isVisible() const
void	moveSelectedElement(double deltaX, double deltaY)
void	moveSelectedElement(const Esri::ArcGISRuntime::Point &newPoint)
void	redo()
void	replaceGeometry(const Esri::ArcGISRuntime::Geometry &geometry)
void	rotateSelectedElement(double angle, const Esri::ArcGISRuntime::Point &origin)
void	scaleSelectedElement(double scaleX, double scaleY, const Esri::ArcGISRuntime::Point &origin)
void	selectGeometry()
void	selectMidVertex(int partIndex, int segmentIndex)
void	selectPart(int partIndex)
void	selectVertex(int partIndex, int vertexIndex)
Esri::ArcGISRuntime::GeometryEditorElement *	selectedElement() const
void	setSnapSettings(Esri::ArcGISRuntime::SnapSettings *snapSettings)
void	setTool(Esri::ArcGISRuntime::GeometryEditorTool *tool)
void	setVisible(bool visible)
Esri::ArcGISRuntime::SnapSettings *	snapSettings() const
void	start(const Esri::ArcGISRuntime::Geometry &initialGeometry)
void	start(Esri::ArcGISRuntime::GeometryType geometryType)
Esri::ArcGISRuntime::Geometry	stop()
Esri::ArcGISRuntime::GeometryEditorTool *	tool() const
void	undo()

Signals

void	canRedoChanged()
void	canUndoChanged()
void	geometryChanged()
void	isStartedChanged()
void	selectedElementChanged()
void	toolChanged()
void	visibleChanged()

Detailed Description

To use a GeometryEditor:

Set the MapView::geometryEditor property.
Call one of the start methods.
To interactively create new geometries from scratch, call start(GeometryType) passing in a GeometryType to determine the type of geometry created.
For geometry editing workflows, pass an existing Geometry into start(const Esri::ArcGISRuntime::Geometry&).
You can then edit the geometry directly on the map view using mouse or touch gestures.
The tool determines how you draw on the map to define the new geometry, for example by adding individual vertices or with a freehand gesture. The default tool is VertexTool.
If you passed in an initial geometry, it is displayed in the view, and you can interact with the geometry to make changes.
Call stop to return the geometry and prevent the geometry editor from processing any more interactions.
Geometries are immutable, therefore a new Geometry object reflecting the updates is returned from geometry and stop each time.

When started (isStarted is true), you can interact with the different GeometryEditorElement objects that compose the representation of the geometry in the map view. Depending on what is selected, different types of GeometryEditorElement are returned from selectedElement.

The type of the current tool determines how you create and edit geometries, with the current InteractionConfiguration or ReticleInteractionConfiguration allowing you to enable or disable different interactions and capabilities of the tool.

The default VertexTool allows you to create and edit geometries by interacting with individual vertices. You can tap to select the different elements and drag to move them, and also tap multiple times on an element to select the different types of GeometryEditorElement representing vertices, parts, or the entire geometry. You can rotate and scale the selected element (if applicable to the selected element type), and can also create new parts in a multipart geometry (if enabled in the InteractionConfiguration).
The FreehandTool is ideal for creating new polygon or polyline geometries using a single freehand drag gesture. It also allows multiple taps to cycle the selected element type.
The ShapeTool is ideal for creating new polygon or polyline geometries with a geometric shape by using a single drag interaction. It also allows multiple taps to cycle the selected element type.
The ReticleVertexTool is recommended for precise, vertex-based, geometry editing on touch devices, especially when using snapping (SnapSettings). It does not support multiple taps to cycle the selected element.

Programmatic changes to the geometry or selectedElement (for example calling selectVertex(int, int) or moveSelectedElement(const Esri::ArcGISRuntime::Point&)) not affected by the settings in InteractionConfiguration or ReticleInteractionConfiguration.

Change the appearance of the geometry by using the GeometryEditorStyle of the current tool - for example to match the symbology used by the graphic or feature being edited.

Enabling snapping can help ensure that interactive edits are more accurate, with fewer errors, by allowing you to create geometries that connect to each other and are coincident. Use snapSettings to configure snapping behavior.

Programmatic editing methods are also provided so you can augment your interactive geometry editing to support specific user requirements. For example:

Use insertVertex(const Esri::ArcGISRuntime::Point&) to add a subsequent vertex based on a GPS location from LocationDisplay.
Use deleteSelectedElement to delete the current selectedElement.
Use moveSelectedElement(const Esri::ArcGISRuntime::Point&) to move the currently selected GeometryEditorElement to a specific Point, or moveSelectedElement(double, double) to nudge it in a specific direction.
Use replaceGeometry(const Esri::ArcGISRuntime::Geometry&) to take the current geometry, apply an operation such as a union or intersect by using GeometryEngine, and then replace the current geometry with the result so you can continue to edit as required.
Use undo and redo to undo and redo individual interactive or programmatic edits.

Use geometryChanged and selectedElementChanged to be notified when a user interaction or API call has changed the selectedElement or geometry. Changing the geometry state can also change canUndo, which triggers canUndoChanged.

Member Function Documentation

`[explicit]` GeometryEditor::GeometryEditor(QObject **parent* = nullptr)

Creates a default GeometryEditor.

parent - The optional parent QObject.

`[override virtual]` GeometryEditor::~GeometryEditor()

Destructor.

bool GeometryEditor::canRedo() const

Returns true if there are actions that can be redone on the geometry, false otherwise.

This applies to both programmatic and interactive changes to the geometry and is useful for enabling or disabling a UI control for redo actions.

The value of canRedo changes, raising the canRedoChanged event, when:

an initial action that can be redone is performed in the GeometryEditor, or
the last remaining action that can be redone was redone

See also redo and canUndo.

`[signal]` void GeometryEditor::canRedoChanged()

Emits this signal when canRedo changes.

bool GeometryEditor::canUndo() const

Returns true if there are actions that can be undone on the geometry, false otherwise.

This applies to both programmatic and interactive changes to the geometry and is useful for enabling or disabling a UI control for undo actions.

The value of canUndo changes, raising the canUndoChanged event, when:

an initial action that can be undone is performed in the GeometryEditor, or
the last remaining action that can be undone was undone

See also undo and canRedo.

`[signal]` void GeometryEditor::canUndoChanged()

Emits this signal when canUndo changes.

void GeometryEditor::clearGeometry()

Clears the current geometry being edited.

Sets geometry to an empty geometry (Geometry::isEmpty = true). The GeometryType is maintained - to edit a different type of geometry, restart the GeometryEditor with the required type.

See also clearSelection.

void GeometryEditor::clearSelection()

Clears the current geometry being edited.

Sets geometry to an empty geometry (Geometry::isEmpty = true). The GeometryType is maintained - to edit a different type of geometry, restart the GeometryEditor with the required type.

See also clearGeometry.

void GeometryEditor::deleteSelectedElement()

Deletes the selected element from the current geometry.

To clear the selection, but leave the state of the geometry unchanged, call clearSelection instead.

Esri::ArcGISRuntime::Geometry GeometryEditor::geometry() const

Returns the current geometry, updated as you interact with the view.

The geometry returned depends on the state of the GeometryEditor:

Returns empty while isStarted is false.
Returns an empty geometry (Geometry::isEmpty is true) immediately after the GeometryEditor was started using start(Esri::ArcGISRuntime::GeometryType).
Returns the input geometry immediately after the GeometryEditor was started using start(const Esri::ArcGISRuntime::Geometry&).
Returns the current geometry while the GeometryEditor is in use (isStarted is true).

If the GeometryEditor was started by calling start(const Esri::ArcGISRuntime::Geometry&), then the geometry is returned in the same SpatialReference as the input geometry. If the input geometry spatial reference is empty, or the editor was started using start(Esri::ArcGISRuntime::GeometryType), then the geometry is returned in the spatial reference of the associated MapView. If no spatial reference is set on either input geometry or via an associated map view, then the spatial reference of the geometry will be empty.

Editing feature data that is reprojected on the fly can introduce spatial errors into the data. When accuracy is important, best practice is to use a spatial reference for the map view which matches the feature layer geometry you are editing. The ArcGIS Pro editing help topic Introduction to projection on the fly contains further advice.

The value of geometry changes, raising the geometryChanged, when:

starting or stopping the geometry editor - for example using start(Esri::ArcGISRuntime::GeometryType) or stop
performing programmatic edits - for example using insertVertex(const Esri::ArcGISRuntime::Point&) or deleteSelectedElement
performing interactive edits - for example adding or moving a vertex
undoing or redoing edits - using undo or redo

See also selectedElementChanged.

`[signal]` void GeometryEditor::geometryChanged()

Emits this signal when geometry changes.

void GeometryEditor::insertVertex(const Esri::ArcGISRuntime::Point &point)

Returns a new vertex at the specified location and inserts it after the currently selected element, or appends the point if there is nothing selected.

point - The location of the new vertex.

If geometry is empty (Geometry::isEmpty is true), the given point is added as the initial vertex, and then selected. If nothing is selected (selectedElement is empty), the point is appended to the end of the geometry, and then selected. If selectedElement is the first vertex in a part of a Multipart, the given point is inserted before the currently selected vertex, and then selected.

If geometry is a non-empty Point, this method replaces the existing point with the given point, and selects it.

bool GeometryEditor::isStarted() const

Returns true if an editing session is active, false otherwise.

When true, interactions with the view can affect the state of the geometry or selectedElement.

{start(const Esri::ArcGISRuntime::Geometry&)}, {Esri::ArcGISRuntime::GeometryEditor::start(Esri::ArcGISRuntime::GeometryType)} {start(Esri::ArcGISRuntime::GeometryType)}, {Esri::ArcGISRuntime::GeometryEditor::stop} {stop}

See also Esri::ArcGISRuntime::GeometryEditor::start(const Esri::ArcGISRuntime::Geometry&).

`[signal]` void GeometryEditor::isStartedChanged()

Emits this signal when isStarted changes.

bool GeometryEditor::isVisible() const

Returns true if the geometry is visible in the view, false otherwise.

See also GeometryEditorStyle::opacity.

void GeometryEditor::moveSelectedElement(double deltaX, double deltaY)

Moves the selected element by the specified distances along the x-axis and y-axis.

deltaX - The distance to move the selected element along the x-axis, in the units of the associated MapView spatial reference.
deltaY - The distance to move the selected element along the y-axis, in the units of the associated MapView spatial reference.

void GeometryEditor::moveSelectedElement(const Esri::ArcGISRuntime::Point &newPoint)

Moves the selected element to the specified location.

newPoint - The new location for the selected element.

If selectedElement is a GeometryEditorVertex, then the location of the vertex is moved to the given point. If the selectedElement is any other type of GeometryEditorElement, then the center of the element is moved to the given point.

void GeometryEditor::redo()

Redoes the last action undone on the geometry.

See also canRedo, undo, and canRedoChanged.

void GeometryEditor::replaceGeometry(const Esri::ArcGISRuntime::Geometry &geometry)

Replaces the current geometry with the specified geometry.

geometry - The new geometry to replace the current geometry. The GeometryType of these geometries must match.

Use this method to make changes to the geometry that are not directly supported using other GeometryEditor methods. For example, to start a new part in a Polygon or Polyline geometry, get the current geometry, use a MultipartBuilder to add the required part, and then pass the updated GeometryBuilder::toGeometry to this method.

`[since Esri::ArcGISRuntime 200.2]` void GeometryEditor::rotateSelectedElement(double angle, const Esri::ArcGISRuntime::Point &origin)

Rotates the selectedElement by the specified angle.

angle - The angle by which to rotate the selected element, counterclockwise, in degrees.
origin - The center of rotation. If empty, the center of the extent of the selectedElement is used.

The angle of rotation is used in the form of the modulo of 360 degrees; for example rotating by 540 degrees is equivalent to rotating the by 180 degrees. A positive value corresponds to a counterclockwise rotation.

If the origin Point has a different SpatialReference than the associated MapView, the point will be reprojected before the geometry is rotated, using the default transformation.

If selectedElement is a GeometryEditorVertex, or a GeometryEditorGeometry of type Point, and the origin parameter is empty (or is at the same location as the selected element), then rotating the selected element has no effect.

This function was introduced in Esri::ArcGISRuntime 200.2.

See also Esri::ArcGISRuntime::GeometryEditor::moveSelectedElement(double, double).

`[since Esri::ArcGISRuntime 200.2]` void GeometryEditor::scaleSelectedElement(double scaleX, double scaleY, const Esri::ArcGISRuntime::Point &origin)

Scales the selected element by the specified factors.

scaleX - The scale factor along the x-axis. It can be positive or negative. It cannot be 0, or a non-numeric value.
scaleY - The scale factor along the y-axis. It can be positive or negative. It cannot be 0, or a non-numeric value.
origin - The point relative to which the geometry will be scaled. If empty, or Geometry::isEmpty is true, the center of the extent of the selectedElement is used.

If the origin Point has a different SpatialReference than the associated MapView, the point will be reprojected before the geometry is rotated, using the default transformation.

Positive scale factors greater than 1 increase the size of the geometry, and positive factors between 0 and 1 reduce the size of the geometry. Negative scale factors produce a geometry reflected across the axes of the origin point. Negative factors less than -1 both reflect and increase the size of the geometry, and negative factors between -1 and 0 both reflect and reduce the size of the geometry.

This function was introduced in Esri::ArcGISRuntime 200.2.

See also Esri::ArcGISRuntime::GeometryEditor::moveSelectedElement(double, double).

void GeometryEditor::selectGeometry()

Selects the entire geometry.

When the entire geometry is selected it can be edited interactively and programmatically. For example you can move the entire geometry interactively by dragging, or call moveSelectedElement(const Esri::ArcGISRuntime::Point&) or moveSelectedElement(double, double) to move it programmatically.

When the entire geometry is selected, the GeometryEditorGeometry returned from selectedElement has a geometry equal to geometry. If the geometry is a Point, then a GeometryEditorVertex is returned from selectedElement instead, which is equivalent to the entire geometry and provides immediate access to the x,y coordinates of the selected point geometry.

See also InteractionConfiguration::setAllowGeometrySelection, clearSelection, selectVertex(int, int), selectMidVertex(int, int), and selectPart(int).

void GeometryEditor::selectMidVertex(int partIndex, int segmentIndex)

Selects mid-vertex with specified indices.

partIndex - The index of the part in the geometry editor's Multipart geometry that contains the mid-vertex to be selected. Use a value of 0 for non-multipart geometry types - Point and Multipoint.
segmentIndex - The index of segment that the mid-vertex to be selected lies on, within the given part of the geometry editor's Multipart geometry, or within the Multipoint geometry. Use a value of 0 for Point geometries.

Mid-vertices do not exist in the geometry. They exist only in the display to serve as a visual cue that new vertices can be inserted between existing vertices. Since they do not exist in the geometry, mid-vertices cannot be programmatically moved or deleted. They can be used to insert a new vertex interactively.

When a mid-vertex is selected, a GeometryEditorMidVertex is returned from selectedElement.

See also InteractionConfiguration::setAllowMidVertexSelection, clearSelection, selectVertex(int, int), selectMidVertex(int, int), and selectGeometry.

void GeometryEditor::selectPart(int partIndex)

Selects part with specified index.

partIndex - The index of the part in the geometry editor's Multipart geometry to be selected. Use a value of 0 for Multipoint geometries.

When a part of a polygon or polyline geometry is selected, a GeometryEditorPart is returned from selectedElement. If the polygon or polyline has only one part, then a GeometryEditorGeometry with a shape equivalent to the entire geometry is returned from selectedElement instead, which provides immediate access to the extent (Geometry::extent) and can be directly used in other geometry operations. If the current geometry is a Point or Multipoint, the entire geometry is selected.

When a part of a Polygon or Polyline (Multipart) geometry is selected it can be edited separately from the other parts of the geometry. For example, you can move only the selected part interactively by dragging, or call moveSelectedElement(const Esri::ArcGISRuntime::Point&) or moveSelectedElement(double, double) to move only the selected part programmatically.

See also InteractionConfiguration::setAllowPartSelection, clearSelection, selectVertex(int, int), selectMidVertex(int, int), and selectGeometry.

void GeometryEditor::selectVertex(int partIndex, int vertexIndex)

Selects vertex with specified indices.

partIndex - The index of the part that contains the vertex (point)) to be selected, within the geometry editor's Multipart geometry. Use a value of 0 for Point and Multipoint (non-multipart geometries).
vertexIndex - The index of the vertex (point) to be selected, within the given part of the geometry editor's Multipart geometry, or within the Multipoint geometry. Use a value of 0 for Point geometries.

When a vertex is selected it can be edited while all other vertices of the geometry are unchanged. For example, you can move only the selected vertex interactively by dragging, or call moveSelectedElement(const Esri::ArcGISRuntime::Point&) or moveSelectedElement(double, double) to move the selected vertex programmatically.

When a vertex is selected, a GeometryEditorVertex is returned from selectedElement.

See also InteractionConfiguration::setAllowVertexSelection, clearSelection, selectVertex(int, int), selectMidVertex(int, int), and selectGeometry.

Esri::ArcGISRuntime::GeometryEditorElement *GeometryEditor::selectedElement() const

Returns the element that is currently selected in the GeometryEditor, or nullptr if nothing is selected.

Clicking or tapping on the different visible elements of a geometry in a view allows you to select and unselect them. This property returns a different type of GeometryEditorElement depending on what is selected - a vertex (GeometryEditorVertex), a mid-vertex (GeometryEditorMidVertex), a part of a polygon or polyline (GeometryEditorPart), or the entire geometry (GeometryEditorGeometry). You can change which selection interactions are allowed by using the InteractionConfiguration of the tool.

You can also programmatically select specific vertices (selectVertex(int, int)), mid-vertices (selectMidVertex(int, int)), parts of polygons or polylines (selectPart(int)), or the entire geometry (selectGeometry). You can clear the selection using clearSelection.

The value of selectedElement changes, raising the selectedElementChanged event, when:

performing programmatic selection - for example using selectGeometry or selectVertex(int, int)
performing interactive selection - for example selecting or unselecting a GeometryEditorElement
the location of the selected element changes - for example moving the selected element programmatically or interactively
performing edits - for example inserting a vertex interactively or deleting the selected element programmatically

It may also change when:

undoing or redoing edits - using undo or redo
stopping the geometry editor using stop

`[signal]` void GeometryEditor::selectedElementChanged()

Emits this signal when selectedElement changes.

`[since Esri::ArcGISRuntime 200.4]` void GeometryEditor::setSnapSettings(Esri::ArcGISRuntime::SnapSettings **snapSettings*)

Sets the snapSettings to snapSettings.

This function was introduced in Esri::ArcGISRuntime 200.4.

See also snapSettings.

void GeometryEditor::setTool(Esri::ArcGISRuntime::GeometryEditorTool **tool*)

Sets the tool to tool.

See also tool.

void GeometryEditor::setVisible(bool visible)

Sets the visible to visible.

See also isVisible.

`[since Esri::ArcGISRuntime 200.4]` Esri::ArcGISRuntime::SnapSettings *GeometryEditor::snapSettings() const

Returns configurable options for interactive snapping.

Snapping allows you to create geometries that connect to each other and are coincident, so that interactive edits are more accurate, with fewer errors. Snapping is disabled by default - see SnapSettings for information about setting up snapping workflows.

This function was introduced in Esri::ArcGISRuntime 200.4.

See also setSnapSettings().

void GeometryEditor::start(const Esri::ArcGISRuntime::Geometry &initialGeometry)

Starts a geometry editing session based on the specified geometry.

initialGeometry - The initial geometry to start the editing session with.

Use this method for data editing workflows, where you have an existing Geometry to be updated. After calling this method, the geometry is drawn in the map view, and interactions with the map view will select and edit the geometry, depending on the current tool and its InteractionConfiguration.

When the SpatialReference of the initial geometry differs from that of the map view, the display will project the geometry to the SpatialReference of the map view, using the default DatumTransformation, for display and user interactions. Editing feature data that is reprojected on the fly can introduce spatial errors into data. When accuracy is important, best practice is to use a spatial reference for the map view which matches the feature layer geometry you are editing. The ArcGIS Pro editing help topic Introduction to projection on the fly contains further advice.

void GeometryEditor::start(Esri::ArcGISRuntime::GeometryType geometryType)

Starts a geometry editing session with an empty geometry of the specified GeometryType.

geometryType - The GeometryType of geometry to edit.

Use this method for data creation workflows, where you know the GeometryType required but do not have an existing geometry to edit. After calling this method, nothing is drawn on the map view initially - user interactions on the map view will define and edit the geometry, depending on the current tool.

GeometryEditor can be used to create Point, Multipoint, Polygon, and Polyline geometries - however FreehandTool, and ShapeTool are suitable for creating Polygon, and Polyline geometries only.

The new geometry will have the SpatialReference of the map view. You can use GeometryEngine::project(const Esri::ArcGISRuntime::Geometry&, const Esri::ArcGISRuntime::SpatialReference&) or GeometryEngine::project(const Esri::ArcGISRuntime::Geometry&, const Esri::ArcGISRuntime::SpatialReference&, Esri::ArcGISRuntime::DatumTransformation*) to project the final result geometry to a different spatial reference if required, for example when editing feature geometry. When accuracy is important, best practice is to use a spatial reference for the map view which matches the feature layer geometry you are creating. The ArcGIS Pro editing help topic Introduction to projection on the fly contains further advice.

Esri::ArcGISRuntime::Geometry GeometryEditor::stop()

Stops the editing session by making the GeometryEditor no longer respond to user interaction and clears the geometry.

See also geometry and geometryChanged.

Esri::ArcGISRuntime::GeometryEditorTool *GeometryEditor::tool() const

Returns the tool defining how you interact with the view to create and edit the geometry.

The default value is a VertexTool with all interactive operations enabled, providing a common way of editing points, multipoints, polygons, and polylines.

The tool can be replaced while a GeometryEditor is started (isStarted = true), enabling a combination of tools to be used to edit a geometry.

See also setTool(), VertexTool, FreehandTool, and ShapeTool.

`[signal]` void GeometryEditor::toolChanged()

Emits this signal when tool changes.

void GeometryEditor::undo()

Undoes the last action on the geometry.

See also canUndo, redo, and canUndoChanged.

`[signal]` void GeometryEditor::visibleChanged()

Emits this signal when isVisible changes.