Detailed Description

See also:: Class MacroEntry, Class MacroButtonData.

Description:: This class is available in release 3.0 and later only.

This class provides access to Macro scripts. Macro scripts (or macros) are scripts that live in buttons and menus in the customizable UI. Methods of this class are availalble to access macros using IDs or category and name strings, methods to edit macro scripts, methods to execute macros, and methods for directory scanning and loading.

The directory instance (access via the global function GetMacroScriptDir()) is used by the CUI to provide a list of available macros in the toolbar/menu editor. The API also provides a way for the CUI to open a macro editor to allow on-the-fly creation of macro scripts.

The macro script manager keeps a directory of all known macros and provides an API for running and editing macros and for accessing and updating the directory.

Macros are normally entered into the directory by the MAXScript compiler as a side-effect of compiling a macro definition. Anyone using MAXScript can at any time eval a macro definition and thereby add CUI macro scripts.

Consequently, macros can be stored in any script file and be loaded just by executing the file. The macro definition syntax permits any number of macros per file.

Most macros will be stored in files in a special CUI macro or config directory so that a user can take all his custom UI stuff with him by copying directories. (This directory supports recursive scanning of sub-dirs, so users can organize their macros). On-the-fly macro creation in the CUI editor or by text drag-and-drop onto the shelf or by evaling a definition in the listener will generate a file in this directory to provide permanent storage.

Note: typedef short MacroID;

Note: In order to use these methods you need to #include "IMACROSCRIPT.H" and link to "MAXSCRPT.LIB".

#include <imacroscript.h>

Inheritance diagram for MacroDir:

Public Member Functions
virtual MacroEntry *	GetMacro (MacroID mid)=0
virtual MacroEntry *	FindMacro (const MCHAR category, const MCHAR name)=0
virtual BOOL	ValidID (MacroID mid)=0
virtual int	Count ()=0
virtual MacroEntry *	GetMacro (int index)=0
virtual MacroEntry *	AddMacro (const MCHAR category, const MCHAR internalCategory, const MCHAR name, const MCHAR tooltip, const MCHAR buttonText, const MCHAR sourceFile, int sourceOffset)=0
virtual MacroEntry *	AddMacro (const MCHAR category, const MCHAR internalCategory, const MCHAR name, const MCHAR tooltip, const MCHAR buttonText, const MCHAR sourceText)=0
virtual BOOL	SetMacro (MacroID mid, const MCHAR tooltip, const MCHAR btnText, const MCHAR *sourceFile, int sourceOffset)=0
virtual MCHAR *	MakeNameValid (MCHAR *s)=0
virtual MCHAR *	MakeCategoryValid (MCHAR *s)=0
virtual BOOL	EditMacro (MacroID mid)=0
virtual Value *	Execute (MacroID mid)=0
virtual Value *	CallHandler (MacroID mid, Value handler_or_name, Value *arg_list, int count, BOOL hold=TRUE)=0
virtual FPStatus	CallHandler (MacroID mid, const MCHAR handler_name, FPParams params, FPValue &result, BOOL hold=TRUE)=0
virtual Value *	GetHandler (MacroID mid, Value *handler_name)=0
virtual void	LoadMacroScripts (const MCHAR *path_name=NULL, BOOL recurse=TRUE)=0
virtual MacroEntry *	LoadMacroScript (const MCHAR *file_name)=0
virtual void	SetMacroScriptPath (const MCHAR *path_name)=0
virtual const MCHAR *	GetMacroScriptPath ()=0

Member Function Documentation

virtual MacroEntry* GetMacro ( MacroID mid ) [pure virtual]

Search for all occurrences

Remarks:: Returns a pointer to the MacroEntry for the macro script whose ID is passed.

Parameters:: MacroID mid

The ID of the macro.

virtual MacroEntry* FindMacro	(	const MCHAR *	category,
		const MCHAR *	name
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Returns a pointer to the MacroEntry corresponding to the given category and name strings passed (or NULL if not found).

Parameters:: MCHAR* category

The category name.

MCHAR* name

The macro script name.

virtual BOOL ValidID ( MacroID mid ) [pure virtual]

Search for all occurrences

Remarks:: Returns TRUE if the macro ID is valid (or unused); otherwise FALSE.

Parameters:: MacroID mid

The ID to check.

virtual int Count ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the number of macro entries in this macro directory.

virtual MacroEntry* GetMacro ( int index ) [pure virtual]

Search for all occurrences

Remarks:: Returns a pointer to the macro entry whose index in the directory is passed.

Parameters:: int index

The zero based index of the entry. This is a value between 0 and Count()-1.

virtual MacroEntry* AddMacro	(	const MCHAR *	category,
		const MCHAR *	internalCategory,
		const MCHAR *	name,
		const MCHAR *	tooltip,
		const MCHAR *	buttonText,
		const MCHAR *	sourceFile,
		int	sourceOffset
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Adds the macro whose parameters are passed and returns a pointer to the new macro entry. This form allows you to define a macro that is already in a file, by giving a source file name and seek offset into that file. This is typically used by the MAXScript compiler and .mcr file scanner to register macro definitions they come across.

Parameters:: MCHAR* category

The category for the macro.

MCHAR* name

The name for the macro.

MCHAR* tooltip

The tooltip text.

MCHAR* buttonText

The button text.

MCHAR* sourceFile

The source file name.

int sourceOffset

The line number of the first line of the script in the source file.

virtual MacroEntry* AddMacro	(	const MCHAR *	category,
		const MCHAR *	internalCategory,
		const MCHAR *	name,
		const MCHAR *	tooltip,
		const MCHAR *	buttonText,
		const MCHAR *	sourceText
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Add or replaces a macro using given source text as the body of the macro. In this overload, name can be NULL in which case a unique name is generated.

This form takes the body of the actual macro script as the sourceText argument and places it in a newly-created file in the UI directory and registers that file and a zero offset as the macro definition. All macroScripts need to be in files somewhere so that they are persistent if referenced in a CUI toolbar that the user saves. This form is used, for example, by the toolbar manager when you drag a piece of selected text onto a toolbar to cause a script button to be created.

Parameters:: MCHAR* category

The category for the macro.

MCHAR* name

The name for the macro or NULL to generate a unique name.

MCHAR* tooltip

The tooltip text.

MCHAR* buttonText

The button text.

MCHAR* sourceText

The source text.

virtual BOOL SetMacro	(	MacroID	mid,
		const MCHAR *	tooltip,
		const MCHAR *	btnText,
		const MCHAR *	sourceFile,
		int	sourceOffset
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Sets the parameters for the macro entry whose ID is passed.

Parameters:: MacroID mid

The macro ID.

MCHAR* tooltip

The tooltip text.

MCHAR* btnText

The button text.

MCHAR* sourceFile

The source file name.

int sourceOffset

The sorce offset.

Returns:: TRUE if set; FALSE if the ID was not found.

virtual MCHAR* MakeNameValid ( MCHAR * s ) [pure virtual]

Search for all occurrences

Remarks:: This method modifies the string in place to be a valid macro name (no punctuations other than spaces).

Parameters:: MCHAR* s

The name string.

virtual MCHAR* MakeCategoryValid ( MCHAR * s ) [pure virtual]

Search for all occurrences

Remarks:: This method modifies the string in place to be a valid category name (no punctuations other than spaces).

Parameters:: MCHAR* s

The category string.

virtual BOOL EditMacro ( MacroID mid ) [pure virtual]

Search for all occurrences

Remarks:: This methods brings up the editor for editing the specified macro script text.

Parameters:: MacroID mid

The ID of the macro script to edit.

virtual Value* Execute ( MacroID mid ) [pure virtual]

Search for all occurrences

Remarks:: Executes the macro script whose ID is passed.

Parameters:: MacroID mid

The ID of the macro to execute.

Returns:: A pointer to the result of executing the macro. If a developer does't care about the result of executing a macroScript, which is usually the case, then the Value* returned from this method can just be ignored. If a developer does care, then the necessary information about working with Value*'s is in the MAXScript SDK documentation.

virtual Value* CallHandler	(	MacroID	mid,
		Value *	handler_or_name,
		Value **	arg_list,
		int	count,
		BOOL	hold = `TRUE`
	)		`[pure virtual]`

Search for all occurrences

virtual FPStatus CallHandler	(	MacroID	mid,
		const MCHAR *	handler_name,
		FPParams *	params,
		FPValue &	result,
		BOOL	hold = `TRUE`
	)		`[pure virtual]`

Search for all occurrences

virtual Value* GetHandler	(	MacroID	mid,
		Value *	handler_name
	)		`[pure virtual]`

Search for all occurrences

virtual void LoadMacroScripts	(	const MCHAR *	path_name = `NULL`,
		BOOL	recurse = `TRUE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This method loads all the macro scripts found in the specified path and optionally its sub-directories. You can point this method at any directory and it will scan it for .mcr files and scan those for macroScript definitions. 3ds Max uses this during startup to scan the UI directory (recursively) for .mcr files.

Parameters:: MCHAR* path_name = NULL

The path to check. If NULL the default path is used.

BOOL recurse = TRUE

If TRUE nested sub-directories are scanned and loaded as well.

virtual MacroEntry* LoadMacroScript ( const MCHAR * file_name ) [pure virtual]

Search for all occurrences

virtual void SetMacroScriptPath ( const MCHAR * path_name ) [pure virtual]

Search for all occurrences

Remarks:: Sets the default path for storing / searching macro script files.

Parameters:: MCHAR* path_name

The path to set.

virtual const MCHAR* GetMacroScriptPath ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the default path for storing / searching macro script files.

MacroDir Class Reference

Detailed Description

Public Member Functions

Member Function Documentation