+\label{sec:CPP-box}
+% ==========================================
+
+Almost everything is performed using macros.
+
+For a quick start, the best you have to do is to run \texttt{bbStudio}, then in the menu \texttt{Tools}, choose the item
+ \texttt{Create black box}, click on \texttt{C++}, and have a look to the generated files, or have a look at the source files of \bbtk core packages.
+
+% ==========================================
+\subsubsection{Black box basic header file (.h)}
+% ==========================================
+
+Let's have a look at the file \texttt{packages/std/bbstdMakeFileName.h}
+
+\begin{file}{\texttt{packages/std/bbstdMakeFileName.h}}
+\small
+\begin{verbatim}
+#ifndef __bbstdMakeFileName_h_INCLUDED__
+#define __bbstdMakeFileName_h_INCLUDED__
+
+#include "bbtkAtomicBlackBox.h"
+
+namespace bbstd
+{
+ class MakeFileName : public bbtk::AtomicBlackBox
+ {
+ BBTK_BLACK_BOX_INTERFACE(MakeFileName,bbtk::AtomicBlackBox);
+ BBTK_DECLARE_INPUT(Directory, std::string);
+ BBTK_DECLARE_INPUT(File, std::string);
+ BBTK_DECLARE_INPUT(Extent, std::string);
+ BBTK_DECLARE_OUTPUT(Out, std::string);
+ BBTK_PROCESS(DoProcess);
+ void DoProcess();
+ protected:
+ virtual void bbUserConstructor();
+ };
+
+ BBTK_BEGIN_DESCRIBE_BLACK_BOX(MakeFileName,bbtk::AtomicBlackBox);
+ BBTK_NAME("MakeFileName");
+ BBTK_AUTHOR("jpr@creatis.insa-lyon.fr");
+ BBTK_CATEGORY("misc");
+ BBTK_DESCRIPTION("Makes a kosher file name");
+ BBTK_INPUT(MakeFileName,Directory,"Directory Name",std::string,
+ "directory name");
+ BBTK_INPUT(MakeFileName,File, "File Name", std::string,
+ "file name");
+ BBTK_INPUT(MakeFileName,Extent, "Extention", std::string,
+ "file extension");
+
+ BBTK_OUTPUT(MakeFileName,Out,"Full File Name",std::string,"file name");
+ BBTK_END_DESCRIBE_BLACK_BOX(MakeFileName);
+
+}
+// EO namespace bbstd
+
+#endif // __bbstdMakeFileName_h_INCLUDED__
+\end{verbatim}
+\end{file}
+
+It includes \texttt{bbtkAtomicBlackBox.h}.
+The box class is \texttt{MakeFileName}.
+It inherits \texttt{bbtk::AtomicBlackBox}.
+It is in the \texttt{bbstd} namespace :
+each box of a given package, say PACK, must be inserted into
+the namespace \texttt{bbPACK}.
+
+The macro \texttt{BBTK\_BLACK\_BOX\_INTERFACE}
+declares the interface of the class: constructor, destructor,
+standard methods (e.g. New), etc.
+The following macros then declare inputs and outputs of the box,
+with their types.
+The macro \texttt{BBTK\_PROCESS} then declares which method to call
+when processing the box (the process callback).
+The callback itself is declared just below.
+
+The line \texttt{virtual void bbUserConstructor();} then
+overloads the virtual method \texttt{bbUserConstructor}
+which is used to perform specific things at construction time.
+You can also overload \texttt{bbUserCopyConstructor}
+and \texttt{bbUserDestructor} with the same signature.
+The black box interface macros are summarized in table
+\ref{CPPInterfaceBasicMacros}.
+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{CPPInterfaceBasicMacros}Black box interface \CPP macros}
+\begin{tabular}{p{\textwidth}}\hline
+ \\ \small \texttt{BBTK\_BLACK\_BOX\_INTERFACE(BOX\_NAME,BBTK\_PARENT)}:
+ Yes, we know the \bbtk parent is redundant with the inheritance list... That's why we allow you to describe your class in \xml format!
+ \\ \small \texttt{BBTK\_VTK\_BLACK\_BOX\_INTERFACE(CLASS,BBTK\_PARENT,VTK\_PARENT) }: Black box interface for \vtk object inherited boxes
+ \dots
+ \\ \small \texttt{BBTK\_ITK\_BLACK\_BOX\_INTERFACE(CLASS,BBTK\_PARENT,ITK\_PARENT) }: Black box interface for \itk object inherited boxes
+ \dots
+ \\ \small \texttt{BBTK\_DECLARE\_INPUT (NAME,TYPE) }: Declares an input of the box, with \texttt{NAME}: the input name (as it will appear to the users of your black box) and \texttt{TYPE}: \CPP type of the input (e.g. double, std::string, vtkImageData*, ...).
+ \\ \small \texttt{BBTK\_DECLARE\_INHERITED\_INPUT(NAME,TYPE,GETMETHOD,SETMETHOD)}: Declares an input of the box which wraps the \texttt{GETMETHOD / SETMETHOD} accessors
+ \\ \small \texttt{BBTK\_DECLARE\_VTK\_INPUT(NAME,TYPE)}:
+ Declares a vtk object-inherited input
+ \\ \small \texttt{BBTK\_DECLARE\_VTK\_IMAGE\_ALGORITHM\_INPUT(NAME,TYPE)}: Declares a vtkImageAlgorithm-inherited input
+ \\ \small \texttt{BBTK\_DECLARE\_VTK\_POLY\_DATA\_ALGORITHM\_INPUT(NAME,TYPE)}: Declares a vtkPolyDataAlgorithm-inherited input
+ \\ \small \texttt{BBTK\_DECLARE\_ITK\_INPUT (NAME,TYPE)}:
+ Declares a itk object-inherited input
+ \\ \small \texttt{BBTK\_DECLARE\_OUTPUT (NAME,TYPE) }:
+ Declares an output of the box
+ \\ \small \texttt{BBTK\_DECLARE\_INHERITED\_OUTPUT(NAME,TYPE,GETMETHOD,SETMETHOD)}:
+ Declares an output of the box which wraps the \texttt{GETMETHOD / SETMETHOD} accessors
+ \\ \small \texttt{BBTK\_DECLARE\_VTK\_OUTPUT(NAME,TYPE)}:
+ Declares a vtk object-inherited output
+ \\ \small \texttt{BBTK\_DECLARE\_ITK\_OUTPUT(NAME,TYPE)}:
+ Declares a itk object-inherited output
+ \\ \small \texttt{BBTK\_DECLARE\_VTK\_PARAM(VTK\_PARENT,NAME,TYPE)}:
+ Declares an input corresponding to an inherited vtk parameter
+ (you know, the ones that are declared by vtkSetMacro/vtkGetMacro). Its name must be the same than the vtk parameter name.
+ \\ \small \texttt{BBTK\_DECLARE\_ITK\_PARAM(NAME,TYPE)}:
+ Declares an input corresponding to an inherited itk parameter
+ \\ \small \texttt{BBTK\_PROCESS(METHOD\_NAME)}:
+ Defines the method to call when the box is processed.
+ \\ \small \texttt{BBTK\_VTK\_PROCESS}: Defines AND implements the default processing method for vtk
+ inherited black boxes (calls \texttt{vtkParent::Update})
+ \\ \small \texttt{BBTK\_ITK\_PROCESS}: Defines AND implements the default processing method for itk
+ inherited black boxes (calls \texttt{itkParent::Update})
+\\
+\hline\end{tabular}
+
+\end{table}
+%================================================
+
+After the black box class declaration
+then comes a zone in which you describe your black box,
+between the macros \texttt{BBTK\_BEGIN\_DESCRIBE\_BLACK\_BOX}
+and \\ \texttt{BBTK\_END\_DESCRIBE\_BLACK\_BOX}.
+
+The macro \texttt{BBTK\_BEGIN\_DESCRIBE\_BLACK\_BOX}
+actually starts the declaration of another class,
+called \texttt{\textless BOXNAME \textgreater Descriptor}
+(in our case \texttt{MakeFileNameDescriptor}).
+The descriptor of a black box :
+\begin{itemize}
+\item has only one instance, which is stored in the package
+\item provides information about the box type (author, description, ...)
+which is used for documentation.
+\item provides information about the box I/Os, mainly their types
+(uses RTTI : \texttt{std::type\_info} ).
+\item is responsible for creating new instances of the box it describes.
+\end{itemize}
+
+As you can see,
+the macros which are between \texttt{BBTK\_BEGIN\_DESCRIBE\_BLACK\_BOX}
+and \texttt{BBTK\_END\_DESCRIBE\_BLACK\_BOX}
+provide the box name (the string),
+its authors, description, category,
+the descriptions of its inputs and outputs.
+Black box descriptor related
+are described in table \ref{CPPDescriptorBasicMacros}.
+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{CPPDescriptorBasicMacros}Black box descriptor \CPP macros}
+\begin{tabular}{p{\textwidth}}\hline
+ \\ \small \texttt{BBTK\_BEGIN\_DESCRIBE\_BLACK\_BOX(BOX\_NAME,BBTK\_PARENT) } :
+ Yes, we know it's redundant with public inheritance ... That's why we allow you to describe your class in xml format!
+ All the following items will be used in the Help interface; describe them carefully (i.e. in a Human understandable way!).
+ \\ \small \texttt{BBTK\_ADAPTOR}: Declares that the box is an adaptor
+ \\ \small \texttt{BBTK\_DEFAULT\_ADAPTOR}: Declares that the box is the default adaptor for its I/O types
+ \\ \small \texttt{BBTK\_NAME(STRING)}: The name of your box
+ \\ \small \texttt{BBTK\_AUTHOR(STRING)}: The author(s) (better you put e-mail adresses)
+ \\ \small \texttt{BBTK\_DESCRIPTION(STRING)}: Brief description of what does the box
+ \\ \small \texttt{BBTK\_CATEGORY(STRING)}: Box categories, semicolon separated (see table \ref{categories})
+ \\ \small \texttt{BBTK\_INPUT(BOX\_NAME,INPUT\_NAME,DESCRIPTION,CPP\_TYPE,INPUT\_NATURE)}
+ \begin{itemize}
+ \item \texttt{BOX\_NAME}: The current black box name.
+ \item \texttt{INPUT\_NAME}: The input name
+ \item \texttt{DESCRIPTION} (string): A brief description of what the parameter is used for.
+ \item \texttt{CPP\_TYPE}: The \CPP type of the input (e.g. double, std::string, vtkImageData*, ...)
+ \item \texttt{INPUT\_NATURE}: The 'nature' of the parameter (see table \ref{nature}) if you wish your box may be used by automatic GUI generator.
+ Supply an empty string ("") if you don't care.
+ \end{itemize}
+ \\ \small\texttt{BBTK\_OUTPUT(BOX\_NAME,OUTPUT\_NAME,DESCRIPTION,CPP\_TYPE)}: The same
+ \\ \small \texttt{BBTK\_END\_DESCRIBE\_BLACK\_BOX(BOX\_NAME)}
+ \\ \hline\end{tabular}
+\end{table}
+
+% ==========================================
+\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}