User's Guide

May 2018

Preface

In late 1994, we decided to learn and investigate Object Oriented programming and C++ to better judge the suitability of these relatively new techniques for scientific programming. We knew that there is no better way to learn a new programming environment than to use it to write a program that can solve a real problem. After a few weeks, we had our first histogramming package in C++. A few weeks later we had a rewrite of the same package using the, at that time, very new template features of C++. Again, a few weeks later we had another rewrite of the package without templates since we could only compile the version with templates on one single platform using a specific compiler. Finally, after about four months we had a histogramming package that was faster and more efficient than the well-known FORTRAN based HBOOK histogramming package. This gave us enough confidence in the new technologies to decide to continue the development. Thus was born ROOT. Since its first public release at the end of 1995, ROOT has enjoyed an ever-increasing popularity. Currently it is being used in all major High Energy and Nuclear Physics laboratories around the world to monitor, to store and to analyse data. In the other sciences as well as the medical and financial industries, many people are using ROOT. We estimate the current user base to be around several thousand people. In 1997, Eric Raymond analysed in his paper 「The Cathedral and the Bazaar」 the development method that makes Linux such a success. The essence of that method is: 「release early, release often and listen to your customers」. This is precisely how ROOT is being developed. Over the last five years, many of our 「customers」 became co-developers. Here we would like to thank our main co-developers and contributors:

Masaharu Goto wrote the C++ interpreter CINT that was an essential part of ROOT before ROOT 6. Despite being 8 time zones ahead of us, we have the feeling he has been sitting in the room next door since 1995.

Andrei and Mihaela Gheata (Alice collaboration) are co-authors of the ROOT geometry classes and Virtual Monte-Carlo. They have been working with the ROOT team since 2000.

Olivier Couet, who after a successful development and maintenance of PAW, has joined the ROOT team in 2000 and has been working on the graphics sub-system.

Ilka Antcheva has been working on the Graphical User Interface classes. She is also responsible for this latest edition of the Users Guide with a better style, improved index and several new chapters (since 2002).

Bertrand Bellenot has been developing and maintaining the Win32GDK version of ROOT. Bertrand has also many other contributions like the nice RootShower example (since 2001).

Valeriy Onoutchin has been working on several ROOT packages, in particular the graphics sub-system for Windows and the GUI Builder (since 2000).

Gerri Ganis has been working on the authentication procedures to be used by the root daemons and the PROOF system (since 2002).

Maarten Ballintijn (MIT) is one of the main developers of the PROOF sub-system (since 1995).

Valeri Fine (now at BNL) ported ROOT to Windows and contributed largely to the 3-D graphics. He is currently working on the Qt layer of ROOT (since 1995).

Victor Perevoztchikov (BNL) worked on key elements of the I/O system, in particular the improved support for STL collections (1997-2001).

Nenad Buncic developed the HTML documentation generation system and integrated the X3D viewer inside ROOT (1995-1997).

Suzanne Panacek was the author of the first version of this User's Guide and very active in preparing tutorials and giving lectures about ROOT (1999-2002).

Axel Naumann has been developing further the HTML Reference Guide and helps in porting ROOT under Windows (cygwin/gcc implementation) (since 2000).

Anna Kreshuk has developed the Linear Fitter and Robust Fitter classes as well as many functions in TMath, TF1, TGraph (since 2005).

Richard Maunder has contributed to the GL viewer classes (since 2004).

Timur Pocheptsov has contributed to the GL viewer classes and GL in pad classes (since 2004).

Sergei Linev has developed the XML driver and the TSQLFile classes (since 2003).

Stefan Roiser has been contributing to the reflex and cintex packages (since 2005).

Lorenzo Moneta has been contributing the MathCore, MathMore, Smatrix & Minuit2 packages (since 2005).

Wim Lavrijsen is the author of the PyRoot package (since 2004).

Further we would like to thank all the people mentioned in the $ROOTSYS/README/CREDITS file for their contributions, and finally, everybody who gave comments, reported bugs and provided fixes.

Happy ROOTing!

Rene Brun & Fons Rademakers

Geneva, July 2007

1 Introduction

In the mid 1990』s, René Brun and Fons Rademakers had many years of experience developing interactive tools and simulation packages. They had lead successful projects such as PAW, PIAF, and GEANT, and they knew PAW the twenty-year-old FORTRAN libraries had reached their limits. Although still very popular, these tools could not scale up to the challenges offered by the Large Hadron Collider, where the data is a few orders of magnitude larger than anything seen before.

At the same time, computer science had made leaps of progress especially in the area of Object Oriented Design, and René and Fons were ready to take advantage of it.

ROOT was developed in the context of the NA49 experiment at CERN. NA49 has generated an impressive amount of data, around 10 Terabytes per run. This rate provided the ideal environment to develop and test the next generation data analysis.

ROOT was, and still is, developed in the 「Bazaar style」, a term from the book 「The Cathedral and the Bazaar」 by Eric S. Raymond. It means a liberal, informal development style that heavily relies on the diverse and deep talent of the user community. The result is that physicists developed ROOT for themselves; this made it specific, appropriate, useful, and over time refined and very powerful. The development of ROOT is a continuous conversation between users and developers with the line between the two blurring at times and the users becoming co-developers.

When it comes to storing and mining large amount of data, physics plows the way with its Terabytes, but other fields and industry follow close behind as they acquiring more and more data over time. They are ready to use the true and tested technologies physics has invented. In this way, other fields and industries have found ROOT useful and they have started to use it also.

In the bazaar view, software is released early and frequently to expose it to thousands of eager co-developers to pound on, report bugs, and contribute possible fixes. More users find more bugs, because they stress the program in different ways. By now, after ten years, the age of ROOT is quite mature. Most likely, you will find the features you are looking for, and if you have found a hole, you are encouraged to participate in the dialog and post your suggestion or even implementation on the ROOT forum.

1.1 The ROOT forum

If you have a question, it is likely that it has been asked, answered, and stored in the ROOT Forum. Please use the search engine to see if your question has already been answered before posting a topic in the Forum.

You can access the ROOT forum at: https://root-forum.cern.ch.

1.2 Contact Information

Several authors wrote this book and you may see a 「change of voice」 from one chapter to the next. We felt we could accept this in order to have the expert explain what they know best. If you would like to contribute a chapter or add to a section, please contact rootdoc@cern.ch. We count on you to send us suggestions on additional topics or on the topics that need more documentation. Please send your comments, corrections, questions, and suggestions to the rootdoc list: rootdoc@cern.ch

We attempt to give the user insight into the many capabilities of ROOT. The book begins with the elementary functionality and progresses in complexity reaching the specialized topics at the end. The experienced user looking for special topics may find these chapters useful: see 「Networking」, 「Writing a Graphical User Interface」, 「Threads」, and 「PROOF: Parallel Processing」.

1.3 Conventions Used in This Book

We tried to follow a style convention for the sake of clarity. The styles in used are described below.

To show source code in scripts or source files:

{
   cout << " Hello" << endl;
   float x = 3.;
   float y = 5.;
   int   i = 101;
   cout <<" x = "<<x<<" y = "<<y<<" i = "<<i<< endl;
}

To show the ROOT command line, we show the ROOT prompt without numbers. In the interactive system, the ROOT prompt has a line number (root[12]); for the sake of simplicity, the line numbers are left off.

root[] TLine l
root[] l.Print()
TLine  X1=0.000000 Y1=0.000000 X2=0.000000 Y2=0.000000

Italic bold monotype font indicates a global variable, for example gDirectory.

When a variable term is used, it is shown between angled brackets. In the example below the variable term <library> can be replaced with any library in the $ROOTSYS directory: $ROOTSYS/<library>/inc.

1.4 The Framework

ROOT is an object-oriented framework aimed at solving the data analysis challenges of high-energy physics. There are two key words in this definition, object oriented and framework. First, we explain what we mean by a framework and then why it is an object-oriented framework.

1.4.1 What Is a Framework?

Programming inside a framework is a little like living in a city. Plumbing, electricity, telephone, and transportation are services provided by the city. In your house, you have interfaces to the services such as light switches, electrical outlets, and telephones. The details, for example, the routing algorithm of the phone switching system, are transparent to you as the user. You do not care; you are only interested in using the phone to communicate with your collaborators to solve your domain specific problems.

Programming outside of a framework may be compared to living in the country. In order to have transportation and water, you will have to build a road and dig a well. To have services like telephone and electricity you will need to route the wires to your home. In addition, you cannot build some things yourself. For example, you cannot build a commercial airport on your patch of land. From a global perspective, it would make no sense for everyone to build their own airport. You see you will be very busy building the infrastructure (or framework) before you can use the phone to communicate with your collaborators and have a drink of water at the same time. In software engineering, it is much the same way. In a framework, the basic utilities and services, such as I/O and graphics, are provided. In addition, ROOT being a HEP analysis framework, it provides a large selection of HEP specific utilities such as histograms and fitting. The drawback of a framework is that you are constrained to it, as you are constraint to use the routing algorithm provided by your telephone service. You also have to learn the framework interfaces, which in this analogy is the same as learning how to use a telephone.

If you are interested in doing physics, a good HEP framework will save you much work. Next is a list of the more commonly used components of ROOT: Command Line Interpreter, Histograms and Fitting, Writing a Graphical User Interface, 2D Graphics, Input/Output , Collection Classes, Script Processor.

There are also less commonly used components, as: 3D Graphics, Parallel Processing (PROOF), Run Time Type Identification (RTTI), Socket and Network Communication, Threads.

1.4.1.1 Advantages of Frameworks

The benefits of frameworks can be summarized as follows:

1.4.2 Why Object-Oriented?

Object-Oriented Programming offers considerable benefits compared to Procedure-Oriented Programming:

1.5 Installing ROOT

To install ROOT you will need to go to the ROOT website at: http://root.cern.ch/root/Availability.html. You have a choice to download the binaries or the source. The source is quicker to transfer since it is only ~22 MB, but you will need to compile and link it. The binaries compiled with no debug information range from ~35 MB to ~45 MB depending on the target platform.

The installation and building of ROOT is described in Appendix A: Install and Build ROOT. You can download the binaries, or the source. The GNU g++ compiler on most UNIX platforms can compile ROOT.

Before downloading a binary version make sure your machine contains the right run-time environment. In most cases it is not possible to run a version compiled with, e.g., gcc4.0 on a platform where only gcc 3.2 is installed. In such cases you'll have to install ROOT from source.

ROOT is currently running on the following platforms: supported platforms

1.6 The Organization of the ROOT Framework

Now after we know in abstract terms what the ROOT framework is, let us look at the physical directories and files that come with the ROOT installation. You may work on a platform where your system administrator has already installed ROOT. You will need to follow the specific development environment for your setup and you may not have write access to the directories. In any case, you will need an environment variable called ROOTSYS, which holds the path of the top ROOT directory.

> echo $ROOTSYS
/opt/root

In the ROOTSYS directory are examples, executables, tutorials, header tutorials files, and, if you opted to download it, the source is here. The directories of special interest to us are bin, tutorials, lib, test, andinclude. The next figure shows the contents of these directories.

ROOT framework directories
ROOT framework directories

1.6.1 $ROOTSYS/bin

The bin directory contains several executables.

root shows the ROOT splash screen and calls root.exe
root.exe the executable that root calls, if you use a debugger such as gdb, you will need to run root.exe directly
rootcling is the utility ROOT uses to create a class dictionary for Cling
rmkdepend a modified version of makedepend that is used by the ROOT build system
root-config a script returning the needed compile flags and libraries for projects that compile and link with ROOT
proofd a small daemon used to authenticate a user of ROOT parallel processing capability (PROOF)
proofserv the actual PROOF process, which is started by proofd after a user, has successfully been authenticated
rootd is the daemon for remote ROOT file access (see the TNetFile)

1.6.2 $ROOTSYS/lib

There are several ways to use ROOT, one way is to run the executable by typing root at the system prompt another way is to link with the ROOT libraries and make the ROOT classes available in your own program.

Here is a short description of the most relevant libraries, the ones marked with a * are only installed when the options specified them.

1.6.2.1 Library Dependencies

ROOT libraries dependencies
ROOT libraries dependencies

The libraries are designed and organized to minimize dependencies, such that you can load just enough code for the task at hand rather than having to load all libraries or one monolithic chunk. The core library (libCore.so) contains the essentials; it is a part of all ROOT applications. In the Figure 1-2 you see that libCore.so is made up of base classes, container classes, meta information classes, operating system specific classes, and the ZIP algorithm used for compression of the ROOT files.

The Cling library (libCling.so) is also needed in all ROOT applications, and even by libCore. A program referencing only TObject only needs libCore; libCling will be opened automatically. To add the ability to read and write ROOT objects one also has to load libRIO. As one would expect, none of that depends on graphics or the GUI.

Library dependencies have different consequences; depending on whether you try to build a binary, or you just try to access a class that is defined in a library.

1.6.2.2 Linktime Library Dependencies

