HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_InfoTree.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: UT_InfoTree.h
7  *
8  * COMMENTS: This class is a tree implemented recursively (i.e. each node in
9  * the tree is itself another tree). Each UT_InfoTree has a name,
10  * an array of property arrays, and finally an array of children
11  * which are also UT_InfoTree objects.
12  *
13  * Put simply, this is a tree in which each node can have as many
14  * children as it likes, and at each node we can store data in the
15  * form of strings (which are stored in arrays/rows, in case we
16  * want to display each row in a spreadsheet table).
17  *
18  * SEE UT_InfoTree.C doc for how to create an UT_InfoTree.
19  *
20  * NOTE: Each direct child must have a unique name amongst the
21  * other children directly beneath us- see declaration of
22  * addChildBranch() for more details.
23  *
24  */
25 
26 #ifndef __UT_InfoTree_h__
27 #define __UT_InfoTree_h__
28 
29 #include "UT_API.h"
30 #include "UT_FloatArray.h"
31 #include "UT_Array.h"
32 #include "UT_StringArray.h"
33 #include "UT_WorkBuffer.h"
34 #include <SYS/SYS_Types.h>
35 #include <iosfwd>
36 
37 class UT_StringHolder;
38 
39 #define TREE_TOP_DEFAULT_NAME "Head of Tree"
40 
41 ////////////////////////////////////////////////////////////////////////////////
42 //
43 // NAME: ut_PropertyRow
44 //
45 // Simply a UT_StringArray, except we provide an append method which takes
46 // an int as a parameter to make the life of our clients easier
47 //
48 ////////////////////////////////////////////////////////////////////////////////
49 
51 {
52 public:
54  ~ut_PropertyRow();
55 
56  void append(const UT_StringHolder &property);
57  void append(const UT_String &property);
58  void append(const char *property);
59 
60  template<class ValType>
61  void append(const ValType &property);
62 
63  int appendSprintf(const char *fmt, ...) SYS_PRINTF_CHECK_ATTRIBUTE(2, 3);
64 };
65 
66 ////////////////////////////////////////////////////////////////////////////////
67 //
68 // NAME: UT_InfoTree
69 //
70 /// This is a tree in which each node can have as many children as it likes,
71 /// and at each node we can store data in the form of strings (which are
72 /// stored in arrays/rows, in case we want to display each row in a
73 /// spreadsheet table).
74 //
75 ////////////////////////////////////////////////////////////////////////////////
76 
78 {
79 public:
80  /// User should always call this constructor with no parameters specified.
81  /// The parameters are only needed when branches are created internally.
82  UT_InfoTree (UT_InfoTree *tree_top = NULL, UT_InfoTree *parent = NULL,
84 
85  /// Recursively deletes all my data and all children, which in turn delete
86  /// all their data and children, etc...
87  ~UT_InfoTree ();
88 
89  /// Clears all our row and column information. Doesn't affect child
90  /// branches.
91  void clearProperties();
92  /// Clears all child branches. Doesn't affect our properties.
93  void clearChildren();
94 
95  /// Create a child or subtree under this tree with the name 'branch_name'
96  /// The caller should NOT call delete on the pointer returned when they are
97  /// done with it, since this class' destructor will take care of any
98  /// children created in addChildBranch(..).
99  ///
100  /// IMPORTANT NOTE: It is assumed that all branches on the same level will
101  /// have *unique* names, BUT this is NOT enforced to prevent a performance
102  /// hit since these trees can get rebuilt pretty often to accurately reflect
103  /// the data they are containing. BOTTOM LINE: Make sure 'branch_name' is
104  /// unique among 'myChildBranches' (otherwise there'll be trouble when we
105  /// decide to traverse a tree given a path of branches - system won't crash,
106  /// but will always choose the first available branch on a level with the
107  /// name it is looking for).
108  UT_InfoTree *addChildBranch(const UT_StringHolder &name);
109  /// Adds a child branch with "Property" and "Value" headings.
110  UT_InfoTree *addChildMap(const UT_StringHolder &name);
111 
112  /// Create a new empty row.
113  ut_PropertyRow *addProperties();
114 
115  /// HOW TO USE: You may add up to 4 properties to a single row at once using
116  /// these methods. If you still need to add more properties to this SAME
117  /// row/array after that, simply use the returned ut_PropertyRow* to call
118  /// 'append()' on and add more properties. To add properties that are
119  /// ints, use the same technique, since there is an 'append()' method in
120  /// ut_PropertyRow that takes an int parameter (or check the overridden
121  /// version of addProperties below). BOTTOM LINE - if you want maximum
122  /// flexibility, call this with no parameters and then append each property
123  /// manually to the returned ut_PropertyRow*.
124  template<class ValType1>
125  ut_PropertyRow *addProperties(const ValType1 &v1);
126  template<class ValType1, class ValType2>
127  ut_PropertyRow *addProperties(const ValType1 &v1,
128  const ValType2 &v2);
129  template<class ValType1, class ValType2, class ValType3>
130  ut_PropertyRow *addProperties(const ValType1 &v1,
131  const ValType2 &v2,
132  const ValType3 &v3);
133  template<class ValType1, class ValType2, class ValType3, class ValType4>
134  ut_PropertyRow *addProperties(const ValType1 &v1,
135  const ValType2 &v2,
136  const ValType3 &v3,
137  const ValType4 &v4);
138 
139  /// Add column headings for this node to be used when the info is displayed
140  /// in a table. THE NUMBER OF HEADINGS ADDED HERE WILL DETERMINE THE NUMBER
141  /// OF COLUMNS DISPLAYED. Note: This class does NOT ensure that the # of
142  /// column headings matches the width of each property array in
143  /// 'myProperties'. Instead, we only display as many properties per row as
144  /// we have number of columns.
145  ///
146  /// The width parameter must either be specified on all columns or on
147  /// none. If set on all columns, it represents the fraction of the total
148  /// width that gets allocated to that column (the values get normalized).
149  /// If any column has a width specified of <= 0.0, the whole thing
150  /// reverts to the default behavior of allocating all columns with
151  /// equal width.
152  void addColumnHeading(const UT_StringHolder &label,
153  fpreal width = -1.0);
154  void addColumnHeading(int label,
155  fpreal width = -1.0);
156 
157  /// Get a pointer to my parent
158  UT_InfoTree *getParentBranch() const;
159 
160  /// Get a pointer to the very top node in the tree
161  UT_InfoTree *getTreeTop() const;
162 
163  /// Return this branch's name
164  const UT_StringHolder &getName() const;
165  /// In case we decide to change the name of this branch
166  void setName(const UT_StringHolder &new_name);
167 
168  /// Return this branch's "type" idwentifier
169  const UT_StringHolder &getInfoType() const;
170  /// In case we decide to change the "type" of this branch
171  void setInfoType(const UT_StringHolder &new_type);
172 
173  /// Get a ptr to a specific descendent branch of this tree, given a
174  /// UT_StringArray of branch names. e.g. if you want to traverse down the
175  /// tree through a child branch named "Antigen" and get a pointer to that
176  /// branch's child called "Rocks", then your UT_StringArray should simply
177  /// have 2 elements, "Antigen" and "Rocks", respectively in that order.
178  /// Method returns NULL if no such valid path found.
179  ///
180  /// NOTE: Again, this assumes all branches at the same level have unique
181  /// names, as stated above for 'addChildBranch()'.
182  UT_InfoTree *getDescendentPtr(UT_StringArray &path);
183 
184  //Accessors for my child branches and data properties
185  const UT_Array<UT_InfoTree *> &getChildBranches() const;
186  const UT_Array<ut_PropertyRow *> &getProperties() const;
187  const ut_PropertyRow &getColumnHeadings() const;
188  const UT_FloatArray &getColumnWidths() const;
189 
190  static const UT_StringHolder &getGeometryInfoType();
191  static const UT_StringHolder &getFieldInfoType();
192 
193 private:
194  UT_InfoTree *myParent;
195  UT_InfoTree *myTreeTop;
196  UT_StringHolder myName;
197  UT_StringHolder myInfoType;
198  UT_Array<UT_InfoTree *> myChildBranches;
199  UT_Array<ut_PropertyRow *> myProperties;
200  ut_PropertyRow myColumnHeadings;
201  UT_FloatArray myColumnWidths;
202 };
203 
204 template<class ValType>
205 void
206 ut_PropertyRow::append(const ValType &property)
207 {
208  UT_WorkBuffer s;
209  s.format("{}", property);
211 }
212 
213 template<class ValType1>
216 {
217  //Create the array
219 
220  //Append ALL properties passed to us
221  row->append(v1);
222 
223  //Return a ptr to the array so the user may add more properties if
224  //necessary
225  return row;
226 }
227 
228 template<class ValType1, class ValType2>
231  const ValType2 &v2)
232 {
233  //Create the array
235 
236  //Append ALL properties passed to us
237  row->append(v1);
238  row->append(v2);
239 
240  //Return a ptr to the array so the user may add more properties if
241  //necessary
242  return row;
243 }
244 
245 template<class ValType1, class ValType2, class ValType3>
248  const ValType2 &v2,
249  const ValType3 &v3)
250 {
251  //Create the array
253 
254  //Append ALL properties passed to us
255  row->append(v1);
256  row->append(v2);
257  row->append(v3);
258 
259  //Return a ptr to the array so the user may add more properties if
260  //necessary
261  return row;
262 }
263 
264 template<class ValType1, class ValType2, class ValType3, class ValType4>
267  const ValType2 &v2,
268  const ValType3 &v3,
269  const ValType4 &v4)
270 {
271  //Create the array
273 
274  //Append ALL properties passed to us
275  row->append(v1);
276  row->append(v2);
277  row->append(v3);
278  row->append(v4);
279 
280  //Return a ptr to the array so the user may add more properties if
281  //necessary
282  return row;
283 }
284 
285 #endif
ut_PropertyRow * addProperties()
Create a new empty row.
GLuint GLsizei const GLchar * label
Definition: glcorearb.h:2544
GLsizei const GLchar *const * path
Definition: glcorearb.h:3340
#define UT_API
Definition: UT_API.h:13
GLfloat GLfloat GLfloat v2
Definition: glcorearb.h:817
GLfloat GLfloat GLfloat GLfloat v3
Definition: glcorearb.h:818
GLint GLsizei width
Definition: glcorearb.h:102
#define SYS_PRINTF_CHECK_ATTRIBUTE(string_index, first_to_check)
Definition: SYS_Types.h:426
#define TREE_TOP_DEFAULT_NAME
Definition: UT_InfoTree.h:39
png_bytepp row
Definition: png.h:1836
GLuint const GLchar * name
Definition: glcorearb.h:785
void append(const UT_StringHolder &property)
double fpreal
Definition: SYS_Types.h:270
size_t format(const char *fmt, const Args &...args)
GLfloat GLfloat v1
Definition: glcorearb.h:816