com.esri.arcgis.controls
Class IPointSnapperProxy

java.lang.Object
  extended by com.esri.arcgis.interop.Dispatch
      extended by com.esri.arcgis.controls.IPointSnapperProxy
All Implemented Interfaces:
IPointSnapper, Externalizable, Serializable

public class IPointSnapperProxy
extends com.esri.arcgis.interop.Dispatch
implements IPointSnapper, Serializable

IPointSnapper Interface

Product Availability

Available with ArcGIS Engine.

See Also:
Serialized Form

Field Summary
 boolean noncastable
           
 
Fields inherited from class com.esri.arcgis.interop.Dispatch
DISPATCH_METHOD, DISPATCH_PROPERTYGET, DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, objRef
 
Constructor Summary
  IPointSnapperProxy()
           
  IPointSnapperProxy(Object obj)
           
protected IPointSnapperProxy(Object obj, String iid)
           
 
Method Summary
 void addListener(String iidStr, Object theListener, Object theSource)
           
 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 removeListener(String iidStr, Object theListener)
           
 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.
 
Methods inherited from class com.esri.arcgis.interop.Dispatch
bindUsingMoniker, constructVtblPosTable, convertToNative, cookieForListener, createDispatch, createObjrefMonikerDisplayName, equals, getActiveObject, getActiveObject, getDefaultProperty, getDispatchIdOfName, getLastErrorCode, getMtsObjectContext, getObjRef, getPropertyByName, getPropertyByName, getVtblPos, hashCode, initDispatch, invoke, invokeMethodByName, invokeMethodByName, invokeMethodByName, invokePropertyGetByName, invokePropertyPutByName, invokePropertyPutByRefByName, isNativeMode, isObjRef, optimizedVtblInvoke, queryInterface, readExternal, release, setNativeMode, setPropertyByName, toString, vtblInvoke, writeExternal
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

noncastable

public boolean noncastable
Constructor Detail

IPointSnapperProxy

public IPointSnapperProxy()

IPointSnapperProxy

public IPointSnapperProxy(Object obj)
                   throws IOException
Throws:
IOException

IPointSnapperProxy

protected IPointSnapperProxy(Object obj,
                             String iid)
                      throws IOException
Throws:
IOException
Method Detail

addListener

public void addListener(String iidStr,
                        Object theListener,
                        Object theSource)
                 throws IOException
Overrides:
addListener in class com.esri.arcgis.interop.Dispatch
Throws:
IOException

removeListener

public void removeListener(String iidStr,
                           Object theListener)
                    throws IOException
Overrides:
removeListener in class com.esri.arcgis.interop.Dispatch
Throws:
IOException

snap

public 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:


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.

Specified by:
snap in interface IPointSnapper
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

public 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.

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

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.

Specified by:
clearCache in interface IPointSnapper
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

cacheShapes

public 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.

Specified by:
cacheShapes in interface IPointSnapper
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

public 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.

Specified by:
updateCachedShapes in interface IPointSnapper
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

public 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.

Specified by:
removeCachedShapes in interface IPointSnapper
Parameters:
token - The token (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setTangentInputPointByRef

public void setTangentInputPointByRef(IPoint point)
                               throws IOException,
                                      AutomationException
Sets the input point used for calculating tangent points along curves.

Product Availability

Available with ArcGIS Engine.

Specified by:
setTangentInputPointByRef in interface IPointSnapper
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

public 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.

Specified by:
getTangentInputPoint in interface IPointSnapper
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

public 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.

Specified by:
getExcludedLayers in interface IPointSnapper
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

public 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.

Specified by:
fullSnap in interface IPointSnapper
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.