MacroEntry Class Reference

This class provides access to a single macro entry. More...

#include <imacroscript.h>

Inheritance diagram for MacroEntry:

Classes
class	DisableCompileGuard
	Helper class for disabling macroscript compiles in an exception-safe manner. More...

Public Member Functions
virtual MacroID	GetID ()=0
	Returns the ID for this macro script.
virtual MSTR &	GetName ()=0
	Returns the name for this macro script.
virtual MSTR &	GetCategory ()=0
	Returns the category for this macro script.
virtual MSTR &	GetInternalCategory ()=0
	Returns the internal category for this macro script.
virtual MSTR &	GetFileName ()=0
	Returns the file name of the script source text for this macro script.
virtual long	GetOffset ()=0
	Returns the byte offset for this macro script.
virtual Value *	GetCode ()=0
	Returns the executable codetree for this macro script.
virtual MSTR &	GetToolTip ()=0
	Returns the tooltip text for the UI button.
virtual MSTR &	GetButtonText ()=0
	Returns the UI button text (for label buttons).
virtual MSTR &	GetButtonIconFile ()=0
	Returns the file name of the icon file.
virtual int	GetButtonIconIndex ()=0
	Returns the zero based index of the icon in the icon file.
virtual MSTR &	GetButtonIconName ()=0
	Returns the name of the multi-resolution icon assigned to the UI button.
virtual short	GetFlags (short mask)=0
	Returns the state of the specified flags.
virtual Value *	Execute ()=0
	Executes this macro entry.
virtual Value *	CallHandler (Value *handler_or_name, Value **arg_list, int count, BOOL hold=TRUE)=0
	Executes the specified handler in this macro entry.
virtual FPStatus	CallHandler (const MCHAR *handler_name, FPParams *params, FPValue &result, BOOL hold=TRUE)=0
	Executes the specified handler in this macro entry.
virtual Value *	GetHandler (Value *handler_name)=0
	Returns a Value* that can be passed to CallHandler() if the specified handler exists, NULL of the handler doesn't exist.
virtual BOOL	HasHandler (const MCHAR *handler_name)=0
	Returns whether the specified handler exists.
virtual BOOL	Compile (Parser *parser=NULL)=0
	Compiles this macro entry.
virtual void	MarkAsUsed ()=0
	Flags the macro as used, and to be compiled by CompileUsed().
virtual void	Reset ()=0
	Clears the code cache and deletes the icon.
virtual void	DeleteThis ()=0
virtual MaxIcon *	GetIcon ()=0
	Returns the icon for this macro script.
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 ()

Static Public Member Functions
static ScripterExport void	DisableCompiles ()
	Disables compile of all the macros.
static ScripterExport void	EnableCompiles ()
	Enables compile of all the macros.
static ScripterExport void	CompileUsed ()
	Batch compiles the macros flagged as used by MarkAsUsed.
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.

Additional Inherited Members
Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * >	interfaces

Detailed Description

This class provides access to a single macro entry.

There are methods provided to access the macro ID, name, category, file name, tooltip, UI button text, and the UI button icon. MacroEntries are returned from methods of class MacroDir. Macro scripts (or macros) are scripts that live in buttons and menus in the new customizable UI. 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. All macro scripts have a name and a category. The category is used to organize the macros into groupings and is given to the macro script at definition time. If you look at the macro scripts list in the UI Customize dialog, you see a Category dropdown with things like 'Cameras', 'DragandDrop', 'LightTools', etc., which is derived from the all categories present in the currently-defined macroscripts. Note that the normal way to define a macroScript is through MAXScript, the .mcr files in the UI/MacroScripts directory contain examples, and they all have category definitions. Note: In order to use these methods you need to link to "MAXSCRPT.LIB".

See also

Class MacroDir, Class MacroButtonData.

Member Function Documentation

GetID()

virtual MacroID GetID ( )

pure virtual

Returns the ID for this macro script.

GetName()

virtual MSTR & GetName ( )

pure virtual

Returns the name for this macro script.

GetCategory()

virtual MSTR & GetCategory ( )

pure virtual

Returns the category for this macro script.

GetInternalCategory()

virtual MSTR & GetInternalCategory ( )

pure virtual

Returns the internal category for this macro script.

The internal category is the non-localized category name

GetFileName()

virtual MSTR & GetFileName ( )

pure virtual

Returns the file name of the script source text for this macro script.

GetOffset()

virtual long GetOffset ( )

pure virtual

Returns the byte offset for this macro script.

There can be any number of macroScripts in a single source file and the offset keeps track of the beginning of its definition in the file.

GetCode()

virtual Value * GetCode ( )

pure virtual

Returns the executable codetree for this macro script.

When the macroScript is defined, only its source file and source offset are registered. When the user first runs it, the MAXScript compiler is used to compile the definition into executable code, which is then cached and used for any later executions and is what this method returns. If this returns NULL, the macro hasn't been compiled or run yet. Another way to run the macro is via the MacroEntry::Execute() and this causes the code to be cached as a side effect also. Normally, developers only ever need to use the Execute() method, but if they are using the MAXScript SDK, they can grab the code using GetCode() and work with it directly.

