ShapeEditor Class Reference

Facilitates interactive creation and editing of vector shapes. More...

Collaboration diagram for ShapeEditor:
Collaboration graph

Public Member Functions

void Clear ()
 Clears the editor returning it to an empty state. More...
 
void CopyOptionsFrom (ShapeDrawingOptions Options)
 Applies visualization options defined by ShapeDrawingOptions instance. More...
 
bool Deserialize (string state)
 Restores the state of object from the string. More...
 
string get_ErrorMsg (int ErrorCode)
 Gets the description of the specific error code. More...
 
bool get_PointXY (int pointIndex, out double x, out double y)
 Gets coordinates of specified point of edited shape. More...
 
double get_SegmentAngle (int segmentIndex)
 Returns directional angle (bearing) of a given segment of edited shape. More...
 
double get_SegmentLength (int segmentIndex)
 Gets length of a given segment of edited shape. More...
 
bool put_PointXY (int pointIndex, double x, double y)
 Sets coordinates of specified point of edited shape. More...
 
bool SaveChanges ()
 Saves any changes made by user. More...
 
string Serialize ()
 Saves the state of the class to the string More...
 
bool StartEdit (int LayerHandle, int ShapeIndex)
 Starts editing of a given shape in specified shapefile. More...
 
bool StartOverlay (tkEditorOverlay overlayType)
 Starts overlay operation for the current shape. More...
 
bool StartUnboundShape (ShpfileType ShpType)
 Initializes editor for creation of unbound shape. More...
 
bool UndoPoint ()
 Allows to undo the last vertex entered by user. More...
 

Properties

tkAngleFormat AngleFormat [get, set]
 Gets or sets angle format to be used to display bearing. More...
 
int AnglePrecision [get, set]
 Gets or sets the number of decimal degrees to be used to display bearing. More...
 
double Area [get]
 Calculates the area of polygon being edited. More...
 
tkAreaDisplayMode AreaDisplayMode [get, set]
 Gets or sets area display mode for polygon shapes. The default value is admNone. More...
 
int AreaPrecision [get, set]
 Gets or sets the number of decimal degrees to be used to display area. More...
 
tkBearingType BearingType [get, set]
 Gets or sets type of the bearing to be display for line segments. More...
 
tkEditorBehavior EditorBehavior [get, set]
 Gets or sets editor behavior during the editing of existing shape, either vertex editor or part editor. More...
 
tkEditorState EditorState [get]
 Gets the state an editor is currently in. See tkEditorState enumeration for details. More...
 
uint FillColor [get, set]
 Gets or sets fill color for the shape being edited. Applies for polygon shapes only. More...
 
byte FillTransparency [get, set]
 Gets or sets fill transparency for the shape being edited. Applies for polygon shapes only. More...
 
ICallback GlobalCallback [get, set]
 Gets or sets a Callback object which handles progress and error messages. More...
 
bool HasChanges [get]
 Returns true if editor has changes caused by user input. More...
 
tkLayerSelection HighlightVertices [get, set]
 Gets or sets value indicating whether vertices of shapes will be highlighted on mouse move when interactive editing tools are used. More...
 
bool IndicesVisible [get, set]
 Gets or sets a value indicating whether the indices of shape's vertices are visible. More...
 
bool IsDigitizing [get]
 Gets a value indicating whether a new shape is currently being created. More...
 
bool IsEmpty [get]
 Returns true if the editor is empty. More...
 
bool IsUsingEllipsoid [get]
 Gets a value indicating whether calculations are performed taking into account the shape of Earth (when map projection is defined), or on 2D plane (Euclidean geometry). More...
 
string Key [get, set]
 A text string associated with object. Any value can be stored by developer in this property. More...
 
int LastErrorCode [get]
 Gets the code of last error which took place inside this object. More...
 
int LayerHandle [get, set]
 Gets layer handle of shape currently being edited. More...
 
double Length [get]
 Gets the length of measured path (in meters if WGS84 compatible projection is set for map and in current map units otherwise). More...
 
tkLengthDisplayMode LengthDisplayMode [get, set]
 Gets or sets length display mode. More...
 
int LengthPrecision [get, set]
 Gets or sets the number of decimal degrees to be used to display length. More...
 
uint LineColor [get, set]
 Gets or sets line color for the shape being edited. More...
 
float LineWidth [get, set]
 Gets or sets line width for the shape being edited. More...
 
int numPoints [get]
 Gets number of points the shape being edited has. More...
 
