HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
PRM_Template.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: PRM_Template.h (Parameter Library)
7  *
8  * COMMENTS:
9  * PRM_Template is the class which contains all the static data
10  * relating to a parameter. It encapsulates the characteristics
11  * of the parameter, such as type, default values, range, etc.
12  * A PRM_Template is used in conjunction with a PRM_Instance to
13  * define a PRM_Parm. A PRM_Instance is to a PRM_Template as
14  * an object is to a class in C++.
15  */
16 
17 #ifndef __PRM_Template__
18 #define __PRM_Template__
19 
20 #include "PRM_API.h"
21 #include "PRM_Callback.h"
22 #include "PRM_Conditional.h"
23 #include "PRM_Name.h"
24 #include "PRM_Type.h"
25 #include <UT/UT_IntArray.h>
26 #include <UT/UT_ValArray.h>
27 #include <UT/UT_String.h>
28 #include <SYS/SYS_Types.h>
29 
30 #define PRM_TYPE_IS_SWITCHER(type) (type.isSwitcher())
31 #define PRM_IS_JOIN(parm) (parm.getTypeExtended() == PRM_TYPE_TOGGLE_JOIN || \
32  parm.getTypeExtended() == PRM_TYPE_JOIN_PAIR)
33 
34 class UT_WorkBuffer;
35 class PRM_ChoiceList;
36 class PRM_Range;
37 class PRM_Default;
38 class PRM_Template;
39 class PRM_SpareData;
40 
42 
44 {
45 public:
46  // An export level is a hint to say if a parm should be displayed or not.
47  // By default, all parms have minimum export level, which means that
48  // they are only displayed if someone asks for a dialog with the minimum
49  // export level. Creating a dialog with a higher export level will only
50  // contain those parameters with higher export levels.
52  {
56  PRM_EXPORT_TBX // for toolboxes
57  };
58 
59  enum
60  {
61  // This is maximum vector size for parameters. This is because we keep
62  // per component flags in uint32 variables. For myAutoScopeField, we
63  // use the high-bit to keep track of whether it's initialized so the
64  // actual limit is 31, not 32.
65  MAX_VECTOR_SIZE = 31
66  };
67 
68  // No extended type given and no export level given.
70  int thevectorsize = 1,
71  PRM_Name *thenameptr = 0,
72  PRM_Default *thedefaults = 0,
73  PRM_ChoiceList *thechoicelistptr = 0,
74  PRM_Range *therangeptr = 0,
75  PRM_Callback thecallbackfunc = 0,
76  PRM_SpareData *thespareptr = 0,
77  int theparmgroup = 1,
78  const char *thehelptext = 0,
79  PRM_ConditionalBase *thecondptr = 0);
80 
81  // No extended type given but export level given.
82  PRM_Template(PRM_Type thetype,
83  PRM_Export theexportlevel,
84  int thevectorsize = 1,
85  PRM_Name *thenameptr = 0,
86  PRM_Default *thedefaults = 0,
87  PRM_ChoiceList *thechoicelistptr = 0,
88  PRM_Range *therangeptr = 0,
89  PRM_Callback thecallbackfunc = 0,
90  PRM_SpareData *thespareptr = 0,
91  int theparmgroup = 1,
92  const char *thehelptext = 0,
93  PRM_ConditionalBase *thecondptr = 0);
94 
95  // Extended type given but no export level given.
96  PRM_Template(PRM_Type thetype,
97  PRM_TypeExtended thetype_ext,
98  int thevectorsize = 1,
99  PRM_Name *thenameptr = 0,
100  PRM_Default *thedefaults = 0,
101  PRM_ChoiceList *thechoicelistptr = 0,
102  PRM_Range *therangeptr = 0,
103  PRM_Callback thecallbackfunc = 0,
104  PRM_SpareData *thespareptr = 0,
105  int theparmgroup = 1,
106  const char *thehelptext = 0,
107  PRM_ConditionalBase *thecondptr = 0);
108 
109  // Extended type given and export level given.
110  PRM_Template(PRM_Type thetype,
111  PRM_TypeExtended thetype_ext,
112  PRM_Export theexportlevel,
113  int thevectorsize = 1,
114  PRM_Name *thenameptr = 0,
115  PRM_Default *thedefaults = 0,
116  PRM_ChoiceList *thechoicelistptr = 0,
117  PRM_Range *therangeptr = 0,
118  PRM_Callback thecallbackfunc = 0,
119  PRM_SpareData *thespareptr = 0,
120  int theparmgroup = 1,
121  const char *thehelptext = 0,
122  PRM_ConditionalBase *thecondptr = 0);
123 
124  // Dynamic multi-parm type contructors:
125 
126  // Notes: - the export level cannot be PRM_EXPORT_TBX (they won't fit)
127  // - the vector size is the number of shown instances (Scroll type)
128  // or the number of instances per tab (Switcher type).
129  // - the default is the number of default instances (int)
130  // - the range is the allowable range of instances, min zero.
131  // - the template list is a list of templates to use as a guide
132  // to create new instances (a template, but I didn't want to use
133  // that word again). Names will have a number suffixed to them
134  // depending on the instance number ("foo1") or %d may be used to
135  // specify where the number is put ("foo%dbar"). The template list
136  // otherwise should look exactly the same as a normal list.
137  // - the start offset is where we start counting our instances,
138  // by default from 1.
139  PRM_Template(PRM_MultiType thetype,
140  PRM_Template *thetemplates,
141  PRM_Export theexportlevel,
142  fpreal multisize,
143  PRM_Name *thenameptr,
144  PRM_Default *thedefaultsize = 0,
145  PRM_Range *thedefaultrange = 0,
146  PRM_SpareData *thespareptr = 0,
147  const char *thehelptext = 0,
148  PRM_ConditionalBase *thecondptr = 0,
149  PRM_Callback thecallbackfunc = 0);
150  // no export option.
151  PRM_Template(PRM_MultiType thetype,
152  PRM_Template *thetemplates,
153  fpreal multisize,
154  PRM_Name *thenameptr,
155  PRM_Default *thedefaultsize = 0,
156  PRM_Range *thedefaultrange = 0,
157  PRM_SpareData *thespareptr = 0,
158  const char *thehelptext = 0,
159  PRM_ConditionalBase *thecondptr = 0,
160  PRM_Callback thecallbackfunc = 0);
161 
162  PRM_Template(const PRM_Template &src);
163  ~PRM_Template();
164 
165  int64 getMemoryUsage(bool inclusive) const;
166 
167  const PRM_Template &operator=(const PRM_Template &src);
168 
169  void initialize(PRM_Type thetype,
170  PRM_TypeExtended thetype_ext,
171  PRM_Export theexportlevel,
172  int thevectorsize,
173  PRM_Name *thenameptr,
174  PRM_Default *thedefaults,
175  PRM_ChoiceList *thechoicelistptr,
176  PRM_Range *therangeptr,
177  PRM_Callback thecallbackfunc,
178  PRM_SpareData *thespareptr,
179  int theparmgroup,
180  const char *thehelptext,
181  PRM_ConditionalBase *thecondptr);
182 
183  void initMulti(PRM_MultiType thetype,
184  PRM_Template *thetemplates,
185  PRM_Export theexportlevel,
186  fpreal multisize,
187  PRM_Name *thenameptr,
188  PRM_Default *thedefaultsize,
189  PRM_Range *thedefaultrange,
190  PRM_Callback thecallbackfunc,
191  PRM_SpareData *thespareptr,
192  const char *thehelptext,
193  PRM_ConditionalBase *thecondptr);
194 
195  // This method is effectively an assignment operator which copies everything
196  // from the source except for the vector size and defaults.
197  void assign(const PRM_Template &src, int thevectorsize,
198  PRM_Default *thedefaults);
199 
200  const PRM_Type &getType() const { return myType; }
201  PRM_MultiType getMultiType() const { return myMultiType; }
202  bool isMultiType() const;
203  bool isRampType() const;
204  bool isRampTypeColor() const;
205  PRM_TypeExtended getTypeExtended() const { return myTypeExtended; }
206  int getVectorSize() const { return myVectorSize; }
207  fpreal getMultiSize() const { return myMultiSize; }
208  void setNamePtr(PRM_Name *name) { myNamePtr = name; }
209  PRM_Name *getNamePtr() { return myNamePtr; }
210  const PRM_Name *getNamePtr() const { return myNamePtr; }
211  PRM_SpareData *getSparePtr() { return mySparePtr; }
212  const PRM_SpareData *getSparePtr() const { return mySparePtr; }
213  PRM_SpareData *getOrCreateSparePtr();
215  { mySparePtr = spare; }
217  { return myConditionalPtr?myConditionalPtr->getConditional(type):NULL;}
218 
220  { return myConditionalPtr?myConditionalPtr->getConditional(type):NULL;}
222  { return myConditionalPtr; }
224  { return myConditionalPtr; }
225 
227  { return getConditionalPtr(PRM_CONDTYPE_DISABLE); }
229  { return getConditionalPtr(PRM_CONDTYPE_DISABLE); }
231  {
232  const PRM_ChoiceList *list;
233  if (!myChoiceListPtr &&
234  (myType & PRM_TYPE_ORDINAL) &&
235  (myType & PRM_TYPE_TOGGLE))
236  list = &PRMtoggleMenu;
237  else
238  list = myChoiceListPtr;
239  return list;
240  }
242  {
243  PRM_ChoiceList *list;
244  if (!myChoiceListPtr &&
245  (myType & PRM_TYPE_ORDINAL) &&
246  (myType & PRM_TYPE_TOGGLE))
247  list = &PRMtoggleMenu;
248  else
249  list = myChoiceListPtr;
250  return list;
251  }
253  {
254  myChoiceListPtr = list;
255  }
256  const PRM_Range *getRangePtr() const { return myRangePtr; }
257  PRM_Range *getRangePtr() { return myRangePtr; }
258  PRM_Callback getCallback() const { return myCallbackFunc; }
259  void setCallback(PRM_Callback callback)
260  { myCallbackFunc = callback; }
261  const UT_String &getHelpText() const { return myHelpText; }
262  unsigned int getAutoScopeField();
263 
265  { return myMultiParmTemplate; }
267  { return myMultiParmTemplate; }
269  {
270  UT_ASSERT(!tplate || !tplate->isRampType());
271  myMultiParmTemplate = tplate;
272  }
273  int getMultiStartOffset() const;
274 
275  /// matchMultiInstance() tests the given name and returns true if it
276  /// might be an instance parm of the multiparm token (with # characters).
277  /// - If the result is true, then the parsed instance index (relative to
278  /// start_offset) is returned.
279  /// - If the index in the name is less that start_offset, then it will be
280  /// rejected.
281  /// - For nested multiparms, the instance_index array contains an array of
282  /// the parent multiparm instance indices that you want to match against.
283  /// If it is NULL, then those checks will be skipped.
284  static bool matchMultiInstance(const char *name,
285  const char *multi_name,
286  int start_offset,
287  int &index,
288  const UT_IntArray *instance_index);
289 
291  {
292  return (index >= 0 && index < myVectorSize)
293  ? myDefaults(index) : 0;
294  }
295  const PRM_Default *getDefault(int index) const
296  {
297  return (index >= 0 && index < myVectorSize)
298  ? myDefaults(index) : 0;
299  }
301  {
302  return myFactoryDefaults;
303  }
305  {
306  myFactoryDefaults = defaults;
307  }
308  void restoreFactoryDefaults();
309  void setFloatDefault(int index, fpreal v);
310  void setOrdinalDefault(int index, int v);
311  void setStringDefault(int index, const char *v);
312  void setDefault(int index, const PRM_Default &d);
313 
314  // This function sets the PRM_TYPE_NORESIM flag on an existing parameter.
315  // This is an odd operation because it is changing the type of a parameter
316  // when it already exists. But setting this flag doesn't really change
317  // the fundamental type of the parameter. This capability is used in
318  // DOP_Table.C for marking parameters related to guide geometry as not
319  // requiring a refresh.
320  void setNoResim(bool noresim);
321  void setNoCook(bool nocook);
322  /// Set the no-cook flag based on the "cook_dependent" spare data. If the
323  /// force flag is set, the no-cook flag will be set to true if the spare
324  /// data doesn't exist.
325  /// @return The value of the nocook flag
326  bool setNoCook(const PRM_SpareData *spare,
327  bool force=false);
328  void setBaseParm(bool baseparm);
329  void setInvisible(bool invisible);
330  bool getInvisible() const
331  { return (myType & PRM_TYPE_INVISIBLE) != 0; }
332  void setJoinNext(bool joinnext);
333  bool getJoinNext() const
334  { return (myType & PRM_TYPE_JOIN_NEXT) != 0; }
335  void setLabelNone(bool labelnone);
336  bool getLabelNone() const
337  { return (myType & PRM_TYPE_LABEL_NONE) != 0; }
338 
340  { myTypeExtended = type_ext; }
341 
343  { return (PRM_Export)myExportLevel; }
345  { myExportLevel = (unsigned char)level; }
346  int getParmGroup() const { return (int)myParmGroup; }
347 
348  // findSubIndex returns -1 if no parameter is found
349  int findSubIndex(const char *thechannelname);
350 
351  void getChannelToken(UT_String &thestrref,
352  int theindex) const;
353  bool hasChannelToken(const char *name,
354  int theindex, int namelen) const;
355  void getChannelLabel(UT_String &thestrref,
356  int theindex) const;
357  void getToken(UT_String &thestrref) const
358  {
359  thestrref = myNamePtr->getToken();
360  }
361  void getLabel(UT_String &thestrref) const
362  {
363  thestrref = myNamePtr->getLabel();
364  }
365 
366  int getExpressionFlag() const
367  {
368  return myNamePtr->getExpressionFlag();
369  }
370 
371  //
372  // Retrieve as strings instead of UT_Strings.
373  const char *getToken() const
374  {
375  return myNamePtr->getToken();
376  }
377  const char *getLabel() const
378  {
379  return myNamePtr->getLabel();
380  }
381  unsigned getTokenHash() const
382  {
383  return myNamePtr->getHash();
384  }
385 
386  // A utility function to count the number of templates in a list. When
387  // counting a list for inclusion into a switcher, nested switchers (and all
388  // their templates) only count as a single template. When for_switcher is
389  // true, the count will include switchers (and all their nested templates)
390  // as a single entity. When for_switcher is false, the function will
391  // return the total size of the template. Similarly for toggle joins &
392  // parm joins with 'for_join'.
393  static int countTemplates(
394  const PRM_Template *templates,
395  bool for_switcher = false,
396  bool for_joins = false,
397  bool for_rows = false);
398  // Finds an index of a template that matches a given token. Returns -1 if
399  // not found.
400  static int getTemplateIndexByToken(
401  const PRM_Template *templates,
402  const char * token);
403 
404  // Returns a pointer to the template right after the PRM_SWITCHER
405  // template that is passed in.
406  static const PRM_Template *getEndOfSwitcher(
407  const PRM_Template *templates);
408  // Returns the number of switcher and non-switcher parms contained
409  // within another switcher.
410  static void getSwitcherStats(
411  const PRM_Template *templates,
412  UT_IntArray &numswitchersonpages,
413  UT_IntArray &numnonswitchersonpages);
414 
415  static bool getEnclosingSwitcherFolder(
416  const PRM_Template *tplates,
417  const int index,
418  int &switcher, int &folder);
419 
420  // Returns the highest export level for any template in the list.
421  static PRM_Export getHighestExportLevel(
422  const PRM_Template *tplates);
423 
424  // Return whether our choicelist is the one used automatically when none
425  // is specified by the user.
426  bool isAutomaticallyGeneratedChoiceList() const;
427 
428  // Find the first folder, if any, with the specified label in a switcher
429  // template. Returns -1 if none exists.
430  int findSwitcherFolderWithLabel(
431  const char *label) const;
432 
433 private:
434  void clearOurData();
435  void buildChannelNames() const;
436  void buildChannelName(UT_WorkBuffer &str,
437  int index) const;
438  void setAutoScopeField();
439 
440  PRM_Type myType;
441  PRM_MultiType myMultiType;
442  PRM_TypeExtended myTypeExtended;
443  int myVectorSize;
444  PRM_Name *myNamePtr;
445  UT_ValArray<PRM_Default *> myDefaults;
446  PRM_Default *myFactoryDefaults;
447  PRM_ChoiceList *myChoiceListPtr;
448  PRM_Range *myRangePtr;
449  PRM_Callback myCallbackFunc;
450  PRM_SpareData *mySparePtr;
451  PRM_ConditionalBase *myConditionalPtr;
452  unsigned char myExportLevel;
453  unsigned char myParmGroup;
454  unsigned char myChoiceListOwnedByMe;
455  unsigned int myAutoScopeField;
456  PRM_Template *myMultiParmTemplate;
457  fpreal myMultiSize;
458  UT_String myHelpText;
459  mutable char **myChannelNames; // just a cache
460  mutable int *myChannelNamesLen; // just a cache
461 };
462 
463 #endif
PRM_Default * getFactoryDefaults() const
Definition: PRM_Template.h:300
const char * getToken() const
Definition: PRM_Template.h:373
PRM_ChoiceList * getChoiceListPtr()
Definition: PRM_Template.h:241
PRM_Default * getDefault(int index)
Definition: PRM_Template.h:290
PRM_Template * getMultiParmTemplate()
Definition: PRM_Template.h:266
const PRM_Type & getType() const
Definition: PRM_Template.h:200
unsigned getTokenHash() const
Definition: PRM_Template.h:381
GLuint GLsizei const GLchar * label
Definition: glcorearb.h:2544
#define SYS_DEPRECATED(__V__)
PRM_Callback getCallback() const
Definition: PRM_Template.h:258
PRM_SpareData * getSparePtr()
Definition: PRM_Template.h:211
const GLdouble * v
Definition: glcorearb.h:836
const PRM_Template * getMultiParmTemplate() const
Definition: PRM_Template.h:264
void setNamePtr(PRM_Name *name)
Definition: PRM_Template.h:208
const PRM_Conditional * getDisablePtr() const
Definition: PRM_Template.h:228
GLint level
Definition: glcorearb.h:107
PRM_ConditionalType
PRM_Conditional * getConditionalPtr(PRM_ConditionalType type)
Definition: PRM_Template.h:216
const UT_String & getHelpText() const
Definition: PRM_Template.h:261
void setExportLevel(PRM_Export level)
Definition: PRM_Template.h:344
PRM_API const PRM_Type PRM_TYPE_TOGGLE
void setCallback(PRM_Callback callback)
Definition: PRM_Template.h:259
PRM_Range * getRangePtr()
Definition: PRM_Template.h:257
long long int64
Definition: SYS_Types.h:106
void setSparePtr(PRM_SpareData *spare)
Definition: PRM_Template.h:214
int getExpressionFlag() const
Definition: PRM_Template.h:366
bool getJoinNext() const
Definition: PRM_Template.h:333
const PRM_Range * getRangePtr() const
Definition: PRM_Template.h:256
#define UT_ASSERT(ZZ)
Definition: UT_Assert.h:102
bool getInvisible() const
Definition: PRM_Template.h:330
const char * getLabel() const
Definition: PRM_Template.h:377
GLint namelen
Definition: glcorearb.h:3338
bool getLabelNone() const
Definition: PRM_Template.h:336
OPENVDB_API void initialize()
Global registration of basic types.
Definition: logging.h:316
PRM_Conditional * getConditional(PRM_ConditionalType type)
GLuint const GLchar * name
Definition: glcorearb.h:785
PRM_API const PRM_Type PRM_TYPE_LABEL_NONE
void getToken(UT_String &thestrref) const
Definition: PRM_Template.h:357
void setFactoryDefaults(PRM_Default *defaults)
Definition: PRM_Template.h:304
PRM_MultiType getMultiType() const
Definition: PRM_Template.h:201
int getVectorSize() const
Definition: PRM_Template.h:206
PRM_TypeExtended getTypeExtended() const
Definition: PRM_Template.h:205
PRM_Conditional * getDisablePtr()
Definition: PRM_Template.h:226
const PRM_ConditionalBase * getConditionalBasePtr() const
Definition: PRM_Template.h:223
PRM_API const PRM_Type PRM_LIST_TERMINATOR
double fpreal
Definition: SYS_Types.h:269
const PRM_Name * getNamePtr() const
Definition: PRM_Template.h:210
PRM_TypeExtended
Definition: PRM_Type.h:508
fpreal getMultiSize() const
Definition: PRM_Template.h:207
PRM_Export exportLevel() const
Definition: PRM_Template.h:342
PRM_API const PRM_Type PRM_TYPE_JOIN_NEXT
void setChoiceListPtr(PRM_ChoiceList *list)
Definition: PRM_Template.h:252
PRM_API const PRM_Type PRM_TYPE_ORDINAL
GLuint index
Definition: glcorearb.h:785
void setMultiParmTemplate(PRM_Template *tplate)
Definition: PRM_Template.h:268
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
bool isRampType() const
const PRM_ChoiceList * getChoiceListPtr() const
Definition: PRM_Template.h:230
const PRM_SpareData * getSparePtr() const
Definition: PRM_Template.h:212
PRM_API const PRM_Type PRM_TYPE_INVISIBLE
int getParmGroup() const
Definition: PRM_Template.h:346
PRM_ConditionalBase * getConditionalBasePtr()
Definition: PRM_Template.h:221
#define PRM_API
Definition: PRM_API.h:10
void setTypeExtended(PRM_TypeExtended type_ext)
Definition: PRM_Template.h:339
void getLabel(UT_String &thestrref) const
Definition: PRM_Template.h:361
PRM_Name * getNamePtr()
Definition: PRM_Template.h:209
const PRM_Conditional * getConditionalPtr(PRM_ConditionalType type) const
Definition: PRM_Template.h:219
PRM_API PRM_ChoiceList PRMtoggleMenu
PRM_MultiType
This type enum defines the different types of multi (dynamic) parameters.
Definition: PRM_Type.h:417
GLenum src
Definition: glcorearb.h:1792
const PRM_Default * getDefault(int index) const
Definition: PRM_Template.h:295