When building your own executable you will have to link against the libraries that contain the classes you use. The ROOT reference guide states the library a class is reference guide defined in. Almost all relevant classes can be found in libraries returned by root-config -glibs; the graphics libraries are retuned by root-config --libs. These commands are commonly used in Makefiles. Using root-config instead of enumerating the libraries by hand allows you to link them in a platform independent way. Also, if ROOT library names change you will not need to change your Makefile.

A batch program that does not have a graphic display, which creates, fills, and saves histograms and trees, only needs to link the core libraries (libCore, libRIO), libHist and libTree. If ROOT needs access to other libraries, it loads them dynamically. For example, if the TreeViewer is used, libTreePlayer and all libraries libTreePlayer depends on are loaded also. The dependent libraries are shown in the ROOT reference guide's library dependency graph. The difference between reference guide libHist and libHistPainter is that the former needs to be explicitly linked and the latter will be loaded automatically at runtime when ROOT needs it, by means of the Plugin Manager. plugin manager

In the Figure 1-2, the libraries represented by green boxes outside of the core are loaded via the plugin manager plugin manager or equivalent techniques, while the white ones are not. Of course, if one wants to access a plugin library directly, it has to be explicitly linked. An example of a plugin library is libMinuit. To create and fill histograms you need to link libHist.so. If the code has a call to fit the histogram, the 「fitter」 will dynamically load libMinuit if it is not yet loaded.

1.6.2.3 Plugins: Runtime Library Dependencies for Linking

plugin manager The Plugin Manager TPluginManager allows postponing library dependencies to runtime: a plugin library will only be loaded when it is needed. Non-plugins will need to be linked, and are thus loaded at start-up. Plugins are defined by a base class (e.g. TFile) that will be implemented in a plugin, a tag used to identify the plugin (e.g. ^rfio: as part of the protocol string), the plugin class of which an object will be created (e.g. TRFIOFile), the library to be loaded (in short libRFIO.so to RFIO), and the constructor to be called (e.g. 「TRFIOFile()」). This can be specified in the .rootrc which already contains many plugin definitions, or by calls to gROOT->GetPluginManager()->AddHandler().

1.6.2.4 Library AutoLoading

When using a class in Cling, e.g. in an interpreted source file, ROOT will automatically load the library that defines this class. On start-up, ROOT parses all files ending on .rootmap rootmap that are in one of the $LD_LIBRARY_PATH (or $DYLD_LIBRARY_PATH for MacOS, or $PATH for Windows). They contain class names and the library names that the class depends on. After reading them, ROOT knows which classes are available, and which libraries to load for them.

When TSystem::Load("ALib") is called, ROOT uses this information to determine which libraries libALib.so depends on. It will load these libraries first. Otherwise, loading the requested library could cause a system (dynamic loader) error due to unresolved symbols.

1.6.3 $ROOTSYS/tutorials

tutorials The tutorials directory contains many example example scripts. They assume some basic knowledge of ROOT, and for the new user we recommend reading the chapters: 「Histograms」 and 「Input/Output」 before trying the examples. The more experienced user can jump to chapter 「The Tutorials and Tests」 to find more explicit and specific information about how to build and run the examples.

The $ROOTSYS/tutorials/ directory include the following sub-directories:

fft: Fast Fourier Transform with the fftw package fit: Several examples illustrating minimization/fitting foam: Random generator in multidimensional space geom: Examples of use of the geometry package (TGeo classes) gl: Visualisation with OpenGL graphics: Basic graphics graphs: Use of TGraph, TGraphErrors, etc. gui: Scripts to create Graphical User Interface hist: Histogramming image: Image Processing io: Input/Output math: Maths and Statistics functions matrix: Matrices (TMatrix) examples mlp: Neural networks with TMultiLayerPerceptron net: Network classes (client/server examples) physics: LorentzVectors, phase space pyroot: Python tutorials pythia: Example with pythia6 quadp: Quadratic Programming smatrix: Matrices with a templated package spectrum: Peak finder, background, deconvolutions splot: Example of the TSplot class (signal/background estimator) sql: Interfaces to SQL (mysql, oracle, etc) thread: Using Threads tmva: Examples of the MultiVariate Analysis classes tree: Creating Trees, Playing with Trees unuran: Interface with the unuram random generator library xml: Writing/Reading xml files

You can execute the scripts in $ROOTSYS/tutorials (or sub-directories) by setting your current directory in the script directory or from any user directory with write access. Several tutorials create new files. If you have write access to the tutorials directory, the new files will be created in the tutorials directory, otherwise they will be created in the user directory.