Shape RawData [get]
 Gets underlying shape data without any attempt to validate it. More...
 
int SelectedVertex [get, set]
 Gets or sets the index of currently selected vertex. More...
 
int ShapeIndex [get]
 Gets index of the shape being edited. More...
 
ShpfileType ShapeType [get, set]
 Gets shape type of the shape currently being edited. More...
 
bool ShowArea [get, set]
 Gets or sets a value indicating whether area will be displayed during creation or editing of polygons. More...
 
bool ShowBearing [get, set]
 Gets or sets a value indicating whether bearing of the line segments will be displayed. More...
 
bool ShowLength [get, set]
 Gets or sets a value indicating whether length of the line segments will be displayed. More...
 
tkLayerSelection SnapBehavior [get, set]
 Gets or sets snapping behavior for Shape Editor (snaps vertices to the vertices of exiting shapes on other layers). More...
 
double SnapTolerance [get, set]
 Gets or sets snapping tolerance in screen coordinates. More...
 
Shape ValidatedShape [get]
 Validates the data stored by editor and returns it as a shape. More...
 
tkEditorValidation ValidationMode [get, set]
 Gets or sets validation mode for the editor. More...
 
bool VerticesVisible [get, set]
 Gets or sets value indicating whether vertices edited shapes are visible. More...
 

Detailed Description

Facilitates interactive creation and editing of vector shapes.

A. General:

Editor work with layers which have their Shapefile.InteractiveEditing property set to true. This may be both regular shapefile layers and OGR layers (shapefile buffer is accessible via OgrLayer.GetBuffer property for them).
In case of OGR layers some other preconditions must also be met to ensure that the changes can be saved back to datasource (see OgrLayer.get_SupportsEditing) even if the interactive editing itself is working.

Each AxMap control has a single instance of shape editor associated with it available by AxMap.ShapeEditor property.
To start editing operation it's enough to set appropriate tool to AxMap.CursorMode property. The following editing tools are currently available:

  • cmAddShape,
  • cmEditShape,
  • cmMoveShapes,
  • cmRotateShapes,
  • cmSplitByPolyline,
  • cmSplitByPolygon,
  • cmEraseByPolygon,
  • cmClipByPolygon.

B. Internal data storage.

Editor can store points and parts of only a single shape at a time. It supports all major shape types: points, multipoints, polylines, polygons. Points entered by user with mouse are stored in internal buffer which can be accessed with ShapeEditor.RawData property.
The data can be validated with ShapeEditor.ValidatedShape. All built-in tools perform validation before saving a new shape to the layer. If validation fails AxMap.ShapeValidationFailed event will be fired to notify the user. Invalid data can be be discarded by pressing Esc button or by calling ShapeEditor.Clear.
This validation behavior will also prevent changing the active tool (AxMap.CursorMode) while the editing operation is in progress.

The rendering of the point data is carried out independently of the layer. Visualization options can be changed by ShapeEditor.FillColor, ShapeEditor.LineColor, ShapeEditor.FillTransparency. When editing of a new shape starts this properties will automatically be set with the values from the parent layer, so the shape being edited will look similar to its layer. To force redraw of the editor programatically it's enough to call AxMap.Redraw2 with RedrawDynamicTools parameter.

C. Creation of new shapes.

  • activated by settings AxMap.CursorMode = cmAddShape;
  • only creation of single part shapes supported;
  • layer to add the shape to is determined after the first mouse click by handling AxMap.ChooseLayer event;
  • new points can be added by left mouse button;
  • previous points can be removed by Ctrl+Z shortcut;
  • newly entered points by default are snapped to the vertices of exiting shapes (see ShapeEditor.SnapBehavior);
  • to finish the creation of shape Ctrl + left mouse click is used;
  • if the data passes validation, a new shape will automatically be inserted to the specified layer;

D. Editing of vertices and parts.

The data from existing shapes during the editing is copied to the editor while the original shape is hidden by setting Shapefile.set_ShapeIsHidden to true. After editing is finished and data in ShapeEditor is successfully validated original shape is substituted with this new data. If the changes are discarded then Shapefile.set_ShapeIsHidden property of the original shape is simply set to false.

Editing mode can be activated by settings AxMap.CursorMode = cmEditShape. Clicking on a shape from any layer with interactive editing enabled will start editing session for this shape. After clicking on blank spot of the map without shapes an attempt to validate the shape and save the changes will be made. Vertices of shapes available for editing are highlighted under mouse cursor (ShapeEditor.HighlightVertices).

