Hold Class Reference
 
 
 
Hold Class Reference

#include <hold.h>

Inheritance diagram for Hold:
BaseInterfaceServer InterfaceServer MaxHeapOperators

Class 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.

Public Member Functions

CoreExport  Hold ()
  constructor
CoreExport  ~Hold ()
  destructor
CoreExport bool  Put (RestoreObj *obj)
  The developer calls this method to register a new restore object with the system.
CoreExport void  Begin ()
  Starts an undo able operation.
CoreExport void  Suspend ()
  Temporarily suspends holding.
CoreExport int  IsSuspended ()
  Reports whether the hold system is suspended or not.
CoreExport void  Resume ()
  It resumes holding if it was suspended.
CoreExport int  Holding ()
  Indicates if theHold.Begin() has been called.
CoreExport int  Restoring (int &isUndo)
  Returns nonzero if the system is restoring and zero if not.
CoreExport int  Redoing ()
  Returns nonzero if the system is redoing and zero if not.
CoreExport int  RestoreOrRedoing ()
  Returns nonzero if the system is restoring or redoing and zero if not.
CoreExport void  DisableUndo ()
  This is used internally.
CoreExport void  EnableUndo ()
  This is used internally.
CoreExport BOOL  IsUndoDisabled ()
  This is used internally.
CoreExport int  GetBeginDepth ()
  Returns current nesting level of Begin() calls.
CoreExport void  Restore ()
  This method will call Restore() on all the restore objects registered since the last Begin().
CoreExport void  Release ()
  This tosses out the restore objects since the last Begin() but still continues holding.
CoreExport void  End ()
  This method is used internally to 3ds Max and should not be called by a plug-in developer.
CoreExport void  Accept (int nameID)
  Records an undo if enabled.
CoreExport void  Accept (const MCHAR *name)
  Records an undo if enabled.
CoreExport void  Cancel ()
  Restores the database to its previous state and throws out the restore object.
CoreExport void  SuperBegin ()
CoreExport void  SuperAccept (int nameID)
CoreExport void  SuperAccept (const 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

unsigned  flags

Friends

class  HoldStore

Member Enumeration Documentation


Constructor & Destructor Documentation

CoreExport Hold ( )

constructor

CoreExport ~Hold ( )

destructor


Member Function Documentation

CoreExport bool Put ( RestoreObj obj )

The developer calls this method to register a new restore object with the system.

Parameters:
obj The restore object to register.
Returns:
- true if successfully added, false if not. It will return false if it's not holding.
        if ( theHold.Holding() ) {
        theHold.Put(new MeshSelectRestore(meshData,this));
        }
CoreExport void Begin ( )

Starts an undo able operation.

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.

CoreExport void Suspend ( )

Temporarily suspends holding.

CoreExport int IsSuspended ( )

Reports whether the hold system is suspended or not.

CoreExport void Resume ( )

It resumes holding if it was suspended.

CoreExport int Holding ( )

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.
        if ( theHold.Holding() ) {
        ...
        } 
CoreExport int Restoring ( int &  isUndo )

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 ( )

Returns nonzero if the system is redoing and zero if not.

CoreExport int RestoreOrRedoing ( )

Returns nonzero if the system is restoring or redoing and zero if not.

CoreExport void DisableUndo ( )

This is used internally.

Plug-In developers should not call this method. Prevents Undo when Accept() is called.

CoreExport void EnableUndo ( )

This is used internally.

Plug-In developers should not call this method. Allows Undo when Accept() is called.

CoreExport BOOL IsUndoDisabled ( )

This is used internally.

Plug-In developers should not call this method. Returns state set by DisableUndo/EnableUndo.

CoreExport int GetBeginDepth ( )

Returns current nesting level of Begin() calls.

CoreExport void Restore ( )

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.

CoreExport void Release ( )

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 ( )

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 )

Records an undo if enabled.

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.
        theHold.Accept(IDS_MOVE);
CoreExport void Accept ( const MCHAR *  name )

Records an undo if enabled.

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 ( )

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 ( const 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. !

Friends And Related Function Documentation

friend class HoldStore [friend]

Member Data Documentation

unsigned flags [protected]