3ds Max C++ API Reference
Loading...
Searching...
No Matches
MacroEntry Class Referenceabstract

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 MSTRGetName ()=0
 Returns the name for this macro script.
 
virtual MSTRGetCategory ()=0
 Returns the category for this macro script.
 
virtual MSTRGetInternalCategory ()=0
 Returns the internal category for this macro script.
 
virtual MSTRGetFileName ()=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 ValueGetCode ()=0
 Returns the executable codetree for this macro script.
 
virtual MSTRGetToolTip ()=0
 Returns the tooltip text for the UI button.
 
virtual MSTRGetButtonText ()=0
 Returns the UI button text (for label buttons).
 
virtual MSTRGetButtonIconFile ()=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 MSTRGetButtonIconName ()=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 ValueExecute ()=0
 Executes this macro entry.
 
virtual ValueCallHandler (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 ValueGetHandler (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 MaxIconGetIcon ()=0
 Returns the icon for this macro script.
 
- Public Member Functions inherited from BaseInterfaceServer
UtilExport BaseInterfaceGetInterface (Interface_ID id) override
 
virtual UtilExport int NumInterfaces () const
 
virtual UtilExport BaseInterfaceGetInterfaceAt (int i) const
 
virtual UtilExport ~BaseInterfaceServer ()
 
- Public Member Functions inherited from InterfaceServer
virtual UtilExport ~InterfaceServer ()
 Destructor.
 
virtual UtilExport BaseInterfaceGetInterface (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 voidoperator new (size_t size)
 Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator new[] (size_t size)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator new[] (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate arrays of objects.
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidaligned_malloc (size_t size, size_t alignment)
 Allocates memory on a specified alignment boundary.
 
static UtilExport voidaligned_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
maskThe flags to get. One or more of the following values:
  1. ME_DROPPED_SCRIPT Macro made from some drag-and-dropped text.
  2. ME_SILENT_ERRORS Macro won't report any runtime errors.
  3. ME_HAS_EXECUTE Macro has execute handler.
  4. ME_TEMPORARY Macro is temporary dropScript.
  5. ME_NO_AUTO_UNDO Execution of the macroscript is not automatically wrapped in a thehold begin/accept.
  6. 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_nameEither the name of the hander to run as a Name value, or the Value* returned by a call to GetHandler().
arg_listAn array of Value* that is passed to the handler function
countThe number of elements in arg_list
holdIf 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_nameThe name of the hander to run
paramsAn array of FPParams* that is passed to the handler function
result[out] If the handler successfully executed, the result of executing the handler
holdIf 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
parserThe 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.