PI/PI_EditScriptedParms.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        PI_EditScriptedParms.h ( OP Library, C++)
 *
 * COMMENTS:    Provides a data structure for holding all the information
 *              required to edit the parameters of a PI_ScriptOperator.
 */

#ifndef __PI_EditScriptedParms__
#define __PI_EditScriptedParms__

#include "PI_API.h"
#include <UT/UT_Color.h>
#include <UT/UT_String.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_PtrArray.h>
#include <CH/CH_ExprLanguage.h>
#include <PRM/PRM_Type.h>
#include <OP/OP_Node.h>

class UT_IntArray;
class UT_SymbolTable;
class PRM_Template;
class PRM_SpareData;
class PRM_Parm;
class PRM_Range;
class PRM_ChoiceList;
class PRM_ScriptImports;
class OP_Operator;
class PI_EditScriptedParms;
class pi_GroupData;

#define PI_MAX_SCRIPT_PARM_SIZE 16
#define PI_FOLDER_DEFAULTNAME   "folder0"

typedef enum {
    PI_MENU_NORMAL = 0,
    PI_MENU_MINI = 1,
    PI_MENU_REPLACE = 2,
    PI_MENU_TOGGLE = 3
} PI_EditScriptedParmMenuType;

typedef enum {
    PI_MENU_NONE = 0,
    PI_MENU_ITEMS = 1,
    PI_MENU_SCRIPT = 2
} PI_EditScriptedParmMenuEnable;

typedef enum {
    PI_FOLDER_TAB,
    PI_FOLDER_RADIO,
    PI_FOLDER_IMPORT,
    PI_FOLDER_MULTILIST,
    PI_FOLDER_MULTISCROLL,
    PI_FOLDER_MULTISWITCHER,
    PI_FOLDER_ENDOFFOLDER,
    PI_FOLDER_NOTAFOLDER
} PI_EditScriptedParmFolderType;

class PI_API PI_EditScriptedParmMenu
{
public:
    PI_EditScriptedParmMenu() {}
    PI_EditScriptedParmMenu( PI_EditScriptedParmMenu const& other );

    bool        isValidChoice() const
                {
                    return myToken.isstring() || myLabel.isstring();
                }
    UT_String   myToken;
    UT_String   myLabel;
};

class PI_API PI_EditScriptedParm
{
public:
     PI_EditScriptedParm();
     PI_EditScriptedParm(const PRM_Template &tplate, OP_Node *node,
                         bool init_auto_links=true);
     PI_EditScriptedParm(PI_EditScriptedParmFolderType ftype);
     PI_EditScriptedParm(const PI_EditScriptedParm &src);
    ~PI_EditScriptedParm();

    void                 setType(const char *type)
                         {
                             myType.harden(type);
                             myCachedTypeIndex = -2;
                         }
    const UT_String      &getType() const { return myType; }

    void                 changeTypeToRampColor();
    void                 changeTypeToRampFloat();

    // Copy default parm values from the current values on the given parameter
    // starting at the specified subindex on that parameter (mapping it to 0
    // on this parameter).
    void                 copyDefaultValuesFromParm(PRM_Parm *parm, int subidx);

    // Resets the autolink values from one or more channels of this parm
    // to the set of currently existing links. Setting subidx to -1 causes
    // all channels to reset their autolinks.
    void                 setAutolinksToCurrentLinks(OP_Node *node, int subidx);

    // Take the incoming list of parm or channel names and add those parms
    // or channels to our autolink values in an intelligent way. The
    // links array will be filled with the name of the parameter each of the
    // parms was linked to (or an emtpy string if no link was made for that
    // parm).
    void                 addParametersToAutolink(const UT_StringArray &parms,
                                                 const char *nodepath,
                                                 bool linkinvisibles,
                                                 PI_EditScriptedParms *owner,
                                                 UT_StringArray &errors);

    void                 setRange(const PRM_Range &range);

    int                  save(ostream &os, int indent, OP_Operator *op,
                              const PI_EditScriptedParm *nextparm,
                              bool in_import_block);
    int                  saveSelectors(ostream &os, const char *tokeni,
                                       OP_Operator *op);
    void                 saveSpareData(ostream &os,
                                       const char *tokeni,
                                       bool skip_import_data);
    void                 saveSpareValue(ostream &os, const char *tokeni,
                                        const char *spare_token);
    // Debug dump of data
    void                 dump(ostream &os);