1.6.4 $ROOTSYS/test

The test directory contains a set of examples example that represent all areas of the framework. When a new release is cut, the examples in this directory are compiled and run to test the new release's backward compatibility. The list of source files is described in chapter 「The Tutorials and Tests」.

The $ROOTSYS/test directory is a gold mine of ROOT-wisdom nuggets, and we encourage you to explore and exploit it. We recommend the new users to read the chapter 「Getting Started」. The chapter 「The Tutorials and Tests」 has instructions on how to build all the programs and it goes over the examples Event and stress.

1.6.5 $ROOTSYS/include

The include directory contains all header files. It is especially important because the header files contain the class definitions.

1.6.6 $ROOTSYS/<library>

The directories we explored above are available when downloading the binaries. When downloading the source you also get a directory for each library with the corresponding header and source files, located in the inc and src subdirectories. To see what classes are in a library, you can check the <library>/inc directory for the list of class definitions. For example, the physics library libPhysics.so contains these class definitions:

> ls -m $ROOTSYS/math/physics/inc/
LinkDef.h, TFeldmanCousins.h, TGenPhaseSpace.h, TLorentzRotation.h,
TLorentzVector.h, TQuaternion.h, TRobustEstimator.h, TRolke.h,
TRotation.h, TVector2.h, TVector3.h

1.7 How to Find More Information

website The ROOT web site has up to date documentation. The ROOT source code automatically generates this documentation, so each class is explicitly documented on its own web page, which is always up to date with the latest official release of ROOT.

The ROOT Reference Guide web pages can be found at class index reference guide http://root.cern.ch/root/html/ClassIndex.html. Each page contains a class description, and an explanation of each method. It shows the class inheritance tree and lets you jump to the parent class page by clicking on the class name. If you want more details, you can even see the source. There is a help page available in the little box on the upper right hand side of each class documentation page. You can see on the next page what a typical class documentation web page looks like. The ROOT web site also contains in addition to this Reference Guide, 「How To's」, a list of publications and example applications.

1.7.1 Class Reference Guide

The top of any class reference page lets you jump to different parts of the documentation. The first line links to the class index and the index for the current module (a group of classes, often a library). The second line links to the ROOT homepage and the class overviews. The third line links the source information - a HTML version of the source and header file as well as the CVS (the source management system used for the ROOT development) information of the files. The last line links the different parts of the current pages.

Example of function documentation, with automatically generated LaTeX-like graphics
Example of function documentation, with automatically generated LaTeX-like graphics
Inheritance tree, showing what the current class derives from, and which classes inherit from it
Inheritance tree, showing what the current class derives from, and which classes inherit from it
HTML version of the source file linking all types and most functions
HTML version of the source file linking all types and most functions

2 Getting Started

We begin by showing you how to use ROOT interactively. There are two examples to click through and learn how to use the GUI. We continue by using the command line, and explaining the coding conventions, global variables and the environment setup. If you have not installed ROOT, you can do so by following the instructions in the appendix, or on the ROOT web site: http://root.cern.ch/root/Availability.html

2.1 Setting the Environment Variables

Before you can run ROOT you need to set the environment variable ROOTSYS and change your path to include root/bin and library path variables to include root/lib. Please note: the syntax is for bash, if you are running tcsh you will have to use setenv instead of export.

  1. Define the variable $ROOTSYS to the directory where you unpacked the ROOT:
$ export ROOTSYS=$HOME/root
  1. Add ROOTSYS/bin to your PATH:
$ export PATH=$PATH:$ROOTSYS/bin
  1. Setting the Library Path

On HP-UX, before executing the interactive module, you must set the library path:

$ export SHLIB_PATH=$SHLIB_PATH:$ROOTSYS/lib

On AIX, before executing the interactive module, you must set the library path:

$ [ -z "$LIBPATH" ] && export LIBPATH=/lib:/usr/lib
$ export LIBPATH=$LIBPATH:$ROOTSYS/lib

On Linux, Solaris, Alpha OSF and SGI, before executing the interactive module, you must set the library path:

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ROOTSYS/lib

On Solaris, in case your LD_LIBRARY_PATH is empty, you should set it:

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ROOTSYS/lib:/usr/dt/lib

If you use the afs version you should set (vers = version number, arch = architecture):

$ export ROOTSYS=/afs/cern.ch/sw/lcg/external/root/vers/arch/root

