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.
#include <imacroscript.h>
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 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.
|
|
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. |
|
Member Function Documentation
| virtual MacroID GetID | ( | ) | [pure virtual] |
Returns the ID for this macro script.
| virtual MSTR& GetName | ( | ) | [pure virtual] |
Returns the name for this macro script.
| virtual MSTR& GetCategory | ( | ) | [pure virtual] |
Returns the category for this macro script.
| virtual MSTR& GetInternalCategory | ( | ) | [pure virtual] |
Returns the internal category for this macro script.
The internal category is the non-localized category name
| virtual MSTR& GetFileName | ( | ) | [pure virtual] |
Returns the file name of the script source text for this macro script.
| 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.
| 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.
| virtual MSTR& GetToolTip | ( | ) | [pure virtual] |
Returns the tooltip text for the UI button.
| virtual MSTR& GetButtonText | ( | ) | [pure virtual] |
Returns the UI button text (for label buttons).
| virtual MSTR& GetButtonIconFile | ( | ) | [pure virtual] |
Returns the file name of the icon file.
| virtual int GetButtonIconIndex | ( | ) | [pure virtual] |
Returns the zero based index of the icon in the icon file.
| 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
| 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.
| 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.
| 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 count The number of elements in params 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.
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 | ) | [pure virtual] |
Returns whether the specified handler exists.
| 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.
| virtual void MarkAsUsed | ( | ) | [pure virtual] |
Flags the macro as used, and to be compiled by CompileUsed().
| 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.
| 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.
| 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.
| virtual void Reset | ( | ) | [pure virtual] |
Clears the code cache and deletes the icon.
| virtual void DeleteThis | ( | ) | [pure virtual] |
| virtual MaxIcon* GetIcon | ( | ) | [pure virtual] |
Returns the icon for this macro script.
