Class IOsnapManager
See Also: Class OsnapHit, Class INode, Class ViewExp, Class Matrix3,The Advanced Topics section on Snapping.
class IOsnapManager
Description:
This class is available in release 2.0 and later only.
This class provides an interface to the OsnapManager. Developers who implement osnaps need to record hits with the osnap manager. Developers implementing command modes are responsible for getting the snap preview done and may be responsible for initializing and closing point sequences. See the Advanced Topics section on Snapping for more details.
Methods:
Prototype:
virtual BOOL getactive() const=0;
Remarks:
This method is used internally but may be called to determine if the OsnapManager is currently on.
Prototype:
virtual BOOL getAxisConstraint()=0;
Remarks:
This method is used internally but may be called to determine if the OsnapManager will use the system level axis constraints when performing translation.
Prototype:
virtual void RecordHit(OsnapHit* somehit)=0;
Remarks:
When a plugin osnap finds a hit, it should call this method to record it with the manager. This will enter the hit in a stack which is sorted based on proximity to the cursor position. When multiple hits are recorded with the manager, the user has the ability to cycle throught the stack.
Parameters:
OsnapHit* somehit
A pointer to the hit to record. The Osnap plugin should instantiate the hits and the manager is responsible for freeing them.
Prototype:
virtual BOOL OKForRelativeSnap()=0;
Remarks:
Some snaps only make sense relative to a reference point. Consider, for example, the tangent snap which looks for points of tangency on splines. You can only find a tangent point relative to a second point. As objects are created and manipulated, the OsnapManager maintains a list of the Points that have been input to the current command mode. This method tells you if the first point has been recorded.
Prototype:
virtual BOOL RefPointWasSnapped()=0;
Remarks:
This method tells you if the point on the top of the reference stack was actually snapped.
Prototype:
virtual Point3 GetRefPoint(BOOL top = TRUE)=0;
Remarks:
This method retrieves the Point on the top of the reference stack. The point returned is in world space. Note that calling this method when the stack is empty will crash the program. Remember to call OKForRelativeSnap() first. Here are the first few lines of the tangent snap’s main method.
void ShapeSnap::Snap(Object* pobj, IPoint2 *p, TimeValue t) {
if(!theman->OKForRelativeSnap())
return;
//Get the reference point
Point3 relpoint(theman->GetRefPoint());//the last point the user clicked.
//transform the reference point into the node's coordinate system
Matrix3 tm = theman-> GetObjectTM();
relpoint = Inverse(tm) * relpoint;
. . .
Parameters:
BOOL top = TRUE
The default is to return the top of the stack, i.e. the last point which was input to the command mode. If you pass FALSE, the bottom of the stack will be returned.
Prototype:
virtual BOOL IsHolding()=0;
Remarks:
This method is used internally. This method tells if the any hits were recorded with the OsnapManager during the last scene traversal.
Prototype:
virtual OsnapHit &GetHit()=0;
Remarks:
This method is used internally. It returns the current hit i.e. the hit which the manager is currently displaying.
Prototype:
virtual ViewExp *GetVpt()=0;
Remarks:
Returns a pointer to a ViewExp. This is only valid for the duration of the current scene traversal. It is guaranteed to be valid while in a plugin’s Snap() method.
Prototype:
virtual INode *GetNode()=0;
Remarks:
Returns a pointer to the node which is currently being snapped.
Prototype:
virtual int GetSnapStrength()=0;
Remarks:
Returns the current snap strength. This is the radius of a circular area about the cursor. It is the plugin’s responsibility to determine if any "interesting" parts of the object lie within this area. For testing points, see the method OsnapManager::CheckPotentialHit().
Prototype:
virtual Matrix3 GetObjectTM()=0;
Remarks:
Returns the object transformation matrix of the node which is currently being snapped.
Prototype:
virtual TimeValue GetTime()=0;
Remarks:
Returns the animation time of the current scene traversal.
Prototype:
virtual void wTranspoint(Point3 *inpt, IPoint3 *outpt)=0;
Remarks:
This method is not currently used. The method transforms a point in the current node’s object space into screen space.
Parameters:
Point3 *inpt
A pointer to the object space point.
IPoint3 *outpt
A pointer to storage for the screen space point.
Prototype:
virtual void Reset()=0;
Remarks:
This method may be called to clear out the OsnapManager’s reference point stack. Typically this is handled internally. However, objects which implement their own creation processes may need to call this method upon completion of a creation cycle.