PRM/PRM_Parm.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:
 *      ramin
 *      Side Effects Software Inc.
 *      20 Maud St.
 *      Toronto, Ontario,  M5V 2M5
 *      Canada
 *      416-366-4607
 *
 * NAME:        PRM_Parm.h (Parameter Library)
 *
 * COMMENTS:
 *              PRM_Parm is the class which contains all the information
 *              about a parameter. A parameter is any value or set of
 *              values that are used in the PRISMS world. It may conatin
 *              expressions, channels, or simple values.
 *
 *              It is divided into two part, the parameter's type
 *              definition, stored in the PRM_Template, and the
 *              parameter's actual data, stored in the PRM_Instance.
 *              Each PRM_Parm contains all the information it needs to
 *              perform its functions independently of other objects.
 */

#ifndef __PRM_Parm__
#define __PRM_Parm__

#include "PRM_API.h"
#include <iostream.h>
#include <UT/UT_Defines.h>
#include <UT/UT_IntArray.h>
#include <UT/UT_SmallObject.h>
#include "PRM_Default.h"
#include "PRM_KeySetType.h"
#include "PRM_Type.h"
#include "PRM_Template.h"
#include "PRM_ParmList.h"

class UT_String;
class UT_TokenString;
class CH_Channel;
class CH_FullKey;
class CH_Collection;
class PRM_Instance;
class PRM_Value;
class PRM_Multi;

