PRM/PRM_Template.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_Template.h (Parameter Library)
 *
 * COMMENTS:
 *      PRM_Template is the class which contains all the static data
 *      relating to a parameter. It encapsulates the characteristics
 *      of the parameter, such as type, default values, range, etc.
 *      A PRM_Template is used in conjunction with a PRM_Instance to 
 *      define a PRM_Parm. A PRM_Instance is to a PRM_Template as
 *      an object is to a class in C++.
 */

#ifndef __PRM_Template__
#define __PRM_Template__

#include "PRM_API.h"
#include <UT/UT_IntArray.h>
#include <UT/UT_PtrArray.h>
#include <UT/UT_String.h>
#include "PRM_DisableList.h"
#include "PRM_Name.h"
#include "PRM_Type.h"

#define PRM_TYPE_IS_SWITCHER(type) (type.isSwitcher())

#define PRM_IS_JOIN(parm) (parm.getTypeExtended() == PRM_TYPE_TOGGLE_JOIN || \
                       parm.getTypeExtended() == PRM_TYPE_JOIN_PAIR)

class PRM_ChoiceList;
class PRM_Range;
class PRM_Default;
class PRM_Template;
class PRM_SpareData;

PRM_API extern PRM_ChoiceList PRMtoggleMenu;

/// This is a callback function that can be used to modify data.
/// It is invoked when the user uses a parameter of type PRM_CALLBACK
/// (this might be a button, or a menu).
/// @param data     Pointer to the node it was called on
/// @param index    The index of the menu entry
/// @param time     Current evaluation time
/// @param tplate   Pointer to the PRM_Template of the parameter it was
///                 triggered for.
/// @return It should return 1 if you want the dialog to refresh
///         (ie if you changed any values) and 0 otherwise.
typedef int (*PRM_Callback)(void *data, int index, float time,
                            const PRM_Template *tplate);

class PRM_API PRM_Template
{
public:
    // An export level is a hint to say if a parm should be displayed or not.
    // By default, all parms have minimum export level, which means that
    // they are only displayed if someone asks for a dialog with the minimum
    // export level.  Creating a dialog with a higher export level will only
    // contain those parameters with higher export levels.
    enum PRM_Export
    {
        PRM_EXPORT_MIN,
        PRM_EXPORT_MED,
        PRM_EXPORT_MAX,
        PRM_EXPORT_TBX          // for toolboxes
    };

    enum
    {
        // This is maximum vector size for parameters. This is because we keep
        // per component flags in uint32 variables. For myAutoScopeField, we
        // use the high-bit to keep track of whether it's initialized so the
        // actual limit is 31, not 32.
        MAX_VECTOR_SIZE = 31
    };

    // No extended type given and no export level given.
                          PRM_Template(PRM_Type thetype = PRM_LIST_TERMINATOR,
                                       int               thevectorsize = 1, 
                                       PRM_Name         *thenameptr = 0,
                                       PRM_Default      *thedefaults = 0,
                                       PRM_ChoiceList   *thechoicelistptr = 0,
                                       PRM_Range        *therangeptr = 0,
                                       PRM_Callback      thecallbackfunc = 0,
                                       PRM_SpareData    *thespareptr = 0,
                                       int               theparmgroup = 1,
                                       const char       *thehelptext = 0,
                                       PRM_DisableList  *thedisableptr = 0);

    // No extended type given but export level given.
                          PRM_Template(PRM_Type thetype,
                                       PRM_Export        theexportlevel,
                                       int               thevectorsize = 1, 
                                       PRM_Name         *thenameptr = 0,
                                       PRM_Default      *thedefaults = 0,
                                       PRM_ChoiceList   *thechoicelistptr = 0,
                                       PRM_Range        *therangeptr = 0,
                                       PRM_Callback      thecallbackfunc = 0,
                                       PRM_SpareData    *thespareptr = 0,
                                       int               theparmgroup = 1,
                                       const char       *thehelptext = 0,
                                       PRM_DisableList  *thedisableptr = 0);

