MacroRecorder Class Reference

Provides various methods to emit pieces of script to the Macro Recorder. More...

#include <macrorec.h>

Inheritance diagram for MacroRecorder:

Classes
class	MacroRecorderDisable
	Class for easily & safely disabling the macro recorder. More...

Public Member Functions
virtual BOOL	BeginCreate (ClassDesc *cd, int flags=0)=0
	Used for implementing a custom creation manager.
virtual void	SetNodeTM (INode *n, Matrix3 m)=0
virtual void	ParamBlockSetValue (ParamBlock *pb, int i, BYTE type,...)=0
virtual void	ParamBlock2SetValue (IParamBlock2 *pb, int i, int tabIndex, BYTE type,...)=0
virtual void	ParamBlock2SetCount (IParamBlock2 *pb, int i, int n)=0
virtual void	SetProperty (ReferenceTarget *targ, const MCHAR *prop_name, BYTE type,...)=0
	Provides a simple way to emit a property assignment script.
virtual void	SetCopy (ReferenceTarget *to_copy)=0
	Used to signal that an mr_reftarg argument in the currently accumulating script should be emitted as a copy.
virtual void	SetSelProperty (const MCHAR *prop_name, BYTE type,...)=0
	Provides a simple way to emit a property assignment script for the current selection set.
virtual void	FunctionCall (const MCHAR *op_name, int arg_count, int keyarg_count,...)=0
	Used to build a MAXScript function call.
virtual void	ScriptString (const MCHAR *s)=0
	Emits a piece of macro script as a literal string.
virtual void	Assign (const MCHAR *var_name, BYTE type,...)=0
	Called to emit script to record the assignment to a MAXScript variable.
virtual void	Assign (BYTE type,...)=0
virtual void	OpAssign (const MCHAR *op, BYTE type,...)=0
virtual void	OperandSequence (int count, BYTE type,...)=0
virtual BOOL	BeginSelectNode ()=0
virtual void	Select (INode *)=0
virtual void	DeSelect (INode *)=0
virtual void	MAXCommand (int com)=0
virtual void	AddComment (const MCHAR *str)=0
virtual void	Cancel ()=0
	Cancels and clears the currently accumulating script.
virtual void	EmitScript ()=0
	Signals the completion of an accumulating script, causing it to be frozen in the recorder pane and any new calls that might have been folded into the current script will cause a new one to be started.
virtual MSTR	GetSubMtlPropName (Mtl *m, int i)=0
	Returns the property name of the 'i-th' sub-material of the specified material.
virtual MSTR	GetSubTexmapPropName (ReferenceTarget *m, int i)=0
	Returns the property name of the 'i-th' sub-texmap of the specified material.
virtual void	Enable ()=0
	Enables the Macro Recorder.
virtual void	Disable ()=0
	Disables the Macro Recorder.
virtual BOOL	Enabled ()=0
	Returns true if the Macro Recorder is enabled (via Enable() ), false otherwise.
virtual BOOL	SuperEnable ()=0
	Super enable and option controls.
virtual void	SuperEnable (BOOL onOff)=0
	In the Scripting Listener Window Macro Recorder pull-down menu choice is an option to enable or disable the Macro Recorder.
virtual BOOL	ShowCommandPanelSwitch ()=0
	Returns TRUE if code is emitted when command panels are changed; FALSE if code is not emitted.
virtual void	ShowCommandPanelSwitch (BOOL onOff)=0
	Determines if the macro recorder will emit script for command panel mode changes.
virtual BOOL	ShowToolSelections ()=0
	Returns true if the macro recorder will emit script for 3ds Max toolbar tool selections, false otherwise.
virtual void	ShowToolSelections (BOOL onOff)=0
	Determines if the macro recorder will emit script for 3ds Max toolbar selections.
virtual BOOL	ShowMenuSelections ()=0
	Returns true if the macro recorder will emit script for 3ds Max menu selections, false otherwise.
virtual void	ShowMenuSelections (BOOL onOff)=0
	Determines if the macro recorder will emit script for 3ds Max menu selections.
virtual BOOL	EmitAbsoluteSceneNames ()=0
	Returns true if specific node names are used in the generated code false, if the current selection is used.
virtual void	EmitAbsoluteSceneNames (BOOL onOff)=0
	Controls whether the code generated refers to the exact node names being operated or or simply the current selection.
virtual BOOL	EmitAbsoluteSubObjects ()=0
	Returns true if recording absolute sub-object numbers, false if using the selection set.
virtual void	EmitAbsoluteSubObjects (BOOL onOff)=0
	Determines if code generated is relative to the current sub-object selection state or if explicit sub-object numbers are generated.