GetToolTip()

virtual MSTR & GetToolTip ( )

pure virtual

Returns the tooltip text for the UI button.

GetButtonText()

virtual MSTR & GetButtonText ( )

pure virtual

Returns the UI button text (for label buttons).

GetButtonIconFile()

virtual MSTR & GetButtonIconFile ( )

pure virtual

Returns the file name of the icon file.

GetButtonIconIndex()

virtual int GetButtonIconIndex ( )

pure virtual

Returns the zero based index of the icon in the icon file.

GetButtonIconName()

virtual MSTR & GetButtonIconName ( )

pure virtual

Returns the name of the multi-resolution icon assigned to the UI button.

See also

QIcon MaxSDK::LoadMaxMultiResIcon( const QString& iconName )

GetFlags()

virtual short GetFlags ( short  mask )

pure virtual

Returns the state of the specified flags.

Parameters

mask

The flags to get. One or more of the following values: ME_DROPPED_SCRIPT Macro made from some drag-and-dropped text. ME_SILENT_ERRORS Macro won't report any runtime errors. ME_HAS_EXECUTE Macro has execute handler. ME_TEMPORARY Macro is temporary dropScript. ME_NO_AUTO_UNDO Execution of the macroscript is not automatically wrapped in a thehold begin/accept. ME_NEEDS_COMPILE Macro marked for delayed compile.

Returns

The mask value ANDed with internal state for the above values

Execute()

virtual Value * Execute ( )

pure virtual

Executes this macro entry.

Returns

A pointer to the result of executing the macro. If a developer doesn't care about the result of executing a macro script, 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 Values is in the MAXScript SDK documentation.

CallHandler() [1/2]

virtual Value * CallHandler ( Value *  handler_or_name, Value **  arg_list, int  count, BOOL  hold = TRUE  )

pure virtual

Executes the specified handler in this macro entry.

Parameters

handler_or_name	Either the name of the hander to run as a Name value, or the Value* returned by a call to GetHandler().
arg_list	An array of Value* that is passed to the handler function
count	The number of elements in arg_list
hold	If true, the execution of the handler will be wrapped in an undo entry. The undo entry's name is the macroscript's name

Returns

A pointer to the result of executing the macro's handler. If a developer doesn't care about the result of executing a macro script, 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.

CallHandler() [2/2]

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

pure virtual

Executes the specified handler in this macro entry.

Parameters

handler_name	The name of the hander to run
params	An array of FPParams* that is passed to the handler function
result	[out] If the handler successfully executed, the result of executing the handler
hold	If true, the execution of the handler will be wrapped in an undo entry. The undo entry's name is the macroscript's name

Returns

The failure or success status of the call.

GetHandler()

virtual Value * GetHandler ( Value *  handler_name )

pure virtual

Returns a Value* that can be passed to CallHandler() if the specified handler exists, NULL of the handler doesn't exist.

HasHandler()

virtual BOOL HasHandler ( const MCHAR *  handler_name )

pure virtual

Returns whether the specified handler exists.

Compile()

virtual BOOL Compile ( Parser *  parser = NULL )

pure virtual

Compiles this macro entry.

Parameters

parser

The specified parser will be used to to perform the compile. If NULL, a temporary parser will be created and used.

Returns

True if the macro successfully compiled.

MarkAsUsed()

virtual void MarkAsUsed ( )

pure virtual

Flags the macro as used, and to be compiled by CompileUsed().

DisableCompiles()

static ScripterExport void DisableCompiles ( )

static

Disables compile of all the macros.

A MacroEntry is implicitly marked as used if an attempt is made to compile it while MacroEntry compiles are disabled. Calls to this method must be paired with a call to EnableCompiles. The used MacroEntrys are DisableCompiles batch compiled with a call to CompileUsed. Nested calls to DisableCompiles are allowed, with MacroEntry compiles disabled until the call to outermost EnableCompiles occurs. See MacroEntry::DisableCompileGuard for a class that disables compiles when instance created, and enables compiles when instance is deleted.

EnableCompiles()

static ScripterExport void EnableCompiles ( )

static

Enables compile of all the macros.

A MacroEntry is implicitly marked as used if an attempt is made to compile it while MacroEntry compiles are disabled. Calls to DisableCompiles must be paired with a call to this method. The used MacroEntrys are then batch compiled with a call to CompileUsed. Nested calls to DisableCompiles are allowed, with MacroEntry compiles disabled until the call to outermost EnableCompiles occurs.

CompileUsed()

static ScripterExport void CompileUsed ( )

static

Batch compiles the macros flagged as used by MarkAsUsed.

A MacroEntry can be explicitly marked as used, or implicitly marked as used if an attempt is made to compile it while MacroEntry compiles are disabled. This method causes the MacroEntrys marked as used to be batch compiled. The batch compile may be multithreaded, so this can be faster than compiling the MacroEntrys individually.

Reset()

virtual void Reset ( )

pure virtual

Clears the code cache and deletes the icon.

DeleteThis()

virtual void DeleteThis ( )

pure virtual

GetIcon()

virtual MaxIcon * GetIcon ( )

pure virtual

Returns the icon for this macro script.