+% ==========================================
+\subsubsection{Black box basic implementation file (.cxx)}
+% ==========================================
+
+Now let's have a look at the file \texttt{packages/std/bbstdMakeFileName.cxx}
+
+\begin{file}{\texttt{packages/std/bbstdMakeFileName.cxx}}
+\small
+\begin{verbatim}
+#include "bbstdMakeFileName.h"
+#include "bbstdPackage.h"
+
+namespace bbstd
+{
+
+ BBTK_ADD_BLACK_BOX_TO_PACKAGE(std,MakeFileName);
+ BBTK_BLACK_BOX_IMPLEMENTATION(MakeFileName,bbtk::AtomicBlackBox);
+
+ void MakeFileName::bbUserConstructor()
+ {
+ bbSetInputDirectory("");
+ bbSetInputFile("");
+ bbSetInputExtent("");
+ }
+
+ void MakeFileName::DoProcess()
+ {
+ ...
+ }
+}
+// EO namespace bbstd
+\end{verbatim}
+\end{file}
+
+The first line includes the header file.
+The second one includes the \texttt{std} package header file.
+This file is automatically generated during cmake configuration :
+for a package named \texttt{\textless PACK \textgreater}, \cmake
+creates the files \texttt{bb\textless PACK \textgreater Package.h}
+and \texttt{bb\textless PACK \textgreater Package.cxx}.
+The header is to be included in any box implementation file and
+the second one is compiled in the package library.
+
+The macro \texttt{BBTK\_ADD\_BLACK\_BOX\_TO\_PACKAGE}
+then registers the box \texttt{MakeFileName} into the package \texttt{std}.
+
+The macro \texttt{BBTK\_BLACK\_BOX\_IMPLEMENTATION} is the
+mirror macro of the macro \texttt{BBTK\_BLACK\_BOX\_INTERFACE} that
+was used in the header : it implements the methods declared in the header.
+
+We then need to write the body of \texttt{bbUserConstrutor}
+and of the processing callback (here \texttt{DoProcess}).
+
+That's all we need for a 'basic' black box.
+The implementation related macros are summarized in table \ref{CPPImplementationBasicMacros}.
+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{CPPImplementationBasicMacros}Black box implementation \CPP macros}
+\begin{tabular}{p{\textwidth}}\hline
+ \\ \small \texttt{BBTK\_ADD\_BLACK\_BOX\_TO\_PACKAGE(PACKAGE\_NAME,BOX\_NAME)}
+ \\ \small \texttt{BBTK\_BLACK\_BOX\_IMPLEMENTATION(BOX\_NAME,BBTK\_PARENT)}
+\\ \hline
+\end{tabular}
+\end{table}
+
+% ==========================================
+\subsubsection{Widget black boxes \CPP macros}
+% ==========================================
+
+See the example of \texttt{package/wx/src/bbwxLayoutLine.h\textbar cxx}.
+The only differences with a non-widget black box are :
+\begin{itemize}
+\item The header must include \texttt{bbtkWxBlackBox.h} and \\
+the class must inherit \texttt{bbtk::WxBlackBox}.
+\item The black box interface must declare the widget creation callback
+with the macro \texttt{BBTK\_CREATE\_WIDGET(CALLBACK)}.
+The callback must be declared in the interface and implemented.
+\item You can overload the method \texttt{void bbUserOnShow()} which
+is called just after the \texttt{wxWindow} has been shown, e.g.
+to refresh its content. Note that \texttt{Layout} widget \emph{MUST}
+overload this method and call \texttt{bbUserOnShowWidget(INPUT\_NAME)}
+for all inputs which correspond to an 'embedded' window
+(the 'Widget1' ... 'WidgetN' inputs,
+see \texttt{package/wx/src/bbwxLayoutLine.cxx})
+\end{itemize}
+
+% ==========================================
+\subsubsection{VTK black boxes \CPP macros}
+% ==========================================
+
+See the example of \texttt{package/wx/src/bbvtkMarchingCubes.h\textbar cxx}.
+The macros are summarized in table \ref{CPPInterfaceBasicMacros}.
+
+% ==========================================
+\subsubsection{Template black boxes \CPP macros}
+% ==========================================
+
+You can write down black box classes \emph{templates}.
+However, only \emph{actual} classes, that is instanciated templates,
+can be inserted into a package.
+
+The files \texttt{package/std/src/bbstdStringTo.h\textbar cxx}
+provide an example of a class template with one template parameter.
+
+The files \texttt{package/std/src/bbstdCast.h\textbar cxx}
+provide an example of a class template with two template parameters.
+
+Class templates related macros are summarized in table \ref{CPPTemplateMacros}.
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{CPPTemplateMacros}Black box templates-related \CPP macros}
+\begin{tabular}{p{\textwidth}}\hline
+% \begin{itemize}
+ \\ \small\texttt{BBTK\_TEMPLATE\_BLACK\_BOX\_INTERFACE(BOX\_NAME,BBTK\_PARENT, TEMPLATE\_PARAMETER)}
+ \\ \small\texttt{BBTK\_TEMPLATE2\_BLACK\_BOX\_INTERFACE(BOX\_NAME,BBTK\_PARENT, TEMPLATE\_PARAMETER\_1, TEMPLATE\_PARAMETER\_2)}
+ \\ \small\texttt{BBTK\_BEGIN\_DESCRIBE\_TEMPLATE\_BLACK\_BOX(BOX\_NAME,BBTK\_PARENT)}: Note that in the descriptor, the template parameter name is \texttt{T}
+\\ \small\texttt{BBTK\_BEGIN\_DESCRIBE\_TEMPLATE2\_BLACK\_BOX(BOX\_NAME,BBTK\_PARENT)}: Note that in the descriptor, the template parameters names are \texttt{T1} and \texttt{T2}
+ \\ \small\texttt{BBTK\_END\_DESCRIBE\_TEMPLATE\_BLACK\_BOX(BOX\_NAME)}
+ \\ \small\texttt{BBTK\_END\_DESCRIBE\_TEMPLATE2\_BLACK\_BOX(BOX\_NAME)}
+ \\ \small\texttt{BBTK\_TEMPLATE\_INPUT(BOX\_NAME,INPUT\_NAME,DESCRIPTION,CPP\_TYPE, INPUT\_NATURE)}: Same than for non-templates, except that the \texttt{CPP\_TYPE} can be the template parameter.
+ \\ \small\texttt{BBTK\_TEMPLATE2\_INPUT(BOX\_NAME,INPUT\_NAME,DESCRIPTION,CPP\_TYPE, INPUT\_NATURE)}: Same remark
+ \\\small \texttt{BBTK\_TEMPLATE\_OUTPUT(BOX\_NAME,OUTPUT\_NAME,DESCRIPTION,CPP\_TYPE)}: Same remark
+ \\ \small\texttt{BBTK\_TEMPLATE2\_OUTPUT(BOX\_NAME,OUTPUT\_NAME,DESCRIPTION,CPP\_TYPE)}: Same remark
+ \\ \small\texttt{BBTK\_BLACK\_BOX\_TEMPLATE\_IMPLEMENTATION(BOX\_NAME,BBTK\_PARENT)}
+ \\ \small\texttt{BBTK\_BLACK\_BOX\_TEMPLATE2\_IMPLEMENTATION(BOX\_NAME,BBTK\_PARENT)}
+ \\ \small\texttt{BBTK\_ADD\_TEMPLATE\_BLACK\_BOX\_TO\_PACKAGE(PACKAGE\_NAME,BOX\_NAME, TEMPLATE\_PARAMETER\_VALUE)}: Adds the black box template instanciated on a certain value of its template parameter to the package. You can put as many such lines with different template parameter values as you want (see e.g. \texttt{package/std/src/bbstdStringTo.cxx})
+ \\ \small\texttt{BBTK\_ADD\_TEMPLATE2\_BLACK\_BOX\_TO\_PACKAGE(PACKAGE\_NAME,BOX\_NAME, TEMPLATE\_PARAMETER\_1\_VALUE, TEMPLATE\_PARAMETER\_2\_VALUE)}:
+The same for two template parameters (see e.g. \texttt{package/std/src/bbstdCast.cxx})
+\\
+%\end{itemize}
+\\ \hline
+\end{tabular}
+\end{table}
+
+
+{\bf IMPORTANT NOTE ON TEMPLATE BLACK BOXES NAMES:}
+
+Two different boxes registered in a package must have two different names.
+Hence when using black box classes templates,
+one must give different names to two instanciations of the template on
+two different types.
+This is typically done with inserting the template parameter type name in the
+black box class name.
+An example is provided in \texttt{package/std/src/bbstdStringTo.h}:
+
+\begin{verbatim}
+ BBTK_BEGIN_DESCRIBE_TEMPLATE_BLACK_BOX(ToString,bbtk::AtomicBlackBox);
+ BBTK_NAME(bbtk::HumanTypeName<T>()+"ToString");
+ ...
+ BBTK_END_DESCRIBE_TEMPLATE_BLACK_BOX(ToString);
+\end{verbatim}
+
+To get the string corresponding to the name of a \CPP type
+(here the template parameter \texttt{T})
+one must use the template \bbtk function \texttt{bbtk::HumanTypeName<T>()}
+\footnote{\texttt{HumanTypeName} returns a human readable type name,
+without special chars such as \texttt{::} or \textless. For example the
+human readable type name of \texttt{std::vector\textless std::string \textgreater} is \texttt{VectorOfString}. The 'inhuman' type name is given
+by the function \texttt{bbtk::TypeName<T>()}.}.
+It is then concatenated to the name \texttt{ToString}.
+This thus gives the name \texttt{IntToString} to the black box \texttt{ToString\textless int \textgreater},
+\texttt{DoubleToString} to the black box \texttt{ToString\textless double \textgreater}, etc.
+
+You can also use \texttt{bbtk::HumanTypeName<T>()}
+in the macro \texttt{BBTK\_DESCRIPTION}, like for example:
+\begin{verbatim}
+ BBTK_DESCRIPTION("Converts a "+bbtk::HumanTypeName<T>()+" ("
+ +bbtk::TypeName<T>()+") into a string");
+\end{verbatim}
+
+
+% ==========================================
+\subsubsection{ITK black boxes \CPP macros}
+% ==========================================
+
+It is a special case of black box templates with also
+special macros for \itk object inherited black boxes.
+
+See the example of \texttt{package/wx/src/bbitkBinaryThresholdImageFilter.h\textbar cxx},
+the tables \ref{CPPInterfaceBasicMacros} and \ref{CPPTemplateMacros}.
+
+Note that
+there is also a mechanism for making
+``generic'' untemplatized itk black boxes.
+See the example in the file above.
+
+% ==========================================
+\section{Configure your project with \cmakens.}
+\label{sec:CMake}
+% ==========================================
+You have to run the \texttt{CMakeSetup} application with your project root directory as location of the sources (this can be done by dragging the icon of the \texttt{CmakeLists.txt} file toward the icon of \texttt{CMakeSetup}). You will have to indicate a location for the binaries, which must be different from the location of the sources. You are likely to encounter some warnings about the compiler version, which you (generally) can ignore. Be careful however with various options, the default state of which is \texttt{OFF}, e.g.: at the very beginning, you will have to put \texttt{ON} the attribute \texttt{BUILD\_BBTK\_PACKAGE\_\emph{your\_package\_name}}. Click on 'Configure' as long as new elements appear or remain in red, then click on 'OK'. \cmake will generate an entire directory tree, with the workspace file (e.g. \texttt{bb\emph{your\_package\_name}.sln} for Microsoft Visual Studio) in the root directory. Note that the tree includes a \texttt{src} directory where the \CPP code of the package is automatically generated.
+%
+% ==========================================
+\section{Compile your project.}
+\label{sec:compile}
+% ==========================================
+Open the workspace file generated by \texttt{CMakeSetup} (e.g. \texttt{bb\emph{your\_package\_name}.sln} for Microsoft Visual Studio), select either the appropriate project to be built, or \texttt{ALL\_BUILD} if applies. Build it in RelWithDebInfo configuration, which corresponds to the configuration in which the bbtk libraries provided by the installer were compiled. The first step of the \texttt{build} process is the generation of \CPP code from \xml files. Note that these new \texttt{.cxx} and \texttt{.h} files are put into the \texttt{src} subdirectory of the directory tree containing the binaries and {\bf not} of the one containing the sources. Indeed, the 'sources' directory tree is intended to contain actual source files, that are to be saved (e.g. with CVS), while the 'binaries' directory tree is intended to contain all the files generated either by \cmake or by the \texttt{build} process.
+
+% ==========================================
+\section{Plug the new package.}
+\label{sec:plugin}
+% ==========================================
+If you want to use the new package with \bbStudio you can plug it dynamically. Use the menu
+\texttt{Tools > Plug package}. You will be prompted to indicate the package directory. Browse the root of the 'binaries' directory tree (the one generated by \cmakens).
+The plug-in mechanism actually consists in automatic adding of appropriate paths into the configuration file.