library: libCore #include "TFolder.h"

# TFolder

class description - source file - inheritance tree (.pdf)

## class TFolder : public TNamed

| Inheritance Chart:
`TObject`
| <- | `TNamed`
| <- | `TFolder` |

        private:

                  TFolder(const TFolder& folder)
             void operator=(const TFolder&)

        public:

                              TFolder()
                              TFolder(const char* name, const char* title)
                      virtual ~TFolder()
                 virtual void Add(TObject* obj)
                     TFolder* AddFolder(const char* name, const char* title, TCollection* collection = 0)
                 virtual void Browse(TBrowser* b)
               static TClass* Class()
                 virtual void Clear(Option_t* option = "")
                 virtual void Copy(TObject&) const
          virtual const char* FindFullPathName(const char* name) const
          virtual const char* FindFullPathName(const TObject* obj) const
             virtual TObject* FindObject(const char* name) const
             virtual TObject* FindObject(const TObject* obj) const
             virtual TObject* FindObjectAny(const char* name) const
                 TCollection* GetListOfFolders() const
              virtual TClass* IsA() const
               virtual Bool_t IsFolder() const
                       Bool_t IsOwner() const
                 virtual void ls(Option_t* option = "*") const
                virtual Int_t Occurence(const TObject* obj) const
                 virtual void RecursiveRemove(TObject* obj)
                 virtual void Remove(TObject* obj)
                 virtual void SaveAs(const char* filename = "")
                 virtual void SetOwner(Bool_t owner = kTRUE)
                 virtual void ShowMembers(TMemberInspector& insp, char* parent)
                 virtual void Streamer(TBuffer& b)
                         void StreamerNVirtual(TBuffer& b)

### Data Members

        protected:

          TCollection* fFolders  pointer to the list of folders
                Bool_t fIsOwner  true if folder own its contained objects

## Class Description

     A TFolder object is a collection of objects and folders.
     Folders have a name and a title and are identified in the folder hierarchy
     by a "Unix-like" naming mechanism. The root of all folders is //root.
     New folders can be dynamically added or removed to/from a folder.
     The folder hierarchy can be visualized via the TBrowser.

     The Root folders hierarchy can be seen as a whiteboard where objects
     are posted. Other classes/tasks can access these objects by specifying
     only a string pathname. This whiteboard facility greatly improves the
     modularity of an application, minimizing the class relationship problem
     that penalizes large applications.

     Pointers are efficient to communicate between classes.
     However, one has interest to minimize direct coupling between classes
     in the form of direct pointers. One better uses the naming and search
     service provided by the Root folders hierarchy. This makes the classes
     loosely coupled and also greatly facilitates I/O operations.
     In a client/server environment, this mechanism facilitates the access
     to any kind of object in //root stores running on different processes.

     A TFolder is created by invoking the TFolder constructor. It is placed
     inside an existing folder via the TFolder::AddFolder method.
     One can search for a folder or an object in a folder using the FindObject
     method. FindObject analyzes the string passed as its argument and searches
     in the hierarchy until it finds an object or folder matching the name.

     When a folder is deleted, its reference from the parent folder and
     possible other folders is deleted.

     If a folder has been declared the owner of its objects/folders via
     TFolder::SetOwner, then the contained objects are deleted when the
     folder is deleted. By default, a folder does not own its contained objects.
     NOTE that folder ownership can be set
       - via TFolder::SetOwner
       - or via TCollection::SetOwner on the collection specified to TFolder::AddFolder

     Standard Root objects are automatically added to the folder hierarchy.
     For example, the following folders exist:
       //root/Files      with the list of currently connected Root files
       //root/Classes    with the list of active classes
       //root/Geometries with active geometries
       //root/Canvases   with the list of active canvases
       //root/Styles     with the list of graphics styles
       //root/Colors     with the list of active colors

     For example, if a file "myFile.root" is added to the list of files, one can
     retrieve a pointer to the corresponding TFile object with a statement like:
       TFile *myFile = (TFile*)gROOT->FindObject("//root/Files/myFile.root");
     The above statement can be abbreviated to:
       TFile *myFile = (TFile*)gROOT->FindObject("/Files/myFile.root");
     or even to:
       TFile *myFile = (TFile*)gROOT->FindObjectAny("myFile.root");
     In this last case, the TROOT::FindObjectAny function will scan the folder hierarchy
     starting at //root and will return the first object named "myFile.root".

     Because a string-based search mechanism is expensive, it is recommended
     to save the pointer to the object as a class member or local variable
     if this pointer is used frequently or inside loops.