If ROOT was installed in $HOME/myroot directory on a local machine, one can do:

cd $HOME/myroot
. bin/thisroot.sh       // or source bin/thisroot.sh

The new $ROOTSYS/bin/thisroot.[c]sh scripts will set correctly the ROOTSYS, LD_LIBRARY_PATH or other paths depending on the platform and the MANPATH. To run the program just type: root.

2.2 Start and Quit a ROOT Session

$ root
   -------------------------------------------------------------------------
  | Welcome to ROOT 6.10/01                             http://root.cern.ch |
  |                                            (c) 1995-2017, The ROOT Team |
  | Built for macosx64                                                      |
  | From heads/v6-10-00-patches@v6-10-00-25-g9f78c3a, Jul 03 2017, 11:39:44 |
  | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q'              |
   -------------------------------------------------------------------------

root [0]

To start ROOT you can type root at the system prompt. This starts up Cling, the ROOT command line C/C++ interpreter, and it gives you the ROOT prompt (root[0]).

It is possible to launch ROOT with some command line options, as shown below:

%  root -?
Usage: root [-l] [-b] [-n] [-q] [dir] [[file:]data.root]
                                                [file1.C ... fileN.C]
Options:
  -b : run in batch mode without graphics
  -n : do not execute logon and logoff macros as specified in .rootrc
  -q : exit after processing command line macro files
  -l : do not show splash screen
  -x : exit on exception
 dir : if dir is a valid directory cd to it before executing

  -?       : print usage
  -h       : print usage
  --help   : print usage
  -config  : print ./configure options
  -memstat : run with memory usage monitoring

For example if you would like to run a script myMacro.C in the background, redirect the output into a file myMacro.log, and exit after the script execution, use the following syntax:

root -b -q myMacro.C > myMacro.log

If you need to pass a parameter to the script use:

root -b -q 'myMacro.C(3)' > myMacro.log

Be mindful of the quotes, i.e. if you need to pass a string as a parameter, the syntax is:

root -b -q 'myMacro.C("text")' > myMacro.log

You can build a shared library with ACLiC and then use this shared library on the command line for a quicker execution (i.e. the compiled speed rather than the interpreted speed). See also 「Cling the C++ Interpreter」.

root -b -q myMacro.so > myMacro.log

ROOT has a powerful C/C++ interpreter giving you access to all available ROOT classes, global variables, and functions via the command line. By typing C++ statements at the prompt, you can create objects, call functions, execute scripts, etc. For example:

root[] 1+sqrt(9)
(const double)4.00000000000000000e+00
root[] for (int i = 0; i<4; i++) cout << "Hello" << i << endl
Hello 0
Hello 1
Hello 2
Hello 3
root[] .q

To exit the ROOT session, type .q.

root[] .q

2.3 Using the GUI

The basic whiteboard on which an object is drawn in ROOT is called a canvas (defined by the class TCanvas). Every object in the canvas is a graphical object in the sense that you can grab it, resize it, and change some characteristics using the mouse. The canvas area can be divided in several sub areas, so-called pads (the class TPad). A pad is a canvas sub area that can contain other pads or graphical objects. At any one time, just one pad is the so-called active pad. Any object at the moment of drawing will be drawn in the active pad. The obvious question is: what is the relation between a canvas and a pad? In fact, a canvas is a pad that spans through an entire window. This is nothing else than the notion of inheritance. The TPad class is the parent of the TCanvas class. In ROOT, most objects derive from a base class TObject. This class has a virtual method Draw() such as all objects are supposed to be able to be 「drawn」. If several canvases are defined, there is only one active at a time. One draws an object in the active canvas by using the statement:

object.Draw()

This instructs the object 「object」 to draw itself. If no canvas is opened, a default one (named 「c1」) is created. In the next example, the first statement defines a function and the second one draws it. A default canvas is created since there was no opened one. You should see the picture as shown in the next figure.

root[] TF1 f1("func1","sin(x)/x",0,10)
root[] f1.Draw()
<TCanvas::MakeDefCanvas>: created default TCanvas with name c1
A canvas with drawing
A canvas with drawing

The following components comprise the canvas window:

At the top of the canvas window are File, Edit, View, Options, Inspect, Classes and Help menus.

2.3.1.1 File Menu

2.3.1.2 Edit Menu

There is only one active menu entry in the Edit menu. The others menu entries will be implemented and will become active in the near future.

2.3.1.3 View Menu

