About Snap Agents
Snap agents facilitate geometry placement. For example, the sketch tools make use of snap agents to enable a user to precisely place an edit sketch vertex. Because snap agents are so widely used, the editing framework manages a snapping environment, which is a collection of snap agents and a snap tolerance (ISnapEnvironment::SnapTolerance).
Snap agents help you place sketch geometries during editing.
Tools that make use of the editing snap environment usually do so in their ITool::OnMouseMove implementation. In this event, tools create a point based on their current location and pass this point to the snap environment which, acting essentially as a black box, either modifies the point's x,y coordinates or does not. The original point is passed into the snap environment engine via a call to ISnapEnvironment::SnapPoint, which takes the point as a parameter. SnapPoint in turn calls each snap agents ISnapAgent::Snap method until one of them returns True. A True response indicates that the snap agent has found a new point that meets its unique snapping criteria; in this case, the original points coordinates are modified to reflect that of the snap point. The first snap agent to return True determines the snapping behavior; no other snap agents are called after this point.
A special type of snap agent is the feature snap agent. Like its name suggests, a feature snap agent snaps to features in the edit session. The snapping environment automatically generates one feature snap agent for every feature class in the edit session. Feature snap agents have two properties that govern their behavior:
- The FeatureClass, which controls the feature class in the edit session it will attempt to snap to.
- The HitType, which controls the part of the feature to snap to, for example, boundary, endpoint, and vertex.
All other snap agents are generally referred to as regular snap agents. ArcMap ships with three of these:
- Perpendicular to sketch
- Edit sketch vertices
- Edit sketch edges
There are two types of snap agents: those that snap to existing features and those that snap to an element of the sketch geometry.
Below you can see the Snapping Environment dockable window. The feature snap agents are listed in the top half of the window, and the regular snap agents are in the bottom half.
It is possible to control the order of the nonfeature snap agents (the regular snap agents) in the snap environment dialog box on a per-user basis by editing the snpdlg.ini file. This .ini file can be found in the Application Data directory in the user's profile, for example, C:\Documents and Settings\Steve\Application Data\ESRI\ArcMap\Editor. The file contains a list of snap agent GUIDs, and the order of these GUIDs controls the order in the dialog box. Note that the .ini file does not override the category settings; for example, the second GUID in the list will be the first snap agent listed in a particular category if its category differs from the snap agent listed above it.
If a desired snap agent does not exist, you can extend the system by creating your own and adding it to the snap environment. Create a custom snap agent by implementing ISnapAgent and IPersistVariant. Note, C++ developers should implement IPersistStream instead of IPersistVariant. Unfortunately, you cannot create a custom feature snap agent; only regular snap agents can be implemented. You could, of course, create a snap agent that behaves exactly like a feature snap agent, but you won't be able to have it appear in the top half on the snapping window. Instead, you will have to create your own control to set its target feature class and hit type.
For an example of a snap agent, see the Subtypes Snap Agent Example. Other examples of edit tasks you may want to create include:
- Snap to center of polygons
- Snap to center of circular arcs
- Snap to buffer
See Also Extending the Editing Framework and Subtypes Snap Agent Example.