Working with the edit sketch (ArcObjects .NET 10.4 SDK)

Summary

This topic outlines requirements and programming techniques to support robust and efficient manipulation of the edit sketch. The discussion includes simplifying the sketch, proper notification of changes to the edit sketch, and working with vertex attributes, such as m-values (measures) and z-values.

Accessing the edit sketch

The edit sketch is a temporary geometry used in conjunction with the editor's EditTasks and in some cases, the editor's CurrentLayer to complete an operation. If you are building new tools to create, edit, or select features inside an edit session, the edit sketch is a useful construct to help accomplish these tasks. To access the edit sketch, obtain a reference from the editor. See the following code example:

[C#]

UIDClass edUID=new UIDClass();
edUID.Value="esriEditor.Editor";
m_editor=m_application.FindExtensionByCLSID(edUID)as IEditor;

IEditSketch3 edSketch=m_editor as IEditSketch3;

[VB.NET]

Dim uID As New UID
uID.Value="esriEditor.Editor"
editor=m_application.FindExtensionByCLSID(uID)

'Make sure you have the editor before casting.
Private editSketch3 As IEditSketch3
If editor Is Nothing Then Exit Sub
editSketch3=editor

Displaying the edit sketch

The editor offers a great deal of flexibility in how the edit sketch displays. The simplest way to customize the edit sketch is to define your symbology for the edit sketch vertices and segments. The edit sketch vertices can be changed through the following properties:

The edit sketch segments' symbology is modified through IEditProperties.SketchSymbol. See the following illustration:

Illustration showing the edit sketch symbology.

How the edit sketch shows on the display is dependent on the context in which the edit sketch is used. For example, if you are creating a line or polygon feature, or modifying a line or polygon feature, you can display it using the values defined by the renderer to display the geometry. How the new or modified feature displays is usually determined by IEditProperties4.UseWYSIWYGSketchSymbol.

Based on this property, if the edit sketch displays using renderer symbology, there are methods to manage the display of the sketch in this manner. In most cases, the first step is to set up the edit sketch to use a specific symbol using IEditSketch3.SetWYSIWYGSketchSymbol.

Each segment of the edit sketch uses the outline of the specified symbol and in the case of a polygon, the fill color of the symbol is also used to shade the polygon's interior. At any time, you can query the edit sketch to determine whether the sketch is using a specific symbol through IEditSketch3.SketchSymbolIsWYSIWYG and the symbol being used via IEditSketch3.WYSIWYGSketchSymbol. If you want to clear the symbol used to display the sketch, call IEditSketch3.CLearWYSIWYGSketchSymbol.

In other cases, where the sketch is just a temporary geometry used to complete a given operation, it can display as a generic set of segments and vertices.

Working with the operation stack

In many cases, working with the edit sketch involves a number of individual edits before the sketch is committed; this is particularly true when creating features from the edit sketch. When performing a series of edits to an edit sketch, each edit can be placed inside a SketchOperationClass. Each sketch operation is placed on the application's operation stack so users can undo and redo individual sketch operations instead of being forced to discard the sketch. Once the sketch is finished, these operations are removed from the stack. See the following code example:

[C#]

void CreateSketchFromEnvelope(IEditor m_Editor)
{
    //Grab the envelope from the active view.
    IActiveView aView=m_editor.Map as IActiveView;
    IEnvelope env=aView.Extent;
    IEditSketch3 edSketch=m_editor as IEditSketch3;
    if (edSketch.GeometryType == esriGeometryType.esriGeometryPolyline)
    {
        //Start a sketch operation and insert the new envelope into the sketch.
        ISketchOperation2 sketchOp=new SketchOperationClass();
        sketchOp.Start(m_editor);
        ISegmentCollection segColl=new PolylineClass();
        segColl.SetRectangle(env);
        edSketch.Geometry=segColl as IGeometry;
        sketchOp.Finish(aView.Extent,
            esriSketchOperationType.esriSketchOperationGeneral, null);
    }

[VB.NET]

Private Sub CreateSketchFromEnvelope(ByVal m_editor As IEditor)
    'Grab the envelope from the active view.
    Dim aView As IActiveView=m_editor.Map
    Dim env As IEnvelope=aView.Extent
    Dim edSketch As IEditSketch3=m_editor
    
    If edSketch.GeometryType=esriGeometryType.esriGeometryPolyline Then
        'Start a sketch operation and insert the new envelope into the sketch.
        Dim sketchOp As ISketchOperation2=New SketchOperationClass
        sketchOp.Start(m_editor)
        
        Dim segColl As ISegmentCollection=New PolylineClass
        segColl.SetRectangle(env)
        edSketch.Geometry=segColl
        sketchOp.Finish(aView.Extent, esriSketchOperationType.esriSketchOperationGeneral, Nothing)
    End If
End Sub

It is not necessary to encapsulate calls to IEditsketch.AddPoint inside a sketch operation; this is done automatically.

Defining the edit sketch geometry

In most cases, the edit sketch geometry is defined by the current task; however, there are often circumstances where it is important to manipulate the sketch based on its geometry type. In some cases, when developing a tool to update the edit sketch, you can choose to set the geometry's type to esriGeometryTypeNull. This effectively ensures that the sketch tools are unavailable to the user.

Adding points to the edit sketch

Adding points to the edit sketch to define a geometry is one of the most common customizations of the edit sketch. The primary method is IEditSketch.AddPoint; although, you can modify the sketch by replacing the entire edit sketch geometry via IEditSketch.Geometry.

Modifying the edit sketch

Some considerations should be made when modifying the edit sketch. As previously mentioned, any modification to the sketch geometry should be encapsulated inside a sketch operation. In addition, as a responsible client, it is imperative that you notify other clients listening to editing events that the edit sketch geometry has changed.

Use ISketchOperation2 to supply an object that supports IPoint and the operation type results in firing the proper method. If you specify the SketchOperationType, ensure the proper event is fired. This is usually done by calling the VertexAdded, VertexDeleted, or VertexMoved methods on IEditSketch3. See the following code example:

[C#]

void RemoveLastPointInSketch(IEditSketch3 edSketch)
{
    if (edSketch == null)
        return ;

    IPointCollection4 ptColl=edSketch.Geometry as IPointCollection4;

    ISketchOperation2 sketchOp=new SketchOperationClass();
    sketchOp.Start(m_editor);

    IPoint pt=ptColl.get_Point(ptColl.PointCount - 1);
    ptColl.RemovePoints(ptColl.PointCount - 1, 1);

    sketchOp.MenuString="Remove last point";
    edSketch.Geometry=ptColl as IGeometry;
    sketchOp.Finish(edSketch.Geometry.Envelope,
        esriSketchOperationType.esriSketchOperationVertexDeleted, pt);
}

[VB.NET]

Private Sub RemoveLastPointInSketch(ByVal edSketch As IEditSketch3)
    If edSketch Is Nothing Then
        Exit Sub
    End If
    
    Dim ptColl As IPointCollection4=edSketch.Geometry
    Dim sketchOp As ISketchOperation2=New SketchOperationClass
    
    sketchOp.Start(m_editor)
    
    Dim pt As IPoint=ptColl.Point(ptColl.PointCount - 1)
    ptColl.RemovePoints(ptColl.PointCount - 1, 1)
    sketchOp.Finish(edSketch.Geometry.Envelope, esriSketchOperationType.esriSketchOperationVertexDeleted, pt)
End Sub

Working with selected vertices

The edit sketch supports the concept of selected vertices. Vertices can be selected on the current edit sketch by either:

Dragging an envelope over a portion of the edit sketch in the map
Setting the checkboxes in the sketch properties window
Programmatically creating a selection of vertices in the sketch

Working with the vertex selection requires the use of the part and vertex indices in the edit sketch geometry. Remember, each time the sketch geometry is modified, this index can change. To select or unselect a specific vertex, use IEditSketch3.SelectVertex or IEditSketch3.UnselectVertex. To unselect all vertices, use IEditSketch3.ClearSelectedVertices.

Attribute awareness

In addition to x,y coordinates information, a given point or vertex can contain information used for measures (m-coordinate) and elevation values (z-coordinate). When working with features in the edit sketch, it is important to understand the awareness of the sketch as well as any points you insert into the sketch. To address this issue, you need to understand whether the sketch is z-aware or m-aware. With this information, you can take the appropriate steps to ensure that the sketch geometry has the appropriate awareness and that its vertices have an appropriate value. In many cases, when you are creating a feature, you need to key off the editor's CurrentLayer to set the awareness.

The awareness of the sketch can be ascertained by using IEditSketch3.MAware and IEditSketch3.ZAware properties.

When adding points to the sketch via IEditSketch3.AddPoint, the editor automatically defines the z-value of the new point if it is undefined (not a number [NaN]). In this case, the new point's z-coordinate value is derived from the editor's CurrentZ property.

Finishing the edit sketch

Before committing the edit sketch, ensure the sketch geometry is considered simple. This is especially important when creating features as the system expects to retrieve and work with simple geometries.

The following code example shows how to simplify a geometry:

[C#]

IGeometry SimplifyGeometry(IGeometry geom)
{
    if (geom == null)
        return null;

    ITopologicalOperator2 topoOp=geom as ITopologicalOperator2;
    topoOp.IsKnownSimple_2=false;

    switch (geom.GeometryType)
    {
        case esriGeometryType.esriGeometryPolygon:
            {
                IPolygon poly=(IPolygon)geom;
                poly.SimplifyPreserveFromTo();
                return poly;
            }
        case esriGeometryType.esriGeometryPolyline:
            {
                IPolyline polyLineGeom=(IPolyline)geom;
                polyLineGeom.SimplifyNetwork();
                return polyLineGeom;
            }
        default:
            {
                topoOp.Simplify();
                return (IGeometry)topoOp;
            }
    }
}

[VB.NET]

Private Function SimplifyGeometry(ByVal geom As IGeometry) As IGeometry
    If geom Is Nothing Then Return Nothing
    
    Dim topoOp As ITopologicalOperator2=geom
    topoOp.IsKnownSimple_2=False
    
    Select Case geom.GeometryType
        Case esriGeometryType.esriGeometryPolygon
            Dim poly As IPolygon=geom
            poly.SimplifyPreserveFromTo()
            Return poly
        Case esriGeometryType.esriGeometryPolyline
            Dim polyLineGeom As IPolyline=geom
            polyLineGeom.SimplifyNetwork()
            Return polyLineGeom
        Case Else
            Return Nothing
    End Select
    
    topoOp.Simplify()
    geom=topoOp
    Return topoOp
End Function

To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):

Additional Requirements

The code examples in this topic assumes you have one or more editable polyline feature classes and an active edit session.

Development licensing	Deployment licensing
ArcGIS for Desktop Basic	ArcGIS for Desktop Basic
ArcGIS for Desktop Standard	ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced	ArcGIS for Desktop Advanced