    // Extended type given but no export level given.
                          PRM_Template(PRM_Type          thetype,
                                       PRM_TypeExtended  thetype_ext,
                                       int               thevectorsize = 1, 
                                       PRM_Name         *thenameptr = 0,
                                       PRM_Default      *thedefaults = 0,
                                       PRM_ChoiceList   *thechoicelistptr = 0,
                                       PRM_Range        *therangeptr = 0,
                                       PRM_Callback      thecallbackfunc = 0,
                                       PRM_SpareData    *thespareptr = 0,
                                       int               theparmgroup = 1,
                                       const char       *thehelptext = 0,
                                       PRM_DisableList  *thedisableptr = 0);

    // Extended type given and export level given.
                          PRM_Template(PRM_Type          thetype,
                                       PRM_TypeExtended  thetype_ext,
                                       PRM_Export        theexportlevel,
                                       int               thevectorsize = 1, 
                                       PRM_Name         *thenameptr = 0,
                                       PRM_Default      *thedefaults = 0,
                                       PRM_ChoiceList   *thechoicelistptr = 0,
                                       PRM_Range        *therangeptr = 0,
                                       PRM_Callback      thecallbackfunc = 0,
                                       PRM_SpareData    *thespareptr = 0,
                                       int               theparmgroup = 1,
                                       const char       *thehelptext = 0,
                                       PRM_DisableList  *thedisableptr = 0);
    
    // Dynamic multi-parm type contructors:
    
    // Notes: - the export level cannot be PRM_EXPORT_TBX (they won't fit)
    //        - the vector size is the number of shown instances (Scroll type)
    //          or the number of instances per tab (Switcher type).
    //        - the default is the number of default instances (int)
    //        - the range is the allowable range of instances, min zero.
    //        - the template list is a list of templates to use as a guide
    //          to create new instances (a template, but I didn't want to use
    //          that word again). Names will have a number suffixed to them
    //          depending on the instance number ("foo1") or %d may be used to
    //          specify where the number is put ("foo%dbar"). The template list
    //          otherwise should look exactly the same as a normal list.
    //        - the start offset is where we start counting our instances,
    //          by default from 1.
    //
    //   Also see $PRM/MutliParm.txt for more detailed programmer information.
    
                          PRM_Template(PRM_MultiType     thetype,
                                       PRM_Template     *thetemplates,
                                       PRM_Export        theexportlevel,
                                       float             multisize,
                                       PRM_Name         *thenameptr,
                                       PRM_Default      *thedefaultsize = 0,
                                       PRM_Range        *thedefaultrange = 0,
                                       PRM_SpareData    *thespareptr = 0,
                                       const char       *thehelptext = 0,
                                       PRM_DisableList  *thedisableptr = 0
                                       );
    // no export option.
                          PRM_Template(PRM_MultiType     thetype,
                                       PRM_Template     *thetemplates,
                                       float             multisize,
                                       PRM_Name         *thenameptr,
                                       PRM_Default      *thedefaultsize = 0,
                                       PRM_Range        *thedefaultrange = 0,
                                       PRM_SpareData    *thespareptr = 0,
                                       const char       *thehelptext = 0,
                                       PRM_DisableList  *thedisableptr = 0
                                       );
                          PRM_Template(const PRM_Template &src);
                         ~PRM_Template();

    const PRM_Template   &operator=(const PRM_Template &src);

    void                 initialize(PRM_Type thetype,
                                    PRM_TypeExtended thetype_ext,
                                    PRM_Export theexportlevel,
                                    int thevectorsize,
                                    PRM_Name *thenameptr,
                                    PRM_Default *thedefaults,
                                    PRM_ChoiceList *thechoicelistptr,
                                    PRM_Range *therangeptr,
                                    PRM_Callback thecallbackfunc,
                                    PRM_SpareData *thespareptr,
                                    int theparmgroup,
                                    const char *thehelptext,
                                    PRM_DisableList *thedisableptr);
    
    void                initMulti(PRM_MultiType thetype,
                                  PRM_Template *thetemplates,
                                  PRM_Export theexportlevel,
                                  float multisize,
                                  PRM_Name *thenameptr,
                                  PRM_Default *thedefaultsize,
                                  PRM_Range *thedefaultrange,
                                  PRM_SpareData *thespareptr,
                                  const char *thehelptext,
                                  PRM_DisableList *thedisableptr
                                  );

    // This method is effectively an assignment operator which copies everything
    // from the source except for the vector size and defaults.
    void                  assign(const PRM_Template &src, int thevectorsize,
                                 PRM_Default *thedefaults);

