MacroRecorder Class Reference

Search for all occurrences

---

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.

#include <macrorec.h>

Inheritance diagram for MacroRecorder:

List of all members.

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, 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 (MCHAR *prop_name, BYTE type,...)=0
	Provides a simple way to emit a property assignment script for the current selection set.
virtual void	FunctionCall (MCHAR *op_name, int arg_count, int keyarg_count,...)=0
	Used to build a MAXScript function call.
virtual void	ScriptString (MCHAR *s)=0
	Emits a piece of macro script as a literal string.
virtual void	Assign (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 (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 (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	MasterEnable ()=0
	master enable and option controls.
virtual void	MasterEnable (BOOL onOff)=0
	In the MAXScript 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.

---

Member Function Documentation

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

Search for all occurrences

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

virtual void SetNodeTM	(	INode *	n,
		Matrix3	m
	)		[pure virtual]

Search for all occurrences

For internal use only.

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

Search for all occurrences

For internal use only.

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

Search for all occurrences

For internal use only.

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

Search for all occurrences

For internal use only.

virtual void SetProperty	(	ReferenceTarget *	targ,
		MCHAR *	prop_name,
		BYTE	type,
			...
	)		[pure virtual]

Search for all occurrences

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.

virtual void SetCopy

(

ReferenceTarget *

to_copy

)

[pure virtual]

Search for all occurrences

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.

virtual void SetSelProperty	(	MCHAR *	prop_name,
		BYTE	type,
			...
	)		[pure virtual]

Search for all occurrences

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.

virtual void FunctionCall	(	MCHAR *	op_name,
		int	arg_count,
		int	keyarg_count,
			...
	)		[pure virtual]

Search for all occurrences

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.

virtual void ScriptString

(

MCHAR *

s

)

[pure virtual]

Search for all occurrences

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 MAXScript Listener.

Parameters:

s	Pointer to the string to emit.

virtual void Assign	(	MCHAR *	var_name,
		BYTE	type,
			...
	)		[pure virtual]

Search for all occurrences

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.

virtual void Assign	(	BYTE	type,
			...
	)		[pure virtual]

Search for all occurrences

virtual void OpAssign	(	MCHAR *	op,
		BYTE	type,
			...
	)		[pure virtual]

Search for all occurrences

virtual void OperandSequence	(	int	count,
		BYTE	type,
			...
	)		[pure virtual]

Search for all occurrences

virtual BOOL BeginSelectNode

(

)

[pure virtual]

Search for all occurrences

For internal use only.

virtual void Select

(

INode *

)

[pure virtual]

Search for all occurrences

For internal use only.

virtual void DeSelect

(

INode *

)

[pure virtual]

Search for all occurrences

For internal use only.

virtual void MAXCommand

(

int

com

)

[pure virtual]

Search for all occurrences

For internal use only.

virtual void AddComment

(

MCHAR *

str

)

[pure virtual]

Search for all occurrences

virtual void Cancel

(

)

[pure virtual]

Search for all occurrences

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.

virtual void EmitScript

(

)

[pure virtual]

Search for all occurrences

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.

virtual MSTR GetSubMtlPropName	(	Mtl *	m,
		int	i
	)		[pure virtual]

Search for all occurrences

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.

virtual MSTR GetSubTexmapPropName	(	ReferenceTarget *	m,
		int	i
	)		[pure virtual]

Search for all occurrences

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.

virtual void Enable

(

)

[pure virtual]

Search for all occurrences

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.

virtual void Disable

(

)

[pure virtual]

Search for all occurrences

Disables the Macro Recorder.

This allows the developer to disable the automatic macro recording.

virtual BOOL Enabled

(

)

[pure virtual]

Search for all occurrences

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

virtual BOOL MasterEnable

(

)

[pure virtual]

Search for all occurrences

master enable and option controls.

In the MAXScript 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.

virtual void MasterEnable

(

BOOL

onOff

)

[pure virtual]

Search for all occurrences

In the MAXScript 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.

virtual BOOL ShowCommandPanelSwitch

(

)

[pure virtual]

Search for all occurrences

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

virtual void ShowCommandPanelSwitch

(

BOOL

onOff

)

[pure virtual]

Search for all occurrences

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.

virtual BOOL ShowToolSelections

(

)

[pure virtual]

Search for all occurrences

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

virtual void ShowToolSelections

(

BOOL

onOff

)

[pure virtual]

Search for all occurrences

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

Parameters:

onOff

true to record toolbar selections, false to ignore them.

virtual BOOL ShowMenuSelections

(

)

[pure virtual]

Search for all occurrences

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

virtual void ShowMenuSelections

(

BOOL

onOff

)

[pure virtual]

Search for all occurrences

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

Parameters:

onOff

true to record menu selections, false to ignore them.

virtual BOOL EmitAbsoluteSceneNames

(

)

[pure virtual]

Search for all occurrences

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

virtual void EmitAbsoluteSceneNames

(

BOOL

onOff

)

[pure virtual]

Search for all occurrences

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.

virtual BOOL EmitAbsoluteSubObjects

(

)

[pure virtual]

Search for all occurrences

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

virtual void EmitAbsoluteSubObjects

(

BOOL

onOff

)

[pure virtual]

Search for all occurrences

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.

virtual BOOL EmitAbsoluteTransforms

(

)

[pure virtual]

Search for all occurrences

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.

virtual void EmitAbsoluteTransforms

(

BOOL

onOff

)

[pure virtual]

Search for all occurrences

Sets if code is generated using absolute transform assignments.

Parameters:

onOff

true for on, false for off.