2.3.1.4 Options Menu

2.3.1.5 Inspect Menu

2.3.1.6 Help Menu

2.3.1.7 Classes Menu

2.3.1.8 Toolbar

The following menu shortcuts and utilities are available from the toolbar:

Create a new canvas window.

Popup the Open File dialog.

Popup the Save As… dialog.

Popup the Print dialog.

Interrupts the current drawing process.

Redraw the canvas.

Inspect the gROOT object.

Create a new objects' browser.

You can create the following graphical objects using the toolbar buttons for primitive drawing. Tool tips are provided for helping your choice.

An Arc or circle: Click on the center of the arc, and then move the mouse. A rubber band circle is shown. Click again with the left button to freeze the arc.

A Line: Click with the left button at the point where you want to start the line, then move the mouse and click again with the left button to freeze the line.

An Arrow:Click with the left button at the point where you want to start the arrow, then move the mouse and click again with the left button to freeze the arrow.

A Diamond: Click with the left button and freeze again with the left button. The editor draws a rubber band box to suggest the outline of the diamond.

An Ellipse: Proceed like for an arc. You can grow/shrink the ellipse by pointing to the sensitive points. They are highlighted. You can move the ellipse by clicking on the ellipse, but not on the sensitive points. If, with the ellipse context menu, you have selected a fill area color, you can move a filled-ellipse by pointing inside the ellipse and dragging it to its new position.

A Pad: Click with the left button and freeze again with the left button. The editor draws a rubber band box to suggest the outline of the pad.

A PaveLabel: Proceed like for a pad. Type the text of label and finish with a carriage return. The text will appear in the box.

A Pave Text: Proceed like for a pad. You can then click on the TPaveText object with the right mouse button and select the option InsertText.

Paves Text: Proceed like for a TPaveText.

A Poly Line: Click with the left button for the first point, move the moose, click again with the left button for a new point. Close the poly-line with a double click. To edit one vertex point, pick it with the left button and drag to the new point position.

A Curly Line: Proceed as for the arrow or line. Once done, click with the third button to change the characteristics of the curly line, like transform it to wave, change the wavelength, etc.

A Curly Arc: Proceed like for an ellipse. The first click is located at the position of the center, the second click at the position of the arc beginning. Once done, one obtains a curly ellipse, for which one can click with the third button to change the characteristics, like transform it to wavy, change the wavelength, set the minimum and maximum angle to make an arc that is not closed, etc.

A Text/Latex string: Click with the left button where you want to draw the text and then type in the text terminated by carriage return. All TLatex expressions are valid. To move the text or formula, point on it keeping the left mouse button pressed and drag the text to its new position. You can grow/shrink the text if you position the mouse to the first top-third part of the string, then move the mouse up or down to grow or shrink the text respectively. If you position the mouse near the bottom-end of the text, you can rotate it.

A Marker: Click with the left button where to place the marker. The marker can be modified by using the method SetMarkerStyle() of TSystem.

A Graphical Cut: Click with the left button on each point of a polygon delimiting the selected area. Close the cut by double clicking on the last point. A TCutG object is created. It can be used as a selection for a TTree::Draw. You can get a pointer to this object with:

TCutG cut = (TCutG*)gPad->GetPrimitive("CUTG")

Once you are happy with your picture, you can select the Save as canvas.C item in the canvas File menu. This will automatically generate a script with the C++ statements corresponding to the picture. This facility also works if you have other objects not drawn with the graphics editor (histograms for example).

2.3.2 The Editor Frame

The ROOT graphics editor loads the corresponding object editor objEditor according to the selected object obj in the canvas respecting the class inheritance. An object in the canvas is selected after the left mouse click on it. For example, if the selected object is TAxis, the TAxisEditor will shows up in the editor frame giving the possibility for changing different axis attributes. The graphics editor can be:

Embedded - connected only with the canvas in the application window that appears on the left of the canvas window after been activated via View menu / Editor. It appears on the left side if the canvas window allowing users to edit the attributes of the selected object via provided user interface. The name of the selected object is displayed on the top of the editor frame in red color. If the user interface needs more space then the height of the canvas window, a vertical scroll bar appears for easer navigation.

Global - has own application window and can be connected to any created canvas in a ROOT session. It can be activated via the context menu entries for setting line, fill, text and marker attributes for backward compatibility, but there will be a unique entry in the near future.

