UT/UT_InfoTree.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:
 *      Sevag Gharibian
 *      Side Effects
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        UT_InfoTree.h
 *
 * COMMENTS:    This class is a tree implemented recursively (i.e. each node in
 *              the tree is itself another tree). Each UT_InfoTree has a name, 
 *              an array of property arrays, and finally an array of children 
 *              which are also UT_InfoTree objects.
 *
 *              Put simply, this is a tree in which each node can have as many 
 *              children as it likes, and at each node we can store data in the 
 *              form of strings (which are stored in arrays/rows, in case we 
 *              want to display each row in a spreadsheet table).               
 *
 *              SEE UT_InfoTree.C doc for how to create an UT_InfoTree.
 *
 *              NOTE: Each direct child must have a unique name amongst the
 *                    other children directly beneath us- see declaration of 
 *                    addChildBranch() for more details.
 *
 */

#ifndef __UT_InfoTree_h__
#define __UT_InfoTree_h__

#include "UT_API.h"
#include <iostream.h>

#include "UT_PtrArray.h"
#include "UT_FloatArray.h"
#include "UT_StringArray.h"

#define  TREE_TOP_DEFAULT_NAME  "Head of Tree"

////////////////////////////////////////////////////////////////////////////////
//
//      NAME: ut_PropertyRow
//
//      Simply a UT_StringArray, except we provide an append method which takes
//      an int as a parameter to make the life of our clients easier
//
////////////////////////////////////////////////////////////////////////////////

class UT_API ut_PropertyRow : public UT_StringArray
{
public:
    ut_PropertyRow();
    ~ut_PropertyRow();

    void append (const char *property);
    void append (int property);
};

////////////////////////////////////////////////////////////////////////////////
//
//      NAME: UT_InfoTree
//
///     This is a tree in which each node can have as many children as it likes,
///     and at each node we can store data in the form of strings (which are 
///     stored in arrays/rows, in case we want to display each row in a 
///     spreadsheet table).             
//
////////////////////////////////////////////////////////////////////////////////

class UT_API UT_InfoTree
{
public:
    /// User should always call this constructor with no parameters specified. 
    /// The parameters are only needed when branches are created internally.
    UT_InfoTree (UT_InfoTree *tree_top = NULL, UT_InfoTree *parent = NULL, 
                 UT_String name = TREE_TOP_DEFAULT_NAME);

    /// Recursively deletes all my data and all children, which in turn delete 
    /// all their data and children, etc...
    ~UT_InfoTree ();

    /// Clears all our row and column information. Doesn't affect child
    /// branches.
    void                                 clearProperties();
    /// Clears all child branches. Doesn't affect our properties.
    void                                 clearChildren();

    /// Create a child or subtree under this tree with the name 'branch_name'
    /// The caller should NOT call delete on the pointer returned when they are 
    /// done with it, since this class' destructor will take care of any
    /// children created in addChildBranch(..).
    ///
    /// IMPORTANT NOTE: It is assumed that all branches on the same level will 
    /// have *unique* names, BUT this is NOT enforced to prevent a performance 
    /// hit since these trees can get rebuilt pretty often to accurately reflect
    /// the data they are containing. BOTTOM LINE: Make sure 'branch_name' is 
    /// unique among 'myChildBranches' (otherwise there'll be trouble when we 
    /// decide to traverse a tree given a path of branches - system won't crash,
    /// but will always choose the first available branch on a level with the 
    /// name it is looking for).
    UT_InfoTree                         *addChildBranch (const char 
                                                         *branch_name);

    /// HOW TO USE: You may add up to 4 properties to a single row at once using
    /// this method. If you still need to add more properties to this SAME 
    /// row/array after that, simply use the returned ut_PropertyRow* to call 
    /// 'append()' on and add more properties. To add properties that are
    /// ints, use the same technique, since there is an 'append()' method in 
    /// ut_PropertyRow that takes an int parameter (or check the overridden 
    /// version of addProperties below). BOTTOM LINE - if you want maximum 
    /// flexibility, call this with no parameters and then append each property 
    /// manually to the returned ut_PropertyRow*. 
    ut_PropertyRow                      *addProperties(const char *a1 = NULL, 
                                                       const char *a2 = NULL,
                                                       const char *a3 = NULL, 
                                                       const char *a4 = NULL);

