Working with the ArcGIS snapping environment

In this topic

• About the ArcGIS snapping environment
• Accessing the snapping environment from ArcMap
• Accessing the snapping environment from ArcGIS Engine
• Working with the snapping cache
• Configuring the snapping environment
  • Snapping priority
  • Additional snapping agents in ArcMap
  • Snapping to other geometries
  • Excluding layers
• Adding snapping to a custom tool

About the ArcGIS snapping environment

Accessing the snapping environment from ArcMap

IPoint m_CurrentMouseCoords;
ISnappingEnvironment m_SnappingEnv;
IPointSnapper m_Snapper;
ISnappingFeedback m_SnappingFeedback;

//Get the snap environment and initialize the feedback.
m_SnappingEnv=m_application.FindExtensionByName("ESRI Snapping")as
    ISnappingEnvironment;
m_Snapper=m_SnappingEnv.PointSnapper;
m_SnappingFeedback=new SnappingFeedbackClass();
m_SnappingFeedback.Initialize(hook, m_SnappingEnv, true);

Dim m_CurrentMouseCoords As IPoint
Dim m_SnappingEnv As ISnappingEnvironment
Dim m_Snapper As IPointSnapper
Dim m_SnappingFeedback As ISnappingFeedback

'Get the snap environment and initialize the feedback.
m_SnappingEnv=TryCast(m_application.FindExtensionByName("ESRI Snapping"), ISnappingEnvironment)
m_Snapper=m_SnappingEnv.PointSnapper
m_SnappingFeedback=New SnappingFeedbackClass()
m_SnappingFeedback.Initialize(hook, m_SnappingEnv, True)

Accessing the snapping environment from ArcGIS Engine

IExtensionManager extensionManager=m_hookHelper2.ExtensionManager;
if (extensionManager != null)
{
    UID guid=new UIDClass();
    guid.Value="{E07B4C52-C894-4558-B8D4-D4050018D1DA}"; //Snapping extension.
    IExtension extension=extensionManager.FindExtension(guid);
    m_SnappingEnvironment=extension as ISnappingEnvironment;
}

Dim extensionManager As IExtensionManager=m_hookHelper2.ExtensionManager
If Not extensionManager Is Nothing Then
    Dim guid As UID=New UID
    guid.Value="{E07B4C52-C894-4558-B8D4-D4050018D1DA}" 'Snapping extension.
    Dim extension As IExtension=extensionManager.FindExtension(guid)
    m_SnappingEnvironment=TryCast(extension, ISnappingEnvironment)
End If

Working with the snapping cache

• A layer is added, moved, or deleted from the table of contents.
• The scale suppression of a layer is changed.
• The visibility of a layer is changed.
• A definition query on a layer is changed.
• A SQL query on a layer is changed.
• A layer's data source is changed.
• A feature is created, updated, or deleted.
• The extent of the map changes.
• The active data frame changes.
• The active view changes (for example, the focus changes from the main map window to a viewer window or you switch from data view to layout view in ArcMap).
• The snapping tolerance (ISnappingEnvironment.Tolerance) is updated.
• Intersection snapping is turned on or off.
• Text snapping is enabled or disabled.
• CacheShapes, UpdateCachedShapes, or RemoveCachedShapes is called.
• The ISnappingEnvironment.IgnoreIMSLayers property is changed.

• IHookHelperEvents.OnHookUpdated
• IActiveViewEvents.ContentsChanged
• IActiveViewEvents.FocusMapChanged
• IObjectClassEvents.OnChange
• IObjectClassEvents.OnCreate
• IObjectClassEvents.OnDelete

Configuring the snapping environment

//Specify combination of esriSnappingType enumerations.
snappingEnvironment.SnappingType=esriSnappingType.esriSnappingTypeEdge +
    esriSnappingType.esriSnappingTypeEndpoint;

//Specify bitwise combination for edge and endpoint snapping.
snappingEnvironment.SnappingType=(esriSnappingType)63;

'Specify combination of esriSnappingType enumerations.
snappingEnvironment.SnappingType=esriSnappingType.esriSnappingTypeEdge + esriSnappingType.esriSnappingTypeEndpoint

'Specify bitwise combination for edge and endpoint snapping.
snappingEnvironment.SnappingType=DirectCast(63, esriSnappingType)

Snapping priority

1. esriSnappingTypePoint
2. esriSnappingTypeIntersection
3. esriSnappingTypeEndpoint
4. esriSnappingTypeVertex
5. esriSnappingTypeMidpoint
6. esriSnappingTypeTangent
7. esriSnappingTypeEdge

Additional snapping agents in ArcMap

public void SetTopologyNodeSnapping(bool SetEnabled)
{
    ESRI.ArcGIS.esriSystem.UID editorUID=new ESRI.ArcGIS.esriSystem.UIDClass();
    editorUID.Value="{F8842F20-BB23-11D0-802B-0000F8037368}"; // esriEditor.Editor
    IEditor editor=ArcMap.Application.FindExtensionByCLSID(editorUID)as IEditor;

    ESRI.ArcGIS.esriSystem.UID editorsnapUID=new ESRI.ArcGIS.esriSystem.UIDClass();
    editorsnapUID.Value="{810F5661-29A6-42C4-BD24-02E300629C36}"; 
        // esriEditorExt.EditorSnapping
    IEditorSnapping editorSnapping=editor.FindExtension(editorsnapUID)as
        IEditorSnapping;

    editorSnapping.SnapToTopologyNodes=SetEnabled;
}

