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