    /// A convenience method - there is often the need to add a name/value pair
    /// where the value is an int, so here is an overridden version of 
    /// addProperties to make life easier! NOTE: NO default parameters for this
    /// version, parameters specified must be valid.
    ut_PropertyRow                      *addProperties(const char *a1, int v1);
    
    /// Add column headings for this node to be used when the info is displayed
    /// in a table. THE NUMBER OF HEADINGS ADDED HERE WILL DETERMINE THE NUMBER
    /// OF COLUMNS DISPLAYED. Note: This class does NOT ensure that the # of 
    /// column headings matches the width of each property array in 
    /// 'myProperties'. Instead, we only display as many properties per row as
    /// we have number of columns.
    ///
    /// The width parameter must either be specified on all columns or on
    /// none. If set on all columns, it represents the fraction of the total
    /// width that gets allocated to that column (the values get normalized).
    /// If any column has a width specified of <= 0.0, the whole thing
    /// reverts to the default behavior of allocating all columns with
    /// equal width.
    void                                 addColumnHeading(const char *label,
                                                          fpreal width = -1.0);
    void                                 addColumnHeading(int label,
                                                          fpreal width = -1.0);

    /// Copies all the information from some other tree into this tree.
    /// Only the row and column informatino is copied. Child branches are
    /// not copied or referenced.
    void                                 copy(const UT_InfoTree &src);
    /// Merges the row and column information from another tree. This
    /// only works if this tree starts out empty, or the column headings
    /// ofthis tree and the source tree match. If the merge couldn't happen,
    /// this function returns false. Otherwise it returns true.
    bool                                 merge(const UT_InfoTree &src);
    
    /// Get a pointer to my parent
    UT_InfoTree                         *getParentBranch () const;

    /// Get a pointer to the very top node in the tree
    UT_InfoTree                         *getTreeTop () const;

    /// Return this node's name
    const UT_String                      &getName () const;

    /// In case we decide to change the name of this node of the tree
    void                                 setName (const char *new_name);
   
    /// Get a ptr to a specific descendent branch of this tree, given a 
    /// UT_StringArray of branch names. e.g. if you want to traverse down the 
    /// tree through a child branch named "Antigen" and get a pointer to that
    /// branch's child called "Rocks", then your UT_StringArray should simply
    /// have 2 elements, "Antigen" and "Rocks", respectively in that order.
    /// Method returns NULL if no such valid path found.
    ///
    /// NOTE: Again, this assumes all branches at the same level have unique
    /// names, as stated above for 'addChildBranch()'.
    UT_InfoTree*                         getDescendentPtr(UT_StringArray &path);
    
    //Accessors for my child branches and data properties
    const UT_PtrArray<UT_InfoTree *>            *getChildBranches() const;
    const UT_PtrArray<ut_PropertyRow *>         *getProperties() const;
    const ut_PropertyRow                        *getColumnHeadings() const;
    const UT_FloatArray                         *getColumnWidths() const;

    /// Write the tree to 'out' for debugging purposes. The caller should not
    /// specify leading_space, it is for internal use during recursive calls. 
    /// NOTE that this function's output is a bit messy, it is solely intended 
    /// for debugging use to get an idea of what your tree looks like. 
    void                                 dumpToFile(ostream &out, 
                                            UT_String leading_space = "") const;

    const char                          *className() const;

private:
    UT_InfoTree                         *myParent;         //My immediate parent
    UT_InfoTree                         *myTreeTop;        //Head of the entire 
                                                           //tree
    UT_String                            myName;           //Name of this branch
    UT_PtrArray<UT_InfoTree *>           myChildBranches;  //My underlying 
                                                           //branches
    UT_PtrArray<ut_PropertyRow *>        myProperties;     //My properties 
    ut_PropertyRow                       myColumnHeadings; //Labels for column
                                                           //headings when 
                                                           //displaying data
    UT_FloatArray                        myColumnWidths;
};

#endif

---