Tag Archives: Add-in

If you are writing a custom tool in ArcMap to select features or create geometry a certain way, then you’ll often need to make it snap to existing features on the map. In the past, snapping was restricted to editing and was somewhat cumbersome for developers to implement. However, ArcGIS 10 provides the ArcGIS Snapping Environment, which offers users a simplified experience in ArcGIS Desktop or ArcGIS Engine and gives developers a straightforward application programming interface (API) to enable snapping in custom tools. This blog entry introduces you to the snapping API and provides sample code that demonstrates how you can incorporate snapping into your own tools.

To implement snapping in a tool, there are two options available depending upon if the tool will be used while editing. If your tool will be used both inside and outside an edit session, you can implement snapping directly by going through the snapping extension. If your tool will be used exclusively within an edit session, you can access snapping indirectly through the Editor object, which takes care of most of the initialization work for you.

Implementing snapping via the extension
First, I am going to show you how to access the snapping environment directly using its extension. This is applicable for a tool that can be used both inside and outside of an edit session. To demonstrate this, I develop a simple tool that reports the x,y location of a mouse click at its snapped location.

I start by creating a tool add-in by following the directions from the SDK help topic, Building add-ins for ArcGIS Desktop. Then, with the help of Working with the ArcGIS snapping environment, I add the code required to enable snapping in the tool. After adding a reference to the ESRI Controls assembly, I can access and initialize the snapping environment in my tool’s Click event. For add-in tools, this event is the OnActivate method.

Next, I can use the cursor location returned from the tools MouseMove event and determine if it actually snaps to anything. If it does, then I update a variable with the snapped position.

The complete code sample is shown below.

using ESRI.ArcGIS.Controls;

using
ESRI.ArcGIS.esriSystem;
using ESRI.ArcGIS.Geometry;

namespace
ToolWithSnapping

{

public
class
ShowMapCoordinates : ESRI.ArcGIS.Desktop.AddIns.Tool

{

ISnappingEnvironment m_SnappingEnv;

IPointSnapper m_Snapper;

ISnappingFeedback m_SnappingFeedback;

IPoint m_Position;

public ShowMapCoordinates()

{

}

Protected override
void OnActivate()

{

//Get the snap environment and initialize the feedback

UID snapUID = new
UID();

snapUID.Value =
“{E07B4C52-C894-4558-B8D4-D4050018D1DA}”;

m_SnappingEnv = ArcMap.Application.

FindExtensionByCLSID(snapUID) as
ISnappingEnvironment;

m_Snapper =
m_SnappingEnv.PointSnapper;

m_SnappingFeedback = new
SnappingFeedbackClass();

m_SnappingFeedback.Initialize(ArcMap.Application,
m_SnappingEnv, true);

}

protected override
void OnMouseMove(MouseEventArgs
arg)

{

//Get the current position in map units

//This is the cursor location before snapping

m_Position
= ArcMap.Document.ActiveView.

ScreenDisplay.DisplayTransformation.ToMapPoint(arg.X, arg.Y);

ISnappingResult snapResult =
null;

//Try to snap the current position

snapResult
= m_Snapper.Snap(m_Position);

m_SnappingFeedback.Update(snapResult, 0);

if (snapResult != null)

//Snapping occurred

//Set the current position to the snapped location

m_Position = snapResult.Location;

}

protected override
void OnMouseDown(MouseEventArgs
arg)

{

System.Windows.Forms.MessageBox.Show(“Map units:rnX: “

+ m_Position.X.ToString() + “rnY: “ +
m_Position.Y.ToString());

}

protected override
void OnRefresh(int
hDC)

{

if (m_SnappingFeedback !=
null)

m_SnappingFeedback.Refresh(hDC);

}

}

}

In my code, the variable m_Position holds the snapped position of the cursor. If my tool were creating geometry or updating screen feedback (such as with INewLineFeedback), then I would use the m_Position variable rather than the mouse position (MouseEventArgs) as the update point.

Implementing snapping in an edit session
As I mentioned before, if you are developing a tool that will be used exclusively in an edit session, implement snapping with the help of the Editor object. The main advantage of doing this is that the Editor will work with either the ArcGIS Snapping Environment or editing classic snapping, but only in an edit session, of course. Classic snapping refers to the snapping functionality that was available during an edit session in ArcGIS 9 and allows you to set up snapping in a more complex manner on a layer-by-layer basis. The ArcGIS Engine edit sketch and any custom tools that derive it are limited to the classic snapping environment.

Generally speaking, there two types of Editor tools you can build: those that use the edit sketch and those that don’t. You would typically use the edit sketch in a tool if you wanted to use the sketch to help you create some geometry or feedback on the screen. You can then take that geometry and use it as the basis to create a feature with it or use it for selections. If you are creating an ArcMap tool that uses the edit sketch, you don’t have to worry about snapping at all since the Editor handles it entirely for you. The edit sketch also comes with its own context menu (the one used by the Polygon or Line construction tools) and shape constructors, so it’s convenient for developers. In ArcGIS 10, you can only build a tool that uses the edit sketch through COM, which creates a .dll.

If you are not using the edit sketch in your tool, which is most likely because it doesn’t provide the geometry you need, then there is a bit more work involved because you have to create your own geometry using mouse clicks and implement snapping yourself. This type of tool can be made into an add-in or COM .dll.

For the sample code, I’ll use the same example of an add-in tool that reports the x,y position of the snapped location. In this case, I only have to reference the Editor and not the Controls assembly to enable snapping.

using
System;

using
ESRI.ArcGIS.Editor;

using
ESRI.ArcGIS.Geometry;

namespace
ToolWithSnappingES

{

public
class
ShowMapCoordinatesES : ESRI.ArcGIS.Desktop.AddIns.Tool

{

IEditor m_Editor =
null;

IPoint m_Position =
null;

public ShowMapCoordinatesES()

{

m_Editor =
ArcMap.Application.FindExtensionByName(“esriEditor.Editor”)
as IEditor;

}

protected override
bool OnDeactivate()

{

if (m_Position != null)

m_Editor.InvertAgent(m_Position, 0);

m_Position
= null;

return true;

}

protected override
void OnMouseMove(MouseEventArgs
arg)

{

if (m_Position != null)

m_Editor.InvertAgent(m_Position, 0);

m_Position
= m_Editor.Display.DisplayTransformation.ToMapPoint(arg.X, arg.Y);

//Get the snap environment from the editor

ISnapEnvironment se = m_Editor
as ISnapEnvironment;

Boolean snapped = se.SnapPoint(m_Position);

m_Editor.InvertAgent(m_Position, 0);

}

protected override
void OnMouseDown(MouseEventArgs
arg)

{

System.Windows.Forms.MessageBox.Show(“Map units:rnX: “

+ m_Position.X.ToString() + “rnY: “ +
m_Position.Y.ToString());

}

protected override
void OnRefresh(int
hDC)

{

if (m_Position != null)

m_Editor.InvertAgent(m_Position, hDC);

}

protected override
void OnUpdate()

{

Enabled =
(m_Editor.EditState == esriEditState.esriStateEditing);

}

}

}

The code is very similar to the extension example, where the variable m_Position holds the snapped position and would be used to create geometry or update feedback. In this case, I have to be careful with refreshing the feedback. The code calls InvertAgent, which essentially paints the screen with the feedback of a blue dot. To erase the feedback, I need to call InvertAgent again. If I get out of sync, I can be left with feedback graphics on the screen that will not go away until I refresh the screen. Normally, though, if you are working with ArcGIS Snapping, the environment takes care of this for you.

For more information
To learn more about developing with the ArcGIS Snapping environment, see Snapping in ArcGIS in the ArcGIS Developer Help.

To view some example editing tools that incorporate snapping, see the Editing Labs group on ArcGIS.com (make sure to filter by Show: All Content at the top of the page).

Post content from Sean (Editing Team)