1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
17 \bbtk version \bbtkVersion
21 Last modified on : October 16, 2008 \\
26 Eduardo D\'avila, Laurent Guigues, Jean-Pierre Roux
29 CREATIS-LRMN, Centre de Recherche en Imagerie Medicale \\ CNRS UMR 5220, INSERM U620\\
31 Universit\'e Claude-Bernard Lyon 1\\
33 http://www.creatis.insa-lyon.fr/creatools/bbtk
37 % ==========================================
39 % ==========================================
47 % ==========================================
49 % ==========================================
51 % ==========================================
53 \section{What is bbtk ?}
54 % ==========================================
55 \BBTK(\bbtkns) is a set of tools
56 (\CPP libraries and executables)
57 providing a \CPP framework for the definition
58 of elementary processing \emph{units}, called {\bf black boxes},
59 and the definition and execution of processing \emph{chains}
60 made up of these black boxes. \\
62 %It's a part of the \texttt{Creatools suite} composed mainly of :
70 %which depend on the OpenSource libraries:
78 % ==========================================
79 \subsection{The black box philosophy}
80 % ==========================================
82 \href{http://www.answers.com/topic/black-box-theater}{The Answers Dictionary} defines a {\bf black box} as
83 \emph{``A device or theoretical construct with known or specified performance characteristics
84 but unknown or unspecified constituents and means of operation''} \\
85 \href{http://en.wikipedia.org/wiki/Black_box_\%28disambiguation\%29}{Wikipedia}
86 defines a {\bf black box} as
87 \emph{``any component in a system in which only the input and output
88 characteristics are of interest, without regard to its internal mechanism
90 We should merge these definitions. :
91 not only the inputs and outputs are of interest but also
92 \emph{what the box does} !
93 Hence, we would say that a black box is any \emph{\bf documented}
94 component of a system, letting the user know
95 \emph{\bf what} the box is supposed to do and
96 \emph{\bf how to use it}
97 but not \emph{\bf how it does it}. \\
99 \BBTK provides a systematic framework
100 to encapsulate (or ``wrap'') any
101 existing \texttt{C} or \CPP processing code into an object
102 (a black box) having a {\bf generic symbolic interface}, where
105 \item{\bf generic} means that the interface is \emph{the same}
106 for all boxes. Hence one does not need to know which particular
107 method allows, say, to set a particular input or
108 get a particular output of the box.
109 One can use a black box in a purely abstract way.
110 \item{\bf symbolic} means that a particular
111 input or output is referenced by a 'name', that is by a symbol
112 which identifies the input or output.
113 It also means that symbolic information (text) is
114 attached to a box: description of the box, author,
115 description of its inputs and outputs, etc.
118 (Actually, genericity is achieved because the interface is symbolic.
119 We let you think about this\dots)
121 Of course, symbolic data attached to a box may be
122 {\bf queried} : what are the inputs/outputs of the box ?
123 what are their type ? their description ? etc.
124 This allows {\bf automatic documentation} of boxes.
126 The abstract definition of black boxes is the most basic
127 aspect of \BBTK architecture.
128 Another key aspect is the groupement of black boxes into
129 so called {\bf packages},
130 which are \emph{dynamic libraries} which can also
131 be queried, in particular about the boxes they provide.
132 The package structure then offers a mechanism which
133 is like a \emph{'plug-in'} mechanism.
134 \BBTK provides the methods to load a package at run-time,
135 and create instances of the boxes it contains.
137 These two mechanisms (black boxes and packages)
138 then gives the way to:
141 \item The definition of an {\bf interpreted script language},
142 which allows to manipulate packages and boxes very easily in symbolic way.
143 \BBTK provides one : \bbs (the Black Box Script language) and its interpreter
144 \bbi (the Black Box Interpreter).
145 \item {\bf Automatic documentation} of existing packages.
146 \texttt{html} documentation of packages is proposed by
150 Finally, these different components allow {\bf efficient} :
153 \item {\bf capitalization and reuse} of existing processing units,
154 including {\bf documentation}
155 \item {\bf testing, prototyping} in a very simple script language
156 \item {\bf inter-operability} between atomic processings which
157 have been written by different persons, using different libraries, etc.
160 % ==========================================
161 \subsection{\bbtk components}
162 % ==========================================
165 \item A \CPP {\bf\emph{library}} - called \bbtk - which defines a framework
166 (abstract classes) to develop black boxes and store them into
167 dynamic libraries, called black box \emph{packages}.
168 \item Different {\bf\emph{"core" black box packages}} :
170 \item {\bf\emph{std}} : the 'standard' package including basic useful boxes.
171 \item {\bf\emph{wx}} : basic graphical interface elements (widgets : sliders, buttons, etc. based on the \texttt{wxWidgets} library).
172 \item {\bf\emph{itk}} : the basic image processing package, based on the \itk library.
173 \item {\bf\emph{vtk}} : the basic images and surfaces processing and visualization package, based on the \vtk library.
174 \item {\bf\emph{wxvtk}} : widget boxes based on the \vtk library (2D and 3D vizualization and
176 %\item {\bf\emph{creaImageIO}} : Provides hight level widgets to read images, including DICOM.
177 \item {\bf\emph{toolsbbtk}} : Tools for bbtk administration and package development.
179 \item A {\bf\emph{Developement environment}}, called \bbStudio, which provides
181 \item An online {\bf\emph{script editor and interpretor}}
182 \item A powerful html {\bf\emph{Help environment}}, integrating :
184 \item Online documentation scaning
185 \item Retreiving boxes on various criterions
186 \item Checking Demo and examples
189 \item An standalone {\bf\emph{interpreter}}, called \bbins, which allows to
190 execute \bbs scripts or commands.
191 \item {\bf\emph{Various Development Utilities}} :
193 \item \bbfy generates the \CPP code of a black box from a
194 description file written in \texttt{xml}.
195 %\item \bbdoc generates the html documentation of a black box package
196 %(author, description, description of its black boxes :
197 %author, description, inputs, outputs, and so on).
198 \item \bbCreatePackage allows to create the basic file architecture.
199 to start the development of a new black box package.
200 \item \bbCreateBlackBox allows to create the basic file architecture.
201 to start the development of a new black box, that will be included in an already existing package.
202 \item \bbs2cpp translates a \texttt{.bbs} script into a \CPP file.
203 \item \bbc (sorry : Linux Only, for the moment) that compiles \texttt{.bbs} scripts into executables.
204 \item \bbRegeneratePackageDoc which creates the html documentation of the Package.
205 \item \bbRegenerateBoxesLists which creates the html pages of the various lists of all the currenly installed boxes.
206 \item \bbPlugPackage which automatically incorporates a new package.
208 \item A full {\bf\emph{documentation}} printable (pdf), browsable (html),
209 queryable throught keywords.
212 The general architecture of \BBTK
213 is shown in figure \ref{bb-architecture}.
216 \caption{\label{bb-architecture}\BBTK architecture}
218 \includegraphics[width=0.6\textwidth]{bb-architecture.png}
224 % ==========================================
225 \section{Getting started with bbStudio}
226 % ==========================================
229 % ==========================================
230 \subsection{The interface}
231 % ==========================================
234 %\vspace{0.5cm}\hrule
235 %\section{The Development environment (bbStudio)}
238 Just run it, typing in a console \bbStudio
239 or clicking on its icon or its menu entry.
241 You'll get something like in figure
242 \ref{bbi-fig-bbStudio-gui-start}
243 (the exact appearance of \bbStudio is Operating System and \bbtk version dependent)
244 At start, \bbStudio opens with a very minimal 'How to use' in the middle. \\
245 Don't forget to read it : it will vanish at the first mouse click. \
252 \caption{\label{bbi-fig-bbStudio-gui-start}The bbStudio Development environment interface at start time}
254 \includegraphics[width=0.7\textwidth]{bbStudioMainPageStart.png}
259 Feel free to resize any part you want.
260 Your preferences will be kept next time you run again \bbStudio. \\
262 Let's have a look at the resized window :
265 \caption{\label{bbi-fig-bbStudio-gui}The bbStudio Development environment interface}
267 \includegraphics[width=0.7\textwidth]{bbStudioMainPage.png}
271 You can see four parts : \texttt{Files}, \texttt{Messages},
272 \texttt{Command}, \texttt{Help}.\\
274 The stuff is written using the Advanced User Interface library of wxWidgets
276 whose 'docking manager' allows windows and toolbars to be floated/docked
278 Please don't use this feature at learning time (the snapshots of this document
279 wouldn't match with your screen ...)
281 \subsubsection{'Files' part}
282 \label{bbi-FilesPart}
284 It's the .bbs script editor.\\
285 If you load a file holding a script, it will be displayed here, and you'll be
286 able to modify it, to save it, to save-as it, to run it, using the
287 lower toolbar (see figure : \ref{lowertoolbar})
290 \caption{\label{lowertoolbar}The lower tool bar}
292 \includegraphics[width=0.7\textwidth]{lowertoolbar2.png}
298 % \item {\bf\emph{New file}} : Create a new file to hold a script
299 % \item {\bf\emph{Open file}} : Open an already existing file holding a script
300 % \item {\bf\emph{Close file}} : Close a file holding a script
301 % \item {\bf\emph{Save file}} : Save he current file (if modified)
302 % \item {\bf\emph{Save file as}} : Save he current file under a different name
303 % \item {\bf\emph{Run file}} : Execute the script you just loaded/modified/written
304 % \item {\bf\emph{cursor position}} : column number : line number
308 \subsubsection{'Messages' part}
309 \label{bbi-MessagesPart}
311 Two kinds of messages will be output here:\\
312 System messages : produced by the kernel, in case of a user mistyping, or an execution error\\
313 Script messages : produced by the \bbtk equivalent of \texttt{printf}
314 or \texttt{std::cout} in user programs
316 \subsubsection{'Command' part}
317 \label{bbi-CommandPart}
319 This is where user will type \bbs commands which are executed on the fly..
321 \subsubsection{'Help' part}
322 \label{bbi-HelpContentsPart}
324 The 'Help' part of \bbStudio is used to browse the html help of \BBTK.
325 All the entries of the starting page are self-explanatory :
327 \item {\bf\emph{Help Contents}}
329 %\item {\bf\emph{Wiki}} : Direct link to the bbtk Wiki (intranet only, right now, www
331 \item {\bf\emph{Demo}} : Link to some 'sophisticated' demonstrations.
332 \item {\bf\emph{Examples}} : Link to some detailed 'How to use' examples
335 \item {\bf\emph{Guides}}
337 \item {\bf\emph{User's Guide}} : This Guide.
338 \item {\bf\emph{Package Developper's Guide}} : Step to step How-to for user who wants to create his own
340 % \item {\bf\emph{Developper's Guide}} : For bbtk kernel developpers. .
341 %\item {\bf\emph{Reference Manual}} :
342 % \item {\bf\emph{Booklet}} : Vade mecum.
343 \item {\bf\emph{Doxygen Documentation}} : Doxygen source browser.
346 \item {\bf\emph{Boxes}} : Lists of currently available Boxes :
348 \item {\bf\emph{ Alphabetical list}},
349 \item {\bf\emph{ List by package}},
350 \item {\bf\emph{ List by category}} : Each box is indexed by a list of keywords, called 'categrories', such as 'read/write',
351 'filter' 'viewer', ...
352 \item {\bf\emph{ List of adaptors}} : A special hidden Box category, called \texttt{{Adaptors}} exists. \\
353 They are used internaly to perform type conversions. Thought there are not end user intended, you may see them.
361 % ==========================================
366 % ==========================================
367 % ==========================================
368 % ==========================================
369 % ==========================================
370 % ==========================================
375 % ==========================================
379 % ==============================================
380 \subsection{Running Demo and Examples}
381 % ==============================================
383 In the part 'Help' (See figure \ref{HelpContents}), select \texttt{Examples} link.
386 \caption{\label{HelpContents}Help}
388 \includegraphics[width=0.7\textwidth]{HelpContents.png}
394 You will get a list of examples (See figure \ref{example}).
396 Due to an unfixed bug in Linux, you will have to click on 'reload' to get it. \\
400 \caption{\label{example}example list}
402 \includegraphics[width=0.7\textwidth]{example.png}
408 %\caption{\label{BoxCategories}Box Categories}
410 %\includegraphics[width=0.7\textwidth]{BoxCategories.png}
415 Select \texttt{wx::exampleSlider} (See figure \ref{exampleSlider});
418 \caption{\label{exampleSlider}example 'exampleSlider'}
420 \includegraphics[width=0.7\textwidth]{exampleSlider.png}
424 You can see the graphical summary representation of the current script (the elementary boxes that compose it, and their
426 Click on \texttt{source}, it will be loaded
427 in the 'Files' part, within the script editor (See figure \ref{exampleSliderSource});
430 \caption{\label{exampleSliderSource}source code of 'exampleSlider'}
432 \includegraphics[width=0.7\textwidth]{exampleSliderSource.png}
436 Run it, using the lower toolbar (see figure : \ref{lowertoolbar})
438 You'll get something like in figure \ref{execSliderSource}.
441 \caption{\label{execSliderSource}execution of 'exampleSlider'}
443 \includegraphics[width=0.7\textwidth]{execSliderSource.png}
447 Feel free to move the slider, to check it actually works...
451 Just a few words on what you saw :
453 \item{in the File part} \\
454 The source code of the script
459 We load the packages std and wx
462 set slider.ReactiveOnTrack 1
464 We create a \texttt{Slider} called \emph{slider}\\
465 We tell it to inform anybody that's interested in, that the cursor moved, each time it moved. \\
466 The default behaviour is to inform, only when cursor is released.
470 We create an \texttt{OutputText} called \emph{text}
471 (in which slider value will be displayed)
474 new LayoutLine layout
476 We create a \texttt{LayoutLine} called \emph{layout},
477 a widget designed to embed other wigets (say, a main window)
479 connect slider.Widget layout.Widget1
480 connect text.Widget layout.Widget2
482 We embed \emph{slider} and \emph{text} into \emph{layout}.
484 connect slider.BoxChange text.BoxExecute
485 connect slider.Out text.In
487 We tell \emph{slider} to inform \emph{text} every time it's modified.\\
488 We tell \emph{slider} to pass its output value (\texttt{Out}) to \emph{text} input value (\texttt{In})
492 We tell \emph{layout} to process itself (it will do it only if it's warned
493 that one of its entries was modified since its (own) last processing).
495 \item{in the Help part}
497 You can see the graphical representation of the workflow (pipeline) of the script, as in figure \ref{SmallGraph}.
501 \caption{\label{SmallGraph}Graphical representation of a pipeline}
503 \includegraphics[width=0.7\textwidth]{SmallGraph.png}
507 Both graphical interface pipeline (\emph{slider} and \emph{text} are embedded into \emph{layout})
508 and processing pipeline (\emph{slider} warns \emph{text} immedialtely when it's modified, \emph{slider} passed \emph{text} its new value).\\
509 Yes, we know : all the arrows (graphical interface pipeline arrows and processing arrows) are blue; we are sorry about that...\\
511 You can get a much more detailled graph, just clicking on the button \\ \texttt{graph (detailled)} in the toolbar of the \texttt{Command} part, like in
512 figure \ref{LargeGraph}.
515 \caption{\label{LargeGraph}Detailled graphical representation of a pipeline}
517 \includegraphics[width=0.75\textwidth]{LargeGraph.png}
524 % ==============================================
525 \subsection{Online Help}
526 % ==============================================
528 Various levels or help are suplied by \bbStudions.
530 % ==========================================
531 \subsubsection{Command line help}
532 % ==========================================
535 The 'working' area (the left one, as opposed to the 'help' area, on the right side) is composed of :
536 one single line area (\texttt{Command}), at the bottom, in which you can enter your commands and
537 a multiple line zone in which the Command interpreter prints out the result of your commands.
538 The upper part contains the script editor; we shall not use it right now, you may reduce it
540 Try typing in the \texttt{Command} area (in this manual,
541 the commands entered by the user will be preceded by a prompt \textgreater) :
546 you get the list of the commands of the interpreter :
579 To get help on a particular command type \texttt{help <command-name>},
587 usage : author <string>
588 Adds the string <string> to the author information of the black box being defined
591 The \texttt{help} command has multiple usages.
592 It is used to get help about almost anything in the interpreter!
593 Type \texttt{'help help'} to get help on the \texttt{help} command itself :
598 (2) help <command name>
599 (3) help packages [all]
600 (4) help <package name> [all]
601 (5) help <black box type>
602 (6) help <black box name>
604 (1) Lists all available commands;
605 (2) Prints help on a particular command;
606 (3) Lists the packages loaded and their black boxes.
607 Add 'all' to list adaptors;
608 (4) Prints short help on the black boxes of a package.
609 Add 'all' to include adaptors;
610 (5) Prints full help on a black box type;
611 (6) Prints information on the inputs, outputs and connectionns
612 of a black box instance.
616 More information about what is a 'box' will be given in the 'Scripting' part of this manual.
618 % ==========================================
619 \subsubsection{Guides}
620 % ==========================================
622 An html version of all the guides is browsable in the \texttt{Help} part of \bbStudions.
624 \item {\bf\emph{User's Guide}} : Step to step How-to for user who wants to create his own
625 application, just using already existing boxes.
626 \item {\bf\emph{Package Developper's Guide}} : Step to step How-to for programmer who wants to create his own
627 black boxes/packages.
628 % \item {\bf\emph{Developper's Guide}} : For bbtk kernel developpers only. (This one is probably not very much
629 % up-to-date, since we spend more time in developping than writing documentation that's not of user concern).
630 % \item {\bf\emph{Reference Manual}} : Contains a exaustive description of all the features for all the commands.
631 %\item {\bf\emph{Booklet}} : Vade mecum.
632 \item {\bf\emph{Doxygen Documentation}} : Doxygen source browser.\\ Automatically generated from source file
633 headers. Should concern only the kernel developpers (i.e. : us).
638 % ==========================================
639 \subsubsection{Boxes Help}
640 % ==========================================
641 Box retrieving on various criteria :
643 \item {\bf\emph{Alphabetical list}} \\ This is the 'zero-level' of retrieving.
644 \item {\bf\emph{List by package}} \\ Several packages are supplied with bbtk :
646 \item {\bf\emph{std}} : the 'standard' package including basic useful boxes.
647 \item {\bf\emph{wx}} : basic graphical interface elements (widgets : sliders, buttons, etc. based on the \texttt{wxWidgets} library).
648 \item {\bf\emph{itk}} : the basic image processing package, based on the \itk library.
649 \item {\bf\emph{vtk}} : the basic images and surfaces processing and vizualization package, based on the \vtk library.
650 \item {\bf\emph{wxvtk}} : widget boxes based on the \vtk library (2D and 3D vizualization and
652 %\item {\bf\emph{creaImageIO}} : Provides hight level widgets to read images, including DICOM.
653 \item {\bf\emph{toolsbbtk}} : Tools for bbtk administration and package development:
655 % \item{\texttt{GUICreateBlackBox}} For creating the XML or C++ code for a new black box
656 % \item{\texttt{GUICreatePackage}} For creating a new bbtk package file structure on disk (Graphical user interface for the shell script bbCreatePackage)
657 % \item{\texttt{MakePackageDoc}} For creating the html documentation of a package. The doc is generated at the 'canonical' location. Works both for a build tree or an installed toolkit.
660 \item {\bf\emph{List by category}}.
663 A given box may belong to more than one \texttt{category}.\\
664 You have to consider categories like keywords to index black boxes.\\
665 Some of them are mutually exclusive.
668 \item{atomic box / complex box}\\
669 Whether it's written is C++ or it's an assembly of several black boxes (atomic or complex).\\
670 Any box is either atomic ou complex.
671 \item{example / demo / application}\\
672 These ones are always complex black boxes.
675 It's just a (simple) example, for programmers, on how to use a given feature.
677 It can be a 'good looking' (a.k.a 'sexy') example on some sophisticated work, done only by using \texttt{bbtk}
680 It's a Final application, end user intended (e.g. Subscale a huge volume witout loading it in memory, Crop a DICOM image, etc)
683 Piece of graphical interface (based on \texttt{wxWidgets})
685 Dicom medical image related box.
689 \item{3D Object creator}
695 % ==========================================
696 \subsubsection{The Package Browser}
697 \label{Package_Browser}
698 % ==========================================
700 You can run it using the tool bar of the 'Command' part. See figure \ref{imPackage_Browser}.
703 \caption{\label{imPackage_Browser}The Package Browser}
705 \includegraphics[width=0.6\textwidth]{Package_Browser.png}
709 It allows you to query informations about what you can find in the packages (boxes and applications), using several criterions
710 (warning : it's case sensitive, i.e '\texttt{Button}' will give different results than '\texttt{button}' ...)
713 All the boxes and applications held in a given package (e.g. \texttt{wxvtk}, \texttt{std}, ...)
715 You can query on a subpart of the name of a box or an application (e.g. \texttt{DICOM})
716 \item Description :\\
717 You can query on a substring of the description of a box or an application (e.g. \texttt{utton} : user wants to get all
718 the\texttt{Button} as well as the \texttt{button} )
720 You can query on a sub part of the category name of a box or an application (e.g. \texttt{3D})
722 You can query all the boxes or applications that have at least one Input entry of the given type (e.g. \texttt{int})
723 \item Output Type :\\
724 You can query all the boxes or applications that have at least one Output entry of the given type (e.g. \texttt{int})
725 \item Input Nature :\\
726 You can query all the boxes or applications that have at least one Input entry of the given nature (e.g. \texttt{signal})
727 \item Output Nature :\\
728 You can query all the boxes or applications that have at least one Output entry of the given nature (e.g.
729 \texttt{signal},\texttt{file name})
733 All these criterions are \emph{AND}ed while the query process.\\
734 You can get the whole description of a given box or application clicking on its name.
738 % ==============================================
739 \subsection{The Menu}
740 % ==============================================
742 At last, let's have a look at \bbStudio menu.(See figure \ref{themenu})
745 \caption{\label{themenu}The bbStudio menu}
747 \includegraphics[width=0.7\textwidth]{themenu.png}
754 \item{\texttt{Open the bbtk configuration file}}
757 \item{\texttt{Tools}}
759 \item{\texttt{Create package}} :
760 Provides a graphical interface to help Package developper to create a new empty package.
761 \item{\texttt{Create black box}}
762 Provides a graphical interface to help Package developper to create a new empty black box, and add it to an already existing package.
763 \item{\texttt{Plug Package}}
764 Incorporates a package into the list of known packages. Updates the html documentation.
765 \item{\texttt{Regenerate package doc}} :
766 if user was supplied new black boxes, and added them to an already existing package, he can update the package documentation, in order to benefit all the features of the Help mechanisms.
767 \item{\texttt{Regenerate boxes list}} :
768 if user wants to update only boxes list (quicker)
769 \item{\texttt{Regenerate all}}
771 \item{\texttt{Show last image graph}}
772 User wants to rebuild the whole documentation.
774 \item{\texttt{Options}}
776 \item{\texttt{Reset before running}} Before running a script, all the already created boxes are destroyed,
777 all the already loaded packages are unloaded (this is the recomended option).
779 \item{\texttt{Windows}}
780 User may decide, for any reason of his own, to hide one or more pannels:
782 \item{\texttt{Show 'Files' panel}}
783 \item{\texttt{Show 'Help' panel}}
784 \item{\texttt{Show 'Command' panel}}
785 \item{\texttt{Show 'Messages' panel}}
786 \item{\texttt{Launch Package browser}} The package browser is a stand alone application. This can be achieved, too,
787 using the lower tool bar : button \texttt{Start Package Browser}.
790 \item{\texttt{About}}
792 \item{\texttt{About}} : Info about \texttt{bbStudio}.
795 % ==========================================
796 \section{bbs scripting}
797 % ==========================================
799 % ==========================================
800 \subsection{Using an already existing script}
801 % ==========================================
803 Using the lower toolbar (see figure : \ref{lowertoolbar}), open the file
806 You'll see it, in the '\texttt{Files}' part.\\ \\
807 You may run it, using the lower toolbar. \\
808 %\texttt{WARNING :} if the script contains one or more \texttt{LayoutSplit}
809 % object, you will have to resize the sub windows. \\ \\
810 You may modify, save or save-as the current script, using the lower toolbar.\\ \\
811 You may have a look at the graphical representation of the pipeline (sorry,
812 right now, to modify the pipeline, you have to modify the script;
813 you cannot modify grapically the pipeline; Work in progress...)
816 % ==========================================
817 \subsection{Inside black boxes}
818 % ==========================================
820 At start the interpreter does not know any black box.
821 If you type \texttt{'help packages'}, which is
822 the third form of the \texttt{help} command, you get :
829 which means that the interpretor only knows one package
830 (library of black boxes) called \texttt{user}
831 and which contains a black box called \texttt{workspace}.
832 The \texttt{user} package is an internal package of the interpreter,
833 which stores user-defined black box types.
834 At start, it already contains
835 one box, called \texttt{workspace}.
836 \texttt{workspace} is a special type of black box,
837 called complex black box, whose purpose is
838 to store other black boxes.
839 Any black box you create in \bbStudio is stored
840 in \texttt{workspace}
841 (this will be explained in details in sections
842 \ref{bbi-writing-scripts} and
843 \ref{bbi-more-on-complex-black-boxes}).
845 If you type \texttt{'help workspace'}, you get :
848 Complex Black Box <user::workspace>
851 Category(s) : complex box;
857 In the text displayed,
858 the \texttt{user::} prepended to the name \texttt{workspace}
859 means that the box \texttt{workspace}
860 belongs to the \texttt{user} package.
861 Then comes a description and three lines which
862 tell that \texttt{workspace} does not have any input
863 nor output nor boxes yet.
865 In order to let the interpreter know of some black boxes,
866 you must load another package.
867 The \texttt{std} package is the ``standard'' package,
868 which contains basic useful black boxes.
880 you get something like :
885 ASCII : ascii codes sequence to string - string to ascii...
886 Add : Adds its inputs
887 ConcatStrings : String concatenation
888 Configuration : Gets configuration informations
889 Div : Divides its inputs
890 ExecBbiCommand : Executes bbi commands
891 ExecSystemCommand : Executes system (O.S.) commands
892 GetVectorCharElement : Gets the i-th element from the input vector (std...
894 MagicBox : Takes *any kind* of data and copies it to its ou...
895 MakeFileName : Makes a kosher file name
896 Mul : Multiplies its inputs
897 MultipleInputs : This box has multiple Void inputs and one Void o...
898 StringRelay : Just copies the value of its input to its output...
899 StringSelect : Outputs the string set to the ith input Ini (In0...
904 Now the interpreter knows the package \texttt{std} and the black boxes it provides,
905 such as the \texttt{Add} box, the \texttt{ConcatStrings} box, and so on. Remark that the
906 content of \texttt{std} may vary from one version to another
907 as new black boxes might be added to it.
913 You'll get a text help, in the 'Message' part :
917 By : laurent.guigues@creatis.insa-lyon.fr
918 Categories : atomic box;math;
920 'BoxExecute' <bbtk::Void> [signal] : Any signal received by this input
922 'BoxProcessMode' <String> [] : Sets the processing mode of the box
923 (Pipeline | Always | Reactive)
924 'In1' <Double> [] : First number to add
925 'In2' <Double> [] : Second number to add
927 'BoxChange' <bbtk::VoidS> [signal] : Signals modifications of the box
928 'Out' <Double> [] : Result
931 After loading the package it belongs to, you can create an \emph{instance} of an \texttt{Add} box by
932 the command \texttt{new} :
938 The \texttt{'a'} at the end is the \emph{name} of the instance,
939 which will be used to reference it later.
940 It is important to distinguish a box \emph{type}
941 and an \emph{instance} of a box type.
942 The \texttt{Add} box of the package \texttt{std} is actually
943 a \emph{box type} , like \texttt{int} is a data type
944 in \texttt{C} langage. The \texttt{new} command allows to create
945 an instance of a box type, exactly like \texttt{int i;} in
946 a \texttt{C} code declares a variable of type \texttt{int} whose
948 Of course, like in \texttt{C} Language, you can declare multiple boxes of the
949 same type in \bbi. \\
951 After the creation of the box \texttt{a}, type :
958 Complex Black Box <user::workspace>
961 Category(s) : complex box;
968 which means that \bbi workspace now contains a black box named \texttt{a},
969 of type \texttt{std::Add}.
976 and have a look to the 'Help' Part (see figure : \ref{HelpAdd})
979 \caption{\label{HelpAdd}The html Help}
981 \includegraphics[width=0.7\textwidth]{HelpAdd.png}
986 You can see a description
987 (the one which was provided by the author of the box),
988 the author(s) of the box (usually e-mail adress(es)) and
989 the categories to which the box belongs.
990 Finally comes the lists of inputs and outputs of the box.
991 For each input or output, \bbi provides
993 its \emph{type} (between \texttt{<} and \texttt{>}, e.g. \texttt{<Int>})
995 Remark that the box \texttt{Add} is not a 'complex' black box
996 but an 'atomic' box, hence its help does not
997 include a pipeline graph.
999 You can see that \texttt{Add} boxes have two inputs,
1000 with name \texttt{In1} and \texttt{In2},
1001 and an output, with name \texttt{Out}.
1003 You can set the input \texttt{In1}
1004 of the \texttt{Add} box \texttt{a} to the value $1$
1010 Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
1016 And you print the output \texttt{Out} of the box \texttt{a} with :
1018 > print "result=$a.Out$"
1022 In the string passed to the \texttt{print} command,
1023 each substring enclosed between a couple of \$ is considered
1024 as the name of an output of a box.
1025 To process this special substrings, the interpretor :
1027 \item Processes the box if needed (see below)
1028 \item Converts the output of the box to a string if possible
1030 \item Substitutes the result in the string to print
1031 \item Postpones an implicit 'new line' character to the string
1036 Box processing is needed if :
1039 \item either at least input has changed since last processing
1040 \item or the input \texttt{'BoxProcessMode'} of the box is set to
1041 \texttt{'Always'}, which forces box reprocessing.
1044 Note that all boxes have an input named \texttt{'BoxProcessMode'}.
1046 Another way to process the box \texttt{a} is to issue the command :
1051 however this command does not display anything (except if the
1052 box itself displays something in its processing).
1053 It just processes the box if needed.
1054 This command is used to execute boxes that do not have any output,
1055 such as boxes that write something to a file or, display a
1056 graphical interface, and so on. \newline
1058 %To exit \bbi, type :
1066 % ==========================================
1072 \item The \texttt{include} command allows to load a package, and the complex black boxes that come with it..
1073 \item \texttt{help} gives help on :
1075 \item Available commands if you just type \texttt{help}.
1076 \item A particular command if you type \texttt{help <command-name>}.
1077 \item All available packages and their boxes (without description) if you type \texttt{help packages}.
1078 \item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
1079 \item A particular black box type (with full description) if you type \texttt{help <box-type-name>}. In particular, \texttt{help workspace} displays information on the content of the \texttt{'workspace'} black box, which stores the boxes created by the user (by \texttt{new}).
1081 %\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
1082 \item \texttt{new} : creates an instance of a black box.
1083 \item \texttt{set} : sets the value of an input of a black box.
1084 \item Under any component of \bbStudions, to reference the input called \texttt{i}
1085 of a black box called \texttt{b} you must type \texttt{'b.i'}.
1086 The same syntax holds for outputs.
1087 \item \texttt{print} : prints a string, substituting each substring of the form \$b.o\$ by the value of the output \texttt{o} of the black box \texttt{b}. Note that an
1088 implicit trailing 'new line character' is added at the final string.
1089 \item \texttt{exec} : runs, if needed, the process of a box.
1090 %\item \texttt{quit} : quits \bbi.
1095 %A more 'modern' way to proceed is to run \texttt{bbStudio}, drag and drop the \texttt{Command} bookmark to the lower \texttt{Welcome to bbStudio!} bar.
1096 %Wou'll get something like in figure \ref{bbCommandPlusHelp} :
1098 %\begin{figure}[!ht]
1099 %\caption{\label{bbCommandPlusHelp}
1100 %An other way to run the command interpreter}
1102 %\includegraphics[width=0.5\textwidth]{bbCommandPlusHelp.png}
1106 % ==========================================
1108 % ==========================================
1109 \subsubsection{Connecting black boxes}
1110 \label{bbi-connecting-black-boxes}
1111 % ==========================================
1113 \BBTK allows to create
1114 and execute processing chains,
1115 also called \emph{pipelines},
1116 by connecting black boxes.
1117 This section explains how to do it with examples.
1118 Read section \ref{bbi-more-on-pipeline-processing} to get
1119 more information on pipeline processing.
1121 First start \bbStudio and load the package \texttt{std}, typing :
1125 in the 'Command' part.
1127 Assume you want to compute $1+2+3$. You can do it by
1128 chaining two \texttt{Add} boxes, as shown in figure
1129 \ref{bbi-fig-connecting-black-boxes-1}.
1132 \caption{\label{bbi-fig-connecting-black-boxes-1} A simple pipeline which adds 3 numbers}
1134 \includegraphics[width=0.5\textwidth]{1plus2plus3.png}
1139 The \bbi instructions to create and execute this pipeline are :
1143 > connect a.Out b.In1
1150 You will see the (very expected) result :
1155 The first three commands build the pipeline,
1156 the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one
1157 prints \texttt{b} black box output (the pipeline is executed before printing, because the interpretor 'knows' the box \texttt{b},
1158 whose output is requested, is not up to date).
1160 The command \texttt{'connect a.Out b.In1'} ``plugs'' the output
1161 \texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the
1163 Once the boxes are connected, the processing of the two boxes are chained :
1164 getting the output of \texttt{b} requires getting its inputs,
1165 hence getting the output of \texttt{a} which is connected to it.
1166 This pipeline mechanism can recurse into arbitrary long
1167 chains of boxes (see \ref{bbi-more-on-pipeline-processing}
1171 Lets' consider an other, more image oriented, example :
1179 > new FileSelector fileDialog
1180 > new ImageReader reader
1182 > new Viewer2D viewer
1184 > connect fileDialog.Out reader.In
1185 > connect reader.Out viewer.In
1186 > connect slider.Out viewer.Slice
1187 > connect slider.BoxChange viewer.BoxExecute
1192 Some explainations : the \texttt{include} instructions load the necessary packages. \\
1194 \texttt{FileSelector} will pop a File Selector, at run time, that will out the user chosen file name. \\
1195 \texttt{Slider} will pop a Slider, at run time, that will out an integer, used later as a slice number.\\
1196 \texttt{ImageReader} will read any itk readable file, whose name is passed as a std::string, and return a pointer on an itk image.\\
1197 \texttt{Viewer2D} displays a plane, whose number is specified by an integer.\\
1199 \texttt{connect fileDialog.Out reader.In} plugs the output of the File Selector (a std::string) to the input of the reader (a std::string, too).\\
1200 \texttt{connect reader.Out viewer.In} plugs the output of the reader (an bbtk::any<bbitk::ImagePointer> which is a type defined by the
1201 itk package which can hold any itk image pointer) to the input of the Viewer (a vtkImageData *)\\
1202 \texttt{connect slider.Out viewer.Slice} plugs the output of the slider (an int) to an other output (named Slide) of the viewer.\\
1203 \texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer that it must re process itself any time the slider is modified.\\
1205 \texttt{exec viewer} processes the viewer.
1208 This would correspond to the graph in figure \ref{bbi-simplegraph}
1212 \caption{\label{bbi-simplegraph}(Very) simple Graph of a (very) simple pipeline}
1214 \includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
1218 Of course, to be able to connect two boxes,
1219 the output and the input must be compatibles.
1220 You can always connect an output to an input of the \emph{same} type,
1221 but you can do more, thanks to particular (hidden) black boxes called {\bf adaptors}.
1223 An adaptor is a black box which has at least one input, called \texttt{In},
1224 and at least one ouput called \texttt{Out} and whose role is to convert
1225 a data of the type of \texttt{In}
1226 into a data of the type of \texttt{Out} (other inputs or outputs may serve
1227 to parameter the adaptor or retreive other useful information).
1229 Under \bbStudions, if you type :
1236 Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
1237 Basic useful black boxes
1240 BoolToString [DA] : Converts a Bool (bool) into a string
1241 CastBoolToChar [DA] : Static cast from Bool (bool) to Char (signed c...
1242 CastBoolToDouble [DA] : Static cast from Bool (bool) to Double (double...
1244 CastBoolToUChar [DA] : Static cast from Bool (bool) to UChar (unsigne...
1245 CastBoolToUInt [DA] : Static cast from Bool (bool) to UInt (unsigned...
1247 CastUIntToBool [DA] : Static cast from UInt (unsigned int) to Bool (...
1248 CastUIntToChar [DA] : Static cast from UInt (unsigned int) to Char (...
1249 CastUIntToDouble [DA] : Static cast from UInt (unsigned int) to Double...
1254 \texttt{[DA]} stands for \emph{default adaptor}.
1256 Once you have loaded the package \texttt{std}, you can
1257 plug an output of type \texttt{char} into an input of type \texttt{double}.
1258 When the interpreter encounters the \texttt{connect} command,
1259 it looks for an adequate \emph{adaptor} in the loaded packages.
1260 In our case, as the package \texttt{std} provides the
1261 \texttt{CastUCharToDouble} adaptor, the interpreter automatically creates an
1262 instance of this adaptor and place it \emph{between}
1263 the output and the input you want to connect
1264 (however this adaptor is hidden to you,
1265 it is embedded into the created connection and does not appear
1266 as an existing black box).
1267 When the pipeline is processed the
1268 adaptor converts the output data into the required input type,
1269 in a totally transparent way.
1270 In our example, the \texttt{CastUCharToDouble} adaptor
1271 would simply cast the value of the \texttt{char} into a \texttt{double},
1272 however arbitrarily complex type conversion may be done.\\
1273 \texttt{WARNING} : these adaptors are \texttt{C++ static cast}, i.e., there is, right now,
1274 no 'intelligent' conversion (only truncation) e.g. think to \texttt{CastDoubleToUChar}!
1277 %Question (for info-dev):
1278 %if two adaptors with the same input and output types exist
1279 %in two different packages, currenly loaded,
1280 %which one is chosen by the interpreter at connection time?
1281 %A feature is missing to specify explicitely which one user wants to choose
1282 %(use a namespace notation ?)
1284 %-> Role of default adaptors
1287 Note that the \texttt{set} and \texttt{print} commands of interpreter
1288 work with adaptors from \texttt{string} to the type of the input to set
1289 or from the type of the output to print to \texttt{string}.
1290 Hence in order to \texttt{set} or \texttt{print} values the adequate
1291 adaptors must be available in the packages currently loaded. \\
1294 % ==========================================
1299 \item The \texttt{connect} command allows to connect two black boxes
1300 \item You can connect two black boxes if (and only if) :
1302 \item The output and the input are of the same type, or
1303 \item There is an adaptor black box in the packages loaded which
1304 converts data of the output type into data of the input type
1306 \item \texttt{help <package name>} does not display the adaptors of the package. To see them use : \texttt{help <package name> all}.
1310 % ==========================================
1312 % ==========================================
1313 \subsubsection{Creating complex black boxes}
1314 \label{bbi-complex-black-boxes}
1315 % ==========================================
1317 Remember the pipeline of figure
1318 \ref{bbi-fig-connecting-black-boxes-1}, which
1319 computed the sum of three doubles.
1320 You can consider it as a whole and define
1321 a new black box type, which will be a \emph{complex black box},
1322 having three inputs and one output,
1323 as shown in figure \ref{bbi-fig-complex-black-box-1}.
1326 \caption{\label{bbi-fig-complex-black-box-1} Creating the complex black box \texttt{Add3}}
1328 \includegraphics[width=0.5\textwidth]{Add3.png}
1332 The \bbi commands to define this complex black box are
1342 > connect a.Out b.In1
1345 > description "adds 3 doubles"
1346 > input x a.In1 "first double to add"
1347 > input y a.In2 "second double to add"
1348 > input z b.In2 "third double to add"
1349 > output result b.Out "output"
1356 As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
1358 The command \texttt{define} then starts the definition
1359 of the complex box type, which will be called \texttt{Add3}.
1361 The next three lines define the pipeline,
1362 exactly in the same way than outside a complex box definition.
1364 The commands \texttt{author}, \texttt{description}, \texttt{input}
1365 and \texttt{output} are commands specific to complex boxes definition :
1367 \texttt{author} and \texttt{description} are used for the documentation
1368 of the new box. You can provide multiple \texttt{author} or
1369 \texttt{description} commands, the arguments of the commands will
1370 be concatenated to produce the final author and description strings.
1372 \texttt{input} and \texttt{output} are used to define the inputs and outputs
1373 of the new complex box.
1374 Their syntax is the same : for each new input/output you need to say
1375 to which internal input/output it corresponds and to provide
1376 a help string documenting the input/output.
1377 In our example, we define that the box \texttt{Add3} has
1378 three inputs : \texttt{x}, \texttt{y} and \texttt{z}.
1379 The input \texttt{x} corresponds to the input \texttt{In1} of the
1380 internal box \texttt{a}.
1381 In the same way, the external input \texttt{y}
1382 corresponds to the internal input \texttt{a.In2}, and
1383 the external input \texttt{In3} to \texttt{b.In2}.
1384 The only output of the new box is called \texttt{result}
1385 and corresponds to \texttt{b.Out}.
1386 The figure \ref{bbi-fig-complex-black-box-1}
1387 illustrates the external to internal
1388 input/output correspondence.
1390 Finally, the \texttt{endefine} command ends the definition of the
1393 After this definition, if you ask for help
1394 on packages, you get :
1405 The \texttt{user} package now contains a new black box type, called
1406 \texttt{Add3}. If you ask for help on this type of box, you get :
1409 Complex Black Box <user::Add3>
1413 'x' <double> : first double to add
1414 'y' <double> : second double to add
1415 'z' <double> : third double to add
1417 'result' <double> : output
1423 and you can use it like any other box, for example type :
1435 As a side note, we can say that, for consistency reasons, it would have been better to name
1436 \texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3},
1437 since all the 'natural entry' of a box is named \texttt{In}, or \texttt{In}\emph{x} if there are more than one 'natural
1441 % ==========================================
1446 \item The \texttt{define/endefine} commands allows to define complex black box types, i.e. types of black boxes made up of other black boxes.
1447 Inside a \texttt{define/endefine} block :
1449 \item The \texttt{author} and \texttt{description} commands allow to document the new type of box
1450 \item The \texttt{input} and \texttt{output} commands allow to define the inputs and outputs of the new type of box, that is to which inputs and outputs
1451 of internal boxes they correspond.
1455 % ==========================================
1457 % ==========================================
1458 \subsubsection{Writing scripts}
1459 \label{bbi-writing-scripts}
1460 % ==========================================
1462 Once you have defined a new type of complex box, you
1463 may like to reuse it. To do this, you can simply
1464 write the \bbi commands defining the new box
1465 into a text file and afterwards include that file in \bbins.
1466 Doing this, you start writing \bbi scripts.
1467 The conventionnal (and mandatory) extension for such scripts is \texttt{bbs}
1469 For consistency reasons, you are requested to prepend \texttt{bb} to the name.
1471 For example, the \texttt{Add3} complex box we previously worked on
1472 can be defined in the \texttt{bbAdd3.bbs} file :
1474 \begin{file}{bbAdd3.bbs}
1476 # Defines the Add3 black box which adds 3 doubles
1482 description "adds 3 doubles"
1488 input x a.In1 "first double to add
1489 input y a.In2 "second double to add
1490 input z b.In2 "third double to add"
1492 output result b.Out "output"
1497 Lines starting with a \texttt{\#} character or a \texttt{\//\//} character are ignored, they
1498 are considered as comments by the interpreter.
1499 To use this file in \bbStudions, click on the \texttt{include} button, and browse your filestore to find the file.
1502 > include bbAdd3.bbs
1504 Complex Black Box <user::Add3>
1508 'x' <double> : first double to add
1509 'y' <double> : second double to add
1510 'z' <double> : third double to add
1512 'result' <double> : output
1520 If the file has the \texttt{bbs} extension, you can ommit it and just type :
1525 \subsubsection{Creating complex black boxes that use complex black boxes}
1526 \label{bbi-complex-complex-black-boxes}
1529 Of course, you can include script files in other script files,
1530 like in the following example :
1532 \begin{file}{bbAdd4.bbs}
1534 # Defines the Add4 black box which adds 4 doubles
1539 description "adds 4 doubles"
1543 input In1 a.In1 "first double to add
1544 input In2 a.In2 "second double to add
1545 input In3 a.In3 "third double to add"
1546 input In4 b.In2 "fourth double to add"
1547 output Out b.Out "output"
1553 The inner boxes have they own entries (In1, In2, In3 for box a, In1, In2 for box b )\\
1554 Only the inputs In1, In2, In3 of box a and the input In2 of box b is of interest for the end user, but he dosn't want to have to
1555 care neither about the inner boxes name, nor about the names of their Inputs.\\
1556 The writer of the complex box has the ability to give these inputs a meaningfull name !
1558 input In3 a.In3 "third double to add"
1559 input In4 b.In2 "fourth double to add"
1563 \subsubsection{Naming Conventions}
1564 \label{bbi-Naming Conventions}
1567 % ==========================================
1569 %\paragraph{Naming Conventions}
1573 % ==========================================
1577 For consistency reasons, you are requested to prepend \texttt{bb}, and postpone an extention \texttt{.bbs},
1578 to the names of the files that hold a \texttt{complex black box} definition.
1580 For example, the \texttt{Add3} complex box we previously worked on
1581 can be defined in the \texttt{bbAdd3.bbs} file.
1584 For consistency reasons, the names of dynamic libraries holding the packages start by \texttt{bb}.
1585 For instance, the package \texttt{wx} will be in the library \texttt{bbwx.dll} (Windows) or \texttt{libbbwx.so}
1590 % ==========================================
1596 \item The \texttt{include} command tells the interpreter to include a script file.
1597 \item Lines starting with a \texttt{\#} or with a \texttt{\//\//} are considered as comments by the interpreter.
1598 \item Lines between a line starting with a \texttt{\//*} an a line ending with a \texttt{*\//} are considered as comments by the interpreter.
1602 % ==========================================
1604 % ==========================================
1605 \subsubsection{Creating command line applications}
1606 \label{bbi-command-line-app}
1607 % ==========================================
1609 Now that you know how to create complex black boxes
1610 (with \texttt{define/endefine}), think
1611 back to the \texttt{workspace} object.
1612 Remember that it is also
1613 a \texttt{complex black box}.
1614 Actually, when you type interpreter commands
1615 outside a \texttt{define/endefine} block,
1616 you progressively define the \texttt{workspace}
1618 You can think of it like if at start the interpreter
1619 was issuing a command \texttt{'define workspace'}
1620 and then letting you define the interior of the box
1623 Remember that the command \texttt{inputs}
1624 allows to define an input of a complex box.
1625 Now, if you use the command \texttt{input}
1626 outside a \texttt{define/endefine} block then
1627 it defines an input of the \texttt{workspace} box,
1628 that is an input of the \emph{main program}.
1629 This input will then be connected to the
1630 parameters that the user passes to the command line.
1632 For example, consider the script :
1634 \begin{file}{add.bbs}
1638 input x a.In1 "first number to add"
1639 input y a.In2 "second number to add"
1644 The third and fourth lines define two inputs \texttt{x}
1645 and \texttt{y}. When you execute this script,
1646 you can pass these two arguments on the command line,
1654 You can also invoke \bbi the option \texttt{-h},
1655 which gives help on the \texttt{workspace} box :
1662 'x' <double> : first number to add
1663 'y' <double> : second number to add
1666 To get a better help, use the \texttt{description}
1667 and \texttt{author} commands :
1669 \begin{file}{add.bbs}
1671 description "Adds two numbers"
1672 author "foo@bar.com"
1675 input x a.In1 "first number to add"
1676 input y a.In2 "second number to add"
1681 Now if you ask for help on the \texttt{add} script, you get :
1688 'x' <double> : first number to add
1689 'y' <double> : second number to add
1692 Rather than getting the inputs of a script
1693 from the command line, you can ask \bbi to
1694 prompt the user for the values, using the \texttt{-t}
1699 x=[the program waits for user answer]2
1700 y=[the program waits for user answer]5
1704 \bbStudio is always compiled in graphical mode (with \wx), therefore
1705 you can also use the \texttt{-g} commutator.
1706 \bbi then prompts the user in graphical mode,
1707 displaying a dialog box for each input,
1708 like in fig. \ref{bb-input-dialog-box}.
1711 \caption{\label{bb-input-dialog-box}Input dialog box}
1713 \includegraphics[width=0.6\textwidth]{enter-the-value-of-x.png}
1717 % ==========================================
1722 \item The \texttt{input}, \texttt{description} and \texttt{author} commands,
1723 when they are used outside a \texttt{define/endefine} block allow
1724 to define the inputs, description and author of the main program.
1725 \item Inputs of the main program can be passed on the command line
1726 using the syntax \texttt{<input-name>=<value>}.
1727 No white space is allowed, if the value or the input name
1728 contains white spaces, enclose them
1729 between double quotes, e.g. \texttt{"parameter with white spaces = gnu's not unix"}.
1730 \item The \texttt{-h} option of \bbi prints help on the main program.
1731 \item The \texttt{-t} option of \bbi orders the program to prompt for its inputs in text mode.
1732 \item The \texttt{-g} option of \bbi orders the program to prompt for its inputs in graphical mode.
1735 % ==========================================
1737 % ==========================================
1738 \subsubsection{Using graphical interface boxes (widget boxes)}
1740 % ==========================================
1742 % ==========================================
1743 \subsubsection{Overview}
1744 \label{bbi-overview}
1745 % ==========================================
1747 Basic graphical interface components are provided in the package \texttt{wx},
1748 such as buttons, sliders, file open/save dialogs, etc.
1750 As first example, type the following commands in \bbi :
1757 When you type \texttt{enter} after the last line,
1758 a window pops up in which you can entrer a text.
1759 When you close the window, the text you entered is printed by
1760 the \texttt{print} command.
1762 Type \texttt{help wx}, you get something like :
1764 Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
1765 Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
1767 ColourSelector : Colour Selector dialog (bbfication of wxColourSele...
1768 ColourSelectorButton : A button which displays a colour picker dialog whe...
1769 CommandButton : Button which executes bbi commands
1770 DirectorySelector : Pops up a directory selection dialog (wxDirDialog)
1771 FileSelector : Pops up a file selection dialog for reading or sav...
1772 InputText : A zone in which the user can enter a text (wxTextC...
1773 LayoutLine : LayoutLine widget (wxBoxSizer)
1774 LayoutSplit : Widget which splits a window in two fixed size par...
1775 LayoutTab : LayoutTab widget (wxNotebook)
1776 OutputText : Text zone to be inserted into a window (wxStaticTe...
1777 RadioButton : RadioButton group widget 0-9 entries
1778 Slider : Slider widget (wxSlider)
1781 You can reproduce the same experiment as above using a
1782 \texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}..
1785 %There are two kinds of widgets : ``terminal'' widgets and ``container'' widgets.
1786 %The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets
1787 %are ``terminal'' widgets.
1788 %``container'' widgets are of another kind : they are
1789 There is a special kind of widget, called '\texttt{Layout}', designed to
1790 contain other widgets in order to build larger dialog boxes.
1791 For example, the \texttt{LayoutSplit} widget is a container which
1792 ``splits'' horizontally a window into two parts,
1793 each part including another widget.
1794 The size of the two parts can be adjusted by the user thanks
1797 The example \texttt{exampleLayoutSplit} demonstrates its use.
1798 Run it : it displays a window with two sliders.
1799 Move the sliders and close the window.
1800 Now look at the source file to see how this is done :
1802 \begin{file}{scripts/test/testSplit.bbs}
1811 connect s1.Widget s.Widget1
1812 connect s2.Widget s.Widget2
1818 First, the two sliders \texttt{s1} and \texttt{s2} are created.
1819 A \texttt{LayoutSplit} box \texttt{s} is also created.
1820 The \texttt{connect} commands then ``includes'' the sliders in the
1822 The input \texttt{Widget} is common to all widget boxes :
1823 every widget can be inserted into another widget.
1824 The outputs \texttt{Widget1},\texttt{Widget2} are specific of \emph{layout}
1826 (in \bbi type \texttt{help Slider} :
1827 you will see the output \texttt{Widget};
1828 type \texttt{help LayoutSplit} :
1829 you will see the inputs \texttt{Widget1} and \texttt{Widget2}
1830 and the output \texttt{Widget}).
1831 When you connect the \texttt{Widget} output of a box
1832 to the \texttt{Widget}i input of a layout widget,
1833 you order to include the widget in the layout.
1834 Of course, the order of connection is important.
1835 In our case, the slider \texttt{s1} is included first,
1836 then the slider \texttt{s2} : \texttt{s1} will be placed
1837 on top of \texttt{s2} (the \texttt{LayoutSplit} box is
1838 implemented that way, but this is arbitrary choice).
1840 Right now, there are only \emph{three} layout widgets in the \texttt{wx} package :
1842 \item {the \texttt{LayoutSplit} widget} we just described, the \texttt{LayoutLine} , and the \texttt{LayoutTab}
1845 \item {the \texttt{LayoutLine} widget} can have multiple children (Widgeti inputs) and
1846 divides its window into as much parts as children,
1847 each part of equal size.
1848 The orientation of the \texttt{LayoutSplit} or of the \texttt{LayoutLine} can be changed by the input \texttt{Orientation}.
1849 %See the example \texttt{example}.
1850 With only those two layout widgets you can already create
1851 complex dialog boxes (of course layouts can be nested, which leads to tree-like structures of widgets). \\
1852 See the script \texttt{exampleComplexLayoutSplit\_In\_LayoutSplit} for an example.
1854 \item {The \texttt{LayoutTab} widget} is based on the \texttt{wxNotebook.}\\
1855 The label of each 'note book' is the name of the object it contains.
1862 %One word about a special widget in the package \texttt{wx} :
1863 %the \texttt{Button}... to be continued.
1865 % ==========================================
1866 \subsubsection{Deeper in the boxes}
1867 \label{bbi-deep-box}
1868 % ==========================================
1870 Any box has three mandatory Inputs :
1872 \item {\bf\emph{BoxExecute}} : Any signal received by this input executes the box
1873 \item {\bf\emph{Boxchange}} : Signals any modification of the box. This output may be connected if necessary to the \emph{BoxExecute}
1874 input of an other box, further within the execution pipeline.
1875 \item {\bf\emph{BoxProcessMode}} : Sets the processing mode of the box :
1877 \item {\bf\emph{Pipeline}} :% bbBackwardUpdate() calls Process() only if Status == MODIFIED \\
1878 The box executes itself only when an input was changed (normal pipeline processing).
1879 \item {\bf\emph{Reactive}} : %bbSetModifiedStatus() calls bbUpdate() \\
1880 Re-processes immediately when \emph{any input} changes.\\
1881 To be more selective, better use \texttt{connect A.BoxChange \emph{currentBox}.BoxExecute}.
1882 \item {\bf\emph{Always}} :% bbUpdate() always calls Process. \\
1883 Usefull for 'sources', that must be processed, even when no input changed (e.g. : FileSelector, ColorSelector)\\
1884 This one is not end user intended (for Package developer only)
1888 Any widget box has five Inputs, that will be dealt with only if the box is not connected to the \emph{Widget}i of any \emph{Layout box} :
1890 \item {\bf\emph{WinHeight}} : Height of the window
1891 \item {\bf\emph{WinWidth}} : Width of the window
1892 \item {\bf\emph{WinTitle}} : Title of the window
1893 \item {\bf\emph{WinClose}} : Any received signal closes the window
1894 \item {\bf\emph{WinHide}} : Any received signal hides the window
1895 \item {\bf\emph{WinDialog}} : When set to 'true', creates a \emph{dialog window}, that blocks the pipeline until it is closed (\emph{modal})
1899 Any \emph{Layout box} (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has one or more mandatory Inputs :
1901 \item {\bf\emph{Widget}}\texttt{i} : e.g. a \emph{LayoutSplit} box (Widget which splits a window in two resizeable parts)
1902 has two Input parameters \emph{Widget1} and \emph{Widget2}, used to embed the child windows.\\
1903 e.g. a \emph{LayoutLine} divides the window in up to 9 (depending on the number of inputs \emph{Widget}i) fixed size parts.
1907 Any widget box has one mandatory Output :
1910 \item {\bf\emph{Widget}} : that is the \texttt{wxWindow} itself. If it's not connected to the \texttt{Widget}\emph{i} of any \emph{Layout box}, it
1911 will popup. If it's connected to the \texttt{Widget}\texttt{\emph{i}} of any \texttt{Layout box},
1912 it will be embedded in its parent window.
1918 % ==========================================
1919 \subsection{More on ...}
1921 % ==========================================
1923 % ==========================================
1924 %\subsubsection{Black box packages}
1925 %\label{bbi-more-on-packages}
1926 % ==========================================
1927 %There are various others user-intended packages :
1930 %---> Were moved in a 'Reference Manual' ?\\
1931 %---> Any suggestion welcome!
1939 % ==========================================
1940 \subsubsection{Pipeline processing}
1941 \label{bbi-more-on-pipeline-processing}
1942 % ==========================================
1944 \item the ``control'' mechanism in bbi.
1946 When a box is requested to update itself, it asks (recursively) each one of its inputs if it was modified.\\
1947 In normal pipe-line mode, it will be re-processed if at least one of its imputs was actually modified, as the output of a previous box.
1949 %(switch exec commands, e.g. Button)
1950 \item the role of ProcessMode to update widgets.
1953 %\subsubsection{Advanced issues}
1954 %\paragraph{Reducing the number of inputs of a box}
1956 % ==========================================
1957 %\subsubsection{Errors}
1958 %\label{bbi-more-on-errors}
1960 % ==========================================
1961 \subsubsection{Creating and using your own uninstalled version of bbStudio}
1962 \label{bbi-more-on-your_own_version}
1964 Suppose you want to run your own uninstalled version (say : you downloaded and compiled the
1965 cvs version in order to use a recently commited patch, but you want to be able
1966 to still use the standard version).
1970 \item cvs checkout the sources :
1975 create a build directory
1979 \item cd in the build directory:
1988 Don't forget to switch ON the flag \texttt{BBTK\_COMPILE\_DEBUG\_MESSAGE} \\
1989 (see figure : \ref{bb-ccmake})
1992 \caption{\label{bb-ccmake}Running ccmake}
1994 \includegraphics[width=0.6\textwidth]{ccmake.png}
1998 \item As usual, type \texttt{c} until there is no longer any area quoted with a * (or highlighted in red)\\
1999 Ask for generation (type \texttt{g} -once is always enough-)
2001 \item Ask for compilation and link.
2007 The dynamic libraries (\texttt{.dll} or \texttt{.so} and the executable programs will be created in the \texttt{bin}
2008 directory of the built tree.
2010 \item choose to install or not your own version.
2014 Linux users : Don't forget to \texttt{sudo} before.
2016 % ==========================================
2023 % ==========================================
2024 %\vspace{0.5cm}\hrule \\
2026 \section{Using third party Package}
2027 \label{Third_Party_Package}
2028 % ==========================================
2029 % ==========================================
2030 \subsection{Plugging in a Package}
2031 \label{Plugging_in_a_Package}
2032 % ==========================================
2034 \bbStudio makes it easy for you : in the menu \texttt{Tools} just click on the
2035 option \texttt{Plug Package}. You will be asked to to '\texttt{Select
2036 package directory}'. Browse untill you find the the install tree, or the the build tree,
2037 depending whether you installed the package or not.\\
2039 \bbStudio will update the Configuration file, generate the 'Package
2040 documentaion', and update the 'Box List'.\\
2041 You will be able to use the new package just as you did for any other \bbtk
2044 % ==========================================
2045 \subsection{Hard incorporating of a Package}
2046 \label{Hard_incorporating_of_a_Package}
2047 % ==========================================
2049 If the Package you want to use is supplied in a non standard way (e.g. : you
2050 where given one ore more dynamic libraries (\texttt{.dll} or \texttt{.so}), and
2051 one or more directories containing \bbtk scripts (\texttt{.bbs}), you will have
2052 to proceed to some (simple) manual operations.\\
2053 \texttt{Nota bene} : This way is hightly discouraged !
2055 % ==========================================
2056 \subsubsection{More on the configuration file}
2057 \label{The_configuration_file}
2058 % ==========================================
2060 First, have a glance at the Configuration, just clicking on \texttt{Config} button of the \texttt{Command} part toolbar.
2062 You'll get something like :
2068 bbtk_config.xml : [/home/jpr/Creatis/bbtk/binLIN/bin/bbtk_config.xml]
2069 Documentation Path : [/home/jpr/Creatis/bbtk/binLIN/bin/../share/bbtk/doc]
2070 Data Path : [/home/jpr/Creatis/bbtk/binLIN/bin/../share/bbtk/data]
2071 Temp Directory : [/home/jpr/Creatis/bbtk/binLIN]
2072 File Separator : [/]
2075 --- [/home/jpr/Creatis/bbtk/binLIN/bin/../share/bbtk/bbs]
2076 --- [/home/jpr/Creatis/bbtk/binLIN/share/bbtk/bbs]
2079 --- [/home/jpr/Creatis/bbtk/binLIN/bin]
2080 --- [/home/jpr/Creatis/bbtk/binLIN/bin/../lib]
2081 --- [/home/jpr/Creatis/bbtk/binLIN/bin]
2082 --- [/home/jpr/Creatis/bbtk/binLIN/bin\Debug]
2083 --- [/home/jpr/Creatis/bbtk/binLIN/bin\Release]
2086 (depending on who you are, and whether \texttt{bbStudio} is installed or not.)\\
2088 Note the two main parts : \texttt{BBS Paths} and \texttt{PACKAGE Paths}
2089 \subsubsection{How bbStudio uses the Configuration file}
2090 \label{How_bbStudio_uses_the_Configuration_file}
2093 At start, \bbi tries to open an \texttt{xml}
2094 configuration file named \texttt{bbtk\_config.xml}.
2097 \item The current directory
2098 \item The subdir \texttt{.bbtk} of the user's home directory.
2100 \item On \texttt{Unix}, the home directory is the
2101 one stored by the environnement variable \texttt{HOME},
2102 typically \texttt{/home/username}.
2103 \item On \texttt{Windows}, the home directory is
2104 the user's profile directory stored by the environnement
2105 variable \texttt{USERPROFILE},
2106 typically \texttt{C:\\...}.
2108 \item If none of these two paths contains the file then it creates
2109 a new one in the \texttt{.bbtk} directory.
2113 To use a third party Package, you will have to update it.\\
2115 \subsubsection{Modifying the Configuration file}
2116 \label{Modifying_the_Configuration_file}
2118 Just use the \texttt{Open bbtk Config file} option of the \texttt{Files} of the \bbStudio menu.
2120 You will get something like :
2123 <description> Sets the search directories in the build tree </description>
2125 <bbs_path> /home/jpr/Creatis/bbtk/binLIN/share/bbtk/bbs </bbs_path>
2126 <package_path> /home/jpr/Creatis/bbtk/binLIN/bin </package_path>
2128 <package_path> /home/jpr/Creatis/bbtk/binLIN/bin\Debug </package_path>
2129 <package_path> /home/jpr/Creatis/bbtk/binLIN/bin\Release </package_path>
2131 <data_path> </data_path>
2133 <default_temp_dir> /home/jpr/Creatis/bbtk/binLIN </default_temp_dir>
2137 To use a new Package :
2140 After the already existing \texttt{xml} tags
2142 (i.e. the lines begining by
2143 \texttt{<bbs\_path>}
2146 \texttt{</bbs\_path>}),
2147 you can add paths to :
2149 \item A custom folder in which to search for \texttt{.bbs} scripts (\texttt{include} command of \bbins) by adding
2150 an \texttt{xml} tag:\\
2151 \texttt{<bbs\_path>}
2152 \emph{complete\_path\_to\_scripts\_folder}
2153 \texttt{<\/bbs\_path>}.
2157 After the already existing tags
2158 \texttt{package\_path}
2159 (i.e. the lines begining by
2160 \texttt{package\_path}
2163 \texttt{/package\_path}),
2164 you can add paths to :
2166 \item A custom folder in which to search for packages (the dynamic libraries
2167 (\texttt{.dll} or \texttt{.so}, called with the \texttt{load} command of \bbins) by adding an \texttt{xml} tag :\\
2168 \texttt{<package\_path>}
2169 \emph{complete\_path\_to\_dynamic\_library\_folder}
2170 \texttt{<\/package\_path>}.
2176 % ==========================================
2177 \subsection{Updating the documentation}
2178 \label{Updating_the_documentation}
2179 % ==========================================
2180 You may add your own boxes (simple boxes, if you are aware enough in \CPP
2181 language), or complex boxes if you are aware enough in bbtk scripting).
2183 To be able to use the Help tools as well as the features provided by this package,
2185 option \texttt{Regenerate package doc} in the menu \texttt{Tools} of \texttt{bbStudio}.\\
2186 You'll be prompted for the Package name. Avoid using the \texttt{-a} option (Regenerate all), since it's time consumming.
2188 To benefit the features of Box indexing you must use the
2189 option \texttt{Regenerate Boxes Lists} in the menu \texttt{Tools} of \texttt{bbStudio}.\\
2192 % ==========================================
2193 \subsection{Using the package}
2194 \label{Using_the_package}
2195 % ==========================================
2197 The only thing you have to do is to \texttt{load} the package, within the script, or from the
2198 \texttt{Command} part, and enjoy the black boxes it contains.
2200 % ==========================================
2201 \subsection{Packages you'll probably want to use }
2202 \label{Packages_you_ll_want_to_use}
2203 % ==========================================
2205 \item{\texttt{creaLib}} \\
2206 a.k.a \texttt{crea}. It's a set of 'low level' utilities, needed by other
2207 packages (an, sure, useful as well for people that doesn't use bbtkns.
2209 \item{\texttt{creaContours}} \\
2210 Provides sophisticated widgets for managing 3D R.O.I. (Regions of interest)
2211 \item{\texttt{creaImageIO}} \\
2212 Allows browsing, selectionning, ordering directories containing images of almost any type
2218 % ==========================================
2219 %\vspace{0.5cm}\hrule \\
2220 \section{Using black boxes in \CPP programs}
2222 % ==========================================
2224 A very useful feature is that you may use any black box within a \CPP program without worrying about \texttt{wxWigets} main window.\\
2226 Let's look a the following bbs script :
2233 # Create the Objects
2236 new LayoutLine layout
2238 # Graphical pipeline
2239 connect slider.Widget layout.Widget1
2240 connect text.Widget layout.Widget2
2242 # Execution pipeline
2243 connect slider.BoxChange text.BoxExecute
2244 connect slider.Out text.In
2250 User wants to create a slider and an output text, within a LayoutLine, and display the slider value in the output text.\\
2251 Think about the (little!) nightmare to code the same, in 'raw C++', using wxWidgets.\\
2253 Using the standalone application \texttt{bbc} you just 'convert' the script.
2256 #include <bbwxSlider.h>
2257 #include <bbwxOutputText.h>
2258 #include <bbtkFactory.h>
2259 #include <bbwxLayoutLine.h>
2261 int main(int argv, char* argc[])
2263 // we need to intanciate a bbtk::Factory to be aware of the adaptors
2264 bbtk::Factory::Pointer factory = bbtk::Factory::New();
2266 // Load the packages
2268 factory->LoadPackage("std");
2269 factory->LoadPackage("wx");
2271 // Create the Objects
2272 // ------------------
2273 bbwx::Slider::Pointer slider = bbwx::Slider::New("slider");
2274 bbwx::OutputText::Pointer text = bbwx::OutputText::New("text");
2275 bbwx::LayoutLine::Pointer layout = bbwx::LayoutLine::New("layout");
2277 // Graphical pipeline
2278 bbtk::Connection::Pointer c1 = bbtk::Connection::New(slider,"Widget",
2281 bbtk::Connection::Pointer c2 = bbtk::Connection::New(text,"Widget",
2284 // Execution pipeline
2285 // ------------------
2287 // We have to pass the 'factory', in order to call automatically an adaptor,
2289 bbtk::Connection::Pointer s2t = bbtk::Connection::New(slider,"Out",
2292 bbtk::Connection::Pointer c3 = bbtk::Connection::New(slider,"BoxChange",
2294 layout->bbSetInputWinDialog(true);
2298 layout->bbExecute();
2301 catch (bbtk::Exception e)
2303 bbtk::MessageManager::SetMessageLevel("Error",1);
2311 % ==========================================
2312 \section{Language reference}
2313 \label{bbi-reference}
2314 % ==========================================
2317 % ==========================================
2318 \subsection{Pipeline creation and execution related commands}
2319 \label{bbi-reference-creation-execution}
2320 % ==========================================
2321 See table \ref{bbi-reference-box}
2323 % ==========================================
2325 \caption{\label{bbi-reference-box} \bbi pipeline creation and execution related commands.}
2327 \begin{tabular}{|lcm{6cm}|}
2329 Command & Parameters & Effect \\ \hline
2331 \texttt{new} & \texttt{<boxtype>} \texttt{<box-name>}&
2332 Creates a box of type \texttt{boxtype} and name
2333 \texttt{box-name}.\\ \hline
2335 \texttt{delete} & \texttt{<box-name>} &
2336 Destroys the box named \texttt{box-name}.\\ \hline
2338 \texttt{connect} & \texttt{<box1.output>} \texttt{<box2.input>} &
2340 \texttt{output} of the box named \texttt{box1}
2341 to the input \texttt{input} of the box named \texttt{box2} \\ \hline
2343 \texttt{set} & \texttt{<box.input>} \texttt{<value>} &
2344 Sets the input \texttt{input} of
2345 the box named \texttt{box} to the value \texttt{value}.
2346 An \texttt{adaptor} must exist
2347 in the packages loaded which converts a \texttt{std::string}
2348 to the type of the input \texttt{input}. \\ \hline
2350 \texttt{print} & \texttt{<string>} &
2351 Prints the string after substituting each token of the form \texttt{\$box.output\$} by the adaptation to string of the value of the
2352 output \texttt{output} of the box named \texttt{box}.
2353 An \texttt{adaptor} must exist
2354 in the packages loaded which converts
2355 the type of the output \texttt{output}
2356 to a \texttt{std::string}.
2359 \texttt{exec} & \texttt{<box-name>} &
2360 Executes the box named \texttt{box-name}.
2362 connected to its inputs
2363 are also processed recursively (pipeline processing).\\ \hline
2364 \texttt{exec} & \texttt{freeze} &
2365 Allows to block execution commands while keeping definition commands active.(This one is not for end user)\\ \hline
2366 \texttt{exec} & \texttt{unfreeze} &
2367 Turns back to 'normal' mode (This one is not for end user).\\ \hline
2370 % ==========================================
2374 % ==========================================
2375 \subsection{Interpreter related commands}
2376 \label{bbi-reference-interpreter}
2377 % ==========================================
2378 See table \ref{tabbbi-reference-interpreter_1} and \ref{tabbbi-reference-interpreter_2}
2379 % ==========================================
2381 \caption{\label{tabbbi-reference-interpreter_1}\bbi intepreter related commands (part 1).}
2383 \begin{tabular}{|lcm{6cm}|}
2385 Command & Parameters & Effect \\ \hline
2387 \texttt{author} & \texttt{<author-name>} &
2388 Adds the string \texttt{<author-name>} to the author information of the black box being defined \\ \hline
2390 \texttt{category} & \texttt{<category-name>} &
2391 Adds the string \texttt{<category-name>} to the category information of the black box being defined \\ \hline
2394 Prints help on available commands \\ \hline
2396 & \texttt{<command-name>} &
2397 Prints help on the command \texttt{command-name} \\ \hline
2399 & \texttt{packages} &
2400 Prints help on available packages and their box types
2401 (without description)\\ \hline
2403 & \texttt{<package-name>} &
2404 Prints help on the package \texttt{package-name} and its boxes
2405 (with brief description).
2406 The package must have been previously loaded \\ \hline
2408 & \texttt{<box-type>} &
2409 Prints help (with full description) on the type of box
2411 The box type must belong to a package which has been previously loaded \\ \hline
2413 & \texttt{<debug-directive>} &
2415 Prints debug info on living bbtk objects containing the string \texttt{expr} (default expr='').
2416 \texttt{-C} checks the factory integrity.
2417 \texttt{-D} turns on objects debug info after main ends\\ \hline
2419 \texttt{include} & \texttt{<file-name>} &
2420 Includes and executes the content of the file named \texttt{file-name}
2421 exactly like if you were typing its content at the place were the
2422 \texttt{include} command is. \\ \hline
2424 \texttt{load} & \texttt{<package-name>} &
2425 Loads the package \texttt{package-name} (use it only if you know that you won't work with complex black boxes) \\ \hline
2427 \texttt{include} & \texttt{<package-name>} &
2428 Loads the package \texttt{package-name} and includes all the complex black boxes that comes with it \\ \hline
2430 \texttt{kind} & \texttt{<box kind>} &
2431 Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline
2436 % This arbitrary part1/part2 is to avoid to have all the tables at the end of the docoment ...
2440 \caption{\label{tabbbi-reference-interpreter_2}\bbi intepreter related commands (part 2).}
2442 \begin{tabular}{|lcm{6cm}|}
2444 Command & Parameters & Effect \\ \hline
2445 \texttt{unload} & \texttt{<package-name>}&
2446 Unloads the package \texttt{package-name}.
2447 The package must have been previously loaded.
2448 No box of a type defined in this package must still exist.\\ \hline
2450 \texttt{message} & \texttt{<category>} \texttt{<level>} &
2451 Sets the level of verbosity of \bbi for the category of messages
2452 \texttt{category} to \texttt{level}.\\ \hline
2453 %See \ref{verbosity}.
2455 \texttt{config} & - & Displays the Configuration parameters\\ \hline
2457 \texttt{reset} & - & Deletes all boxes and unloads all packages so
2458 that \bbi gets back to its initial state \\ \hline
2460 \texttt{quit} & - & Exits the interpreter (Don't use it under \bbStudions)\\ \hline
2464 % ==========================================
2468 % ==========================================
2469 \subsection{Complex black box definition related commands}
2470 \label{bbi-reference-black-box-definition}
2471 % ==========================================
2473 See table \ref{bbi-reference-complex-box}
2474 % ==========================================
2476 \caption{\label{bbi-reference-complex-box} \bbi complex black box definition related commands.}
2478 \begin{tabular}{|lcm{6cm}|}
2480 Command & Parameters & Effect \\ \hline
2483 \texttt{define} & \texttt{<box-type>} &
2484 Starts the definition of a complex black box of type
2485 \texttt{box-type}\\ \hline
2487 \texttt{endefine} & - &
2488 Ends the definition of a complex black box type\\ \hline
2490 \texttt{author} & \texttt{<string>} &
2491 Sets the author(s) of the complex black box currently being defined \\ \hline
2493 \texttt{description} & \texttt{<string>} &
2494 Sets the description of the complex black box currently being defined \\ \hline
2496 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
2497 Defines a new input for the current complex black box,
2498 named \texttt{name}.
2499 It is defined as corresponding to
2500 the input \texttt{input} of the box \texttt{box}.
2502 \texttt{<help>} is the help string for the new input.
2503 The box \texttt{box} must already have been created in the complex box
2504 and of course have an input named \texttt{input}.\\ \hline
2506 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
2507 Defines a new output for the current complex black box,
2508 named \texttt{name}.
2509 It is defined as corresponding to
2510 the output \texttt{output} of the box \texttt{box}.
2511 \texttt{<help>} is the help string for the new output.
2512 The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}. \\ \hline
2517 % ==========================================
2521 \section{Install and run time issues}
2525 For some strange reasons (?!?), at \texttt{cmake} time, you may be warned that an error occured while documentation generation.\\
2526 Take it easy, \texttt{make} again!\\
2528 \item{\bbStudio} is written using the Advanced User Interface library of wxWidgets.
2529 If, after some hazardous floating/docking operations onto the frame, you feel
2530 very unhappy with the result, just remove from the hidden directory
2531 \texttt{.bbtk} the file named \texttt{bbStudio.aui}. \\
2536 %\section{Conclusion}