Class MacroDir
See Also: Class MacroEntry, Class MacroButtonData.
class MacroDir : public InterfaceServer
Description:
This class is available in release 3.0 and later only.
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".
The following global functions are not part of this class but are available for use:
Function:
MacroDir& GetMacroScriptDir();
Remarks:
This global function is available in release 3.0 and later only.
Returns a reference to the macro script directory.
Function:
void InitMacroScriptDir();
Remarks:
This global function is available in release 3.0 and later only.
This is an internal only function used by 3ds max during startup to get the macroScript system initialized.
Methods:
public:
Prototype:
virtual MacroEntry* GetMacro(MacroID mid)=0;
Remarks:
Returns a pointer to the MacroEntry for the macro script whose ID is passed.
Parameters:
MacroID mid
The ID of the macro.
Prototype:
virtual MacroEntry* FindMacro(TCHAR* category, TCHAR* name)=0;
Remarks:
Returns a pointer to the MacroEntry corresponding to the given category and name strings passed (or NULL if not found).
Parameters:
TCHAR* category
The category name.
TCHAR* name
The macro script name.
Prototype:
virtual BOOL ValidID(MacroID mid)=0;
Remarks:
Returns TRUE if the macro ID is valid (or unused); otherwise FALSE.
Parameters:
MacroID mid
The ID to check.
Prototype:
virtual int Count()=0;
Remarks:
Returns the number of macro entries in this macro directory.
Prototype:
virtual MacroEntry* GetMacro(int index)=0;
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.
Prototype:
virtual MacroEntry* AddMacro(TCHAR* category, TCHAR* name, TCHAR* tooltip, TCHAR* buttonText, TCHAR* sourceFile, int sourceOffset)=0;
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:
TCHAR* category
The category for the macro.
TCHAR* name
The name for the macro.
TCHAR* tooltip
The tooltip text.
TCHAR* buttonText
The button text.
TCHAR* sourceFile
The source file name.
int sourceOffset
The line number of the first line of the script in the source file.
Prototype:
virtual MacroEntry* AddMacro(TCHAR* category, TCHAR* name, TCHAR* tooltip, TCHAR* buttonText, TCHAR* sourceText)=0;
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:
TCHAR* category
The category for the macro.
TCHAR* name
The name for the macro or NULL to generate a unique name.
TCHAR* tooltip
The tooltip text.
TCHAR* buttonText
The button text.
TCHAR* sourceText
The source text.
Prototype:
virtual BOOL SetMacro(MacroID mid, TCHAR* tooltip, TCHAR* btnText, TCHAR* sourceFile, int sourceOffset)=0;
Remarks:
Sets the parameters for the macro entry whose ID is passed.
Parameters:
MacroID mid
The macro ID.
TCHAR* tooltip
The tooltip text.
TCHAR* btnText
The button text.
TCHAR* sourceFile
The source file name.
int sourceOffset
The sorce offset.
Return Value:
TRUE if set; FALSE if the ID was not found.
Prototype:
virtual TCHAR* MakeNameValid(TCHAR* s)=0;
Remarks:
This method modifies the string in place to be a valid macro name (no punctuations other than spaces).
Parameters:
TCHAR* s
The name string.
Prototype:
virtual TCHAR* MakeCategoryValid(TCHAR* s)=0;
Remarks:
This method modifies the string in place to be a valid category name (no punctuations other than spaces).
Parameters:
TCHAR* s
The category string.
Prototype:
virtual BOOL EditMacro(MacroID mid)=0;
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.
Prototype:
virtual Value* Execute(MacroID mid)=0;
Remarks:
Executes the macro script whose ID is passed.
Parameters:
MacroID mid
The ID of the macro to execute.
Return Value:
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.
Prototype:
virtual void LoadMacroScripts(TCHAR* path_name = NULL, BOOL recurse = TRUE)=0;
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:
TCHAR* 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.
Prototype:
virtual void SetMacroScriptPath(TCHAR* path_name)=0;
Remarks:
Sets the default path for storing / searching macro script files.
Parameters:
TCHAR* path_name
The path to set.
Prototype:
virtual TCHAR* GetMacroScriptPath()=0;
Remarks:
Returns the default path for storing / searching macro script files.