Public Member Functions | Properties
ShapeEditor Class Reference

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

List of all members.

Public Member Functions

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

Properties

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

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:

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.

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:

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:

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:

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

Clears the editor returning it to an empty state.

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

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
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.
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.
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.
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.
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.

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.

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

Saves the state of the class to the string.

Returns:
A string with the state or an empty string on failure.
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.

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.

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.

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

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

New API 4.9.3:
Added in version 4.9.3

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
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.

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

int ShapeEditor.AreaPrecision [get, set]

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

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

New API 4.9.3:
Added in version 4.9.3

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

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

uint ShapeEditor.FillColor [get, set]

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

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

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

Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.

Returns true if editor has changes caused by user input.

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

bool ShapeEditor.IndicesVisible [get, set]

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

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
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.

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).

string ShapeEditor.Key [get, set]

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

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

int ShapeEditor.LayerHandle [get, set]

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.

double ShapeEditor.Length [get, set]

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

Gets or sets length display mode.

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
uint ShapeEditor.LineColor [get, set]

Gets or sets line color for the shape being edited.

float ShapeEditor.LineWidth [get, set]

Gets or sets line width for the shape being edited.

Gets number of points the shape being edited has.

Gets underlying shape data without any attempt to validate it.

Gets or sets the index of currently selected vertex.

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.

Gets shape type of the shape currently being edited.

bool ShapeEditor.ShowArea [get, set]

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

bool ShapeEditor.ShowBearing [get, set]

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
bool ShapeEditor.ShowLength [get, set]

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

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

double ShapeEditor.SnapTolerance [get, set]

Gets or sets snapping tolerance in screen coordinates.

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

Gets or sets validation mode for the editor.

See tkEditorValidation enumeration for details.

bool ShapeEditor.VerticesVisible [get, set]

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

 All Classes Files Functions Enumerations Properties Events