virtual BOOL	EmitAbsoluteTransforms ()=0
	Tells if the code is generated using absolute transform assignments.
virtual void	EmitAbsoluteTransforms (BOOL onOff)=0
	Sets if code is generated using absolute transform assignments.
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 ()

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.
Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * >	interfaces

Detailed Description

Provides various methods to emit pieces of script to the Macro Recorder.

There are also methods to specify the nature of the scripts generated by the user operating 3ds Max. Additionally there are methods to enable or disable the recording of scripts. This class may be used by plug-ins but is also used internally as part of the 3ds Max Macro Recorder. Inside key areas of 3ds Max macro scripts are emitted corresponding to the operation being performed. For example when a call goes to a parameter block to set a value 3ds Max internally call this classes method ParamBlock2SetValue(...) to emit script to record the change. Thus, many operations a plug-in performs are recorded automatically. There are however operations a plug-in can perform which won't be recorded automatically. In these cases methods of this class may be used to emit script to record these operations. Several of the functions in this class use an ellipsis argument (...). This ellipsis is the var-args style of passing information to a method. This allows a developer to pass a variable number of values to the method. These are typically a set of tag values followed by some C++ types. The sample code shown with many of the methods shows how this is done. For a starting point for more general information on variable argument lists see va_arg in the Window help file. An instance of the MacroRecorder can be retrieved using the function Interface::GetMacroRecorder().

See also

ClassDesc, INode, IParamBlock, IParamBlock2, Matrix3, ReferenceTarget.

Member Function Documentation

BeginCreate()

virtual BOOL BeginCreate ( ClassDesc *  cd, int  flags = 0  )

pure virtual

Used for implementing a custom creation manager.

This method starts a special accumulation 'mode' in which certain other Macro Recorder calls are treated specially until the next EmitScript(). BeginCreate() effectively signals the start of a scene node creation and enters a mode in which calls to SetNodeTM(), SetProperty(), ParamBlockXSetValue() and SetSelProperty() all generate keyword parameters to the current constructor, rather than emitting stand-alone property assignment scripts. Outside the 'create' mode, a call to SetNodeTM() would generate something like: move $foo [10,0,0]

but when in the mode would add a pos: argument to the constructor:

sphere radius:20 pos:[10,0,0]

Parameters:

ClassDesc* cd Points to the class descriptor for the plug-in.

Returns

This tells you whether MAXScript successfully entered the BeginCreate mode. It will fail if MAXScript can't create the object described by the ClassDesc, so you might use it in some generic situations to decided whether to call the closing EmitScript().

SetNodeTM()

virtual void SetNodeTM ( INode *  n, Matrix3  m  )

pure virtual

For internal use only.

ParamBlockSetValue()

virtual void ParamBlockSetValue ( ParamBlock *  pb, int  i, BYTE  type,   ...  )

pure virtual

For internal use only.

ParamBlock2SetValue()

virtual void ParamBlock2SetValue ( IParamBlock2 *  pb, int  i, int  tabIndex, BYTE  type,   ...  )

pure virtual

For internal use only.

ParamBlock2SetCount()

virtual void ParamBlock2SetCount ( IParamBlock2 *  pb, int  i, int  n  )

pure virtual

For internal use only.

SetProperty()

virtual void SetProperty ( ReferenceTarget *  targ, const MCHAR *  prop_name, BYTE  type,   ...  )

pure virtual

Provides a simple way to emit a property assignment script.

An example of this type of script is s: $sphere01.radius = 50

Parameters

targ	Pointer to the object whose property is changing.
prop_name	The string which is the name of the property. This is the fixed machine-parsable name.
type	One of the type tags from List of Macro Recorder Value Types
...	This ellipsis is the var-args style of passing information to a method. This allows a developer to pass a variable number of values to a method. These are typically a set of 'tags' followed by some C++ data types.

SetCopy()

virtual void SetCopy ( ReferenceTarget *  to_copy )

pure virtual

Used to signal that an mr_reftarg argument in the currently accumulating script should be emitted as a copy.

For example, when maps or materials are dragged onto sub-map/mtl buttons in the material editor, an instance/copy requester dialog is presented and depending on the choice, either a direct assignment or assignment of a copy is appropriate:

meditMaterials[4].materialList[2] = meditMaterials[11] //instance
meditMaterials[4].materialList[2] = copy meditMaterials[11] //copy