    int                  getNMenu() const  { return myMenu.entries(); }
    void                 addMenu(const char *token = 0, const char *label = 0);
    void                 moveMenu(int idx);
    void                 destroyMenu(int idx);
    int                  checkNullMenu();
    void                 clearMenuItems();

    void                 setMenu(const PRM_ChoiceList *menu, bool minimenu);

    // Get our parm type index from our string type for use when building
    // channels, or applying autolinks. It will return -1 for import blocks
    // and tab folder which do not allow any of this sort of activity.
    // The return value can be used to interface to theParmTypes array ONLY!
    int                  getParmTypeIdxForChannels() const;
    // Set the parameter size in a safe way.
    void                 setSize(int size);

    // Fill the array with all the channels for this parameter.
    void                 buildChannelNames(UT_StringArray &ch) const;

    // An alternate accessor to get the list of channel names.  This method
    // updates the channel name cache, if necessary, and returns a constant
    // reference directly to the cache in an attempt to avoid the overhead of
    // building a UT_StringArray.
    const UT_PtrArray<const char *>     &getChannelNames() const;

    // Copy all the spare data for the specified folder index from the given
    // reference data.  The index is the vector index of this folder in the
    // corresponding switcher parameter.
    void                 extractGroupSpareData(const PRM_SpareData *ref,
                                               int index);

    // Merges the provided spare data into our spare data.
    void                 mergeSpareData(const PRM_SpareData *srcsparedata);

    const char          *getSpareValue(const char *token) const;
    void                 setSpareValue(const char *token, const char *value);
    void                 copySpareValue(const char *token,
                                        const PRM_SpareData &ref);

    const char          *getCallbackData() const;
    void                 setCallbackData(const char *value);
    CH_ScriptLanguage    getCallbackLanguage() const;
    void                 setCallbackLanguage(CH_ScriptLanguage language);

    const char          *getOpFilter() const;
    void                 setOpFilter(const char *value);
    void                 setOpFilter(const PRM_SpareData *spareptr);
    const char          *getRManType() const;
    void                 setRManType(const char *value);
    int                  getMultiStartOffset() const;
    void                 setMultiStartOffset(int value);
    void                 setRampColorType(UT_ColorType color_type);
    UT_ColorType         getRampColorType() const;
    const char          *getRampBasisVar() const;
    void                 setRampBasisVar(const char *value);
    const char          *getRampKeysVar() const;
    void                 setRampKeysVar(const char *value);
    const char          *getRampValuesVar() const;
    void                 setRampValuesVar(const char *value);
    const char          *getImportSource() const;
    void                 setImportSource(const char *value);
    const char          *getImportToken() const;
    void                 setImportToken(const char *value);
    const char          *getImportMask() const;
    void                 setImportMask(const char *value);
    bool                 getImportEnable() const;
    void                 setImportEnable(bool value);
    bool                 getExportDisable() const;
    void                 setExportDisable(bool value);
    bool                 getUnquotedFlag() const;
    void                 setUnquotedFlag(bool value);
    bool                 getIsGroupStart() const;
    bool                 getIsGroupEnd() const;
    bool                 getIsGroupParm() const;
    bool                 getIsMultiParm() const;
    bool                 getIsRampParm() const;
    bool                 getIsRampParmColor() const;
    bool                 getIsRampParmFloat() const;
    bool                 getIsFileParm() const;
    bool                 getIsBasicStringParm() const;

    const char          *getRampBasisDefault() const;
    void                 setRampBasisDefault(const char *value);
    bool                 getRampShowControlsDefault() const;
    void                 setRampShowControlsDefault(bool value);

    void                 clearRampDefaults();

    const char          *getFileChooserMode() const;
    void                 setFileChooserMode(const char *value);

    // This utility method returns string constants.
    static const char   *getScriptType(const PRM_Type &ptype,
                                       PRM_TypeExtended etype,
                                       PRM_MultiType mtype, int size);

    static bool          parmTypeUsesOpFilter(const char *type);

    static const char   *getExportDisableToken();

