Hold Class Reference

#include <hold.h>

Class Description

See also

Class RestoreObj, The Undo and Redo System.

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.

Inheritance diagram for Hold:

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

Protected Types
enum	{ kInRestore, kInUndo, kInRedo }

Protected Attributes
unsigned	flags
Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * >	interfaces

Friends
class	HoldStore

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...

Member Enumeration Documentation

anonymous enum

protected

Enumerator
kInRestore
kInUndo
kInRedo

         {
        kInRestore,
        kInUndo,
        kInRedo
    };

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.

theHold.Begin();

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 The Undo and Redo System.

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