cmEditShape cursor supports 2 behaviors which can be set by ShapeEditor.EditorBehavior property:

  • vertex editor - adding, moving, deleting of vertices; moving a shape as a whole;
  • part editor - moving and deleting of separate shape parts.

To add new parts to the shape or create holes in polygon, ShapeEditor.StartOverlay method can be used. It allows user to digitize a new polygon which afterwards will be overlayed with original shape in either union (eoAddPart) or difference mode (eoRemovePart).

E. Polyline and polygon overlays:

Overlays a single vector layer with custom digitized polygon or polyline. Currently the following tools of this type are available:

  • cmSplitByPolyline - splits polylines or polygons into multiple shapes;
  • cmSplitByPolygon - can be used to create a whole in polygon and a separate polygon shape to fill this hole;
  • cmEraseByPolygon - shapes and parts of shapes that intersect with the polygon will be removed from the layer;
  • cmClipByPolygon - only parts of shapes that intersect the polygon will remain, all other shapes will be removed.

At first the tools work like cmAddShape tool, i.e. allow to digitize either polyline or polygon. After it's finished (Ctrl + left mouse button) and the newly digitized shape is checked for validity, AxMap.ChooseLayer event will be fired. If the layer handle provided by user in this event represents vector layer in interactive editing mode, then the requested operation will be performed on this layer.

F. Group operations.

These operations work on a number of selected shapes within a single layer. The layer can be selected by handing AxMap.ChooseLayer event.

Currently there are 2 built-in tools available:

  • cmRotateShapes - can rotate selected shapes around the centre of the bounding box;
  • cmMoveShapes - can move selected shapes.

Technically group operations aren't related to the ShapeEditor class, however they are mentioned here to cover all the available tools.

G. Undo list.

All the operations performed by user are registered in so called Undo list (AxMap.UndoList). User can revert them (Ctrl+Z or UndoList.Undo) or apply once again (Ctrl+Shift+Z or UndoList.Redo). When interactive editing session is taking place no other editing must be done programatically without registering in the Undo list. Otherwise Undo list will become invalid.

Note
The fully working implementation of the shape editor can be examined in the the Demo application included in MapWinGIS installation (starting from v4.9.3). The source code for this application is available in the repository.
New API 4.9.3:
Added in version 4.9.3

Member Function Documentation

◆ Clear()

void ShapeEditor.Clear ( )

Clears the editor returning it to an empty state.

The method will discard any changes made to the shape being edited.

◆ CopyOptionsFrom()

void ShapeEditor.CopyOptionsFrom ( ShapeDrawingOptions  Options)

Applies visualization options defined by ShapeDrawingOptions instance.

This method can be used to make the editor look consistent with the way subject shape looks in regular mode.

Parameters
OptionsInstance of visualization options.
See also
Shapefile.DefaultDrawingOptions

◆ Deserialize()

bool ShapeEditor.Deserialize ( string  state)

Restores the state of object from the string.

Parameters
stateA string generated by ShapeEditor.Serialize() method
Returns
True on success.

◆ get_ErrorMsg()

string ShapeEditor.get_ErrorMsg ( int  ErrorCode)

Gets the description of the specific error code.

Parameters
ErrorCodeThe error code returned by LastErrorCode property.
Returns
String with the description.

◆ get_PointXY()

bool ShapeEditor.get_PointXY ( int  pointIndex,
out double  x,
out double  y 
)

Gets coordinates of specified point of edited shape.

Parameters
pointIndexIndex of point.
xX in projected map coordinates.
yY in projected map coordinates.
Returns
True if index of point within bounds.

◆ get_SegmentAngle()

double ShapeEditor.get_SegmentAngle ( int  segmentIndex)

Returns directional angle (bearing) of a given segment of edited shape.

Parameters
segmentIndexSegment index to calculate angle for.
Returns
Angle in degrees.

◆ get_SegmentLength()

double ShapeEditor.get_SegmentLength ( int  segmentIndex)

Gets length of a given segment of edited shape.

Parameters
segmentIndexSegment index to calculate length for.
Returns
Length of segment in meters.

If map projection is set and compatible with WGS84 geodesic distance will be returned. Otherwise Euclidean geometry will be used.

◆ put_PointXY()

bool ShapeEditor.put_PointXY ( int  pointIndex,
double  x,
double  y 
)

Sets coordinates of specified point of edited shape.