    UT_String                            myName;
    UT_String                            myLabel;
    bool                                 myUseLabel;
    UT_String                            myClass;
    UT_String                            myCategory;
    int                                  myGroupID;
    bool                                 myInvisible;
    int                                  myExport;
    int                                  mySize;
    UT_String                            myDefaults[PI_MAX_SCRIPT_PARM_SIZE];
    CH_ExprLanguage                      myDefaultExprLanguage;
    int                                  myRangeEnable;
    float                                myRange[2];
    bool                                 myRangeLock[2];
    PI_EditScriptedParmMenuEnable        myMenuEnable;
    PI_EditScriptedParmMenuType          myMenuType;
    PI_EditScriptedParmFolderType        myFolderType;
    UT_String                            myMenuScript;
    CH_ScriptLanguage                    myMenuScriptLanguage;
    int                                  myDoAutolink[PI_MAX_SCRIPT_PARM_SIZE];
    UT_String                            myAutolink[PI_MAX_SCRIPT_PARM_SIZE];
    UT_String                            myOldAutolink[PI_MAX_SCRIPT_PARM_SIZE];
    UT_String                            myDisable;
    UT_String                            myHelpText;
    UT_PtrArray<PI_EditScriptedParmMenu *> myMenu;
    PRM_SpareData                       *mySpareData;
    bool                                 myJoinNextFlag;
    bool                                 myTabBreak;
    bool                                 myReserved;

    class PI_API PI_ParmType {
        public:
            const char                  *myLabel;
            const char                  *myDSToken;
            PRM_Type                     myType;
            const char                  *myIcon;
            int                          myExport;
            int                          mySize;
            int                          myMenu;
            int                          myString;
            int                          myRange;
            float                        myMin, myMax;
            const char                  *myDefault;
            const char                  *mySuffix[PI_MAX_SCRIPT_PARM_SIZE];
            int                          myUseFloatDefs;
    };
    static PI_ParmType                   theParmTypes[];

private:
    void                 defaultInit();
    void                 initMenu(const PRM_ChoiceList *menu, bool minimenu);

    void                 updateChannelNameCache(int parmtypeidx) const;
    void                 rebuildChannelNameCache(int parmtypeidx) const;

    UT_String                            myType;
    mutable int                          myCachedTypeIndex;

    // A mutable cache for the channel names last built for this parameter,
    // along with the settings last used to build it.
    mutable UT_PtrArray<const char *>    myCachedChannelNames;
    mutable UT_String                    myChannelCacheToken;
    mutable int                          myChannelCacheTypeIndex;

};

typedef UT_PtrArray<PI_EditScriptedParm *> PI_EditScriptedParmArray;

class PI_API PI_EditScriptedParms
{
public:
                         PI_EditScriptedParms();
                         // Use this constructor to edit spare parameters.
                         PI_EditScriptedParms(OP_Node *node,
                                              bool add_reserved_parms,
                                              bool init_auto_links);
                         // Use this constructor to edit DA parameters.
                         PI_EditScriptedParms(OP_Operator *op,
                                              OP_Node *node,
                                              bool add_reserved_parms);
                         // Get parameters from a dialog script.
                         // The node is just a reference used to determine
                         // what parameters should be reserved.
                         PI_EditScriptedParms(OP_Node *node,
                                              UT_IStream &is,
                                              bool spareparms,
                                              bool skip_reserved,
                                              bool init_auto_links);
                         // Get parameters from a array of parm templates.
                         // The node is just a reference used to determine
                         // what parameters should be reserved.
                         PI_EditScriptedParms(OP_Node *node,
                                              const PRM_Template *tplate,
                                              bool spareparms,
                                              bool skip_reserved,
                                              bool init_auto_links);
                         // Copy constructor.
                         PI_EditScriptedParms(const PI_EditScriptedParms &src);
                        ~PI_EditScriptedParms();

    // Merge the contents of another PI_EditScriptedParms into this one.
    // The only change to the parms being merged is to resolve conflicts
    // with existing parm names, and ensure no reserved parm names are used.
    // The new parms are always added to the end of the current parms.  The
    // reserved flag from the source parms is preserved, so be careful when
    // merging parameters from different sources.
    void                         mergeParms(const PI_EditScriptedParms &src);

    // Remove all our parameters.
    void                         clearParms();

    // Save the parms in dialog script format.
    int                          save(ostream &os, UT_String &warnings);

    // Dump the parameters, in a meaningless format, but useful for debugging.
    void                         dump(ostream &os);

    // Compile these parameters, which means eliminating all information
    // about the parameters that is not absolutely required for proper
    // functioning.
    void                         compile();

    // Get our individual parms.
    PI_EditScriptedParmArray    &getParms() { return myParms; }
    int                          getNParms() const;
    PI_EditScriptedParm         *getParm(int i);
    int                          getParmIndexWithName(const char *name);
    PI_EditScriptedParm         *getParmWithName(const char *name);
    int                          getParmIndex(PI_EditScriptedParm *p);
    PI_EditScriptedParm         *getFolderWithLabel(const char *label);