The actual assignment script is set up using a macroRecorder->SetProperty() call with the dropped map/material supplied as an mr_reftarg argument. In situations where the copy/instance status is known, you can emit directly an mr_funcall argument for the copy, but there may be situations in which this choice is decided in some piece of remote code or control flow and so you can use this method to condition the emitted script to apply a 'copy ' call.

Parameters

to_copy

The pointer to the object to be copied.

SetSelProperty()

virtual void SetSelProperty ( const MCHAR *  prop_name, BYTE  type,   ...  )

pure virtual

Provides a simple way to emit a property assignment script for the current selection set.

Sample Code:

macroRecorder->SetSelProperty(_M("material"), mr_reftarg, (Mtl*)dropThis);

Parameters

prop_name	The name of the property to set.
type	One of the type tags from List of Macro Recorder Value Types.
...	This ellipsis is the var-args style of passing information to a method. This allows a developer to pass a variable number of values to a method. These are typically a set of 'tags' followed by some C++ types.

FunctionCall()

virtual void FunctionCall ( const MCHAR *  op_name, int  arg_count, int  keyarg_count,   ...  )

pure virtual

Used to build a MAXScript function call.

In the general case, such a call may have positional arguments followed by keyword arguments. Sample Code:

macroRecorder->FunctionCall(_M("addModifier"), 2, 1, mr_reftarg, this,
mr_create, mod->ClassID(), mod->SuperClassID(), 0, _M("before"), mr_int,
before);

This generates an addModifier() function call, such as * addModifier $foo (bend()) before:3 The call has 2 positional arguments and 1 keyword argument (hence the 2, 1). The first positional is given as mr_reftarg, this which refers to the current node, the second positional is given as mr_create, mod->ClassID(), mod->SuperClassID(), 0 which causes a 0-argument constructor to be emitted for the modifier, and finally the single keyword argument is given as _M("before"), mr_int, before which is the keyword name followed by the arg value.

Parameters

op_name	Pointer to the function to call.
arg_count	The number of positional arguments in the var-args section.
keyarg_count	The number of keyword arguments in the var-args section.
...	This ellipsis is the var-args style of passing information to a method. This allows a developer to pass a variable number of values to a method. These are typically a set of 'tags' followed by some C++ types. List of Macro Recorder Value Types for a list of potential tags and arguments.

ScriptString()

virtual void ScriptString ( const MCHAR *  s )

pure virtual

Emits a piece of macro script as a literal string.

To understand when this is used consider the following example. Say you have a button in your user interface which does a certain thing but there is no way using the other macro recorder calls of constructing the piece of script that you need emitted. For instance the button may invoke a for loop. In such a case you can use this method to emit a macro script string which does a for loop. This is a string, just as you would type it into the Scripting Listener.

Parameters

s	Pointer to the string to emit.

Assign() [1/2]

virtual void Assign ( const MCHAR *  var_name, BYTE  type,   ...  )

pure virtual

Called to emit script to record the assignment to a MAXScript variable.

Parameters

var_name	The variable name.
type	One of the type tags from List of Macro Recorder Value Types
...	This ellipsis is the var-args style of passing information to a method. This allows a developer to pass a variable number of values to a method. These are typically a set of 'tags' followed by some C++ types.

Assign() [2/2]

virtual void Assign ( BYTE  type,   ...  )

pure virtual

OpAssign()

virtual void OpAssign ( const MCHAR *  op, BYTE  type,   ...  )

pure virtual

OperandSequence()

virtual void OperandSequence ( int  count, BYTE  type,   ...  )

pure virtual

BeginSelectNode()

virtual BOOL BeginSelectNode ( )

pure virtual

For internal use only.

Select()

virtual void Select ( INode *  )

pure virtual

For internal use only.

DeSelect()

virtual void DeSelect ( INode *  )

pure virtual

For internal use only.

MAXCommand()

virtual void MAXCommand ( int  com )

pure virtual

For internal use only.

AddComment()

virtual void AddComment ( const MCHAR *  str )

pure virtual

Cancel()

virtual void Cancel ( )

pure virtual

Cancels and clears the currently accumulating script.

This would be used for example, if the operation that is being accumulated can be canceled by the user, such as right-clicking out of a transform or a geometry node create. There are calls to macroRecorder()->Cancel() in the MOUSE_ABORT processing in the default creation manager.

EmitScript()

virtual void EmitScript ( )

pure virtual

Signals the completion of an accumulating script, causing it to be frozen in the recorder pane and any new calls that might have been folded into the current script will cause a new one to be started.

For example, when you drag the time slider, the sliderTime assignment script accumulates the changes, but when you let go of the mouse button, an EmitScript() is called, so that subsequent drags will start a separate script fragment. Same with interactive transforms and node creation.

