com.esri.arcgis.editor
Interface ISnapAgent

All Superinterfaces:

Serializable

All Known Subinterfaces:

IFeatureSnapAgent, IFeatureSnapAgent2

All Known Implementing Classes:

FeatureSnap

public interface ISnapAgent
extends Serializable

Provides access to members that snap point locations using a tolerance.

Remarks

All snap agents implement this interface.

Tools that work with snapping typically call the ISnapEnvironment::SnapPoint method every time the mouse moves. SnapPoint in turn calls each snap agents Snap method in succession until one of them returns true. True means a new point has been found that meets the qualifications set within a particular snap agents snap method. For example, is the passed in point representing the Sketch tools current location, within 10 meters of a Parcel vertex. The first snap agent to return true, modifies the passed in points x,y location to reflect that of the new snap point location and no other snap agents are called.

Create custom snap agents by implementing this interface and register it in the ESRI Snap Agents component category. All snap agents registered in this component category will show up in the Snapping Window. All snap agents should additionally implement IPersistVariant (VB) or IPersistStream(C++). Implementing either IPersistVariant or IPersistStream enables snap agents to persist their state in a map document. These interfaces also have an important role with regards to the editor's snapping window, their implementation helps turn snap agents off and on.

When To Use

The ISnapAgent interface is typically used in two scenarios: creating new custom snap agents and accessing properties of an existing snap agent. Implement this interface when creating a custom snap agent.

Product Availability

Available with ArcGIS Desktop.

See Also:

ISnapEnvironment, IGeometry

Method Summary

String	getName() The name of the snap agent shown in the UI.
boolean	snap(IGeometry geom, IPoint point, double tolerance) Called by the editor to perform the actual snapping logic.

Method Detail

getName

String getName()
               throws IOException,
                      AutomationException

The name of the snap agent shown in the UI.

Remarks

To find a particular snap agent you made need to cycle through all of the loaded snap agents using the Name property. For Feature Snap Agents, the name is that of their featureclass.

When creating a custom snap agent, make sure to give it a unique name.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:

The name

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

snap

boolean snap(IGeometry geom,
             IPoint point,
             double tolerance)
             throws IOException,
                    AutomationException

Called by the editor to perform the actual snapping logic.

Remarks

Each snap agent uniquely implements the Snap method. Although each snap agent's Snap method can be called directly, typically the ISnapEnvironment::SnapPoint method is used to call this function for each loaded snap agent until one of them reports it has modified the passed in point's properties. To facilitate this behavior, each snap agent's Snap method must return a Boolean variable indicating whether or not it has modified the passed in points coordinates.

Snapping the passed in point means changing its x,y location properties. Because an IPoint interface pointer is passed into this function ByValue , direct edits of the point's parameters is possible. Resetting the IPoint interface to a different Point object will have no effect after leaving the scope of the function.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:

geom - A reference to a com.esri.arcgis.geometry.IGeometry (in)

point - A reference to a com.esri.arcgis.geometry.IPoint (in)

tolerance - The tolerance (in)

Returns:

The snapped

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

See Also:

ISnapEnvironment