+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}
+\small
+
+\begin{itemize}
+
+ \item \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!
+
+ \item \texttt{BBTK\_VTK\_BLACK\_BOX\_INTERFACE(CLASS,BBTK\_PARENT,VTK\_PARENT) } Black box interface for \vtk object inherited boxes
+ \dots
+ \item \texttt{BBTK\_ITK\_BLACK\_BOX\_INTERFACE(CLASS,BBTK\_PARENT,ITK\_PARENT) } Black box interface for \itk object inherited boxes
+ \dots
+ \item \texttt{BBTK\_DECLARE\_INPUT (NAME,TYPE) } Declares an input of the box
+\begin{itemize}
+\item \texttt{NAME} : the input name (as it will appear to the users of your black box)
+\item \texttt{TYPE} : \CPP type of the input (e.g. double, std::string, vtkImageData*, ...)).
+\end{itemize}
+ \item \texttt{BBTK\_DECLARE\_INHERITED\_INPUT(NAME,TYPE,GETMETHOD,SETMETHOD)} Declares an input of the box which wraps the \texttt{GETMETHOD / SETMETHOD} accessors
+
+ \item \texttt{BBTK\_DECLARE\_VTK\_INPUT(NAME,TYPE)}
+ Declares a vtk object-inherited input
+ \item \texttt{BBTK\_DECLARE\_VTK\_IMAGE\_ALGORITHM\_INPUT(NAME,TYPE)} Declares a vtkImageAlgorithm-inherited input
+ \item \texttt{BBTK\_DECLARE\_VTK\_POLY\_DATA\_ALGORITHM\_INPUT(NAME,TYPE)} Declares a vtkPolyDataAlgorithm-inherited input
+ \item \texttt{BBTK\_DECLARE\_ITK\_INPUT (NAME,TYPE)}
+ Declares a itk object-inherited input
+ \item \texttt{BBTK\_DECLARE\_OUTPUT (NAME,TYPE) }
+ Declares an output of the box
+ \item \texttt{BBTK\_DECLARE\_INHERITED\_OUTPUT(NAME,TYPE,GETMETHOD,SETMETHOD)}
+ Declares an output of the box which wraps the \texttt{GETMETHOD / SETMETHOD} accessors
+ \item \texttt{BBTK\_DECLARE\_VTK\_OUTPUT(NAME,TYPE)}
+ Declares a vtk object-inherited output
+ \item \texttt{BBTK\_DECLARE\_ITK\_OUTPUT(NAME,TYPE)}
+ Declares a itk object-inherited output
+
+ \item \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.
+
+ \item \texttt{BBTK\_DECLARE\_ITK\_PARAM(NAME,TYPE)}
+ Declares an input corresponding to an inherited itk parameter
+
+ \item \texttt{BBTK\_PROCESS(METHOD\_NAME)}
+ Defines the method to call when the box is processed.
+ \item \texttt{BBTK\_VTK\_PROCESS} Defines AND implements the default processing method for vtk
+ inherited black boxes (calls \texttt{vtkParent::Update})
+ \item \texttt{BBTK\_ITK\_PROCESS} Defines AND implements the default processing method for itk
+ inherited black boxes (calls \texttt{itkParent::Update})
+\end{itemize}
+\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}
+\small
+
+ \begin{itemize}
+ \item \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!).
+ \item \texttt{ BBTK\_ADAPTOR } : Declares that the box is an adaptor
+ \item \texttt{ BBTK\_DEFAULT\_ADAPTOR } : Declares that the box is the default adaptor for its I/O types
+ \item \texttt{BBTK\_NAME} : the name of your box
+ \item \texttt{BBTK\_AUTHOR} : author name (better you put e-mail adress)
+ \item \texttt{BBTK\_DESCRIPTION} : brief description of what does the box
+ \item \texttt{BBTK\_CATEGORY} : box category (see table \ref{categories})
+ \item \texttt{BBTK\_INPUT(BOX\_NAME,INPUT\_NAME,DESCRIPTION,CPP\_TYPE,INPUT\_NATURE)} for each one of the input parameters, you have to supply :
+ \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}
+ \item \texttt{ BBTK\_OUTPUT(BOX\_NAME,OUTPUT\_NAME,DESCRIPTION,CPP\_TYPE)}
+ \item \texttt{BBTK\_END\_DESCRIBE\_BLACK\_BOX(BOX\_NAME)} : means the torture is (almost) over.
+ \end{itemize}
+
+\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}
+\small
+
+ \begin{itemize}
+ \item \texttt{BBTK\_ADD\_BLACK\_BOX\_TO\_PACKAGE} : (Package name, Blackbox name)
+ \item \texttt{BBTK\_BLACK\_BOX\_IMPLEMENTATION} : (Blackbox name, Blackbox basic parent \\ (bbtk::AtomicBlackBox/ bbtk::WxBlackBox)see :\label{basic_parent}
+ \item \texttt{Process} :definition of your own callback function, that will be called in the box method. \\ At least, you'll write here the default initialisation of the outputs
+ \end{itemize}
+
+\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.