Hold Class Reference

#include <hold.h>

Inheritance diagram for Hold:

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 undoable 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 commandResId)
	For internal use only.
CoreExport void	Accept (const MCHAR *commandName)
	Signals the completion of an undoable operation.
CoreExport void	Accept (const OperationDesc &opDesc)
	Signals the completion of an undoable operation.
CoreExport void	Cancel ()
	Aborts an undoable operation previously initiated with Begin().
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.
Public Member Functions inherited from BaseInterfaceServer
UtilExport BaseInterface *	GetInterface (Interface_ID id) override
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.
virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)
template<class InterfaceType >
InterfaceType *	GetTypedInterface ()

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator.
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator.
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary.
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary.
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc.

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

Member Enumeration Documentation

anonymous enum

anonymous enum

protected

Enumerator
kInRestore
kInUndo
kInRedo

         {
        kInRestore,
        kInUndo,
        kInRedo
    };

Constructor & Destructor Documentation

Hold()

CoreExport Hold

(

)

constructor

~Hold()

CoreExport ~Hold

(

)

destructor

Member Function Documentation

Put()

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));
}

Begin()

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

Suspend()

CoreExport void Suspend

(

)

Temporarily suspends holding.

IsSuspended()

CoreExport int IsSuspended

(

)

Reports whether the hold system is suspended or not.

Resume()

CoreExport void Resume

(

)

It resumes holding if it was suspended.

Holding()

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() ) {
...
} 

Restoring()

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.

Redoing()

CoreExport int Redoing

(

)

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

RestoreOrRedoing()

CoreExport int RestoreOrRedoing

(

)

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

DisableUndo()

CoreExport void DisableUndo

(

)

This is used internally.

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

EnableUndo()

CoreExport void EnableUndo

(

)

This is used internally.

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

IsUndoDisabled()

CoreExport BOOL IsUndoDisabled

(

)

This is used internally.

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

GetBeginDepth()

CoreExport int GetBeginDepth

(

)

Returns current nesting level of Begin() calls.

Restore()

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.

Release()

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.

End()

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.

Accept() [1/3]

CoreExport void Accept

(

int

commandResId

)

For internal use only.

Accept() [2/3]

CoreExport void Accept

(

const MCHAR *

commandName

)

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

commandName

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.

Accept() [3/3]

CoreExport void Accept

(

const OperationDesc &

opDesc

)

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 information in its operation descriptor.

Remarks

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

This method overload shall be used when the operation is also reported to ADP "MAX.MODEL" way point.

Parameters

opDesc

The command description with all Adp reportable information together with string to be displayed to the user, as the name of the undo operation (e.g. to appear in the Edit menu).

Cancel()

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.

SuperBegin()

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.

SuperAccept() [1/2]

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.

SuperAccept() [2/2]

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.

SuperCancel()

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.

GetSuperBeginDepth()

CoreExport int GetSuperBeginDepth

(

)

Remarks

Implemented by the System.

Returns current nesting level of SuperBegin() calls.

GetGlobalPutCount()

CoreExport int GetGlobalPutCount

(

)

Remarks

Returns the number of times Put() has been called in the current session of 3ds Max.

Execute()

CoreExport INT_PTR Execute	(	int	cmd,
		ULONG_PTR	arg1 = 0,
		ULONG_PTR	arg2 = 0,
		ULONG_PTR	arg3 = 0
	)

Size()

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

HoldStore

friend class HoldStore

friend

Member Data Documentation

flags

unsigned flags

protected