#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 undoable 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)
	For internal use only. More...

CoreExport void	Accept (const MCHAR *name)
	Signals the completion of an undoable operation. More...

CoreExport void	Cancel ()
	Aborts an undoable operation previously initiated with Begin(). 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 undoable operation.

When a plugin is about to start a user-triggered operation that should be undoable (normally as a result of pressing a button or activating a UI control in some way), this method must be called to initiate the undoable operation. This method turns the undo system on - placing it in the "holding" state, such that any subsequent scene modifications will get registered as undoable operations. For example, any change in ParamBlock2 parameter values will automatically be registered with the undo system if and only if Begin() has been called. Failure to call Begin() before performing scene changes will render those changes permanent and impossible to undo.

Following the completion of the user-triggered operation, Accept() must be called to signal completion of the undo operation.

Internally, a counter is used to support overlapping undoable operations. The undoable operation is registered by the system only once the counter returns to 0 - i.e. once there have been an equal number of Accept() and Begin().

Remarks: For every call to Begin(), there should be a matching call to either Cancel() or Accept().

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 )

For internal use only.

CoreExport void Accept ( const MCHAR * name )

Signals the completion of an undoable operation.

Once a user-triggered, undoable operation has been completed, this method must be called to signal that completion to the system. The undoable operation is registered and published using the provided as its title.

Remarks: For every call to Begin(), there should be a matching call to either Cancel() or Accept().

Parameters

name	The string which is to be displayed to the user, as the name of the undo operation (e.g. to appear in the Edit menu). The system will prepend "Undo " to the string.

CoreExport void Cancel ( )

Aborts an undoable operation previously initiated with Begin().

If an undo operation is to be aborted before it was completed (through Accept()), then this method should be called. All scene changes that have been registered since Begin() was called are undone by this method.

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

Hold Class Reference

Class Description

Public Member Functions

Protected Types

Protected Attributes

Friends

Additional Inherited Members

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation