thehold
This structure exposes all but 3 of the theHold public SDK methods. (The 3 methods missing are not useful in the MXS scripting context.)
The undo / redo system of 3ds Max uses a global instance of the Hold class called theHold. Developers call methods of theHold object to participate in the undo / redo system.
For methods that take arguments, the arguments are checked before use, but they won't throw an error if argument is incorrect. Instead, a default string of "" will be used for Accept and SuperAccept, and &unsupplied for Restoring.
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. The parameter is the string to appear in the Edit menu next to Undo or Redo.
When a developer is about to modify the database he 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 the Holdis 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.
Restores the database to its previous state and throws out the restore object. This cancels the operation.
This is used internally. Plug-In developers should not call this method. Prevents Undo when Accept() is called.
This is used internally. Plug-In developers should not call this method. Allows Undo when Accept() is called.
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.
Returns the number of times Put() has been called in the current session of3ds Max.
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.
Return Value: true if theHold is holding; otherwise false.
Returns nonzero if the system is redoing and zero if not.
This tosses out the restore objects since the last Begin() but still continues holding. Group several Begin-End lists into a single Super-group.
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.
Returns nonzero if the system is restoring or redoing and zero if not.
Returns nonzero if the system is restoring and zero if not. The isUndo parameter is updated to indicate if the restore is coming from an undo. It's assigned nonzero if it is; zero if not.
This is used internally. It resumes holding if it was suspended.
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. The string parameter is the text to appear in the Edit menu next to Undo or Redo.
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.
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.
Returns true if suspended, false otherwise.
Returns the superlevel depth. Normally 0, incremented for each call to SuperBegin, decremented for each call to SuperAccept or SuperCancel.
Returns the current number of undo/redo entries. Available in 3ds Max 8 and higher.
Returns the maximum number of undo/redo entries - same as 'Scene Undo Levels' setting in Preference Settings dialog. Available in 3ds Max 8 and higher.
Sets the maximum number of undo/redo entries. Available in 3ds Max 8 and higher.
Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.