This reference page is linked to from the following overview topics: General Best Practices, Calling CopyBaseData(), The Undo and Redo System, How to Enable Undo and Redo, Deriving from RestoreObj, Super-holds, Undo Memory Limits, Undo and Redo in a Controller.
Detailed Description
- See also:
- Class RestoreObj, Undo
and Redo.
- 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.
#include <hold.h>
Inheritance diagram for Hold:
Public Member Functions |
|
| CoreExport | Hold () |
| CoreExport | ~Hold () |
| CoreExport void | Put (RestoreObj *rob) |
| CoreExport void | Begin () |
| CoreExport void | Suspend () |
| CoreExport int | IsSuspended () |
| CoreExport void | Resume () |
| CoreExport int | Holding () |
| CoreExport int | Restoring (int &isUndo) |
| CoreExport int | Redoing () |
| CoreExport int | RestoreOrRedoing () |
| CoreExport void | DisableUndo () |
| CoreExport void | EnableUndo () |
| CoreExport BOOL | IsUndoDisabled () |
| CoreExport int | GetBeginDepth () |
| CoreExport void | Restore () |
| CoreExport void | Release () |
| CoreExport void | End () |
| CoreExport void | Accept (int nameID) |
| CoreExport void | Accept (MCHAR *name) |
| CoreExport void | Cancel () |
| CoreExport void | SuperBegin () |
| CoreExport void | SuperAccept (int nameID) |
| CoreExport void | SuperAccept (MCHAR *name) |
| CoreExport void | SuperCancel () |
| CoreExport int | GetSuperBeginDepth () |
| CoreExport int | GetGlobalPutCount () |
| CoreExport INT_PTR | Execute (int cmd, ULONG_PTR arg1=0, ULONG_PTR arg2=0, ULONG_PTR arg3=0) |
| CoreExport DWORD_PTR | Size () const |
| Returns the (approximate) memory usage of
this hold. |
|
Protected Types |
|
| enum | { kInRestore, kInUndo, kInRedo } |
Protected Attributes |
|
| friend | HoldStore |
| unsigned | flags |
Member Enumeration Documentation
anonymous enum [protected] |
{
kInRestore,
kInUndo,
kInRedo
};
Constructor & Destructor Documentation
| CoreExport Hold | ( | ) |
| CoreExport ~Hold | ( | ) |
Member Function Documentation
| CoreExport 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:
-
rob The restore object to register.
- Example:
- Example code from EDMREST.CPP
if ( theHold.Holding() ) {
theHold.Put(new MeshSelectRestore(meshData,this));
}
| CoreExport 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();
| CoreExport void Suspend | ( | ) |
- Remarks:
- Implemented by the System.
This is used internally. It temporarily suspends holding.
| CoreExport int IsSuspended | ( | ) |
| CoreExport void Resume | ( | ) |
- Remarks:
- Implemented by the System.
This is used internally. It resumes holding if it was suspended.
| CoreExport 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.
- Returns:
- Nonzero if theHold is holding; otherwise 0.
- Example:
-
if ( theHold.Holding() ) { ... }
| CoreExport int Restoring | ( | int & | isUndo | ) |
- Remarks:
- Implemented by the System.
Returns nonzero if the system is restoring and zero if not.
- Parameters:
-
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.
| CoreExport int Redoing | ( | ) |
- Remarks:
- Implemented by the System.
Returns nonzero if the system is redoing and zero if not.
| CoreExport int RestoreOrRedoing | ( | ) |
- Remarks:
- Implemented by the System.
Returns nonzero if the system is restoring or redoing and zero if not.
| CoreExport 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.
| CoreExport 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.
| CoreExport BOOL IsUndoDisabled | ( | ) |
- Remarks:
- Implemented by the System.
This is used internally. Plug-In developers should not call this method. Returns state set by DisableUndo/EnableUndo.
| CoreExport int GetBeginDepth | ( | ) |
- Remarks:
- Implemented by the System.
Returns current nesting level of Begin() calls.
| CoreExport void Restore | ( | ) |
| CoreExport 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.
| CoreExport 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.
| CoreExport 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:
-
nameID The resource ID of the string to appear in the Edit menu next to Undo or Redo.
- Example:
- theHold.Accept(IDS_MOVE);
| CoreExport void Accept | ( | MCHAR * | 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:
-
name The string to appear in the Edit menu next to Undo or Redo.
| CoreExport void Cancel | ( | ) |
- Remarks:
- Implemented by the System.
Restores the database to its previous state and throws out the restore object. This cancels the operation.
| CoreExport 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.
| CoreExport 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:
-
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.
| CoreExport void SuperAccept | ( | MCHAR * | 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:
-
name The string to appear in the Edit menu next to Undo or Redo.
| CoreExport 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.
| CoreExport int GetSuperBeginDepth | ( | ) |
- Remarks:
- Implemented by the System.
Returns current nesting level of SuperBegin() calls.
| CoreExport int GetGlobalPutCount | ( | ) |
- Remarks:
- Returns the number of times Put() has been called in the current session of 3ds Max.
| CoreExport INT_PTR Execute | ( | int | cmd, |
| ULONG_PTR | arg1 = 0, |
||
| ULONG_PTR | arg2 = 0, |
||
| ULONG_PTR | arg3 = 0 |
||
| ) |
| CoreExport DWORD_PTR Size | ( | ) | const |
Returns the (approximate) memory usage of this hold.
The memory returned is the sum of all RestoreObj's Size() methods, so the accuracy of this method depends on the accuracy of the restore objects.
- See also:
- RestoreObj::Size
- Returns:
- Size, in bytes, of the restore objects held by this hold. !
Member Data Documentation
friend HoldStore
[protected] |
unsigned flags
[protected] |
