HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
PI_SpareProperty.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: PI_SpareProperty.h ( PI Library, C++)
7  *
8  * COMMENTS: Spare properties provide a way to specify UI for well defined
9  * spare parameters. The spare properties load in dialog script
10  * files, defining parameters. There's a hierarchy to the
11  * parameters.
12  *
13  * There are different "classes" of properties (i.e. properties
14  * for mantra9.0 or prman12.5). The class is defined by the
15  * name/label of the dialog script.
16  *
17  * Each parameter also has a "category". The parameters are
18  * bundled into their categories. When the spare property is
19  * added to an operator, the property will automatically be
20  * shuffled into a folder with the given category label.
21  *
22  * Categories are specified by a parmtag "category" in the dialog
23  * script.
24  *
25  * If the category is an empty string (""), then the parameter
26  * will not be considered to be a property, but rather just a
27  * place holder. Place holders can be inserted between groups of
28  * parameters to avoid the automatic aglomeration of groups
29  * performed by dialog script parsing. They can also just be
30  * placeholders.
31  *
32  * Sometimes, parameters come in "bundles". Parameters which
33  * belong together. Groups in the dialog script are used for this
34  * purpose. The parmtag specifying the category should be put on
35  * the group. All parameters in the group will be added
36  * simultaneously when the user adds the group.
37  *
38  * The help-tag stored on parameters is accessible.
39  */
40 
41 #ifndef __PI_SpareProperty__
42 #define __PI_SpareProperty__
43 
44 #include "PI_API.h"
45 
46 class UT_WorkBuffer;
47 class UT_StringArray;
48 class UT_String;
49 class PRM_ScriptParm;
50 class OP_Node;
52 
53 typedef enum {
57 
58 typedef enum {
59  PI_SPARE_PROPERTY_ASIS, // Put spare parms at end of folder
60  PI_SPARE_PROPERTY_REPACKAGE, // Re-package original parameters
62 
63 /// @brief Specifies collections of pre-defined spare parameter definitions
64 ///
65 /// This class manages all the spare property lists. These property lists are
66 /// used by Houdini to quickly add pre-defined parameters to parameter dialogs.
67 ///
68 /// Parameters are collected into "classes". These class collections store
69 /// parameters that have a common purpose. These classes correspond to the
70 /// parameter definitions in $HH/soho/parameters.
71 ///
72 /// Each class has a set of "categories". Each category corresponds to a
73 /// folder of properties. For example, "Shading".
74 ///
75 /// So, the hierarchy is: class.category.property
76 ///
78 public:
79  /// If the class_pattern is nil, the list of classes will be returned.
80  /// If the category is nil, the list of categories for matching classes
81  /// will be returned.
82  ///
83  /// All parameters which are contained within the class pattern and
84  /// category pattern will be returned. If the quiet flag is false, the
85  /// associated category of each parameter will also be printed, otherwise,
86  /// just the parameter name will be listed.
87  static void list(UT_String &errors, UT_WorkBuffer &wbuf,
88  const char *class_pattern = 0,
89  const char *category = 0,
90  bool quiet = false);
91 
92  // Create a new spare property (or properties) for the node
93  // Top level folder is the folder to put the parameter (and folder) in. If
94  // the top_level_folder is null, the folder will be added to the top level
95  // switcherr (or one will be created).
96  static bool addProperty(OP_Node *node,
97  const char *top_level_folder,
98  const char *class_pattern,
99  const char *parameter,
100  UT_String &errors,
101  PI_SPARE_PROPERTY_FILTER ignore_filter,
102  PI_SPARE_PROPERTY_PACKAGE repackage,
103  const char *category_override=nullptr);
104  static bool addProperty(PI_EditScriptedParms &editparms,
105  const char *top_level_folder,
106  const char *class_pattern,
107  const char *parameter,
108  UT_String &errors,
109  OP_Node *node,
110  PI_SPARE_PROPERTY_FILTER ignore_filter,
111  PI_SPARE_PROPERTY_PACKAGE repackage,
112  const char *category_override=nullptr);
113 
114  // Initialize the spare properties by loading in all the dialog scripts.
115  // Calling initialize multiple times is ok. Each call will re-load the
116  // dialogs (i.e. dsreload)
117  static bool initialize(UT_String &errors);
118 
119  // Adding a class file will add a path to the list of files scanned for
120  // properties. Thus, it's possible to add a dialog script after
121  // initialization. This method will automatically call initialize() and
122  // return errors from the initialization.
123  static bool addClassFile(UT_String &errors,
124  const char *path, int pathvar=-1);
125 
126  /// Get a list of the class files
127  static int getClassFiles(UT_StringArray &list);
128 
129  /// Get a list of all the classes defined by the files
130  /// Each class has a list of tags associated with it (defined in the .ds
131  /// file). You can filter the class selection based on the tag expression.
132  static int getClasses(UT_StringArray &list,
133  const char *filter_tags="*");
134 
135  /// Each parameter class as properties.
136  /// This method returns the "label" for the class.
137  static const char *getClassLabel(const char *name);
138 
139  // Checks whether or not the given name is a class
140  static bool isClass(const char *name);
141 
142  // Get a list of all the categories for a given class pattern
143  static int getCategories(UT_StringArray &list,
144  const char *class_pattern);
145 
146  // Get a list of all the parameters for a given a class and category
147  // pattern.
148  static int getParameters(UT_StringArray &list,
149  const char *class_pattern,
150  const char *category);
151 
152  /// @{
153  /// Populate `parms` with a set of parameters representing a class, or a
154  /// category, or the properties in a category.
155  static void getClassAsParameters(
156  PI_EditScriptedParms &parms,
157  const char *class_name);
158  static void getCategoryAsParameters(
159  PI_EditScriptedParms &parms,
160  const char *class_name,
161  const char *category_name);
162  static void getCategoryPropertiesAsParameters(
163  PI_EditScriptedParms &parms,
164  const char *class_name,
165  const char *category_name);
166  /// @}
167 
168  // Get a pointer to the PRM_ScriptParm that defines a property
169  static const PRM_ScriptParm *getParmDefinition(const char *classname,
170  const char *parameter);
171 
172  // Get the name of the class that owns the specified property
173  static bool getClassName(const PRM_ScriptParm *property,
174  UT_String &classname);
175 };
176 
177 #endif
GLsizei const GLchar *const * path
Definition: glcorearb.h:3340
#define PI_API
Definition: PI_API.h:10
PI_SPARE_PROPERTY_PACKAGE
OPENVDB_API void initialize()
Global registration of basic types.
Definition: logging.h:318
GLuint const GLchar * name
Definition: glcorearb.h:785
Specifies collections of pre-defined spare parameter definitions.
PI_SPARE_PROPERTY_FILTER