    // Given a list of folder names, return the index of the start of the
    // innermost folder, or -1 if there is no such folder.
    int                          getNestedFolderIndex(
                                    const UT_StringArray &folder_labels);

    // Given the index of a parameter, return the parms corresponding to the
    // containing folders.
    void                         getContainingFolders(
                                    int parm_index,
                                    UT_PtrArray<PI_EditScriptedParm *> &result);

    // Find a parm that already has a particular autolink.
    PI_EditScriptedParm         *getParmWithAutolink(const char *channelpath,
                                                     const char *nodepath,
                                                     int *linkedsubidx = 0);

    // For a group start parm or group end parm, find the opposite end of
    // that group. Otherwise return -1.
    int                          getMatchingGroupParm(int parm) const;

    // Returns true if the group parameter specified is the first page
    // in a series of folders.
    bool                         getIsFirstPage(int parm) const;

    // Returns the position of the group parameter that contains the specified
    // parameter. If there is no parent group parameter, -1 is returned.
    int                          getParentGroupParm(int parm);

    // Get information about the menu associated with a particular parameter.
    int                          getNMenu(int parm);
    PI_EditScriptedParmMenu     *getMenu(int parm, int i);
    const char                  *getMenuScript(int parm);

    // Test if a parameter can be moved from srcidx to dstidx. For example,
    // a folder start token is not allowed to be moved beyond a corresponding
    // end token. Returns true if parm move is allowed, false otherwise.
    bool                 isParmMoveAllowed(int first, int last, int offset);

    // Add, remove, and reorder parameters.
    void                 addParm(PI_EditScriptedParm *parm);
    bool                 moveParms(int first, int last, int offset);
    void                 moveParms(const UT_IntArray &movingparms, int destpos);

    // Adds parms for the multiparm templates attached to the specified
    // parm. This function works recursively if the multiparm templates
    // contain other multiparms.
    void                 insertMultiParmTemplates(const PRM_Template *tplate,
                                                  const char *parentparmname,
                                                  const OP_Node *linktonode,
                                                  const char *nameprefix,
                                                  const char *labelprefix,
                                                  int insertat);

    // Apply a permutation to a block of parameters.  This method only does
    // sanity checking on the permutation itself, and not on the parameters
    // themselves, so use it with caution.  For example, don't screw up the
    // order of group begin and end entries.
    //
    // The permutation array must consist of a permutation of the indicies
    // [first..(first + permutation.entries() - 1)].
    //
    // The operation applied is basically:
    //   new_parms(first+i) = old_parms(permutation(i))
    void                 permuteParms(int first,
                                      const UT_IntArray &permutation);

    // If we are told to remove a group start or end parm, we automatically
    // remove the opposite end of that group.  Returns the number of parms
    // removed.
    int                  removeParms(int first, int last);

    // joins cannot occur over folder boundaries, or at the end of the parm
    // list.
    void                 removeInvalidJoins();
 
    // Copy default parm values from the current values on the specified node.
    void                 copyDefaultsFromNode(OP_Node *node);

    int                  checkReservedName(const char *name) const;
    bool                 containsReservedParm() const;
    void                 initializeReserveNames(OP_Parameters *node);
    void                 initializeReserveFlags();
    void                 makeSafeParmName(PI_EditScriptedParm *parm,
                                          UT_String &parmname,
                                          const UT_SymbolTable *extrareserved,
                                          bool checkexistingparms);

    // Set all autolink values for all parameters to the current set of
    // links.
    void                 setAutolinksToCurrentLinks();

    // Take the list of parm or channel names and add those parms or channels
    // to the autolink fields of the appropriate PI_EditScriptedParm. The
    // links array will be filled with the name of the parameter each of the
    // parms was linked to (or an emtpy string if no link was made for that
    // parm).
    void                 addParametersToAutolinks(PI_EditScriptedParm &destparm,
                                        const UT_StringArray &parms,
                                        const char *nodepath,
                                        bool linkinvisibles,
                                        PI_EditScriptedParmArray &changedparms,
                                        UT_StringArray &errors);

    // Makes sure that none of our parm names contain too many hashes for
    // the multiparm instace level they are at. This is called right before
    // saving. Extra hashes are converted to underscores.
    void                 fixParmNamesForInstanceLevel();