The user interface for the following classes is available since ROOT v.4.04: TAttLine, TAttFill, TAttMarker, TAttText, TArrow, TAxis, TCurlyArc, TCurlyLine, TFrame, TH1, TH2, TGraph, TPad, TCanvas, TPaveStats. For more details, see 「The Graphics Editor」, 「The User Interface for Histograms」, 「The User Interface for Graphs」.

2.3.3 Classes, Methods and Constructors

Object oriented programming introduces objects, which have data members and methods. The next line creates an object named f1 of the class TF1 that is a one-dimensional function. The type of an object is called a class. The object itself is called an instance of a class. When a method builds an object, it is called a constructor.

TF1 f1("func1","sin(x)/x",0,10)

In our constructor the function sin(x)/x is defined for use, and 0 and 10 are the limits. The first parameter, func1 is the name of the object f1. Most objects in ROOT have a name. ROOT maintains a list of objects that can be searched to find any object by its given name (in our example func1).

The syntax to call an object's method, or if one prefers, to make an object to do something is:

object.method_name(parameters)

The dot can be replaced by 「->」 if object is a pointer. In compiled code, the dot MUST be replaced by a 「->」 if object is a pointer.

object_ptr->method_name(parameters)

So now, we understand the two lines of code that allowed us to draw our function. f1.Draw() stands for 「call the method Draw() associated with the object f1 of the class TF1」. Other methods can be applied to the object f1 of the class TF1. For example, the evaluating and calculating the derivative and the integral are what one would expect from a function.

root[] f1.Eval(3)
(Double_t)4.70400026866224020e-02
root[] f1.Derivative(3)
(Double_t)(-3.45675056671992330e-01)
root[] f1.Integral(0,3)
(Double_t)1.84865252799946810e+00
root[] f1.Draw()

By default the method TF1::Paint(), that draws the function, computes 100 equidistant points to draw it. The number of points can be set to a higher value with:

root[] f1.SetNpx(2000);

Note that while the ROOT framework is an object-oriented framework, this does not prevent the user from calling plain functions.

2.3.4 User Interaction

Now we will look at some interactive capabilities. Try to draw the function sin(x)/x again. Every object in a window (which is called a canvas) is, in fact, a graphical object in the sense that you can grab it, resize it, and change its characteristics with a mouse click. For example, bring the cursor over the x-axis. The cursor changes to a hand with a pointing finger when it is over the axis. Now, left click and drag the mouse along the axis to the right. You have a very simple zoom.

When you move the mouse over any object, you can get access to selected methods by pressing the right mouse button and obtaining a context menu. If you try this on the function TF1, you will get a menu showing available methods. The other objects on this canvas are the title, a TPaveText object; the x and y-axis, TAxis objects, the frame, a TFrame object, and the canvas a TCanvas object. Try clicking on these and observe the context menu with their methods.

A context menu
A context menu

For example try selecting the SetRange() method and putting -10, 10 in the dialog box fields. This is equivalent to executing f1.SetRange(-10,10) from the command line, followed by f1.Draw(). Here are some other options you can try.

Once the picture suits your wishes, you may want to see the code you should put in a script to obtain the same result. To do that, choose Save / canvas.C entry of the File menu. This will generate a script showing the options set in the current canvas. Notice that you can also save the picture into various file formats such as PostScript, GIF, etc. Another interesting possibility is to save your canvas into the native ROOT format (.rootfile). This will enable you to open it again and to change whatever you like. All objects associated to the canvas (histograms, graphs) are saved at the same time.

2.3.5 Building a Multi-pad Canvas

Let us now try to build a canvas with several pads.

root[] TCanvas *MyC = new TCanvas("MyC","Test canvas",1)
root[] MyC->Divide(2,2)

Once again, we call the constructor of a class, this time the class TCanvas. The difference between this and the previous constructor call (TF1) is that here we are creating a pointer to an object. Next, we call the method Divide() of the TCanvas class (that is TCanvas::Divide()), which divides the canvas into four zones and sets up a pad in each of them. We set the first pad as the active one and than draw the functionf1there.

root[] MyC->cd(1)
root[] f1->Draw()

All objects will be drawn in that pad because it is the active one. The ways for changing the active pad are:

root[] MyC->cd(3)

Pads are numbered from left to right and from top to bottom. Each new pad created by TCanvas::Divide() has a name, which is the name of the canvas followed by _1, _2, etc. To apply the method cd() to the third pad, you would write:

root[] MyC_3->cd()

2.3.6 Saving the Canvas