GetSubMtlPropName()

virtual MSTR GetSubMtlPropName ( Mtl *  m, int  i  )

pure virtual

Returns the property name of the 'i-th' sub-material of the specified material.

Parameters

m	The material whose 'i-th' sub-material property name is returned.
i	The zero based index of the sub-material.

GetSubTexmapPropName()

virtual MSTR GetSubTexmapPropName ( ReferenceTarget *  m, int  i  )

pure virtual

Returns the property name of the 'i-th' sub-texmap of the specified material.

Parameters

m	The material or texmap whose 'i-th' sub-texmap property name is returned.
i	The zero based index of the sub-texmap.

Enable()

virtual void Enable ( )

pure virtual

Enables the Macro Recorder.

This call is 'nestable', i.e. it uses a use counter internally so recursive or nested code can manage local enables and disable states.

Disable()

virtual void Disable ( )

pure virtual

Disables the Macro Recorder.

This allows the developer to disable the automatic macro recording.

Enabled()

virtual BOOL Enabled ( )

pure virtual

Returns true if the Macro Recorder is enabled (via Enable() ), false otherwise.

SuperEnable() [1/2]

virtual BOOL SuperEnable ( )

pure virtual

Super enable and option controls.

In the Scripting Listener Window Macro Recorder pull-down menu choice is an option to enable or disable the Macro Recorder. This method corresponds to that state.

Returns

true if enabled, false if disabled.

SuperEnable() [2/2]

virtual void SuperEnable ( BOOL  onOff )

pure virtual

In the Scripting Listener Window Macro Recorder pull-down menu choice is an option to enable or disable the Macro Recorder.

This method sets this state.

Parameters

onOff

true for enabled; false for disabled.

ShowCommandPanelSwitch() [1/2]

virtual BOOL ShowCommandPanelSwitch ( )

pure virtual

Returns TRUE if code is emitted when command panels are changed; FALSE if code is not emitted.

ShowCommandPanelSwitch() [2/2]

virtual void ShowCommandPanelSwitch ( BOOL  onOff )

pure virtual

Determines if the macro recorder will emit script for command panel mode changes.

Parameters

onOff

true to record command panel changes, false to ignore them.

ShowToolSelections() [1/2]

virtual BOOL ShowToolSelections ( )

pure virtual

Returns true if the macro recorder will emit script for 3ds Max toolbar tool selections, false otherwise.

ShowToolSelections() [2/2]

virtual void ShowToolSelections ( BOOL  onOff )

pure virtual

Determines if the macro recorder will emit script for 3ds Max toolbar selections.

Parameters

onOff

true to record toolbar selections, false to ignore them.

ShowMenuSelections() [1/2]

virtual BOOL ShowMenuSelections ( )

pure virtual

Returns true if the macro recorder will emit script for 3ds Max menu selections, false otherwise.

ShowMenuSelections() [2/2]

virtual void ShowMenuSelections ( BOOL  onOff )

pure virtual

Determines if the macro recorder will emit script for 3ds Max menu selections.

Parameters

onOff

true to record menu selections, false to ignore them.

EmitAbsoluteSceneNames() [1/2]

virtual BOOL EmitAbsoluteSceneNames ( )

pure virtual

Returns true if specific node names are used in the generated code false, if the current selection is used.

EmitAbsoluteSceneNames() [2/2]

virtual void EmitAbsoluteSceneNames ( BOOL  onOff )

pure virtual

Controls whether the code generated refers to the exact node names being operated or or simply the current selection.

Parameters

onOff

true to record absolute scene names, false to use the selection set.

EmitAbsoluteSubObjects() [1/2]

virtual BOOL EmitAbsoluteSubObjects ( )

pure virtual

Returns true if recording absolute sub-object numbers, false if using the selection set.

EmitAbsoluteSubObjects() [2/2]

virtual void EmitAbsoluteSubObjects ( BOOL  onOff )

pure virtual

Determines if code generated is relative to the current sub-object selection state or if explicit sub-object numbers are generated.

Parameters

onOff

true to record explicit, absolute sub-object numbers; false to use the selection set.

EmitAbsoluteTransforms() [1/2]

virtual BOOL EmitAbsoluteTransforms ( )

pure virtual

Tells if the code is generated using absolute transform assignments.

Returns

true if code is generated using absolute transform assignments, false if relative transforms operations are generated.

EmitAbsoluteTransforms() [2/2]

virtual void EmitAbsoluteTransforms ( BOOL  onOff )

pure virtual

Sets if code is generated using absolute transform assignments.

Parameters

onOff

true for on, false for off.