Index: trunk/SophyaLib/Manual/piapp.tex
===================================================================
--- trunk/SophyaLib/Manual/piapp.tex	(revision 3439)
+++ trunk/SophyaLib/Manual/piapp.tex	(revision 3441)
@@ -132,5 +132,5 @@
 
 We thank also the persons who have helped us by useful suggestions, among others : \\
-S. Bargot, S. Du, S. Plasczczynski, C. Renault and D. Yvon.
+S. Bargot, S. Plasczczynski, C. Renault and D. Yvon.
 
 %%%
@@ -1501,6 +1501,153 @@
 \section{On the fly C++ execution}
 \label{flycplusplus}
-and the option window activated by the menu: 
-{\bf Special/CxxExecOption}.
+Piapp operates on the underlying SOPHYA class library objects.
+Obviously, only a small fraction of functionalities in the libraries 
+are directly available through the commands. On the fly C++ compilation
+and execution in piapp provides an easy access to the whole class library. 
+
+The {\bf NamedObjMgr} class handles most of the communication between different
+component of the application, including user c++ code. 
+The NamedObjMgr class implements a singleton scheme, where all instances of the
+class operate on the same data.
+Most operations, in particular directory and object management are thread-safe.
+The most usefull NamedObjMgr methods in user code are:
+\begin{itemize}
+\item Adding an object using its pointer. The object should be created using new. \\
+{\tt \small bool NamedObjMgr::AddObj(AnyDataObj* obj, string \& nom, bool crd=false) } 
+\item Adding an object using its reference. The Object Adapter is used to Clone
+the object. For classes like TArray or Spherical maps, implementing reference sharing,
+the cloned object shares its data with the original object.
+The Cloned object is then added to the list. \\
+{\tt \small bool NamedObjMgr::AddObj(AnyDataObj\& obj, string \& nom, bool crd=false)}
+\item Object display methods : \\
+{\tt \small NamedObjMgr::DisplayObj(string \& nom, string dopt="")  \\
+NamedObjMgr::DisplayImage(string \& nom, \ldots ) \\
+NamedObjMgr::DisplayNT(string \& nom, \ldots )} \\
+\ldots
+\item Access to other parts of the piapp application : \\
+{\tt \small PIStdImgApp* NamedObjMgr::GetImgApp() \\
+PIACmd* PIStdImgApp::CmdInterpreter() }
+\end{itemize}
+
+\subsection{How does it work ?}
+When one the {\bf CxxExecutorCmd} \myppageref{CxxExecutorCmd} commands
+({\tt c++exec} or {\tt c++execfrf}) is invoked, piapp performs the 
+following operations:
+\begin{itemize}
+\item Create a c++ file, and includes the usual libstc++ and SOPHYA header files
+(file named PIATmp\_xxx/cxx\_spiapp.cc)
+\item The user code is put in a c++ function: \\
+{\small \tt  int usercxx( vector<string> \& args ) }
+\item References to all objects present in the current working NamedObjMgr directory
+(default=/home) are declared and initialized. Objects in the current directory can 
+thus be easily accessed through variables bearing the corresponding object name
+in piapp. 
+\item The c++ source file is compiled and linked with SOPHYA libraries, 
+and any additional library, specified through {\tt c++mylibs} \myppageref{cZZmylibs}).
+The compilation and link steps are carried by the SOPHYA class {\b CxxCompilerLinker}.
+\item The resulting shared object is loaded by piapp and the function
+{\tt usercxx()} is called.
+\end{itemize}
+
+To facilitate communication with piapp/NamedObjMgr, two CPP macros are defined:
+\begin{itemize}
+\item[\rond] {\bf KeepObj(VarName) } where VarName is a user declared 
+c++ variable, corresponding to an object inheriting from AnyDataObj.
+When this macro is called, the corresponding object is cloned by the object
+Adapter and added to the list managed by NamedObjMgr, 
+with VarName as the object name. 
+\item[\rond] {\bf DisplayObj(VarName, graphic\_att) } adds the object and
+request its display.  
+\end{itemize}
+
+\subsection{Examples}
+
+\begin{enumerate}
+\item Computation using TimeStamp object. \\[1mm]
+%%
+$\longrightarrow$ File compdate.cc :
+\begin{verbatim}
+  TimeStamp now;     // Current date
+  TimeStamp y2000(2000,1,1,12,0,0.);  // 1 jan 2000, 12:00 
+  cout << " Y2000=" << y2000 << " --> Now: " << now << endl; 
+  cout << " From Y2000 to Now= " << now.ToDays() - y2000.ToDays() << " days" << endl;
+\end{verbatim}
+$\longrightarrow$ piapp commands : \\
+{\tt piapp> c++execfrf compdate.cc} \\
+$\longrightarrow$ The result : \\
+\begin{verbatim}
+PIABaseExecutor: Call usercxx( ... )                                
+ Y2000= 01/01/2000 12:00:0.0 UT  --> Now:  13/12/2007 14:20:50.0 UT 
+ From Y2000 to Now= 2903.1 days                                 
+\end{verbatim}
+%%%%
+\item Working with objects in piapp: \\[1mm]
+\begin{verbatim}
+#  We create three vectors
+newvec va 256 sin(x/5.)
+newvec vb 256 cos(x/18.)*exp(-x/150.)
+newvec vc 256
+#  We call c++exec to make an operation on these vectors
+c++exec vc=va+3.*vb;
+#  Display the resulting vector
+disp vc
+\end{verbatim}
+%%%
+\item Creating and adding new objects \\[1mm]
+$\longrightarrow$ File myf\_fft.h :
+\begin{verbatim}
+inline double myf(double x)
+{
+return(3*sin(0.2*x)+4*cos(x)+5*sin(4*x+0.25) 
+       +3.5*cos(9*x+0.45) + 0.05*x);
+}
+\end{verbatim}
+$\longrightarrow$ File myf\_fft.h :
+\begin{verbatim}
+TVector<r_8> in(4048);
+TVector<r_8> noise(4048);
+TVector< complex<r_8> > out;
+in = RegularSequence(0., 0.05);
+noise = RandomSequence(RandomSequence::Gaussian, 0., 4.);
+MathArray<r_8> ma;
+ma.ApplyFunctionInPlace(in, myf);
+in += noise;
+FFTPackServer FFTServ;
+cout << " Calling FFT " << endl;
+FFTServ.FFTForward(in, out); 
+DisplayObj(in, "");
+DisplayObj(out, "red");
+\end{verbatim}
+$\longrightarrow$ piapp commands :
+\begin{verbatim}
+# Remove existing in/out objects
+rm in out
+# Divide then graphic window in two regions
+zone 1 2
+#  Compile and execute the c++ code
+c++execfrf fft.icc myf_fft.h
+listobjs
+\end{verbatim}
+\end{enumerate}
+
+\subsection{Include files, libraries \ldots}
+\begin{itemize}
+\item[\rond] The different steps of c++exec or c++execfrf
+can be performed by the following commands: {\tt c++create , c++createfrf, 
+c++compile, c++link, call}. This is useful when the same code
+has to be executed multiple times.
+\item[\rond] An interactive editing / c++ execution window can be 
+displayed through the menu-bar, \menubar{Tools/CxxExecutorWindow} 
+\item[\rond] The {\tt c++import} \myppageref{cZZimport} 
+activate inclusion of header files for additional SOPHYA modules, 
+such as Samba SkyMap SkyT FitsIOServe \ldots.
+\item[\rond] The inclusion of additional header files and libraries 
+can be specified using the {\tt c++include} \myppageref{cZZinclude}
+and  {\tt c++mylibs} \myppageref{cZZmylibs}.
+\item[\rond] A dialog window for changing various c++ compile and link 
+options can be displayed by through the menu-bar 
+\menubar{Special/CxxExecOption} 
+\end{itemize}
+
 
 %%%%%%%%%%%%%%% Section 8 :  command reference
