imacroscript.h

Go to the documentation of this file.

/*  
 *      imacroscript.h - Public interface to Macro script manager for the MAX CUI
 *
 *  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.
 *
 *  The directory is used by the CUI to provide a list of available macros in the 
 *  toolbar/menu/shelf editor.  The API also provides a way for the CUI
 *  to open a macro editor to allow on-the-fly creation of macro scripts. 
 *
 *  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.
 *
 *          Copyright (c) Autodesk, Inc, 1998.  John Wainwright.
 *
 */

#pragma once

#include "iFnPub.h"
#include "actiontableTypedefs.h"
#include "maxscript/ScripterExport.h"
// forward declarations
class Value;
class Parser;

typedef short MacroID;
/* ----------------  macro directory -------------------------- */

class MacroEntry : public BaseInterfaceServer
{
public:
    // access
    virtual MacroID     GetID() = 0;
    virtual MSTR&       GetName() = 0;
    virtual MSTR&       GetCategory() = 0;
    virtual MSTR&       GetInternalCategory() = 0;
    virtual MSTR&       GetFileName() = 0;

    virtual long        GetOffset() = 0;

    virtual Value*      GetCode() = 0;
    virtual MSTR&       GetToolTip() = 0;
    virtual MSTR&       GetButtonText() = 0;
    virtual MSTR&       GetButtonIconFile() = 0;
    virtual int         GetButtonIconIndex() = 0;

    virtual short       GetFlags(short mask) = 0;

    // execution

    virtual Value*      Execute() = 0;

    // R4 extension to support body structured into handlers

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

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

    virtual Value*      GetHandler(Value* handler_name)=0;

    virtual BOOL        HasHandler(const MCHAR* handler_name)=0;


    virtual BOOL        Compile(Parser* parser = NULL) = 0;

    virtual void        MarkAsUsed() = 0;


    ScripterExport static void          DisableCompiles();


    ScripterExport static void          EnableCompiles();


    ScripterExport static void          CompileUsed();

    virtual void        Reset() = 0;

    // cleanup
    virtual void        DeleteThis() = 0;

    virtual MaxIcon*    GetIcon()=0;
};

#define ME_DROPPED_SCRIPT   0x0001      // macro made from some drag-and-dropped text
#define ME_SILENT_ERRORS    0x0002      // macro won't report any runtime errors
#define ME_HAS_EXECUTE      0x0004      // has execute handler
#define ME_TEMPORARY        0x0008      // temporary dropScript
#define ME_NO_AUTO_UNDO     0x0010      // execution of the macroscript is not automatically wrapped in a thehold begin/accept
#define ME_NEEDS_COMPILE    0x0020      // macro should be compiled when maxscript starts up

#define BAD_MACRO_ID        -1          // illegal macroID 

class MacroDir : public InterfaceServer
{
public:

    // access by ID or category & name strings
    virtual MacroEntry* GetMacro(MacroID mid) = 0;
    virtual MacroEntry* FindMacro(const MCHAR* category, const MCHAR* name) = 0;
    virtual BOOL        ValidID(MacroID mid) = 0;

    // iteration 
    virtual int         Count() = 0;
    virtual MacroEntry* GetMacro(int index) = 0;

    // macro entry management

// LAM - 10/15/01 - when SDK can change, remove the following and uncomment the versions where internalCategory
// is passed in. Internally, only the verions using internalCategory are used.
    virtual MacroEntry* AddMacro(const MCHAR* category, const MCHAR* internalCategory, const MCHAR* name, 
                                 const MCHAR* tooltip, const MCHAR* buttonText,
                                 const MCHAR* sourceFile, int sourceOffset) = 0;
    virtual MacroEntry* AddMacro(const MCHAR* category, const MCHAR* internalCategory, const MCHAR* name, 
                                 const MCHAR* tooltip, const MCHAR* buttonText,
                                 const MCHAR* sourceText) = 0;

    virtual BOOL        SetMacro(MacroID mid, const MCHAR* tooltip, const MCHAR* btnText, const MCHAR* sourceFile, int sourceOffset) = 0;
    virtual MCHAR*      MakeNameValid(MCHAR* s) = 0;
    virtual MCHAR*      MakeCategoryValid(MCHAR* s) = 0;
    
    // editing
    virtual BOOL        EditMacro(MacroID mid) = 0;
    
    // execution
    virtual Value*      Execute(MacroID mid) = 0;
    // R4 extension to support body structured into handlers
    virtual Value*      CallHandler(MacroID mid, Value* handler_or_name, Value** arg_list, int count, BOOL hold = TRUE)=0;
    virtual FPStatus    CallHandler(MacroID mid, const MCHAR* handler_name, FPParams* params, FPValue& result, BOOL hold = TRUE)=0;
    virtual Value*      GetHandler(MacroID mid, Value* handler_name)=0;

    // macro-script file directory scanning & loading
    virtual void        LoadMacroScripts(const MCHAR* path_name = NULL, BOOL recurse = TRUE) = 0;
    virtual MacroEntry* LoadMacroScript(const MCHAR* file_name) = 0;

    // set & get default path for storing/searching macro script files
    virtual void        SetMacroScriptPath(const MCHAR* path_name) = 0;
    virtual const MCHAR*        GetMacroScriptPath() = 0;
};

#if defined(BLD_CORE)

    extern MacroDir& GetMacroScriptDir();
#else

    extern ScripterExport MacroDir& GetMacroScriptDir();
    extern ScripterExport void InitMacroScriptDir();
#endif

// ActionTableIds
const ActionTableId   kActionMacroScripts = 647394;
const ActionContextId kActionMacroScriptsContext = 647394;