Parameters
pointIndexIndex of point.
xX in projected map coordinates.
yY in projected map coordinates.
Returns
True if index of point within bounds.

◆ SaveChanges()

bool ShapeEditor.SaveChanges ( )

Saves any changes made by user.

The editor will try to validate underlying shape on this call. If validation succeeds the changes will be passed to the original shapefile or other actions defined by current interactive tool will be triggered. Depending on editor state the actions will be:

  • esDigitize: new shape will be added to the shapefile set by ShapeEditor.LayerHandle property;
  • esEdit: shapefile will be updated with modified version of shape;
  • esDigitizeUnbound: a tool which started the unbound mode execute the appropriate action (clipping, selection by polygon, etc.);
  • esOverlay: current overlay operation (i.e. eoAddPart or eoRemovePart) will be discarded, editor will return in esEdit state after which an attempt will be made to validate and save shape in regular manner.
Returns
True on success.
See also
AxMap.CursorMode, ShapeEditor.EditorState

◆ Serialize()

string ShapeEditor.Serialize ( )

Saves the state of the class to the string

Returns
A string with the state or an empty string on failure.

◆ StartEdit()

bool ShapeEditor.StartEdit ( int  LayerHandle,
int  ShapeIndex 
)

Starts editing of a given shape in specified shapefile.

Parameters
LayerHandleLayer handle of the shapefile.
ShapeIndexIndex of shape to edit.
Returns
True on success.

The method will populate the editor with vertices of specified shape, hide original shape with Shapefile.put_ShapeIsHidden and set ShapeEditor.EditorState to esEdit.

◆ StartOverlay()

bool ShapeEditor.StartOverlay ( tkEditorOverlay  overlayType)

Starts overlay operation for the current shape.

Editor must be in esEdit state already, i.e. ShapeEditor.StartEdit must be called first.

Parameters
overlayTypeType of overlay operation.
Returns
True on success.

◆ StartUnboundShape()

bool ShapeEditor.StartUnboundShape ( ShpfileType  ShpType)

Initializes editor for creation of unbound shape.

Unbound shape is the one which is not linked to particular shapefile. This method is used internally by a number of built-in tools, like cmSelectByPolygon or cmSplitByPolyline.

Parameters
ShpTypeType of shape to be created.
Returns
True on success.

◆ UndoPoint()

bool ShapeEditor.UndoPoint ( )

Allows to undo the last vertex entered by user.

The method works when new shape is being created, i.e. ShapeEditor.IsDigitizing return true.

Returns
True on success, false if the editor is empty and there is no points to undo.

Property Documentation

◆ AngleFormat

tkAngleFormat ShapeEditor.AngleFormat
getset

Gets or sets angle format to be used to display bearing.

New API 4.9.3:
Added in version 4.9.3

◆ AnglePrecision

int ShapeEditor.AnglePrecision
getset

Gets or sets the number of decimal degrees to be used to display bearing.

This setting is not used when AngleFormat is set to minutes or seconds.

New API 4.9.3:
Added in version 4.9.3

◆ Area

double ShapeEditor.Area
get

Calculates the area of polygon being edited.

Precise calculations on ellipsoid will be used if map projection is set and compatible with WGS84. Otherwise simply Euclidean geometry will be used.

◆ AreaDisplayMode

tkAreaDisplayMode ShapeEditor.AreaDisplayMode
getset

Gets or sets area display mode for polygon shapes. The default value is admNone.

◆ AreaPrecision

int ShapeEditor.AreaPrecision
getset

Gets or sets the number of decimal degrees to be used to display area.

New API 4.9.3:
Added in version 4.9.3

◆ BearingType

tkBearingType ShapeEditor.BearingType
getset

Gets or sets type of the bearing to be display for line segments.

New API 4.9.3:
Added in version 4.9.3

◆ EditorBehavior

tkEditorBehavior ShapeEditor.EditorBehavior
getset

Gets or sets editor behavior during the editing of existing shape, either vertex editor or part editor.

◆ EditorState

tkEditorState ShapeEditor.EditorState
get

Gets the state an editor is currently in. See tkEditorState enumeration for details.

◆ FillColor

uint ShapeEditor.FillColor
getset

Gets or sets fill color for the shape being edited. Applies for polygon shapes only.

◆ FillTransparency

byte ShapeEditor.FillTransparency
getset

Gets or sets fill transparency for the shape being edited. Applies for polygon shapes only.

◆ GlobalCallback

ICallback ShapeEditor.GlobalCallback
getset