/* */

TFolder() : TNamed()

     default constructor used by the Input functions

     This constructor should not be called by a user directly.
     The normal way to create a folder is by calling TFolder::AddFolder

TFolder(const char *name, const char *title) : TNamed(name,title)

     create a normal folder.
     use Add or AddFolder to add objects or folders to this folder

TFolder(const TFolder &folder) : TNamed(folder)

~TFolder()

     folder destructor. Remove all objects from its lists and delete
     all its sub folders

void Add(TObject *obj)

     Add object to this folder. obj must be a TObject or a TFolder

TFolder* AddFolder(const char *name, const char *title, TCollection *collection)

     Create a new folder and add it to the list of folders of this folder
     return a pointer to the created folder
     Note that a folder can be added to several folders

     if (collection is non NULL, the pointer fFolders is set to the existing
     collection, otherwise a default collection (Tlist) is created
     Note that the folder name cannot contain slashes.

void Browse(TBrowser *b)

     Browse this folder

void Clear(Option_t *option)

     Delete all objects from a folder list

const char* FindFullPathName(const char *name) const

     return the full pathname corresponding to subpath name
     The returned path will be re-used by the next call to GetPath().

const char* FindFullPathName(const TObject *) const

     return the full pathname corresponding to subpath name
     The returned path will be re-used by the next call to GetPath().

TObject* FindObject(const TObject *) const

     find object in an folder

TObject* FindObject(const char *name) const

     search object identified by name in the tree of folders inside
     this folder.
     name may be of the forms:
       A, specify a full pathname starting at the top ROOT folder
         //root/xxx/yyy/name

       B, specify a pathname starting with a single slash. //root is assumed
         /xxx/yyy/name

       C, Specify a pathname relative to this folder
         xxx/yyy/name
         name

TObject* FindObjectAny(const char *name) const

     return a pointer to the first object with name starting at this folder

Bool_t IsOwner() const

     folder ownership has been set via
       - TFolder::SetOwner
       - TCollection::SetOwner on the collection specified to TFolder::AddFolder

void ls(Option_t *option) const

     List folder contents
       if option contains "dump",  the Dump function of contained objects is called
       if option contains "print", the Print function of contained objects is called
       By default the ls function of contained objects is called.
      Indentation is used to identify the folder tree

      The <regexp> will be used to match the name of the objects.

Int_t Occurence(const TObject *object) const

     Return occurence number of object in the list of objects of this folder.
     The function returns the number of objects with the same name as object
     found in the list of objects in this folder before object itself.
     If only one object is found, return 0;

void RecursiveRemove(TObject *obj)

     Recursively remove object from a Folder

void Remove(TObject *obj)

     Remove object from this folder. obj must be a TObject or a TFolder

void SaveAs(const char *filename)

     Save all objects in this folder in filename
     Each object in this folder will have a key in the file where the name of
     the key will be the name of the object.

void SetOwner(Bool_t owner)

     Set ownership
     If the folder is declared owner, when the folder is deleted, all
     the objects added via TFolder::Add are deleted via TObject::Delete,
     otherwise TObject::Clear is called.

     NOTE that folder ownership can be set
       - via TFolder::SetOwner
       - or via TCollection::SetOwner on the collection specified to TFolder::AddFolder

### Inline Functions

                    void operator=(const TFolder&)
                    void Copy(TObject&) const
            TCollection* GetListOfFolders() const
                  Bool_t IsFolder() const
                 TClass* Class()
                 TClass* IsA() const
                    void ShowMembers(TMemberInspector& insp, char* parent)
                    void Streamer(TBuffer& b)
                    void StreamerNVirtual(TBuffer& b)

Author: Rene Brun 02/09/2000
Last update: root/base:$Name: $:$Id: TFolder.cxx,v 1.22 2003/02/09 18:35:17 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *