#include <imacroscript.h>

Class Description

See also: Class MacroEntry, Class MacroButtonData.

Description:: 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".

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

Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)

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 Function Documentation

virtual MacroEntry* GetMacro ( MacroID mid )

pure virtual

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

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

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

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

virtual MacroEntry* GetMacro ( int index )

pure virtual

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

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

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

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

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

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

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

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

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

pure virtual

virtual Value* GetHandler	(	MacroID	mid,
		Value *	handler_name
	)

pure virtual

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

pure virtual

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

virtual void SetMacroScriptPath ( const MCHAR * path_name )

pure virtual

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

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

MacroDir Class Reference

Class Description

Public Member Functions

Additional Inherited Members

Member Function Documentation