Developing sketch tools

Using the components, classes, and methods contained within the WinForms namespace, you can build shape editing into your client application. Shape editing is centered on geometry objects and the concept of a sketch, it is not required if you are only updating the attributes of a feature. A sketch is like a temporary drawing that has tools used to create or edit geometries and can be displayed in the map with a sketchgraphiclayer. You can use the sketch to perform vertex edits on existing feature geometries by loading the shape into a specific sketch tool.

The following is a list of key features related to sketching in the WinForms namespace:

• Editing functionality is exposed as a set of classes and controls.
• All the current editing tools are available to you as MapActions. These editing map actions interact with the Map using the mouse, the stylus, or the rocker for screen digitizing or screen feedback.
• The provided map actions include the following:
  • AddVertexSketchTool—Create a new geometry
  • DeleteVertexSketchTool—Delete vertices in an existing geometry
  • InsertVertexSketchTool—Insert or move new vertices in an existing geometry
  • MoveVertexSketchTool—Move vertices in an existing geometry
• Developers can create their own sketching tools, such as a tracing tool or a copy parallel tool, by creating a new tool that inherits from the SketchTool base class.
• The SketchTool allows you to draw or digitize simple geometries or a multipart geometry, as well as polygon's shells and holes.
• Sketching supports a SnappingEnvironment.
• The drawing feedback is isolated from the sketching tool, so you can use a graphic layer type called "SketchGraphicLayer" to do the drawing for you instead of writing your own drawing feedback.

The editing sketch tools are built-in MapAction components like zoom in and pan. These tools provide the functionality of the most common tasks when editing data. Any of these tools can be associated to the Map by using the Map.MapAction property.

The Map provides an instantiated SnappingEnvironment object, which is shared with the sketch tool. The SnappingEnvironment has a list of SnappingAgents; each SnappingAgent requires a MapLayer to be constructed, and it provides two types of snapping: Vertex and Edge.

To render feedback on the screen, you must have one SketchGraphicLayer in the Map.MapGraphicLayers collection. More SketchGraphicLayers can be added to the Map, but only the first element of the list will be used by the sketching tools.

Architecture of the sketch namespace

Workflow for editing with sketch

The following steps outline the basic workflow when using the sketching tools. Specific usage and examples with code are detailed in following sections.

Steps:

1. To begin working with the sketching tools, you need to establish the editing environment and ensure the correct featuresource to edit has been specified and has the required permissions.
2. Add a SketchGraphicsLayer to the Map.MapGraphicLayers collection.

   private void map1_IsValidChanged(object sender, EventArgs e) 
   {
     if (!map1.IsValid) 
       return; 
     // Creates an instance of a SketchGraphicLayer 
     SketchGraphicLayer sketchGraphicLayer = new SketchGraphicLayer();
     // Sets the MapGraphicLayer name
     sketchGraphicLayer.LayerName = "myeditsSketchGraphicLayer";
     // Adds the SketchGraphicLayer to the collection of MapGraphicLayers 
     map1.MapGraphicLayers.Add(sketchGraphicLayer);
   }
   

3. Set up the snapping environment if required.

   private void menuItem1_Click(object sender, EventArgs e) 
   {
     // Creates a new instance of a parcels SnapAgent 
     SnappingAgent snapAgent = new SnappingAgent(mobilecache1.FeatureSources["Parcels"]); 
     // Activates the SnapAgent 
     snapAgent.Active = true; 
     // Specifies the SnappingType
     snapAgent.SnappingType = SnappingType.Vertex | SnappingType.Edge;
     // Adds the SnapAgent to the collection
     map1.SnappingEnvironment.SnappingAgents.Add(snapAgent); 
   }
   

4. If you're creating features, you must create an empty geometry of the type (polygon, line, point, or multipoint) you want to capture and set it to the SketchGraphicLayer.Geometry property. This should be the same geometry type as the layer for which you want to create features. If you're modifying an existing feature's geometry, you need to obtain that geometry via the SelectionMapAction or code, then assign the geometry to the sketchMapAction.Geometry property. The geometry will then appear as a sketch that can be modified (DeleteVertexSketchTool, InsertVertexSketchTool, MoveVertexSketchTool) in the map display.
5. Set one of the sketching tools to be the current MapAction on the map.
6. Use the mouse, stylus, or rocker to work with the sketch. For example, create a new sketch via AddVertexSketchTool or delete a few vertices of an existing geometry via DeleteVertexSketchTool.
7. Once you've finished sketching or altering an existing geometry, you have to get the geometry from the SketchMapGraphicLayer and either create a FeatureDataRow to add the new geometry, or to modify the geometry column value of an existing FeatureDataRow.

Create a sketch geometry

To create a geometry, you need to create an empty geometry of the type that matches the featuresource you're editing and set it to the SketchGraphicLayer.Geometry property.

To enable the AddVertexSketchtool, set it to the Map.MapAction property.

private void menuItem1_Click(object sender, EventArgs e)
{ 
  //Selects a specific cache layer 
  FeatureSource featureSource = mobileCache1.FeatureSources["parcels"] as FeatureSource; 
  // Sets map action to be add vertex sketch 
  map1.MapAction = addVertexSketchTool1; 
  // Get the feature geometry type 
  GeometryType geometryType = featureSource.GeometryType; 
  // Get the appropriate SketchGraphicLayer 
  SketchGraphicLayer sketchGraphicLayer = (map1.MapGraphicLayers["myeditsSketchGraphicLayer"]) as SketchGraphicLayer; 
  // Creates a new empty instance of a geometry based on 
  // the selected layer geometry type and pass it to the sketch 
  if (geometryType == GeometryType.Point)
    sketchGraphicLayer.Geometry = new ESRI.ArcGIS.Mobile.Geometries.Point();
  else if (geometryType == GeometryType.Polygon) 
    sketchGraphicLayer.Geometry = new Polygon();
  else if (geometryType == GeometryType.Polyline)
    sketchGraphicLayer.Geometry = new Polyline(); 
  else if (geometryType == GeometryType.Multipoint)
    sketchGraphicLayer.Geometry = new Multipoint(); 
}

Start digitizing

Using the input device (mouse, stylus, rocker), click or tap the location for the vertices to add. As you add new vertices, sketch segments will be drawn for polygons and polylines. For points, one click or tap will create a geometry. For multipoints, each vertex will create a point part in the sketch's geometry.

The following diagrams illustrate creating a sketch:

Polygons

Polylines

Points

Multipoints

Finish the sketch

Finishing sketching is a task that is part of every client application using the sketching tools. The following sample code shows how to finish a simple geometry:

private void menuItem1_Click(object sender, EventArgs e) 
{ 
  //Selects a specific cache layer 
  FeatureSource featureSource = mobileCache1.FeatureSources["parcels"] as FeatureSource; 
  // Get the appropriate SketchGraphicLayer
  SketchGraphicLayer sketchGraphicLayer = (map1.MapGraphicLayers["myeditsSketchGraphicLayer"]) as SketchGraphicLayer; 
  // Gets the feature layer data table schema
  FeatureDataTable featureDataTable = featureSource.GetDataTable();
  // Creates a new row 
  FeatureDataRow featureDataRow = featureDataTable.NewRow();
  // Sets the new geometry to the geometry field 
  featureDataRow[featureSource.GeometryColumnIndex] = sketchGraphicLayer.Geometry; 
  // Adds the new row to the feature layer data table 
  featureDataTable.Rows.Add(featureDataRow); 
  // Updates the feature layer data table
  featureDataTable.SaveInFeatureSource(); 
  // Clear the sketch's geometry 
  sketchGraphicLayer.Geometry = null;
}

Create multipart sketch geometry

A multipart geometry is composed of more than one part. To create a multipart, start digitizing a new sketch. When the part is done, you increment the Geometry.CurrentPartIndex. When you continue to digitize on the screen, the next part's coordinate collection is created.

The following diagrams illustrate creating multipart sketches.

Digitizing multiple shells

Digitizing a shell and hole

The following example shows how to finish a part through code:

private void menuItem1_Click(object sender, EventArgs e) 
{
  // Get the appropriate SketchGraphicLayer 
  SketchGraphicLayer sketchGraphicLayer = (map1.MapGraphicLayers["myeditsSketchGraphicLayer"]) as SketchGraphicLayer; 
  // Gets the sketch geometry 
  Geometry geometry = sketchGraphicLayer.Geometry; 
  if (geometry == null || geometry.GeometryType == GeometryType.Point) 
    return; 
  // Gets current part in the sketch's geometry 
  int partIndex = geometry.CurrentPartIndex; 
  // Creates an instance of coordinate collection 
  CoordinateCollection newPartCoordinateCollection = new CoordinateCollection();  
  // Adds the empty coordinate collection to the geometry
  geometry.Parts.Add(newPartCoordinateCollection); 
  //Increments the part index 
  partIndex++; 
  // Sets the new coordinate collection index 
  geometry.CurrentPartIndex = partIndex;
 }

Modify an existing geometry

Sketch tools are used to modify existing geometries as well as create new ones. To use these tools, you must set the SketchGraphicLayer.Geometry to an existing feature's geometry.

You can perform the following edits:

Deleting vertices

The following code passes a geometry to the SketchGraphicLayer and sets the DeleteVertexSketchTool as the Map.MapAction:

// Contains a geometry 
private Geometry m_geometry; 
private void menuItem1_Click(object sender, EventArgs e)
  {
  // Selects a specific cache layer 
  FeatureSource featureSource = mobileCache1.FeatureSources["parcels"] as FeatureSource; 
  // Sets map action to be add vertex sketch 
  map1.MapAction = deleteVertexSketchTool1; 
  // Get the appropriate SketchGraphicLayer
  SketchGraphicLayer sketchGraphicLayer = (map1.MapGraphicLayers["myeditsSketchGraphicLayer"]) as SketchGraphicLayer; 
  // // Query filter to find a specific feature by its ID 
  QueryFilter queryFilter = new QueryFilter(new int[] { 5473 });
  m_geometry = null;
  // Using a feature datareader to update features 
  using (FeatureDataReader featureDataReader = featureSource.GetDataReader(queryFilter, null)) 
  {
    while (featureDataReader.Read()) 
    // Gets the feature's geometry
    m_geometry = featureDataReader.GetGeometry();
  } 
  if (m_geometry == null)
    return; 
  // Sets the feature geometry to the SketchGraphicLayer 
  sketchGraphicLayer.Geometry = m_geometry; 
}

To use the DeleteVertexSketchTool, move your mouse or tap near the vertex you want to delete.

Inserting vertices

The following code passes a geometry to the SketchGraphicLayer and sets the InsertVertexSketchTool as the Map.MapAction:

private void menuItem1_Click(object sender, EventArgs e) 
  { 
  // Sets map action to be add vertex sketch 
  map1.MapAction = insertVertexSketchTool1;
  if (m_geometry == null)
    return;
  // Get the appropriate SketchGraphicLayer 
  SketchGraphicLayer sketchGraphicLayer = (map1.MapGraphicLayers["myeditsSketchGraphicLayer"]) as SketchGraphicLayer; 
  // Sets the feature geometry to the SketchGraphicLayer 
  sketchGraphicLayer.Geometry = m_geometry; 
}

To use the InsertVertexSketchTool, move your mouse or tap near the geometry edge where you want to insert a vertex. Once a new vertex has been introduced, this will remain active in order to move it to a specific location.

Moving vertices

The following code passes a geometry to the SketchGraphicLayer and sets the MoveVertexSketchTool as the Map.MapAction:

private void menuItem1_Click(object sender, EventArgs e) 
{
  // Sets map action to be add vertex sketch 
  map1.MapAction = moveVertexSketchTool1;
  if (m_geometry == null)
    return;
  // Get the appropriate SketchGraphicLayer 
  SketchGraphicLayer sketchGraphicLayer = (map1.MapGraphicLayers["myeditsSketchGraphicLayer"]) as SketchGraphicLayer; 
  // Sets the feature geometry to the SketchGraphicLayer 
  sketchGraphicLayer.Geometry = m_geometry; 
}

To use the MoveVertexSketchTool, move your mouse or tap near the vertex you want to move. This will remain active in order to move it to a specific location.