class PRM_API PRM_Parm : public UT_SmallObject<PRM_Parm,
                                       UT_SMALLOBJECT_CLEANPAGES_DEFAULT,
                                       UT_SMALLOBJECT_PAGESIZE_DEFAULT,
                                       UT_SMALLOBJECT_THREADSAFE_OFF>
{
public:
                 // for these constructors, a nil CH_Collection is invalid
                 // only PRM_ParmList handles a nil correctly
                 PRM_Parm(PRM_Template  *thetemplate,
                          CH_Collection *thechgroupptr,
                          PRM_ParmList  *owner,
                          PRM_ParmOwner *node);
                 PRM_Parm(PRM_Parm      *theprm,
                          CH_Collection *thechgroupptr,
                          PRM_ParmList  *owner,
                          PRM_ParmOwner *node);
                ~PRM_Parm();

    void         adopt(PRM_Parm &thesrcparm);
    void         adoptOverrides(PRM_Parm &srcparm);

    void         revertToDefaults(float time);
    void         revertToDefault(float time, int index, bool propagate=true);
    void         restoreFactoryDefaults();
    void         restoreFactoryDefault(int index);

    static bool  getDestructiveRevertToDefaultFlag() 
                    { return myDestructiveRevertToDefaultFlag; }
    static void  setDestructiveRevertToDefaultFlag(bool v)
                    { myDestructiveRevertToDefaultFlag = v;    }

    static bool  getRevertInvisibleToDefaultsFlag() 
                    { return myRevertInvisibleToDefaultsFlag; }
    static void  setRevertInvisibleToDefaultsFlag(bool v)
                    { myRevertInvisibleToDefaultsFlag = v;    }

    static bool  getMakeSpareParmsForUnknownChannelsFlag() 
                    { return myMakeSpareParmsForUnknownChannelsFlag; }
    static void  setMakeSpareParmsForUnknownChannelsFlag(bool v)
                    { myMakeSpareParmsForUnknownChannelsFlag = v;    }

    // Static functions to access PRM_Instance subclass static functions.
    static bool  isFloatExpression(const char *str);
    static bool  isStringExpression(const char *str,
                                    CH_StringMeaning meaning,
                                    PRM_Template *tplate = NULL);
    static bool  isOrdinalExpression(const char *str,
                                     const PRM_Template *tplate = NULL);
    static bool  isOrdinalExpression(const PRM_Default &dflt,
                                     const PRM_Template *tplate = NULL);

    // Static functions to convert string parm values to and from
    // expressions.
    static void  convertStringToExprLanguage(const char *str,
                                             UT_String &expr,
                                             PRM_Template *tplate = NULL);
    static void  convertStringFromExprLanguage(const char *str,
                                               UT_String &expr);

    // Static functions to access PRM_Multi static functions.
    static bool  getIsAddingOrRemovingMultiParms();
    // Replace a number in the source string and return the result in the
    // destination (work buffer)
    static bool  replaceMultiNumber(UT_String &str, const char *replace);
    // If there are any numeric placeholders left in the specified string,
    // this function replaces them with underscores.
    static bool  replaceRemainingMultiNumbers(UT_String &str);
    // Instance a string, replacing all '#' marks with integers from the
    // index list.
    static void  instanceMultiString(UT_String &token,
                                const UT_IntArray &indexlist,
                                bool fill_remaining=true);
    static void  instanceMultiString(UT_String &token,
                                const int *indexlist, int num,
                                bool fill_remaining=true);

    static int   getAlwaysHardenFlag() { return myAlwaysHardenFlag; }
    static void  setAlwaysHardenFlag(int o) { myAlwaysHardenFlag = o; }

    int          isDefault() const;
    int          isDefault(int index) const;
    int          isFactoryDefault() const;
    int          isFactoryDefault(int index) const;

    // isTrueFactoryDefault differs from isFactoryDefault in that it 
    // will do a string compare on the expression if there is one, thus
    // an expression that evaluates to the default value will still not be a
    // "true" factory default.
    int          isTrueFactoryDefault(int index) const;
    int          isTrueFactoryDefault() const;
    
    // These are exactly like isTrueFactoryDefault() except that it excludes
    // the checking of the lock flag. This is because we don't want locked
    // parms to show up bolded in the parameters pane.
    int          isFactoryDefaultUI(int index) const;
    int          isFactoryDefaultUI() const;

    void         overwriteDefaults(float time);
    void         overwriteDefault(float time, int index);

    CH_Channel  *getChannel(int subindex) const;

    void         buildOpDependencies(void *ref_id, int thread);
    void         changeOpRef(const char *new_fullpath, const char *old_fullpath,
                             const char *old_cwd, const char *chan_name,
                             const char *old_chan_name,
                             void (*undo_callback)(void *), void *undo_data,
                             int thread);

    void         getValue(float time, int &intref, int index,
                          int thread) const;
    void         getValue(float time, float &floatref, int index,
                          int thread) const;
    void         getValue(float time, UT_String &strref, int index,
                          bool expand, int thread) const;
    void         getValues(float time, float *floatref, int thread) const;
    void         getValues(float time, int *intref, int thread) const;
    void         getDefaultValue(float &floatref, int index) const;

    // The following method is very similar to getExpressionOrValue() except
    // that it returns a custom string when the parameter is overridden by a
    // CHOP.
    void         getExpressionStringForUI(float thetime, UT_String &thestrref,
                                          int theindex, int thread) const;

    // The following method, unlike getExpressionOnly(), will convert the
    // value to a string and return that if there is no channel.
    void         getExpressionOrValue(float thetime, UT_String &thestrref,
                                      int theindex, int thread) const;

    // The following method returns the expression string, returning an empty
    // string in the case of a parameter with no channel/expression.
    void         getExpressionOnly(float thetime, UT_String &thestrref,
                                   int theindex, int thread) const;

    bool         setExpression(float thetime, const UT_String &thestrref,
                               CH_ExprLanguage language,
                               int theindex, bool evaluate = true,
                               bool rmchannel = false, bool propagate = true);

    int          addChannel(const char *name);
    int          addChannel(const char *name, const char *expr,
                            CH_ExprLanguage language);
    void         reloadChannelPtrs();
    int          channelPtrModified(const char *name);

    // if thehardenflag is set, then keyframes are added for animated 
    // parameters instead of stashing the values and setting the
    // pending flags. If thehardenflag is greater than one, then
    // keyframes are added even if the parm is being set to the
    // value it already contained. (ie like the force flag of hardenChanges)
    //
    // returns true if the value was set, of false otherwise (eg, parm locked)

    bool         setValue(const float thetime, const UT_String &thestrref,
                          CH_StringMeaning meaning,
                          const int thekillexprflag = 0, const int theindex=0,
                          const int thehardenflag = 0, bool propagate = 1);

    bool         setValue(const float thetime, const float thefloat,
                          const int thekillexprflag = 0, const int theindex=0,
                          const int thehardenflag = 0, bool propagate = 1);

    bool         setValue(const float thetime, const int theint,
                          const int thekillexprflag = 0, const int theindex=0,
                          const int thehardenflag = 0, bool propagate = 1);

    //
    // The setValues methods set all entries in the vector at once...
    // returns true if the values were set, of false otherwise (eg, parm locked)
    //
    bool          setValues(const float thetime, const float *thefloats,
                            const int thekillexprflag = 0,
                            const int thehardenFlag = 0, bool propagate = 1);

    bool          setValues(const float thetime, const int *theints,
                            const int thekillexprflag = 0,
                            const int thehardenFlag = 0, bool propagate = 1);

    bool                 isMultiParm() const;
    void                 insertMultiParmItem(int index, bool propagate = 1);
    void                 removeMultiParmItem(int index, bool propagate = 1);
    void                 revertMultiParmItem(int index);
    void                 assignMultiParmItem(int from, int to);
    int                  getMultiParmNumItems() const;
    int                  getMultiParmInstancesPerItem() const;
    const char          *getMultiParmToken(int p, int index) const;
    int                  getMultiParmUIEntries() const;
    const PRM_Template  *getMultiParmTemplate(int idx) const;
    PRM_Template        *getMultiParmTemplate(int idx);
    void                 copyMultiParm(PRM_Parm *src);

    // These functions allow a linear traversal of all multiparm instances
    // parameters.
    PRM_Parm            *getMultiParm(int idx) const;
    int                  getMultiParmCount() const;

    // The only difference between the next two functions is that the
    // second send the change notification without question. The first
    // calls the second, but only if the parm isn't a PRM_CALLBACK. In
    // those cases we usually don't want to actually send out change
    // notifications. The notable exception is the opparm -c command.
    void         valueChanged(int propagate = 1)
                    { privateValueChanged(propagate, /*update_multi*/1); }
    void         sendValueChanged(int propagate = 1);
    void         indirectChange(bool expr_changed = false);

    PRM_Callback getCallback() { return getTemplatePtr()->getCallback(); }
    int          setOverride(int theindex, int data_idx, const char *source);
    const char  *getOverride(int theindex) const;
    int          getOverrideDataIndex(int theindex) const;
    bool         getOverrideNodePath(int theindex, UT_String &path) const;
    bool         getOverrideTrackName(int theindex, UT_String &trackname) const;
    int          setOverrideDisable(int theindex, int onoff);
    int          getIsOverrideActive(int theindex) const;

    void         copyValue(float t, int dest_vi,
                           const PRM_Parm &src_parm, int src_vi,
                           bool set_name_alias,
                           bool current_value_only);

    void         addChannels();
    void         addChannel(int theindex);
    void         addChannel(int theindex, const char *theexpr,
                            CH_ExprLanguage language);
    void         removeChannel(int theindex);

    void         clearAndDestroyChannels();

    int          getChannelCount() const;
    int          isTimeDependent() const;
    bool         isTimeDependent(int subindex) const;
    int          isDataDependent(float gtime) const;
    bool         isDataDependent(float gtime, int subindex) const;
    void         forceTimeDependent(void);
    
    const PRM_Type      &getType() const;
    PRM_TypeExtended    getTypeExtended() const;
    PRM_MultiType       getMultiType() const;
    float                getMultiSize() const;
    int                  getMultiStartOffset() const;

    bool         isRampType() const;
    bool         isRampTypeColor() const;

    int          getVectorSize() const;
    void         getChannelToken(UT_String &thestrref, int theindex = 0) const;
    void         getChannelLabel(UT_String &thestrref, int theindex = 0) const;
    void         getToken(UT_String &thestrref) const;
    void         getLabel(UT_String &thestrref) const;
    void         getHelpText(UT_String &helptext) const;

    const char  *getToken() const;
    const char  *getLabel() const;

    void         getChannelLabelForUI(UT_String &thestrref, int vec_idx) const;

    const PRM_SpareData *getSparePtr() const;

    unsigned     getTokenHash() const;

    bool         hasChannelAlias(int subindex) const ;
    void         getChannelAlias(UT_String &stringref, int subindex) const;

    // This performs all the checks to verify that a parameter can be accessed
    bool         canAccess(uint mask) const;

    // Sets a channel alias.
    // Do not use this call -- use the OP_Node version to ensure that all
    // dependencies and symbol tables are updated correctly.
    bool         setChannelAlias(const char *token_alias, int subindex);

    PRM_ChoiceList *getChoiceListPtr();
    const PRM_ChoiceList *getChoiceListPtr() const;

    // Return the group input notify value.  It is nil by default, but
    // can be created by calling createInputNotifyValue.
    PRM_Value   *inputNotifyValue();
    void         createInputNotifyValue();

    // A parameter becomes dirty whenever its value is set.
    int          isDirty(int vector_idx=0) const;
    int          areAllFlagsClean() const;
    void         clearAllDirtyFlags();

    int          findParmIndex(const char *thechannelname, bool allow_alias);
    
    const PRM_Template  *getTemplatePtr() const;
    PRM_Template        *getTemplatePtr();

    PRM_Instance        *getInstancePtr();

    // These two may be redundant now.
    void                 setChannelGroupPtr(CH_Collection *thechgroupptr);
    CH_Collection       *getChannelGroupPtr() const;

    unsigned     getEnableState(int comp = -1) const;
    unsigned     getInstanceEnableState(int comp = -1) const;
    bool         getActiveTakeFlag() const;
    bool         getAlwaysTakeFlag() const;
    void         setActiveTakeFlag(int onoff);
    int          setEnableState(int thestate, int comp = -1);
    bool         getBypassFlag() const;
    void         setBypassFlag(bool v);
    
    int          getExpressionState();
    void         setExpressionState(int state);
    int          getValueState();
    void         setValueState(int state);
    
    // hardenChanges() will create keys if the parm already has channels
    void         hardenChanges(float time, char forceflag = 0,
                               const char *patt = 0,
                               CH_ChannelRefList *list = 0);
    void         hardenChanges(float time, char forceflag, int index,
                                const char *patt = 0,
                                CH_ChannelRefList *list = 0);
    // setKey() will create keys even if the parm has no channels
    void         setKey(float time, int index);
    void         setKey(float time, int index, const char *exp,
                        CH_ExprLanguage language,
                        const char *patt = 0, CH_ChannelRefList *list = 0);
    
    void setFullKey(float gtime, int index, CH_FullKey const& key, 
                    bool accel_ratios = true);
    
    CH_StringMeaning getStringMeaning(float time, int index) const;

    // If this parm contains an expression this function returns that
    // expression's language.  Otherwise, it returns the language that it
    // would be if it was turned into an expression.
    CH_ExprLanguage getExprLanguageIfMadeAnExpression(float time, int index);

    // If there is an expression, this function returns whether the
    // expression's language for the segment at the given time is the same as
    // the node's langauge.  If there is no expression, this function returns
    // true.
    bool          languageIsNodesLanguage(float time, int index);

    int           changePending(int index);
    PRM_ChanState getChanState(float thetime) const;
    PRM_ChanState getChanState(float time, int index) const;

    void          save(ostream &os, int binary, bool compiled) const;
    bool          load(UT_IStream &is);
    void          saveCommand(ostream &os, int values=0, int index=-1) const;
    int           loadCommand(int argc, char *argv[], int theindex, int vonly,
                              PRM_KeySetType set_type);

    float        findNextKey(float theoldtime, int theindex = -1);
    float        findPrevKey(float theoldtime, int theindex = -1);

    int          findString(const char *str, bool fullword,
                            bool usewildcards) const;
    int          changeString(const char *from, const char *to, bool fullword);

    int          getInterestDirtyFlag();
    void         setInterestDirtyFlag();
    void         clearInterestDirtyFlag();

    int          getExtraInterestFlag();
    void         setExtraInterestFlag();
    void         clearExtraInterestFlag();

    bool         getUndoSavedFlag();

    // WARNING: the setUndoSavedFlag method should only be called from
    // OP_Parameters.  Calling it from anywhere else can cause undo errors.
    void         setUndoSavedFlag(bool f);

    bool         getAutoTakeUndoSavedFlag();

    // WARNING: the setAutoTakeUndoSavedFlag method should only be called from
    // OP_Parameters.  Calling it from anywhere else can cause undo errors.
    void         setAutoTakeUndoSavedFlag(bool f);

    bool         getLockedFlag(int vec_idx) const;
    bool         areAllComponentsLocked() const;
    void         setLockedFlag(int vec_idx, bool f);
    unsigned int getLockedField() const;
    bool         getAutoScopedFlag(int vec_idx) const;
    void         setAutoScopedFlag(int vec_idx, bool f);
    unsigned int getAutoScopedField() const;

    bool         getMagicString(UT_TokenString &string, float t,
                                int parm_group_mask /*=1*/,
                                bool add_if_default /*= true*/,
                                bool ignore_group /*= false*/,
                                int thread);

    void         destroyChildParms();

    PRM_ParmList        *getOwner() const;

    void                 setMostRecentCallbackValue(int value);
    int                  getMostRecentCallbackValue() const;

    PRM_ParmOwner       *getParmOwner() const;
    void                 clearParmOwner();

    // Returns true if this parm is compatible with other_parm.  Being 
    // compatible means that the two parms have the same token string,
    // the same size and are of the same type.
    bool                 isCompatible(const PRM_Parm &other_parm) const;

    // Returns true if the parm is of the basic type check_type, as defined
    // in PRM_Type.h as basic types.
    bool                 isOfBasicType(PRM_Type check_type) const;

    // Returns true if this parm and other_parm are of the same basic type,
    // and have equal values (including evaluated expressions), and false
    // otherwise.
    bool                 isParmValueEqual(PRM_Parm &other_parm, int vec_index,
                                          float time, int thread) const;
    bool                 isParmValueEqual(int vec_index, PRM_Parm &other_parm,
                                          int other_index, float time,
                                          int thread) const;

    // Returns true if the channame is the token (or alias) of the channel at 
    // vec_index, and returns false otherwise.
    bool                 hasChannelName(const char *channame,
                                        int vec_index) const;

    // Returns the aliases of all the channels in this parm in one string
    // separated by the character sep.
    void                 getAllChannelAliases(UT_String &aliasstring, 
                                              char sep ='/') const;

    // Methods for accessing and setting the active handle binding flag
    bool                 isActive(const int index) const;
    void                 setActive(const int index, const bool active);

    int64                getMemUsage(UT_Bool onlythis) const;

    bool                 isSpareParm() const;
    void                 setSpareParm(bool sp) const;

    const PRM_Instance  *getMultiParmOwner() const;
    void                 setMultiParmOwner(const PRM_Multi *multiparmowner);

    /// Return the list of instance indicies for this parameter.
    /// If this parameter is part of a multi-parameter, then its index in the
    /// multi-parm array will be inserted into the indices array.  If the
    /// multi-parm is nested in other multi-parms, then the indices array will
    /// have multiple entries (with the outer multi-parm listed first, and the
    /// inner-most multi-parm last in the array).
    /// \param indices The list of index instances.
    /// \param instance_index Each multi-parm can have multiple parameters in
    /// each instance.  If instance_index is true, the instance number will be
    /// returned.  Otherwise the raw offset into the multi-parm will be
    /// extracted.
    int                  getMultiInstanceIndex(UT_IntArray &indices,
                                bool instance_index=true) const;

    void                 rebuildParmDependency();

    bool                 isRotationParm() const;

    // For explanations of path vs ch_name, see comment for 
    // constructChannelReference
    void                setChannelReference(float thetime,
                                            int theindex, 
                                            const char *path, 
                                            const char *ch_name=NULL,
                                            bool evaluate=true,
                                            bool rmchannel=false);

    // Construct the string representing reference to the channel given by 
    // path/name from this parameter. 
    // If name == NULL, path is assumed to be (node path + channel name)
    // If name not NULL, path is assumed to be a path without channel name, 
    // name is assumed to be channel name without the path.
    void                 constructChannelReference(UT_String &reference,
                                                   CH_ExprLanguage language,
                                                   const char *path, 
                                                   const char *ch_name=NULL);
    
private:
    void                 privateValueChanged(int propagate, int update_multi);

private:
    PRM_Instance        *myInstancePtr;
    PRM_ParmList        *myOwner;
    int                  myMostRecentCallbackValue;

    static int           myAlwaysHardenFlag;
    static bool          myDestructiveRevertToDefaultFlag;
    static bool          myRevertInvisibleToDefaultsFlag;
    static bool          myMakeSpareParmsForUnknownChannelsFlag;
};

#endif

---