    // Turn the auto link values from all our parms into channel references
    // on the appropriate nodes. The function is not const because it actually
    // changes the auto link values.
    void                 applyAutoLinks(UT_StringArray &errors,
                                        OP_NodeList &changednodes,
                                        UT_IntArray &changedparms);

    // The applyAutoLinks call happens before the node's templates are
    // updated. So after updating the templates, we need to force any
    // changed nodes to rebuild their dependencies and recook.
    void                 updateNodesFromApplyAutoLinks(
                                        OP_NodeList &changednodes,
                                        UT_IntArray &changedparms);

    // This function is called whenever a node's name is changed. It goes
    // through all our parm's auto links and changes any references from the
    // old node name to the new node name.
    bool                 updateAutoLinksForNameChange(
                                        const UT_String &refnodepath,
                                        const UT_String &oldpath,
                                        const UT_String &newpath);

    // Gets the node that is associated with these parms. This value is
    // used for finding and setting parameter links, and detecting parm
    // name conflicts.
    OP_Node             *getNode() const;

    // These functions are used to control the table of multiparm link
    // information used by piGetCurrentLinks.
    static void                  buildMultiparmInfo(OP_Node *refnode);
    static void                  clearMultiparmInfo();
    static void                  lockMultiparmInfo();
    static void                  releaseMultiparmInfo();
    static const UT_SymbolTable &getBuiltMultiparmInfo();

private:
    // Returns a pointer to the base parm templates, which is the myBase
    // member if editing HDA parms, or the operator templates if editing
    // spare parameters.
    const PRM_Template  *getBaseParmTemplates() const;
    // Returns a pointer to the base parm template (if any) that matches
    // the supplied parameter name.
    const PRM_Template  *getBaseParmTemplate(const char *parmname) const;

    // This utility function helps makeSafeParmName generate a list of all
    // multiparm instance parms in this PI_EditScriptedParms.
    void                 buildMParmInst(PI_EditScriptedParm *skipparm,
                                        UT_StringArray &mparminst,
                                        UT_IntArray &mparmlvl) const;

    // This utility function figures out the depth of multiparm nesting
    // for the specified parm.
    int                  getMultiParmInstanceLevel(
                                        PI_EditScriptedParm *parm) const;

    // Utility function for makeSafeParmName which recursively checks a
    // PRM_Template array (and any multiparm templates in that array) for
    // conflicting parm names.
    bool                 conflictsWithTemplate(const PRM_Template *tplate,
                                        const UT_StringArray &mparmtplates,
                                        const UT_StringArray &channels,
                                        const UT_StringArray &mparminst,
                                        const UT_IntArray &mparmlvl) const;

    void                 createImportGroups(int offset,
                                        UT_RefArray<pi_GroupData> &gstack,
                                        const PRM_ScriptImports *imports,
                                        int &import_index);
    void                 createImportGroupsBeforeGroupEnd(
                                        int offset, int depth,
                                        int switcher_index, int folder,
                                        const PRM_ScriptImports *imports,
                                        int &import_index);
    void                 createParms(const PRM_Template *tplates,
                                        const PRM_ScriptImports *imports,
                                        bool skip_reserved,
                                        bool init_auto_links=true);
    void                 createParms(UT_PtrArray<const PRM_Template *> &tplates,
                                        const PRM_ScriptImports *imports,
                                        bool skip_reserved,
                                        bool init_auto_links=true);
    void                 removeInvalidGroups(int startpos);

    void                 saveGroupHeader(ostream &os, int index,
                                        int &glevel,
                                        int &import_depth,
                                        bool &in_import_block);
    void                 saveGroupFooter(ostream &os, int index,
                                        int &glevel,
                                        int &import_depth,
                                        bool &in_import_block);
    void                 saveImportHeader(ostream &os, int index,
                                        int &glevel,
                                        int &import_depth,
                                        bool &in_import_block);
    void                 saveImportFooter(ostream &os, int index,
                                        int &glevel,
                                        int &import_depth,
                                        bool &in_import_block);
    void                 saveMultiParmHeader(ostream &os, int index,
                                        int &glevel,
                                        int &import_depth,
                                        bool &in_import_block);
    void                 saveMultiParmFooter(ostream &os, int index,
                                        int &glevel,
                                        int &import_depth,
                                        bool &in_import_block);

    PI_EditScriptedParmArray     myParms;
    UT_SymbolTable               myReservedParmNames;
    OP_Operator                 *myOp;
    int                          myNodeId;
    bool                         myIsEditingSpareParms;
};

#endif

---