+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
+{