GTreeNodeT.hh

Go to the documentation of this file.

//======================================================================
/*! \file GTreeNodeT.hh
 *
 *  Include file for GTreeNodeT template class.
 */
//======================================================================

#ifndef G_TREE_NODE_T_HH
#define G_TREE_NODE_T_HH

#include "GNamedListT.hh"

template <class T> class GTreeBranchT;
template <class T> class GTreeLeafT;

#include "GItem.hh"
#include "GItemList.hh"

//======================================================================
/*! \class GTreeNodeT
 *
 *  Template abstract base class to define a tree structure of objects.
 *  The tree elements inherit from the GNamed class for objects
 *  identification.
 *
 *  The main elements of a tree structure are:
 *  - the branches (GTreeBranchT), that can contain other (sub-)branches
 *    and/or leaves;
 *  - the leaves (GTreeLeafT), that is a terminal node, with a pointer
 *    to an object of class \b T.
 *
 *  The template class provide functions to dupplicate the tree structure,
 *  with GItem object pointing to the original tree class \b T objects.
 *
 *  \b Warning: \n
 *    - Do not use "/" (slash) character in names of objects from
 *      tree structure, unless explicitely specifying sub-tree
 *      branches.
 *
 *  See \ref gcpp_templates for more information about the template classes.
 *
 *  \image html GTreeT.png
 */
template <class T> class GTreeNodeT : public GNamed
{
  //------------------------------------------------------------
  /*! \object_doc */
  GObjectV(GTreeNodeT<T>)
  //------------------------------------------------------------

  protected:
    GTreeBranchT<T>               * parent;       ///< Parent element of the tree
    GListIterT < GTreeNodeT <T> > * list_iter;    ///< Pointer to the iterator in parent list

    void                          * user_data;    ///< Pointer to a additional user data

  public:

  //------------------------------------------------------------
  /** @name Constructors, affectation, destructor */
  //@{
    GTreeNodeT ( );
    GTreeNodeT ( const GTreeNodeT<T> & original );
    virtual ~GTreeNodeT ( );
  //@}

  //------------------------------------------------------------
  /** @name Tree structure functions */
  //@{
    virtual void  SetParent   ( GTreeBranchT<T> * parent_ptr );           // inline
    virtual void  SetListIter ( GListIterT<GTreeNodeT <T> > * iter_ptr ); // inline

    virtual const GTreeBranchT<T> * GetParent ( ) const;   // inline
    virtual       GTreeBranchT<T> * GetParent ( );         // inline
    virtual const GTreeNodeT<T>   * GetRoot   ( ) const;   // inline
    virtual       GTreeNodeT<T>   * GetRoot   ( );         // inline

    virtual bool  IsBranch ( ) const;     //inline
    virtual bool  IsLeaf   ( ) const;     //inline

    void          SetUserData ( void * data );    // inline
    void *        GetUserData ( ) const;          // inline

    virtual GListIterT < GTreeNodeT <T> > GetListIter ( ) const; // inline

  //@}

  //------------------------------------------------------------
  /** @name Tree structure exploration */
  //@{
    virtual   GTreeNodeT<T> * NextNode  ( );

    virtual   GTreeLeafT<T> * FirstLeaf ( );
    virtual   GTreeLeafT<T> * NextLeaf  ( );

    virtual   GTreeNodeT<T>   * FindNode    ( const string & name );
    virtual   GTreeBranchT<T> * FindBranch  ( const string & name );
  //@}


  //------------------------------------------------------------
  /** @name Tree construction functions */
  //@{
    virtual GTreeBranchT<T> * AddBranch ( const string & bname ); // inline
    virtual GTreeBranchT<T> * AddBranch ( const string & parent, const string & bname );

    virtual GTreeLeafT<T>   * AddLeaf   ( T & object_ref );       // inline
    virtual GTreeLeafT<T>   * AddLeaf   ( const string & parent, T & object_ref );

    virtual GTreeLeafT<T>   * AddLeaf   ( T * object_ptr );       // inline
    virtual GTreeLeafT<T>   * AddLeaf   ( const string & parent, T * object_ptr );
  //@}

  //------------------------------------------------------------
  /** @name Element information */
  //@{
    u_int           GetLevel    ( ) const;
    virtual string  GetFullName ( ) const;

    /*! Function returning the number of leaves.*/
    virtual u_int   GetLeafCount      ( ) const = 0;

    /*! Function returning the total number of leaves, recursively in the
     *  tree structure.*/
    virtual u_int   GetLeafTotalCount ( ) const = 0;

  //@}

  //------------------------------------------------------------
  /** @name Creation of objects structures from the tree */
  //@{
    virtual GNamedListT<T>    * CreateList ( );

    virtual GTreeNodeT<GItem> * CreateItemTree ( ) const = 0;
    virtual GItemList         * CreateItemList ( );
  //@}

  //------------------------------------------------------------
  /** @name Print out */
  //@{
    /*! Print the list: elements are given by their name or associated information.
     *  \param  fp      file pointer
     *  \param  prefix  text written before each line
     *  \param  info    if true, the information is printed instead of the name
     */
    virtual void  Print ( FILE * fp = stdout, const string & prefix = "", bool info = false ) const = 0;
  //@}
};

//----------------------------------------------------------------------
// Inline functions
#include "icc/GTreeNodeT.icc"

//======================================================================
#endif