Gets or sets a Callback object which handles progress and error messages.

Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.

◆ HasChanges

bool ShapeEditor.HasChanges
get

Returns true if editor has changes caused by user input.

◆ HighlightVertices

tkLayerSelection ShapeEditor.HighlightVertices
getset

Gets or sets value indicating whether vertices of shapes will be highlighted on mouse move when interactive editing tools are used.

◆ IndicesVisible

bool ShapeEditor.IndicesVisible
getset

Gets or sets a value indicating whether the indices of shape's vertices are visible.

◆ IsDigitizing

bool ShapeEditor.IsDigitizing
get

Gets a value indicating whether a new shape is currently being created.

The property will return true is ShapeEditor is either in esDigitize, esDigitizeUnbound or esOverlay states.

See also
ShapeEditor.EditorState

◆ IsEmpty

bool ShapeEditor.IsEmpty
get

Returns true if the editor is empty.

Empty means that its underlying shape object has no points. However ShapeEditor.EditorState can be different from esNone.

◆ IsUsingEllipsoid

bool ShapeEditor.IsUsingEllipsoid
get

Gets a value indicating whether calculations are performed taking into account the shape of Earth (when map projection is defined), or on 2D plane (Euclidean geometry).

◆ Key

string ShapeEditor.Key
getset

A text string associated with object. Any value can be stored by developer in this property.

◆ LastErrorCode

int ShapeEditor.LastErrorCode
get

Gets the code of last error which took place inside this object.

◆ LayerHandle

int ShapeEditor.LayerHandle
getset

Gets layer handle of shape currently being edited.

This property will be set automatically by ShapeEditor.StartEdit method, and reverted back to -1 value by ShapeEditor.Clear or ShapeEditor.SaveChanges methods.

◆ Length

double ShapeEditor.Length
get

Gets the length of measured path (in meters if WGS84 compatible projection is set for map and in current map units otherwise).

◆ LengthDisplayMode

tkLengthDisplayMode ShapeEditor.LengthDisplayMode
getset

Gets or sets length display mode.

◆ LengthPrecision

int ShapeEditor.LengthPrecision
getset

Gets or sets the number of decimal degrees to be used to display length.

New API 4.9.3:
Added in version 4.9.3

◆ LineColor

uint ShapeEditor.LineColor
getset

Gets or sets line color for the shape being edited.

◆ LineWidth

float ShapeEditor.LineWidth
getset

Gets or sets line width for the shape being edited.

◆ numPoints

int ShapeEditor.numPoints
get

Gets number of points the shape being edited has.

◆ RawData

Shape ShapeEditor.RawData
get

Gets underlying shape data without any attempt to validate it.

◆ SelectedVertex

int ShapeEditor.SelectedVertex
getset

Gets or sets the index of currently selected vertex.

◆ ShapeIndex

int ShapeEditor.ShapeIndex
get

Gets index of the shape being edited.

This property will be set automatically by ShapeEditor.StartEdit method, and reverted back to -1 value by ShapeEditor.Clear or ShapeEditor.SaveChanges methods.

◆ ShapeType

ShpfileType ShapeEditor.ShapeType
getset

Gets shape type of the shape currently being edited.

◆ ShowArea

bool ShapeEditor.ShowArea
getset

Gets or sets a value indicating whether area will be displayed during creation or editing of polygons.

◆ ShowBearing

bool ShapeEditor.ShowBearing
getset

Gets or sets a value indicating whether bearing of the line segments will be displayed.

New API 4.9.3:
Added in version 4.9.3

◆ ShowLength

bool ShapeEditor.ShowLength
getset

Gets or sets a value indicating whether length of the line segments will be displayed.

New API 4.9.3:
Added in version 4.9.3

◆ SnapBehavior

tkLayerSelection ShapeEditor.SnapBehavior
getset

Gets or sets snapping behavior for Shape Editor (snaps vertices to the vertices of exiting shapes on other layers).

◆ SnapTolerance

double ShapeEditor.SnapTolerance
getset

Gets or sets snapping tolerance in screen coordinates.

◆ ValidatedShape

Shape ShapeEditor.ValidatedShape
get

Validates the data stored by editor and returns it as a shape.

◆ ValidationMode

tkEditorValidation ShapeEditor.ValidationMode
getset

Gets or sets validation mode for the editor.

See tkEditorValidation enumeration for details.

◆ VerticesVisible

bool ShapeEditor.VerticesVisible
getset

Gets or sets value indicating whether vertices edited shapes are visible.