Class MacroEntry
See Also: Class MacroDir, Class MacroButtonData.
class MacroEntry : public BaseInterfaceServer
Description:
This class is available in release 3.0 and later only.
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 #include "IMACROSCRIPT.H" and link to "MAXSCRPT.LIB".
Methods:
public:
Prototype:
virtual MacroID GetID()=0;
Remarks:
Returns the ID for this macro script. Note: typedef short MacroID;
Prototype:
virtual TSTR& GetName()=0;
Remarks:
Returns the name for this macro script.
Prototype:
virtual TSTR& GetCategory()=0;
Remarks:
Returns the category for this macro script.
Prototype:
virtual TSTR& GetFileName()=0;
Remarks:
Returns the file name of the script source text for this script.
Prototype:
virtual void SetFileName(TCHAR* fn)=0;
Remarks:
Sets the file name for the script source.
Parameters:
TCHAR* fn
The file name to set.
Prototype:
virtual void SetOffset(int o)=0;
Remarks:
Sets the offset for this macro script entry. 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.
Parameters:
int o
The offset to set.
Prototype:
virtual long GetOffset()=0;
Remarks:
Returns the offset for this macro script entry. See SetOffset() above.
Prototype:
virtual Value* GetCode()=0;
Remarks:
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.
Prototype:
virtual TSTR& GetToolTip()=0;
Remarks:
Returns the tooltip text for the UI button.
Prototype:
virtual void SetToolTip(TCHAR* tt)=0;
Remarks:
Sets the tooltip text for the UI button.
Parameters:
TCHAR* tt
The tooltip text to set.
Prototype:
virtual TSTR& GetButtonText()=0;
Remarks:
Returns the UI button text (for label buttons).
Prototype:
virtual void SetButtonText(TCHAR* bt)=0;
Remarks:
Sets the UI button text (for label buttons).
Parameters:
TCHAR* bt
The button text.
Prototype:
virtual void SetButtonIcon(TCHAR* icnf, int indx)=0;
Remarks:
Sets the UI button icon via a base icon file name and index into the specified BMP bitmap.
Parameters:
TCHAR* icnf
The file name of the BMP file. See the remarks in Class CUIFrameMgr for details on the naming scheme.
int indx
The zero based index of the icon in the BMP file. The first icon is 0, the second is 1, etc.
Prototype:
virtual TSTR& GetButtonIconFile()=0;
Remarks:
Returns the file name of the icon file.
Prototype:
virtual int GetButtonIconIndex()=0;
Remarks:
Returns the zero based index of the icon in the icon file.
Prototype:
virtual void SetFlags(short mask)=0;
Remarks:
Sets the specified flags.
Parameters:
short mask
The flags to set. 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.
Prototype:
virtual void ClearFlags(short mask)=0;
Remarks:
Clears the specifed flags.
Parameters:
short mask
The flags to clear. 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.
Prototype:
virtual short GetFlags(short mask)=0;
Remarks:
Returns the state of the specified flags.
Parameters:
short 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.
Prototype:
virtual Value* Execute()=0;
Remarks:
Executes this macro entry.
Return Value:
A pointer to the result of executing the macro. If a developer does'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.