IPointSnapper.CacheShapes Method

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

[Visual Basic .NET]
Public Function CacheShapes ( _
    ByVal pShapes As IGeometryBag, _
    ByVal Name As String _
) As Integer

[C#]
public int CacheShapes (
    IGeometryBag pShapes,
    string Name
);

[C++]
HRESULT CacheShapes(
  IGeometryBag* pShapes,
  BSTR Name,
  long* token
);

[C++]
Parameters
pShapes [in]
  pShapes is a parameter of type IGeometryBag
Name [in]
  Name is a parameter of type BSTR
token [out, retval]
  token is a parameter of type long

Product Availability

Errors Returned

NullReferenceException  - returned when GeometryBag is null.

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.

See Also