    const PRM_Type       &getType() const       { return myType; }
    PRM_MultiType         getMultiType() const  { return myMultiType; }
    bool                  isMultiType() const;
    bool                  isRampType() const;
    bool                  isRampTypeColor() const;
    PRM_TypeExtended      getTypeExtended() const { return myTypeExtended; }
    int                   getVectorSize() const { return myVectorSize; }
    float                 getMultiSize() const  { return myMultiSize; }
    void                  setNamePtr(PRM_Name *name) { myNamePtr = name; }
    PRM_Name             *getNamePtr()          { return myNamePtr; }
    const PRM_Name       *getNamePtr() const    { return myNamePtr; }
    PRM_SpareData        *getSparePtr()         { return mySparePtr; }
    const PRM_SpareData  *getSparePtr() const   { return mySparePtr; }
    PRM_SpareData        *getOrCreateSparePtr();
    PRM_DisableList      *getDisablePtr()       { return myDisablePtr; }
    const PRM_DisableList*getDisablePtr() const { return myDisablePtr; }
    const PRM_ChoiceList *getChoiceListPtr() const
                          {
                              const PRM_ChoiceList      *list;
                              if (!myChoiceListPtr &&
                                      (myType & PRM_TYPE_ORDINAL) &&
                                      (myType & PRM_TYPE_TOGGLE))
                                  list = &PRMtoggleMenu;
                              else
                                  list = myChoiceListPtr;
                              return list;
                          }
    PRM_ChoiceList       *getChoiceListPtr()    
                          {
                              PRM_ChoiceList    *list;
                              if (!myChoiceListPtr &&
                                      (myType & PRM_TYPE_ORDINAL) &&
                                      (myType & PRM_TYPE_TOGGLE))
                                  list = &PRMtoggleMenu;
                              else
                                  list = myChoiceListPtr;
                              return list;
                          }
    void                  setChoiceListPtr(PRM_ChoiceList *list)
                          {
                              myChoiceListPtr = list;
                          }
    const PRM_Range      *getRangePtr() const   { return myRangePtr; }
    PRM_Range            *getRangePtr()         { return myRangePtr; }
    PRM_Callback          getCallback()         { return myCallbackFunc; }
    const UT_String      &getHelpText() const   { return myHelpText; }
    unsigned int          getAutoScopeField();

    const PRM_Template   *getMultiParmTemplate() const
                          { return myMultiParmTemplate; }
    PRM_Template         *getMultiParmTemplate() 
                          { return myMultiParmTemplate; }
    void                  setMultiParmTemplate(PRM_Template *tplate)
                          { myMultiParmTemplate = tplate; }
    int                   getMultiStartOffset() const;

    /// matchMultiInstance() tests the given name and returns true if it
    /// might be an instance parm of the multiparm token (with # characters).
    /// - If the result is true, then the parsed instance index (relative to
    ///   start_offset) is returned.
    /// - If the index in the name is less that start_offset, then it will be
    ///   rejected.
    /// - For nested multiparms, the instance_index array contains an array of
    ///   the parent multiparm instance indices that you want to match against.
    ///   If it is NULL, then those checks will be skipped.
    static bool           matchMultiInstance(const char *name,
                                             const char *multi_name,
                                             int start_offset,
                                             int &index,
                                             const UT_IntArray *instance_index);

    PRM_Default          *getDefault(int index)
                          {
                              return (index >= 0 && index < myVectorSize)
                                  ? myDefaults(index) : 0;
                          }
    const PRM_Default    *getDefault(int index) const
                          {
                              return (index >= 0 && index < myVectorSize)
                                  ? myDefaults(index) : 0;
                          }
    PRM_Default          *getFactoryDefaults() const
                          {
                              return myFactoryDefaults;
                          }
    void                  setFactoryDefaults(PRM_Default *defaults)
                          {
                              myFactoryDefaults = defaults;
                          }
    void                  restoreFactoryDefaults();
    void                  setFloatDefault(int index, float v);
    void                  setOrdinalDefault(int index, int v);
    void                  setStringDefault(int index, const char *v);
    void                  setDefault(int index, const PRM_Default &d);

    // This function sets the PRM_TYPE_NORESIM flag on an existing parameter.
    // This is an odd operation because it is changing the type of a parameter
    // when it already exists. But setting this flag doesn't really change
    // the fundamental type of the parameter. This capability is used in
    // DOP_Table.C for marking parameters related to guide geometry as not
    // requiring a refresh.
    void                  setNoResim(bool noresim);
    void                  setNoCook(bool nocook);
    void                  setBaseParm(bool baseparm);
    void                  setInvisible(bool invisible);
    void                  setJoinNext(bool joinnext);

    PRM_Export            exportLevel() const
                          { return (PRM_Export)myExportLevel; }
    void                  setExportLevel(PRM_Export level)
                          { myExportLevel = (unsigned char)level; }
    int                   getParmGroup() const { return (int)myParmGroup; }

    // findParmIndex returns -1 if no parameter is found
    int                   findParmIndex(const char *thechannelname);

    void                  getChannelToken(UT_String &thestrref,
                                          int theindex) const;
    void                  getChannelLabel(UT_String &thestrref,
                                          int theindex) const;
    void                  getToken(UT_String &thestrref) const
                          {
                            thestrref = myNamePtr->getToken();
                          }
    void                  getLabel(UT_String &thestrref) const
                          {
                            thestrref = myNamePtr->getLabel();
                          }

    int                   getExpressionFlag() const
                          {
                            return myNamePtr->getExpressionFlag();
                          }

    //
    // Retrieve as strings instead of UT_Strings.
    const char           *getToken() const
                          {
                            return myNamePtr->getToken();
                          }
    const char           *getLabel() const
                          {
                            return myNamePtr->getLabel();
                          }
    unsigned              getTokenHash() const
                          {
                            return myNamePtr->getHash();
                          }

    // A utility function to count the number of templates in a list.  When
    // counting a list for inclusion into a switcher, nested switchers (and all
    // their templates) only count as a single template.  When for_switcher is
    // true, the count will include switchers (and all their nested templates)
    // as a single entity.  When for_switcher is false, the function will
    // return the total size of the template. Similarly for toggle joins &
    // parm joins with 'for_join'.
    static int                   countTemplates(
                                        const PRM_Template *templates,
                                        bool for_switcher = false,
                                        bool for_joins = false,
                                        bool for_rows = false);
    // Finds an index of a template that matches a given token. Returns -1 if
    // not found.
    static int                   getTemplateIndexByToken(
                                        const PRM_Template *templates,
                                        const char * token);

    // Returns a pointer to the template right after the PRM_SWITCHER
    // template that is passed in.
    static const PRM_Template   *getEndOfSwitcher(
                                        const PRM_Template *templates);
    // Returns the number of switcher and non-switcher parms contained
    // within another switcher.
    static void                  getSwitcherStats(
                                        const PRM_Template *templates,
                                        UT_IntArray &numswitchersonpages,
                                        UT_IntArray &numnonswitchersonpages);

    static bool                  getEnclosingSwitcherFolder(
                                        const PRM_Template *tplates,
                                        const int index,
                                        int &switcher, int &folder);

    // Return whether our choicelist is the one used automatically when none
    // is specified by the user.
    bool                         isAutomaticallyGeneratedChoiceList() const;

    // Find the first folder, if any, with the specified label in a switcher
    // template.  Returns -1 if none exists.
    int                          findSwitcherFolderWithLabel(
                                                    const char *label) const;

private:
    void                  clearOurData();
    void                  buildChannelNames() const;
    void                  buildChannelName(UT_String &str, int index) const;
    void                  setAutoScopeField();
    
    PRM_Type                     myType;
    PRM_MultiType                myMultiType;
    PRM_TypeExtended             myTypeExtended;
    int                          myVectorSize;
    PRM_Name                    *myNamePtr;
    UT_PtrArray<PRM_Default *>   myDefaults;
    PRM_Default                 *myFactoryDefaults;
    PRM_ChoiceList              *myChoiceListPtr;
    PRM_Range                   *myRangePtr;
    PRM_Callback                 myCallbackFunc;
    PRM_SpareData               *mySparePtr;
    PRM_DisableList             *myDisablePtr;
    unsigned char                myExportLevel;
    unsigned char                myParmGroup;
    unsigned int                 myAutoScopeField;
    PRM_Template                *myMultiParmTemplate;
    float                        myMultiSize;
    UT_String                    myHelpText;
    mutable char               **myChannelNames;    // just a cache
};

#endif

---