Public Sub SetTopologyNodeSnapping(SetEnabled As Boolean)
    Dim editorUID As ESRI.ArcGIS.esriSystem.UID=New ESRI.ArcGIS.esriSystem.UIDClass()
    editorUID.Value="{F8842F20-BB23-11D0-802B-0000F8037368}"
    
    ' esriEditor.Editor
    Dim editor As IEditor=TryCast(ArcMap.Application.FindExtensionByCLSID(editorUID), IEditor)
    Dim editorsnapUID As ESRI.ArcGIS.esriSystem.UID=New ESRI.ArcGIS.esriSystem.UIDClass()
    editorsnapUID.Value="{810F5661-29A6-42C4-BD24-02E300629C36}"
    
    ' esriEditorExt.EditorSnapping
    Dim editorSnapping As IEditorSnapping=TryCast(editor.FindExtension(editorsnapUID), IEditorSnapping)
    editorSnapping.SnapToTopologyNodes=SetEnabled
End Sub

Snapping to other geometries

Excluding layers

• IMS layers
  The IgnoreIMSLayers property excludes Internet map server (IMS) feature service layers from participating in the snapping cache. In most cases, the time required to build the snapping cache against IMS layers is lengthy, so they are automatically excluded from the snapping cache. In certain situations, the IMS layer response time is reasonable (such as an IMS service on an intranet). Setting this property to false will include these layers in the snapping cache. By default, IgnoreIMSLayers is set to true.
• Individual layers
  The ExcludedLayers property limits the set of available layers used in snapping to a subset of the layers available in the map. To manage the list of layers available for snapping, you must acquire a reference to the set of excluded layers, passed as an ISet reference. Using the set, you can manage the layers by adding or removing a given layer using ISet.Add, ISet.Remove, or ISet.RemoveAll. See the following code example:

ISet excludedLayerSet=new ESRI.ArcGIS.esriSystem.SetClass();
pointSnapper.ExcludedLayers(ref excludedLayerSet);

//Add a layer to be excluded. 
excludedLayerSet.Add(excludedLayer);
pointSnapper.ClearCache();

Dim excludedLayerSet As ISet=New ESRI.ArcGIS.esriSystem.SetClass()
pointSnapper.ExcludedLayers(excludedLayerSet)

'Add a layer to be excluded.
excludedLayerSet.Add(excludedLayer)
pointSnapper.ClearCache()

Adding snapping to a custom tool

1. In the tool's OnClick event,
   • Obtain a reference to the snapping extension
   • Acquire references to ISnappingEnvironment and IPointSnapper
   • Initialize the SnappingFeedback (optional)
2. In the tool's OnMouseMove event,
   • Call IPointSnapper.Snap during mouse move using the current location
   • If a SnapResult is returned:
     • Update the cursor location
     • Update the snapping feedback (if using feedback)
3. In the tool's Refresh method,
   • Refresh the snapping feedback (if using feedback)

public override void OnMouseMove(int Button, int Shift, int X, int Y)
{
    //Convert the point from pixels to map units.
    m_CurrentMouseCoords=QueryMapPoint(m_screenDisplay, X, Y);

    //Test the location against the snap environment.
    ISnappingResult snapResult=m_Snapper.Snap(m_CurrentMouseCoords);

    //Update the snapping feedback.
    m_SnappingFeedback.Update(snapResult, 0);

    //Update the current location to move the cursor to the snapped location.
    if (snapResult != null)
        m_CurrentMouseCoords=snapResult.Location;

    m_linefeedback.MoveTo(m_CurrentMouseCoords);
}

Public Overrides Sub OnMouseMove(ByVal Button As Integer, ByVal Shift As Integer, ByVal X As Integer, ByVal Y As Integer)
'Convert the point from pixels to map units.
m_CurrentMouseCoords=QueryMapPoint(m_screenDisplay, X, Y)
'Test the location against the snap environment.
Dim snapResult As ISnappingResult=m_Snapper.Snap(m_CurrentMouseCoords)
'Update the snapping feedback.
m_SnappingFeedback.Update(snapResult, 0)
'Update the current location to move the cursor to the snapped location.
If Not snapResult Is Nothing Then
    m_CurrentMouseCoords=snapResult.Location
End If
m_linefeedback.MoveTo(m_CurrentMouseCoords)
End Sub

public override void Refresh(int hDC)
{
    //Refresh the previous location of the snap tip.
    if (m_SnappingFeedback != null)
        m_SnappingFeedback.Refresh(hDC);
}

Public Overrides Sub Refresh(ByVal hDC As Integer)
'Refresh the previous location of the snap tip.
If Not m_SnappingFeedback Is Nothing Then
    m_SnappingFeedback.Refresh(hDC)
End If
End Sub

See Also:

• ESRI.ArcGIS.Controls
• ESRI.ArcGIS.Editor
• ESRI.ArcGIS.EditorExt