Class Hold
See Also: Class RestoreObj, Undo and Redo.
class Hold : public BaseInterfaceServer
Description:
The undo / redo system of 3ds max uses a global instance of this class called theHold. Developers call methods of theHold object to participate in the undo / redo system.
Methods:
Prototype:
void Begin();
Remarks:
Implemented by the System.
When a developer is about to modify the database they should check to see if theHold is 'holding'. This indicates that the Begin() method has been called. This signifies the beginning of a potential undo/redo operation. If theHold is not holding, they should call Begin(). After Begin() has been called the system is ready to accept restore objects.
In certain cases the system may already be 'holding' when the plug-in is about to begin its modification to the database. For example controllers would normally not call Begin() because it usually has been called already. A procedural object will normally call Begin() because there is no other part of the system that may alter a procedural object so Begin() would not have been called.
Example:
theHold.Begin();
Prototype:
int Holding();
Remarks:
Implemented by the System.
This indicates if theHold.Begin() has been called. Any operation that modifies the database checks to see if theHold is currently in a holding state. If the undo system is 'holding' it is ready to accept restore objects. For more details see the Advanced Topics section on Undo / Redo.
Return Value:
Nonzero if theHold is holding; otherwise 0.
Example:
if ( theHold.Holding() ) {
...
}
Prototype:
int Restoring(int& isUndo);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Returns nonzero if the system is restoring and zero if not.
Parameters:
int& isUndo
This parameter is updated to indicate if the restore is coming from an undo. It's assigned nonzero if it is; zero if not.
Prototype:
int Redoing();
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Returns nonzero if the system is redoing and zero if not.
Prototype:
int RestoreOrRedoing();
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Returns nonzero if the system is restoring or redoing and zero if not.
Prototype:
void Accept(int nameID);
Remarks:
Implemented by the System.
Leaves the database in its modified state and registers an undo object with the undo system. This will allow the user to undo the operation.
Parameters:
int nameID
The resource ID of the string to appear in the Edit menu next to Undo or Redo.
Example:
theHold.Accept(IDS_MOVE);
Prototype:
void Accept(TCHAR *name);
Remarks:
Implemented by the System.
Leaves the database in its modified state and registers an undo object with the undo system. This will allow the user to undo the operation.
Parameters:
TCHAR *name
The string to appear in the Edit menu next to Undo or Redo.
Prototype:
void Cancel();
Remarks:
Implemented by the System.
Restores the database to its previous state and throws out the restore object. This cancels the operation.
Prototype:
void End();
Remarks:
Implemented by the System.
This method is used internally to 3ds max and should not be called by a plug-in developer. It leaves the database in its modified state but throws out the restore object.
Prototype:
void Put(RestoreObj *rob);
Remarks:
Implemented by the System.
The developer calls this method to register a new restore object with the system. Once this object is registered the developer should set the A_HELD flag of Animatable, i.e. call SetAFlag(A_HELD). This indicates that a restore object is registered with the system.
Parameters:
RestoreObj *rob
The restore object to register.
Example:
Example code from EDMREST.CPP
if ( theHold.Holding() ) {
theHold.Put(new MeshSelectRestore(meshData,this));
}
Prototype:
void Suspend();
Remarks:
Implemented by the System.
This is used internally. It temporarily suspends holding.
Prototype:
void Resume();
Remarks:
Implemented by the System.
This is used internally. It resumes holding if it was suspended.
Prototype:
void EnableUndo();
Remarks:
Implemented by the System.
This is used internally. Plug-In developers should not call this method. Allows Undo when Accept() is called.
Prototype:
void DisableUndo();
Remarks:
Implemented by the System.
This is used internally. Plug-In developers should not call this method. Prevents Undo when Accept() is called.
Prototype:
void Restore();
Remarks:
Implemented by the System.
This method will call Restore() on all the restore objects registered since the last Begin(). This restores the database to the state it was in when Begin() was called. The restore objects are NOT deleted.
Prototype:
void Release();
Remarks:
Implemented by the System.
This tosses out the restore objects since the last Begin() but still continues holding.
Group several Begin-End lists into a single Super-group.
Prototype:
void SuperBegin();
Remarks:
Implemented by the System.
Normally this is NOT needed but in special cases this can be useful. This allows a developer to group a set of Begin()/Accept() sequences to be undone in one operation.
Consider the case of the user using the Shift-Move command to create a new node in the scene. There are two parts to this process. First the node must be cloned and second the position must be tracked as the user moves the mouse to place the new node in the scene. Naturally if the user wanted to Undo this operation, they would expect a single selection of the Undo command would accomplish it. However the process was not a single operation. There was the initial cloning of the node, and then the iterative process of moving the node in the scene, restoring its position, moving it again, restoring it again, etc. Cases like this are handled using methods of theHold named SuperBegin(), SuperAccept() and SuperCancel(). These allow the developer to group several restore objects together so that they may be undone via a single selection of Undo. Note that in this example it is only necessary to use SuperBegin() and SuperAccept() because the move was restoring interactively. Normally a developer does NOT need to use these methods even if they have several operations that modify the database. The undo system will automatically register all the restore objects needed as part of the undo object when theHold.Accept() is called and these may be undone using a single UNDO command.
Sample Code:
See the sample program \MAXSDK\SAMPLES\OBJECTS\BONES.CPP.
Prototype:
void SuperAccept(int nameID);
Remarks:
Implemented by the System.
When a developer has used SuperBegin(), this method is used to Accept. This leaves the database in its modified state and registers the restore object with the undo system. This will allow the user to undo the operation.
Parameters:
int nameID
The resource ID of the string to appear in the Edit menu next to Undo or Redo.
Sample Code:
See the sample program \MAXSDK\SAMPLES\OBJECTS\BONES.CPP.
Prototype:
void SuperAccept(TCHAR *name);
Remarks:
Implemented by the System.
When a developer has used SuperBegin(), this method is used to Accept. This leaves the database in its modified state and registers the restore object with the undo system. This will allow the user to undo the operation.
Parameters:
TCHAR *name
The string to appear in the Edit menu next to Undo or Redo.
Prototype:
void SuperCancel();
Remarks:
Implemented by the System.
When a developer has used SuperBegin(), this method is used to Cancel. This restores the database to its previous state and throws out the restore object. This cancels the operation.
Sample Code:
See the sample program \MAXSDK\SAMPLES\OBJECTS\BONES.CPP.
Prototype:
int GetGlobalPutCount();
Remarks:
This method is available in release 2.0 and later only.
Returns the number of times Put() has been called in the current session of 3ds max.