com.esri.arcgis.controls
Interface IPointSnapper

All Superinterfaces:

Serializable

All Known Implementing Classes:

IPointSnapperProxy

public interface IPointSnapper
extends Serializable

IPointSnapper Interface

Product Availability

Available with ArcGIS Engine.

Method Summary

int	cacheShapes(IGeometryBag pShapes, String name) Adds a shape to the snapping cache.
void	clearCache() Clears the underlying snapping cache.
ISnappingResult	fullSnap(IPoint point) Fully attempts to snap the specified point without regard to time.
void	getExcludedLayers(ISet ppSet) Returns a reference to the set of layers that will be excluded in snapping.
IPoint	getTangentInputPoint() Sets the input point used for calculating tangent points along curves.
void	removeCachedShapes(int token) Remove the shape from the cache.
void	setTangentInputPointByRef(IPoint point) Sets the input point used for calculating tangent points along curves.
ISnappingResult	snap(IPoint point) Attempts to snap the specified point.
void	updateCachedShapes(int token, IGeometryBag pShapes) Updates the shapes in the cache for the given token.

Method Detail

snap

ISnappingResult snap(IPoint point)
                     throws IOException,
                            AutomationException

Attempts to snap the specified point. This is used for tool snapping.

Remarks

Snap is the mechanism by which a test point (usually the cursor location) is evaluated against the snapping environment to determine whether any of the snapping criteria have been met. This information is returned in the form of a snap result. If the snapping criteria are not met, a null snap result is returned. If a valid snap location was determined, the snap result defines the snap location along with information about which snapping type was satisfied.

Evaluating Snap candidates
The snapping environment honors the following layer settings:

• Layer visibility, including scale suppression
• Definition queries
• SQL queries

Only features which match the criteria specified by these settings are evaluated against the snap candidate.
In addition, only those snapping types specified on the snapping environment are evaluated. These are evaluated in a specific order. This snapping type order is fixed. It is important to note that layer order is secondary when a snap candidate is considered. This means that the point snapping type is evaluated against all layers before any subsequent snapping types are enabled. The closest snap result for a given snapping type is always returned, regardless if other valid snap results were identified.

Snapping Type Priority

1. Point
2. Intersection
3. Endpoint
4. Vertex
5. Midpoint
6. Tangent
7. Edge
   

Product Availability

Available with ArcGIS Engine.

Parameters:

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

Returns:

A reference to a com.esri.arcgis.controls.ISnappingResult

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

clearCache

void clearCache()
                throws IOException,
                       AutomationException

Clears the underlying snapping cache.

Remarks

While Snapping is enabled and calls to IPointSnapper.Snap are being made, a cache of the visible features is being actively maintained.

The cache is cleared in a number of instances for you; as a developer you do not need to account for these situations. The following list describes the cases when ClearCache is called.

• 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 (e.g. focus changes from 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.
• CachedShapes, UpdateCachedShapes, or RemoveCachedShapes is called.
• ExcludeIMSLayers property is changed.

When any of the following events are fired, the snapping cache is cleared.

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

There is no method to build the cache explicitly; this is handled internally when a client issues a call to IPointSnapper.Snap, at which time it is determined whether the cache needs to be rebuilt.

Product Availability

Available with ArcGIS Engine.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

cacheShapes

int cacheShapes(IGeometryBag pShapes,
                String name)
                throws IOException,
                       AutomationException

Adds a shape to the snapping cache. Use the returned token to remove the shape from the cache.

Remarks

CacheShapes provides a mechanism to snap to geometries that are not part of a feature associated with a featurelayer. For example, snapping to the edit sketch in the ArcMap editor utilizes this approach, and adds the current edit sketch into the snapping cache using this method.

As a developer, it is your responsibility to ensure that the lifetime and currency of the cached shapes you inject are maintained. Failure to do this will result in shapes being orphaned in the cache, while may result in invalid snapping results from a user perspective. Two other methods are used to manage these caches, IPointSnapper.UpdateCachedShapes and IPointSnapper.RemovedCachedShapes.

Managing these caches uses a token-based approach. When you add geometries to the cache, CacheShapes returns a token that corresponds to those shapes. This token can then be used in the other methods to specify which shapes you want replaced (UpdateCachedShapes) or removed (RemoveCachedShapes).

The Name argument is used when a snap result is returned after snapping to a cached shape, this is returned in lieu of the layer name in the SnapTip. Empty strings are considered valid, but do not provide any real indication to about what was snapped to.

Product Availability

Available with ArcGIS Engine.

Parameters:

pShapes - A reference to a com.esri.arcgis.geometry.IGeometryBag (in)

name - The name (in)

Returns:

The token

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

updateCachedShapes

void updateCachedShapes(int token,
                        IGeometryBag pShapes)
                        throws IOException,
                               AutomationException

Updates the shapes in the cache for the given token. The token is acquired by calling CacheShape.

Remarks

UpdateCachedShapes updates the geometries associated with a given token. The snap cache is cleared when a call to UpdateCachedShapes is made; the next subsequent call to Snap will build the cache.

Product Availability

Available with ArcGIS Engine.

Parameters:

token - The token (in)

pShapes - A reference to a com.esri.arcgis.geometry.IGeometryBag (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

removeCachedShapes

void removeCachedShapes(int token)
                        throws IOException,
                               AutomationException

Remove the shape from the cache. The token is acquired by calling CacheShape.

Remarks

RemoveCachedShapes clears any shapes associated with a given token from the snapping cache. An exception is thrown when an invalid token provided. The snap cache is cleared when a call to RemoveCachedShapes is made; the next subsequent call to Snap will build the cache.

Product Availability

Available with ArcGIS Engine.

Parameters:

token - The token (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setTangentInputPointByRef

void setTangentInputPointByRef(IPoint point)
                               throws IOException,
                                      AutomationException

Sets the input point used for calculating tangent points along curves.

Product Availability

Available with ArcGIS Engine.

Parameters:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getTangentInputPoint

IPoint getTangentInputPoint()
                            throws IOException,
                                   AutomationException

Sets the input point used for calculating tangent points along curves.

Remarks

TangentInputPoint defines the location from which points of tangency along curved segments are calculated. In most cases this is the last point in a polyline geometry. If the tangentInputPoint is not specified, no snapping to tangents of curved segments will occur. Once specified, set the tangentInputPoint to null to ensure any points of tangency are made from the correct point.

In practice, when writing a tool that utilizes snapping, it is the developer’s responsibility to ensure the tangentInputPoint is updated and its lifetime is maintained properly.

Product Availability

Available with ArcGIS Engine.

Returns:

A reference to a com.esri.arcgis.geometry.IPoint

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getExcludedLayers

void getExcludedLayers(ISet ppSet)
                       throws IOException,
                              AutomationException

Returns a reference to the set of layers that will be excluded in snapping.

Product Availability

Available with ArcGIS Engine.

Parameters:

ppSet - A reference to a com.esri.arcgis.system.ISet (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

fullSnap

ISnappingResult fullSnap(IPoint point)
                         throws IOException,
                                AutomationException

Fully attempts to snap the specified point without regard to time. Use Snap for tool snapping.

Product Availability

Available with ArcGIS Engine.

Parameters:

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

Returns:

A reference to a com.esri.arcgis.controls.ISnappingResult

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.