]> Creatis software - bbtk.git/blob - kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex
*** empty log message ***
[bbtk.git] / kernel / doc / bbtkUsersGuide / bbtkUsersGuide.tex
1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
3 \input{config.tex}
4 \begin{document}
5 \bbtkGuide[User's Guide]
6 % ==========================================
7
8
9 % ==========================================
10 \newpage
11 \hrule
12 \section{Introduction}
13 % ==========================================
14 \subsection{What is bbtk ?}
15 % ==========================================
16 \BBTK(\bbtkns) is a set of tools 
17 (\CPP libraries and executables) 
18 providing a \CPP framework for the definition 
19 of elementary processing \emph{units}, called {\bf black boxes}, 
20 and the definition and execution of processing \emph{chains} 
21 made up of these black boxes. \\
22
23 %It's a part of the \texttt{Creatools suite} composed mainly of :
24 %\begin{verbatim}
25 % bbtk
26 % creaContours
27 % creaImageIO
28 % creaLib
29  
30 %\end{verbatim}
31 %which depend on the OpenSource libraries: 
32 %\begin{verbatim}
33 % gdcm 
34 % itk
35 % vtk
36 % wxWidgets
37 %\end{verbatim}
38
39 % ==========================================
40 \subsubsection{The black box philosophy}
41 % ==========================================
42
43 \href{http://www.answers.com/topic/black-box-theater}{The Answers Dictionary} defines a {\bf black box} as 
44 \emph{``A device or theoretical construct with known or specified performance characteristics 
45 but unknown or unspecified constituents and means of operation''} \\
46 \href{http://en.wikipedia.org/wiki/Black_box_\%28disambiguation\%29}{Wikipedia}
47 defines a {\bf black box} as 
48 \emph{``any component in a system in which only the input and output 
49 characteristics are of interest, without regard to its internal mechanism 
50 or structure''}. \\
51 We should merge these definitions. : 
52 not only the inputs and outputs are of interest but also 
53 \emph{what the box does} !
54 Hence, we would say that a black box is any \emph{\bf documented} 
55 component of a system, letting the user know  
56 \emph{\bf what} the box is supposed to do and 
57 \emph{\bf how to use it}
58 but not \emph{\bf how it does it}. \\
59
60 \BBTK provides a systematic framework 
61 to encapsulate (or ``wrap'') any 
62 existing \texttt{C} or \CPP processing code into an object 
63 (a black box) having a {\bf generic symbolic interface}, where 
64
65 \begin{itemize}
66 \item{\bf generic} means that the interface is \emph{the same} 
67 for all boxes. Hence one does not need to know which particular 
68 method allows, say, to set a particular input or 
69 get a particular output of the box. 
70 One can use a black box in a purely abstract way. 
71 \item{\bf symbolic} means that a particular 
72 input or output is referenced by a 'name', that is by a symbol 
73 which identifies the input or output. 
74 It also means that symbolic information (text) is 
75 attached to a box: description of the box, author, 
76 description of its inputs and outputs, etc.
77 \end{itemize}
78
79 (Actually, genericity is achieved because the interface is symbolic. 
80 We let you think about this\dots)
81
82 Of course, symbolic data attached to a box may be 
83 {\bf queried} : what are the inputs/outputs of the box ? 
84 what are their type ? their description ? etc.
85 This allows {\bf automatic documentation} of boxes. 
86
87 The abstract definition of black boxes is the most basic 
88 aspect of \BBTK architecture. 
89 Another key aspect is the groupement of black boxes into 
90 so called {\bf packages}, 
91 which are \emph{dynamic libraries} which can also 
92 be queried, in particular about the boxes they provide. 
93 The package structure then offers a mechanism which 
94 is like a \emph{'plug-in'} mechanism.
95 \BBTK provides the methods to load a package at run-time, 
96 and create instances of the boxes it contains. 
97
98 These two mechanisms (black boxes and packages) 
99 then gives the way to:
100
101 \begin{itemize}
102 \item The definition of an {\bf interpreted script language}, 
103 which allows to manipulate packages and boxes very easily in symbolic way. 
104 \BBTK provides one :  \bbs (the Black Box Script language) and its interpreter
105 \bbi (the Black Box Interpreter). 
106 \item {\bf Automatic documentation} of existing packages. 
107 \texttt{html} documentation of packages is proposed by 
108 \bbStudions.
109 \end{itemize}
110
111 Finally, these different components allow {\bf efficient} :
112
113 \begin{itemize}
114 \item {\bf capitalization and reuse} of existing processing units, 
115 including {\bf documentation} 
116 \item {\bf testing, prototyping} in a very simple script language
117 \item {\bf inter-operability} between atomic processings which 
118 have been written by different persons, using different libraries, etc. 
119 \end{itemize}
120
121 % ==========================================
122 \subsubsection{\bbtk components}
123 % ==========================================
124 \BBTK includes :
125 \begin{itemize}
126   \item A \CPP {\bf\emph{library}} - called \bbtk - which defines a framework 
127     (abstract classes) to develop black boxes and store them into 
128     dynamic libraries, called black box \emph{packages}.
129   \item Different {\bf\emph{"core" black box packages}} :
130     \begin{itemize}
131       \item {\bf\emph{std}} : the 'standard' package including basic useful boxes.
132       \item {\bf\emph{wx}} : basic graphical interface elements (widgets : sliders, buttons, etc. based on the \texttt{wxWidgets} library).  
133       \item {\bf\emph{itk}} : the basic image processing package, based on the \itk library.
134       \item {\bf\emph{vtk}} : the basic images and surfaces processing and visualization package, based on the \vtk library.
135       \item {\bf\emph{wxvtk}} : widget boxes based on the \vtk library (2D and 3D vizualization and
136       interaction).
137       %\item {\bf\emph{creaImageIO}} : Provides hight level widgets to read images, including DICOM.
138       \item {\bf\emph{toolsbbtk}} : Tools for bbtk administration and package development.     
139     \end{itemize}
140   \item A {\bf\emph{Developement environment}}, called \bbStudio, which provides
141     \begin{itemize}
142       \item An online {\bf\emph{script editor and interpretor}}
143       \item A powerful html {\bf\emph{Help environment}}, integrating :       
144         \begin{itemize}
145           \item Online documentation scaning
146           \item Retreiving boxes on various criterions
147           \item Checking Demo and examples
148         \end{itemize}
149       \end{itemize}
150       \item An standalone {\bf\emph{interpreter}}, called \bbins, which allows to 
151            execute \bbs scripts or commands.
152       \item {\bf\emph{Various Development Utilities}} :
153          \begin{itemize}
154             \item \bbfy generates the \CPP code of a black box from a 
155                description file written in \texttt{xml}.
156                 %\item \bbdoc generates the html documentation of a black box package 
157                 %(author, description, description of its black boxes : 
158                 %author, description, inputs, outputs, and so on).
159             \item \bbCreatePackage allows to create the basic file architecture. 
160                to start the development of a new black box package.
161             \item \bbCreateBlackBox allows to create the basic file architecture. 
162                to start the development of a new black box, that will be included in an already existing package.              
163             \item \bbs2cpp translates a \texttt{.bbs} script into a \CPP file.
164             \item \bbc (sorry : Linux Only, for the moment) that compiles \texttt{.bbs} scripts into executables.
165             \item \bbRegeneratePackageDoc which creates the html documentation of the Package.
166             \item \bbRegenerateBoxesLists which creates the html pages of the various lists of all the currenly installed boxes.
167             \item \bbPlugPackage which automatically incorporates a new package.                  
168          \end{itemize}
169       \item A full {\bf\emph{documentation}} printable (pdf), browsable (html),
170       queryable throught keywords.        
171 \end{itemize}
172
173 The general architecture of \BBTK 
174 is shown in figure \ref{bb-architecture}.
175
176 \begin{figure}[!ht]
177 \caption{\label{bb-architecture}\BBTK architecture}
178 \begin{center}
179 \includegraphics[width=0.6\textwidth]{bb-architecture.png}
180 \end{center}
181 \end{figure}
182
183 %%\newpage
184
185 % ==========================================
186 \subsection{Content of this guide}
187 % ==========================================
188
189
190
191 % ==========================================
192 \newpage
193 \hrule
194 \section{Getting started with bbStudio}
195 \label{bbStudio}
196 % ==========================================
197
198
199 % ==========================================
200 \subsection{The interface}
201 % ==========================================
202
203
204 %\vspace{0.5cm}\hrule
205 %\section{The Development environment (bbStudio)}
206 %\label{bbStudio}
207
208 Just run it, typing in a console \bbStudio 
209 or clicking on its icon or its menu entry.
210 You'll get something like in figure 
211 \ref{bbi-fig-bbStudio-gui-start}
212 (the exact appearance of \bbStudio is Operating System and \bbtk version dependent).
213
214 At start, \bbStudio opens with a very minimal 'How to use' in the middle. 
215 Don't forget to read it : it will vanish at the first mouse click. 
216
217
218 \begin{figure}[!ht]
219 \caption{\label{bbi-fig-bbStudio-gui-start}The bbStudio Development environment interface at start time}
220 \begin{center}
221 \includegraphics[width=0.7\textwidth]{bbStudioMainPageStart.png}
222 \end{center}
223 \end{figure}
224
225 %Let's have a look at the resized window :
226 %\begin{figure}[!ht]
227 %\caption{\label{bbi-fig-bbStudio-gui}The bbStudio Development environment interface}
228 %\begin{center}
229 %\includegraphics[width=0.7\textwidth]{bbStudioMainPage.png}
230 %\end{center}
231 %\end{figure}
232
233 The interface is divided into four parts : \texttt{Files}, \texttt{Messages},
234  \texttt{Command}, \texttt{Help}.
235 It is written using the Advanced User Interface library of wxWidgets
236 (a.k.a. AUI),
237 whose 'docking manager' allows windows and toolbars to be floated/docked 
238 onto a frame.
239 Feel free to resize/reposition any part you want.
240 Your preferences will be kept next time you run again \bbStudions. 
241
242 %Please don't use this feature at learning time 
243 %(the snapshots of this document wouldn't match with your screen ...)
244
245 \subsubsection{'Files' part}
246 \label{bbi-FilesPart}
247
248 It's the \bbs script editor.
249
250 If you load a file holding a script, it will be displayed here, and you'll be
251 able to modify it, to save it, to save-as it, to run it, using the
252 lower toolbar (see figure \ref{lowertoolbar})
253
254 \begin{figure}[!ht]
255 \caption{\label{lowertoolbar}The 'Files' lower tool bar}
256 \begin{center}
257 \includegraphics[width=0.7\textwidth]{lowertoolbar2.png}
258 \end{center}
259 \end{figure}
260
261
262 % \begin{itemize}
263 %   \item {\bf\emph{New file}} : Create a new file to hold a script
264 %   \item {\bf\emph{Open file}} : Open an already existing file holding a script 
265 %   \item {\bf\emph{Close file}} : Close a file holding a script
266 %   \item {\bf\emph{Save file}} : Save he current file (if modified)
267 %   \item {\bf\emph{Save file as}} : Save he current file under a different name
268 %   \item {\bf\emph{Run file}} : Execute the script you just loaded/modified/written
269 %   \item {\bf\emph{cursor position}} : column number : line number   
270 % \end{itemize}
271
272
273 \subsubsection{'Messages' part}
274 \label{bbi-MessagesPart}
275
276 Two kinds of messages will be output here:\\
277 System messages : produced by the kernel, in case of a user mistyping, or an execution error\\
278 Script messages : produced by the \bbtk equivalent of \texttt{printf} 
279 or \texttt{std::cout} in user programs.
280
281 \subsubsection{'Command' part}
282 \label{bbi-CommandPart}
283
284 You can type here \bbs commands which are executed on the fly.
285 The buttons are shortcuts to usual commands.
286
287 \subsubsection{'Help' part}
288 \label{bbi-HelpContentsPart}
289
290 The 'Help' part of \bbStudio is used to browse the html help of \BBTKns.
291
292
293 % ==========================================
294
295
296
297
298 % ==========================================
299 % ==========================================
300 % ==========================================
301 % ==========================================
302 % ==========================================
303
304
305
306
307 % ==========================================
308
309 %\newpage
310
311 % ==============================================
312 \subsection{Running Demos and Examples}
313 % ==============================================
314
315 In the 'Help' part (See figure \ref{HelpContents}), select \texttt{Examples} link.
316
317 \begin{figure}[!ht]
318 \caption{\label{HelpContents}\bbStudio 'Help' panel}
319 \begin{center}
320 \includegraphics[width=0.7\textwidth]{HelpContents.png}
321 \end{center}
322 \end{figure}
323
324 %\newpage
325
326 You will get a list of examples (See figure \ref{example}).
327
328 Note : due to an unfixed bug in Linux, you have to click on 'reload' to get it. \\ 
329
330
331 \begin{figure}[!ht]
332 \caption{\label{example}Examples list}
333 \begin{center}
334 \includegraphics[width=0.7\textwidth]{example.png}
335 \end{center}
336 \end{figure}
337
338
339 %\begin{figure}[!ht]
340 %\caption{\label{BoxCategories}Box Categories}
341 %\begin{center}
342 %\includegraphics[width=0.7\textwidth]{BoxCategories.png}
343 %\end{center}
344 %\end{figure} 
345
346
347 Select \texttt{wx::exampleSlider}.
348  
349 \begin{figure}[!ht]
350 \caption{\label{exampleSlider}Html documentation of example 'exampleSlider'}
351 \begin{center}
352 \includegraphics[width=0.7\textwidth]{exampleSlider.png}
353 \end{center}
354 \end{figure}
355
356 You can see information on the example and 
357 the graphical representation of the workflow defined by the script
358 (the elementary boxes that compose it, and their connections, see figure \ref{exampleSlider}).
359
360 Click on \texttt{[source]}, it will be loaded
361 in the 'Files' part, within the script editor (See figure \ref{exampleSliderSource});
362
363 \begin{figure}[!ht]
364 \caption{\label{exampleSliderSource}Source code of 'exampleSlider'}
365 \begin{center}
366 \includegraphics[width=0.7\textwidth]{exampleSliderSource.png}
367 \end{center}
368 \end{figure}
369
370 Run it, using the 'Files' toolbar (see figure \ref{lowertoolbar})
371
372 You'll get something like in figure \ref{execSliderSource}.
373
374 \begin{figure}[!ht]
375 \caption{\label{execSliderSource}Execution of 'exampleSlider'}
376 \begin{center}
377 \includegraphics[width=0.7\textwidth]{execSliderSource.png}
378 \end{center}
379 \end{figure}
380
381 Feel free to move the slider, to check it actually works...
382
383 %\newpage
384
385 Just a few words on what you saw :
386 \begin{itemize}
387 \item{In the source code of the script} : \\
388 \begin{verbatim}
389    load std
390    load wx
391 \end{verbatim}
392 These \bbs commands load the packages std and wx
393 \begin{verbatim}
394    new Slider     slider
395    set slider.ReactiveOnTrack 1
396 \end{verbatim}
397 We create a \texttt{Slider} box called \emph{slider}.
398
399 We tell it to inform anybody that's interested in, that the cursor moved, each time it moved. 
400 The default behaviour is to inform only when cursor is released.
401 \begin{verbatim}
402    new OutputText text
403 \end{verbatim}
404 We create an \texttt{OutputText} box called \emph{text} 
405 (in which slider value will be displayed)
406
407 \begin{verbatim}
408    new LayoutLine layout
409 \end{verbatim}
410 We create a \texttt{LayoutLine} box called \emph{layout},
411 a widget box designed to embed other widgets (say, a main window)
412 \begin{verbatim}
413    connect slider.Widget    layout.Widget1
414    connect text.Widget      layout.Widget2
415 \end{verbatim}
416 We embed \emph{slider} and \emph{text} into  \emph{layout}.
417 \begin{verbatim}
418    connect slider.BoxChange text.BoxExecute
419    connect slider.Out       text.In
420 \end{verbatim}
421 We tell  \emph{slider} to inform \emph{text} every time it's modified.
422
423 We tell  \emph{slider} to pass its output value (\texttt{Out}) 
424 to \emph{text}  input value (\texttt{In})
425 \begin{verbatim}
426    exec layout
427 \end{verbatim}
428 We tell \emph{layout} to process itself. 
429 This also produces the execution of the boxes connected to it (the slider, the text).
430
431 \item{In the Help part}
432
433 You can see the graphical representation of the workflow (pipeline) created by the script, 
434 as in figure \ref{SmallGraph}.
435
436
437 \begin{figure}[!ht]
438 \caption{\label{SmallGraph}Graphical representation of a pipeline}
439 \begin{center}
440 \includegraphics[width=0.7\textwidth]{SmallGraph.png}
441 \end{center}
442 \end{figure}
443
444 The representation includes 
445 both the graphical interface-related pipeline 
446 (\emph{slider} and \emph{text} are embedded into \emph{layout})
447  and the data processing-related pipeline 
448 (\emph{slider} warns \emph{text} immediately when it's modified, 
449 \emph{slider} passes \emph{text} its output value)\footnote{Yes, we know : all the arrows (graphical interface pipeline arrows and data processing arrows) 
450 are blue; using different colors is planned for next release...}.
451  
452 You can get a much more detailled graph, 
453 like in figure  \ref{LargeGraph}, 
454 just clicking on the button 
455 '\texttt{graph (detailled)}' in the toolbar of the \texttt{Command} part. 
456
457  
458 \begin{figure}[!ht]
459 \caption{\label{LargeGraph}Detailled graphical representation of a pipeline}
460 \begin{center}
461 \includegraphics[width=0.75\textwidth]{LargeGraph.png}
462 \end{center}
463 \end{figure} 
464
465 \end{itemize}
466 %\newpage
467
468 % ==============================================
469 \subsection{Online Help}
470 % ==============================================
471
472 Various levels or help are suplied by \bbStudions.
473
474 % ==========================================
475 \subsubsection{Command line help}
476 % ==========================================
477
478
479 The 'working' area (the left one, as opposed to the 'help' area, on the right side) is composed of : 
480 one single line area (\texttt{Command}), at the bottom, in which you can enter your commands and 
481 a multiple line zone in which the Command interpreter prints out the result of your commands.
482 %The upper part contains the script editor; we shall not use it right now, you may reduce it.
483 Command line help for the black box scripting language (\bbsns) can be obtained 
484 in this zone (see \ref{Scripting}).
485
486 % ==========================================
487 \subsubsection{Guides}
488 % ==========================================
489
490 An html version of all the guides is browsable in the \texttt{Help} part of \bbStudions.
491  \begin{itemize}      
492      \item {\bf\emph{User's Guide}} : This guide !
493      \item {\bf\emph{Package Developper's Guide}} : Step to step How-to for programmer who wants to create his own
494      black boxes/packages.
495     % \item {\bf\emph{Developper's Guide}} : For bbtk kernel developpers only. (This one is probably not very much
496     %  up-to-date, since we spend more time in developping than writing documentation that's not of user concern).
497     % \item {\bf\emph{Reference Manual}} : Contains a exaustive description of all the features for all the commands.
498     %\item {\bf\emph{Booklet}} : Vade mecum.     
499      \item {\bf\emph{Doxygen Documentation}} : Doxygen source browser.\\ Automatically generated from source files. Should only concern the kernel developpers.
500    \end{itemize}
501         
502
503   
504
505 % ==========================================
506 \subsubsection{Boxes Help}
507 % ==========================================
508  Lists of currently available boxes from installed packages
509    \begin{itemize} 
510     \item {\bf\emph{Alphabetical list}} : %This is the 'zero-level' of retrieving.
511     \item {\bf\emph{List by package}} Boxes indexed by package
512     \item {\bf\emph{List by category}} :
513      Each box is indexed by a list of keywords, called 'categories', such as '\texttt{read/write}',
514      '\texttt{filter}' '\texttt{viewer}', ...
515     A given box may belong to more than one \texttt{category}, however some categories are mutually exclusive.
516     Standard categories are :
517     \begin {itemize}
518        \item\texttt{atomic box}/\texttt{complex box}\\
519        Whether it's a 'atomic' unit written is C++ and available in binary form in a package or it's an assembly of several black boxes (atomic or complex) which is described in \bbs script language.\\
520        Any box is either atomic ou complex.\\
521        Any pipeline described in a \bbs script is itself viewed as a complex black box hence is tagged as belonging to this category.
522        \item\texttt{example} / \texttt{demo} / \texttt{application}\\
523           These ones are scripts which produce a result when executed (i.e. they execute a pipeline like \texttt{exampleSlider} above), contrarily to the scripts which only define complex boxes but do not instanciate and execute boxes. 
524           \begin {itemize}
525              \item\texttt{example} : It's just a (simple) example, for programmers, on how to use a given feature. The \texttt{Examples} link on the starting page links to the list of the boxes of this category.
526              \item\texttt{demo} : It can be a 'good looking' (a.k.a 'sexy') example on some sophisticated work, done only by using \texttt{bbtk}. The \texttt{Demos} link on the starting page links to the list of the boxes of this category.
527              \item\texttt{application} : It's a final application, end user intended (e.g. Subscale a huge volume witout loading it in memory, Crop a DICOM image, etc.)         
528           \end {itemize}
529         \item\texttt{widget} : A piece of graphical interface (based on \texttt{wxWidgets})
530         \item\texttt{dicom} : Dicom medical image-related box.
531         \item\texttt{viewer} : A box allowing to view something (e.g. an image).
532         \item\texttt{read/write} : An I/O-related box
533         \item\texttt{mesh} : A mesh-related box
534         \item\texttt{filter} : A filter, mainly image filters.
535         \item\texttt{image} : An image-related box
536         \item\texttt{3D object creator} : A box which creates a 3D object to be injected into a 3D view (e.g. a plane, a surface).
537         \item\texttt{math} : Math
538         \item\texttt{misc} : Miscellaneous...       
539     \end {itemize}
540   Remark that the list of categories is 'auto-extensible' : each time a new box is created which belongs to a new category and the boxes list is regenerated, then the new category appears in the list, holding the new box. The above list only contains the categories used in the packages provided with current \bbtk release.
541     \item {\bf\emph{ List of adaptors}}  : The adaptors are a special type of black box which are used internaly to perform type conversions. Thought there are not end user intended, you may see their list. Adaptors belong to the \texttt{adaptor} category.
542   \end {itemize}
543   
544 % ==========================================      
545 \subsubsection{The Package Browser}
546 \label{Package_Browser}
547 % ==========================================
548
549 The package browser is a standalone application which 
550 dynamically loads and queries the available packages. 
551 It is thus a smarter tool than the static html documentation.
552 You can run it with the command \texttt{bbPackageBrowser} 
553 or in \bbStudio using either the button of the 'Command' part 
554 or the menu entry 'Windows$>$Start Package Browser'. 
555 Remark that it may take some time to start because it loads all available 
556 packages at start.
557 Its appearance is reproduced in figure \ref{imPackage_Browser}.
558
559 \begin{figure}[!ht]
560 \caption{\label{imPackage_Browser}The Package Browser}
561 \begin{center}
562 \includegraphics[width=0.6\textwidth]{Package_Browser.png}
563 \end{center}
564 \end{figure}
565
566 It allows you to find boxes using a multi-criteria filtering principle : 
567 The boxes listed are the one whose attributes match \emph{all} the 
568 words entered in the 'Filter' part.
569 You can get the whole description of a given box clicking on its name.
570
571 Warnings : 
572
573 \begin{itemize}
574 \item It's case sensitive, i.e '\texttt{Button}' 
575 will give different results than '\texttt{button}'
576 \item You have to press enter in the filter zone to update the boxes list
577 \item A filtering string only has to match a subpart of the related attribute of a box.
578 For example, entering 'utt' in the 'Name' attribute will match a box called 'Button'.
579 \end{itemize}
580
581 Attributes :
582
583 \begin {itemize}
584 \item Package : The name of the package to which the box belongs (e.g. \texttt{wxvtk}, \texttt{std})
585 \item Name : The name of a box or an application (e.g. \texttt{Reader}, \texttt{example})
586 \item Description : A part of the description of a box (e.g. \texttt{3D}, \texttt{image})
587 \item Category : The categories of the box (e.g. \texttt{demo})
588 \item Input/Output Type : The \CPP type of an input or output (e.g. \texttt{int}, \texttt{vtkImageData*}, \texttt{std::string})
589 \item Input/Output Nature : The \texttt{nature} of an input or output (e.g. \texttt{file name}, \texttt{signal}) 
590 \end {itemize}
591
592 %If 'Show widgets' is selected then 
593
594
595 %%\newpage 
596
597 % ==============================================
598 \subsection{The Menu}
599 % ==============================================
600
601 At last, let's have a look at \bbStudio menu.(See figure \ref{themenu})
602
603 \begin{figure}[!ht]
604 \caption{\label{themenu}The bbStudio menu}
605 \begin{center}
606 \includegraphics[width=0.7\textwidth]{themenu.png}
607 \end{center}
608 \end{figure}
609
610 \begin {itemize}
611   \item{\texttt{File}}
612      \begin {itemize}
613         \item{\texttt{Open the bbtk configuration file}}
614         \item{\texttt{Quit}}
615      \end {itemize}       
616   \item{\texttt{Tools}}
617      \begin {itemize}
618         \item{\texttt{Create package}} :
619         Provides a graphical interface to help package developpers to create a new empty package.
620         \item{\texttt{Create black box}}
621         Provides a graphical interface to help package developpers to create a new empty black box, and add it to an already existing package.  
622         \item{\texttt{Plug Package}}
623         Incorporates a package into the list of known packages. Updates the html documentation.
624         \item{\texttt{Regenerate package doc}} :
625         If a package has changed (e.g. new boxes) this updates the package html documentation.
626         \item{\texttt{Regenerate boxes list}} :
627         Updates the boxes lists (alphabetical, by package, ...)
628         \item{\texttt{Regenerate all}}
629         Regenerates all the packages documentations and the boxes lists (may be long...).
630         \item{\texttt{Show last graph}}
631         Shows the last pipeline graph that was generated
632      \end {itemize}     
633   \item{\texttt{Options}}
634      \begin {itemize}
635         \item{\texttt{Reset before running}} Before running a script, all the already created boxes are destroyed, 
636         all the already loaded packages are unloaded (this is the recomended option).   
637      \end {itemize}     
638   \item{\texttt{Windows}}
639   User may decide, for any reason of his own, to hide one or more panels:
640      \begin {itemize}
641         \item{\texttt{Show 'Files' panel}}
642         \item{\texttt{Show 'Help' panel}}
643         \item{\texttt{Show 'Command' panel}}
644         \item{\texttt{Show 'Messages' panel}}
645         \item{\texttt{Start Package browser}} : starts the package browser (see \ref{Package_Browser}).
646      \end {itemize}     
647   \item{\texttt{About}}
648      \begin {itemize}
649         \item{\texttt{About}} : Info about \texttt{bbStudio}.       
650      \end {itemize}     
651 \end {itemize}
652
653
654
655
656 % ==========================================
657 % ==========================================
658 % ==========================================
659 % ==========================================
660 \newpage
661 \hrule
662 \section{Writing black box scripts (\bbsns)}
663 \label{Scripting}
664 % ==========================================
665 % ==========================================
666 % ==========================================
667
668 This section introduces how to write down black box scripts (\bbsns) 
669 to create and execute pipelines. 
670
671 % ==========================================
672 \subsection{The commands}
673 % ==========================================
674 In \bbStudio, try typing in the \texttt{Command} area (in what follows, 
675 the commands entered by the user will be preceded by a prompt \textgreater) :
676 \begin{verbatim}
677 > help 
678 \end{verbatim}
679
680 you get the list of the commands of the interpreter :
681 \begin{verbatim}
682 Available commands :
683  author
684  category
685  config
686  connect
687  debug
688  define
689  delete
690  description
691  endefine
692  endpackage
693  exec
694  graph
695  help
696  include
697  index
698  input
699  kind
700  load
701  message
702  new
703  newgui
704  output
705  package
706  print
707  quit
708  reset
709  set
710  unload
711 \end{verbatim}
712
713 To get help on a particular command type \texttt{help <command-name>},
714 for example:
715 \begin{verbatim}
716 > help author
717 \end{verbatim}
718
719 gives :
720 \begin{verbatim}
721  usage : author <string>
722   Adds the string <string> to the author information of the black box being defined
723 \end{verbatim}
724
725 The \texttt{help} command has multiple usages. 
726 It is used to get help about almost anything in the interpreter!
727 Type \texttt{'help help'} to get help on the \texttt{help} command itself :
728 \begin{verbatim}
729 > help help
730  usage : 
731          (1) help 
732          (2) help <command name> 
733          (3) help packages [all]
734          (4) help <package name> [all]
735          (5) help <black box type> 
736          (6) help <black box name>
737   Effect :
738          (1) Lists all available commands;
739          (2) Prints help on a particular command; 
740          (3) Lists the packages loaded and their black boxes.
741              Add 'all' to list adaptors; 
742          (4) Prints short help on the black boxes of a package.
743              Add 'all' to include adaptors; 
744          (5) Prints full help on a black box type; 
745          (6) Prints information on the inputs, outputs and connectionns
746              of a black box instance.
747 \end{verbatim}
748
749 %More information about what is a 'box' will be given in the 'Scripting' part of this manual.
750
751
752 % ==========================================
753 \subsection{Creating and executing black boxes}
754 % ==========================================
755
756 At start the interpreter does not know any black box. 
757 If you type \texttt{'help packages'}, which is 
758 the third form of the \texttt{help} command, you get :
759 \begin{verbatim}
760 > help packages
761 user
762   workspace
763 \end{verbatim}
764
765 which means that the interpretor only knows one package 
766 (library of black boxes) called \texttt{user}
767 and which contains a black box called \texttt{workspace}.
768 The \texttt{user} package is an internal package of the interpreter, 
769 which stores user-defined black box types. 
770 At start, it already contains 
771 one box, called \texttt{workspace}.
772 \texttt{workspace} is a special type of black box, 
773 called complex black box, whose purpose is 
774 to store other black boxes. 
775 Any black box you create in \bbStudio is stored 
776 in \texttt{workspace}  
777 (this will be explained in details in sections 
778 \ref{bbi-writing-scripts} and 
779 \ref{bbi-more-on-complex-black-boxes}). 
780
781 If you type \texttt{'help workspace'}, you get :
782 \begin{verbatim}
783 > help workspace
784  Complex Black Box <user::workspace>
785   User's workspace
786   By : bbtk
787   Category(s) : complex box;
788   * No inputs
789   * No outputs
790   * No boxes
791 \end{verbatim}
792
793 In the text displayed, 
794 the \texttt{user::} prepended to the name \texttt{workspace} 
795 means that the box \texttt{workspace} 
796 belongs to the \texttt{user} package. 
797 Then comes a description and three lines which 
798 tell that \texttt{workspace} does not have any input 
799 nor output nor boxes yet.
800
801 In order to let the interpreter know of some black boxes, 
802 you must load another package. 
803 The \texttt{std} package is the ``standard'' package, 
804 which contains basic useful black boxes. 
805
806 To load it, type :
807 \begin{verbatim}
808 > include std
809 \end{verbatim}
810
811 Then if you type :
812 \begin{verbatim}
813 > help packages
814 \end{verbatim}
815
816 you get something like :
817
818 \begin{verbatim}
819
820  std
821    ASCII                   : ascii codes sequence to string - string to ascii...
822    Add                     : Adds its inputs
823    ConcatStrings           : String concatenation
824    Configuration           : Gets configuration informations
825    Div                     : Divides its inputs
826    ExecBbiCommand          : Executes bbi commands
827    ExecSystemCommand       : Executes system (O.S.) commands
828    GetVectorCharElement    : Gets the i-th element from the input vector (std...
829      ...
830    MagicBox                : Takes *any kind* of data and copies it to its ou...
831    MakeFileName            : Makes a kosher file name
832    Mul                     : Multiplies its inputs
833    MultipleInputs          : This box has multiple Void inputs and one Void o...
834    StringRelay             : Just copies the value of its input to its output...
835    StringSelect            : Outputs the string set to the ith input Ini (In0...
836  user
837    workspace 
838 \end{verbatim}
839
840 Now the interpreter knows the package \texttt{std} and the black boxes it provides,
841 such as the \texttt{Add} box, the \texttt{ConcatStrings} box, and so on. Remark that the 
842 content of \texttt{std} may vary from one version to another 
843 as new black boxes might be added to it. 
844 If you type :  
845 \begin{verbatim}
846 > help Add
847 \end{verbatim}
848
849 You'll get a text help, in the 'Message' part :
850 \begin{verbatim}
851 Black Box <std::Add>
852   Adds its inputs
853   By : laurent.guigues@creatis.insa-lyon.fr
854   Categories : atomic box;math;
855   * Inputs : 
856      'BoxExecute'     <bbtk::Void> [signal] : Any signal received by this input 
857                                               executes the box
858      'BoxProcessMode' <String>     []       : Sets the processing mode of the box 
859                                               (Pipeline | Always | Reactive)
860      'In1'            <Double>     []       : First number to add
861      'In2'            <Double>     []       : Second number to add
862   * Outputs : 
863      'BoxChange'      <bbtk::VoidS> [signal] : Signals modifications of the box
864      'Out'            <Double>     []       : Result
865 \end{verbatim}
866
867 After loading the package it belongs to, you can create an \emph{instance} of an \texttt{Add} box by 
868 the command \texttt{new} :
869
870 \begin{verbatim}
871 > new Add a
872 \end{verbatim}
873
874 The \texttt{'a'} at the end is the \emph{name} of the instance, 
875 which will be used to reference it later. 
876 It is important to distinguish a box \emph{type} 
877 and an \emph{instance} of a box type. 
878 The \texttt{Add} box of the package \texttt{std} is actually 
879 a \emph{box type} , like \texttt{int} is a data type 
880 in \texttt{C} langage. The \texttt{new} command allows to create 
881 an instance of a box type, exactly like \texttt{int i;} in 
882 a \texttt{C} code declares a variable of type \texttt{int} whose 
883 name is \texttt{i}. 
884 Of course, like in \texttt{C} Language, you can declare multiple boxes of the 
885 same type in \bbi. \\
886
887 After the creation of the box \texttt{a}, type :
888 \begin{verbatim}
889 > help workspace
890 \end{verbatim}
891
892 you get :
893 \begin{verbatim}
894 Complex Black Box <user::workspace>
895  User's workspace
896  By : bbtk
897  Category(s) : complex box;
898  * No inputs
899  * No outputs
900  * Boxes : 
901     'a' <std::Add>
902 \end{verbatim}
903
904 which means that \bbi workspace now contains a black box named \texttt{a},
905 of type \texttt{std::Add}.
906
907
908 Type 
909 \begin{verbatim}
910 Help Add
911 \end{verbatim}
912  and have a look to the 'Help' Part (see figure : \ref{HelpAdd})
913   
914 \begin{figure}[!ht]
915 \caption{\label{HelpAdd}The html Help}
916 \begin{center}
917 \includegraphics[width=0.7\textwidth]{HelpAdd.png}
918 \end{center}
919 \end{figure}
920
921
922 You can see a description 
923 (the one which was provided by the author of the box), 
924 the author(s) of the box (usually e-mail adress(es)) and 
925 the categories to which the box belongs. 
926 Finally comes the lists of inputs and outputs of the box.
927 For each input or output, \bbi provides 
928 its \emph{name} , 
929 its \emph{type} (between \texttt{<} and  \texttt{>}, e.g. \texttt{<Int>})
930 and a description.    
931 Remark that the box \texttt{Add} is not a 'complex' black box 
932 but an 'atomic' box, hence its help does not 
933 include a pipeline graph. 
934
935 You can see that  \texttt{Add} boxes have two inputs, 
936 with name \texttt{In1} and \texttt{In2},
937 and an output, with name \texttt{Out}.
938
939 You can set the input \texttt{In1} 
940 of the \texttt{Add} box \texttt{a} to the value $1$ 
941 by the command :
942 \begin{verbatim}
943 > set a.In1 1 
944 \end{verbatim}
945
946 Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
947 is done with :
948 \begin{verbatim}
949 > set a.In2 2
950 \end{verbatim}
951  
952 And you print the output \texttt{Out} of the box \texttt{a} with :
953 \begin{verbatim}
954 > print "result=$a.Out$"
955 result=3
956 \end{verbatim}
957
958 In the string passed to the \texttt{print} command, 
959 each substring enclosed between a couple of \$ is considered 
960 as the name of an output of a box. 
961 To process this special substrings, the interpretor :
962 \begin{enumerate}
963 \item Processes the box if needed (see below)
964 \item Converts the output of the box to a string if possible 
965 (see below)
966 \item Substitutes the result in the string to print
967 \item Postpones an implicit 'new line' character to the string
968 \end{enumerate}
969
970 %\paragraph
971
972 Box processing is needed if :
973
974 \begin{itemize}
975 \item either at least input has changed since last processing 
976 \item or the input \texttt{'BoxProcessMode'} of the box is set to 
977 \texttt{'Always'}, which forces box reprocessing. 
978 \end{itemize}
979
980 Note that all boxes have an input named \texttt{'BoxProcessMode'}.
981
982 Another way to process the box \texttt{a} is to issue the command :
983 \begin{verbatim}
984 > exec a
985 \end{verbatim}
986
987 however this command does not display anything (except if the 
988 box itself displays something in its processing).
989 It just processes the box if needed. 
990 This command is used to execute boxes that do not have any output,  
991 such as boxes that write something to a file or, display a 
992 graphical interface, and so on. \newline
993
994 %To exit \bbi, type :
995 %\begin{verbatim}
996 %> quit
997 %Good bye !
998 %\end{verbatim}
999
1000
1001
1002 % ==========================================
1003 \hrule
1004
1005 \paragraph{Summary}
1006 %\hrule
1007 \begin{itemize}
1008 \item The \texttt{include} command allows to load a package, and the complex black boxes that come with it..
1009 \item \texttt{help} gives help on :
1010 \begin{itemize} 
1011 \item Available commands if you just type \texttt{help}.
1012 \item A particular command if you type \texttt{help <command-name>}.
1013 \item All available packages and their boxes (without description) if you type \texttt{help packages}.
1014 \item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
1015 \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}).
1016 \end{itemize}
1017 %\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
1018 \item \texttt{new} : creates an instance of a black box. 
1019 \item \texttt{set} : sets the value of an input of a black box. 
1020 \item Under any component of  \bbStudions, to reference the input called \texttt{i} 
1021 of a black box called \texttt{b} you must type \texttt{'b.i'}. 
1022 The same syntax holds for outputs.
1023 \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
1024 implicit trailing 'new line character' is added at the final string.
1025 \item \texttt{exec} : runs, if needed, the process of a box. 
1026 %\item \texttt{quit} : quits \bbi.
1027 \end{itemize}
1028 \hrule
1029
1030 %\paragraph{Note :}
1031 %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.
1032 %Wou'll get something like in figure \ref{bbCommandPlusHelp} :
1033
1034 %\begin{figure}[!ht]
1035 %\caption{\label{bbCommandPlusHelp}
1036 %An other way to run the command interpreter}
1037 %\begin{center}
1038 %\includegraphics[width=0.5\textwidth]{bbCommandPlusHelp.png}
1039 %\end{center}
1040 %\end{figure}
1041
1042 % ==========================================
1043
1044 % ==========================================
1045 \subsection{Connecting black boxes}
1046 \label{bbi-connecting-black-boxes}
1047 % ==========================================
1048
1049 \BBTK allows to create 
1050 and execute processing chains, 
1051 also called \emph{pipelines}, 
1052 by connecting black boxes.
1053 This section explains how to do it with examples. 
1054 Read section \ref{bbi-more-on-pipeline-processing} to get 
1055 more information on pipeline processing.
1056
1057 First start \bbStudio and load the package \texttt{std}, typing :
1058 \begin{verbatim}
1059 > include std
1060 \end{verbatim}
1061 in the 'Command' part.
1062
1063 Assume you want to compute $1+2+3$. You can do it by 
1064 chaining two \texttt{Add} boxes, as shown in figure 
1065 \ref{bbi-fig-connecting-black-boxes-1}. 
1066
1067 \begin{figure}[!ht]
1068 \caption{\label{bbi-fig-connecting-black-boxes-1} A simple pipeline which adds 3 numbers}
1069 \begin{center}
1070 \includegraphics[width=0.5\textwidth]{1plus2plus3.png}
1071 \end{center}
1072 \end{figure}
1073
1074
1075 The \bbi instructions to create and execute this pipeline are :
1076 \begin{verbatim}
1077 > new Add a
1078 > new Add b
1079 > connect a.Out b.In1
1080 > set a.In1 1
1081 > set a.In2 2
1082 > set b.In2 3
1083 > print $b.Out$
1084 \end{verbatim}
1085
1086 You will see the (very expected) result :
1087 \begin{verbatim}
1088 6
1089 \end{verbatim}
1090
1091 The first three commands build the pipeline, 
1092 the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one 
1093 prints \texttt{b} black box output (the pipeline is executed before printing, because the interpretor 'knows' the box  \texttt{b}, 
1094 whose output is requested, is not up to date).
1095  
1096 The command \texttt{'connect a.Out b.In1'} ``plugs'' the output 
1097 \texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the 
1098 box \texttt{b}. 
1099 Once the boxes are connected, the processing of the two boxes are chained :
1100 getting the output of \texttt{b} requires getting its inputs, 
1101 hence getting the output of \texttt{a} which is connected to it. 
1102 This pipeline mechanism can recurse into arbitrary long 
1103 chains of boxes (see \ref{bbi-more-on-pipeline-processing} 
1104 for details).
1105
1106
1107 Lets' consider an other, more image oriented, example :
1108
1109 \begin{verbatim}
1110 > include vtk
1111 > include wx
1112 > include itk
1113 > include wxvtk
1114
1115 > new FileSelector fileDialog
1116 > new ImageReader  reader 
1117 > new Slider       slider
1118 > new Viewer2D     viewer
1119
1120 > connect fileDialog.Out   reader.In 
1121 > connect reader.Out       viewer.In
1122 > connect slider.Out       viewer.Slice
1123 > connect slider.BoxChange viewer.BoxExecute
1124
1125 > exec viewer
1126 \end{verbatim}
1127
1128 Some explainations : the \texttt{include} instructions load the necessary packages. \\
1129
1130 \texttt{FileSelector} will pop a File Selector, at run time, that will out the user chosen file name. \\
1131 \texttt{Slider} will pop a Slider, at run time, that will out an integer, used later as a slice number.\\ 
1132 \texttt{ImageReader} will read any itk readable file, whose name is passed as a std::string, and return a pointer on an itk image.\\
1133 \texttt{Viewer2D} displays a plane, whose number is specified by an integer.\\
1134 \\
1135 \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).\\
1136 \texttt{connect reader.Out       viewer.In} plugs the output of the reader (an bbtk::any<bbitk::ImagePointer> which is a type defined by the
1137 itk package which can hold any itk image pointer) to the input of the Viewer (a vtkImageData *)\\
1138 \texttt{connect slider.Out       viewer.Slice} plugs the output of the slider (an int) to an other output (named Slide) of the viewer.\\
1139 \texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer that it must re process itself any time the slider is modified.\\
1140 \\
1141 \texttt{exec viewer} processes the viewer.
1142
1143
1144 This would correspond to the graph in figure \ref{bbi-simplegraph}
1145
1146
1147 \begin{figure}[!ht]
1148 \caption{\label{bbi-simplegraph}(Very) simple Graph of a (very) simple pipeline}
1149 \begin{center}
1150 \includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
1151 \end{center}
1152 \end{figure}
1153    
1154 Of course, to be able to connect two boxes, 
1155 the output and the input must be compatibles. 
1156 You can always connect an output to an input of the \emph{same} type, 
1157 but you can do more, thanks to particular (hidden) black boxes called {\bf adaptors}.
1158
1159 An adaptor is a black box which has at least one input, called \texttt{In}, 
1160 and at least one ouput called \texttt{Out} and whose role is to convert 
1161 a data of the type of \texttt{In} 
1162 into a data of the type of \texttt{Out} (other inputs or outputs may serve 
1163 to parameter the adaptor or retreive other useful information).
1164
1165 Under \bbStudions, if you type :
1166 \begin{verbatim}
1167 > load std
1168 > help std all
1169 \end{verbatim}
1170 you get :
1171 \begin{verbatim}
1172  Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
1173  Basic useful black boxes
1174  Black boxes : 
1175       ...
1176    BoolToString        [DA]  : Converts a Bool (bool) into a string
1177    CastBoolToChar      [DA]  : Static cast from Bool (bool) to Char (signed c...
1178    CastBoolToDouble    [DA]  : Static cast from Bool (bool) to Double (double...
1179       ...
1180    CastBoolToUChar     [DA]  : Static cast from Bool (bool) to UChar (unsigne...
1181    CastBoolToUInt      [DA]  : Static cast from Bool (bool) to UInt (unsigned...
1182       ...
1183    CastUIntToBool      [DA]  : Static cast from UInt (unsigned int) to Bool (...
1184    CastUIntToChar      [DA]  : Static cast from UInt (unsigned int) to Char (...
1185    CastUIntToDouble    [DA]  : Static cast from UInt (unsigned int) to Double...
1186       ...      
1187
1188 \end{verbatim}
1189
1190 \texttt{[DA]}  stands for \emph{default adaptor}.
1191
1192 Once you have loaded the package \texttt{std}, you can 
1193 plug an output of type \texttt{char} into an input of type \texttt{double}. 
1194 When the interpreter encounters the \texttt{connect} command, 
1195 it looks for an adequate \emph{adaptor} in the  loaded packages. 
1196 In our case, as the package \texttt{std} provides the 
1197 \texttt{CastUCharToDouble} adaptor, the interpreter automatically creates an 
1198 instance of this adaptor and place it \emph{between} 
1199 the output and the input you want to connect 
1200 (however this adaptor is hidden to you, 
1201 it is embedded into the created connection and does not appear 
1202 as an existing black box). 
1203 When the pipeline is processed the 
1204 adaptor converts the output data into the required input type, 
1205 in a totally transparent way.
1206 In our example, the \texttt{CastUCharToDouble} adaptor 
1207 would simply cast the value of the \texttt{char} into a \texttt{double}, 
1208 however arbitrarily complex type conversion may be done.\\
1209 \texttt{WARNING} : these adaptors are \texttt{C++ static cast}, i.e., there is, right now,
1210  no 'intelligent' conversion (only truncation) e.g. think to \texttt{CastDoubleToUChar}!
1211
1212 %\begin{verbatim}
1213 %Question (for info-dev): 
1214 %if two adaptors with the same input and output types exist 
1215 %in two different packages, currenly loaded, 
1216 %which one is chosen by the interpreter at connection time?
1217 %A feature is missing to specify explicitely which one user wants to choose 
1218 %(use a namespace notation ?)
1219
1220 %-> Role of default adaptors
1221 %\end{verbatim}
1222
1223 Note that the \texttt{set} and \texttt{print} commands of interpreter 
1224 work with adaptors from \texttt{string} to the type of the input to set 
1225 or from the type of the output to print to \texttt{string}. 
1226 Hence in order to \texttt{set} or \texttt{print} values the adequate 
1227 adaptors must be available in the packages currently loaded. \\
1228
1229
1230 % ==========================================
1231 \hrule
1232 \paragraph{Summary}
1233 %\hrule
1234 \begin{itemize}
1235 \item The \texttt{connect} command allows to connect two black boxes
1236 \item You can connect two black boxes if (and only if) : 
1237 \begin{itemize}
1238 \item The output and the input are of the same type, or
1239 \item There is an adaptor black box in the packages loaded which 
1240 converts data of the output type into data of the input type
1241 \end{itemize}
1242 \item \texttt{help <package name>} does not display the adaptors of the package. To see them use : \texttt{help <package name> all}.
1243 including adaptors
1244 \end{itemize}
1245 \hrule
1246 % ==========================================
1247
1248 % ==========================================
1249 \subsection{Creating complex black boxes}
1250 \label{bbi-complex-black-boxes}
1251 % ==========================================
1252
1253 Remember the pipeline of figure 
1254 \ref{bbi-fig-connecting-black-boxes-1}, which 
1255 computed the sum of three doubles.
1256 You can consider it as a whole and define 
1257 a new black box type, which will be a \emph{complex black box}, 
1258 having three inputs and one output, 
1259 as shown in figure \ref{bbi-fig-complex-black-box-1}.
1260
1261 \begin{figure}[!ht]
1262 \caption{\label{bbi-fig-complex-black-box-1} Creating the complex black box \texttt{Add3}}
1263 \begin{center}
1264 \includegraphics[width=0.5\textwidth]{Add3.png}
1265 \end{center}
1266 \end{figure}
1267
1268 The \bbi commands to define this complex black box are 
1269 the following :
1270
1271 \begin{verbatim}
1272 > load std
1273 >
1274 > define Add3
1275 >
1276 > new Add a
1277 > new Add b
1278 > connect a.Out b.In1
1279 >
1280 > author "myself"
1281 > description "adds 3 doubles"
1282 > input x a.In1 "first double to add"
1283 > input y a.In2 "second double to add"
1284 > input z b.In2 "third double to add"
1285 > output result b.Out "output"
1286 >
1287 > endefine
1288 \end{verbatim}
1289
1290 Explainations :
1291
1292 As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
1293
1294 The command \texttt{define} then starts the definition 
1295 of the complex box type, which will be called \texttt{Add3}. 
1296
1297 The next three lines define the pipeline, 
1298 exactly in the same way than outside a complex box definition. 
1299
1300 The commands \texttt{author}, \texttt{description}, \texttt{input} 
1301 and \texttt{output} are commands specific to complex boxes definition :
1302
1303 \texttt{author} and \texttt{description} are used for the documentation 
1304 of the new box. You can provide multiple \texttt{author} or 
1305 \texttt{description} commands, the arguments of the commands will 
1306 be concatenated to produce the final author and description strings.
1307
1308 \texttt{input} and \texttt{output} are used to define the inputs and outputs 
1309 of the new complex box. 
1310 Their syntax is the same : for each new input/output you need to say 
1311 to which internal input/output it corresponds and to provide 
1312 a help string documenting the input/output.
1313 In our example, we define that the box \texttt{Add3} has 
1314 three inputs : \texttt{x}, \texttt{y} and \texttt{z}. 
1315 The input \texttt{x} corresponds to the input \texttt{In1} of the 
1316 internal box \texttt{a}. 
1317 In the same way, the external input \texttt{y} 
1318 corresponds to the internal input \texttt{a.In2}, and 
1319 the external input \texttt{In3} to \texttt{b.In2}. 
1320 The only output of the new box is called \texttt{result}
1321 and corresponds to \texttt{b.Out}. 
1322 The figure \ref{bbi-fig-complex-black-box-1} 
1323 illustrates the external to internal 
1324 input/output correspondence.
1325
1326 Finally, the \texttt{endefine} command ends the definition of the 
1327 new box type.
1328
1329 After this definition, if you ask for help 
1330 on packages, you get :
1331 \begin{verbatim}
1332 > help packages
1333 std
1334   Add
1335   ...
1336 user
1337   Add3
1338   workspace
1339 \end{verbatim}
1340
1341 The \texttt{user} package now contains a new black box type, called 
1342 \texttt{Add3}. If you ask for help on this type of box, you get :
1343 \begin{verbatim}
1344 > help Add3
1345 Complex Black Box <user::Add3>
1346  adds 3 doubles
1347  By : myself
1348  * Inputs : 
1349     'x'      <double> : first double to add
1350     'y'      <double> : second double to add
1351     'z'      <double> : third double to add
1352  * Outputs : 
1353     'result' <double> : output
1354  * Boxes : 
1355     'a' <std::Add>
1356     'b' <std::Add>
1357 \end{verbatim}
1358
1359 and you can use it like any other box, for example type :
1360
1361 \begin{verbatim}
1362 > new Add3 a
1363 > set a.x 1
1364 > set a.y 2
1365 > set a.z 3
1366 > print $a.result$
1367 6
1368 \end{verbatim}
1369
1370
1371 As a side note, we can say that, for consistency reasons, it would have been better to name  
1372 \texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3}, 
1373 since all the 'natural entry' of a box is named \texttt{In}, or \texttt{In}\emph{x} if there are more than one  'natural
1374 entry'
1375 .
1376 \newline
1377 % ==========================================
1378 \hrule
1379 \paragraph{Summary}
1380 %\hrule
1381 \begin{itemize}
1382 \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. 
1383 Inside a \texttt{define/endefine} block :
1384 \begin{itemize}
1385 \item The \texttt{author} and \texttt{description} commands allow to document the new type of box
1386 \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 
1387 of internal boxes they correspond.  
1388 \end{itemize}
1389 \end{itemize}
1390 \hrule
1391 % ==========================================
1392
1393 % ==========================================
1394 \subsection{Writing scripts files}
1395 \label{bbi-writing-scripts}
1396 % ==========================================
1397
1398 Once you have defined a new type of complex box, you 
1399 may like to reuse it. To do this, you can simply 
1400 write the \bbs commands defining the new box 
1401 into a text file and afterwards include that file in \bbins. 
1402 Doing this, you start writing \bbs scripts.
1403 The conventional (and mandatory) extension for such scripts is \texttt{bbs} 
1404 (black box script).
1405 For consistency reasons, you are requested to prepend \texttt{bb} to the name.
1406
1407 For example, the \texttt{Add3} complex box we previously worked on 
1408 can be defined in the \texttt{bbAdd3.bbs} file :
1409
1410 \begin{file}{bbAdd3.bbs}
1411 \begin{verbatim}
1412 # Defines the Add3 black box which adds 3 doubles 
1413 load std
1414
1415 define Add3
1416   # I am the author 
1417   author "myself"
1418   description "adds 3 doubles"
1419   # Pipeline creation
1420   new Add a
1421   new Add b
1422   connect a.Out b.In1
1423   # Inputs definition
1424   input x a.In1 "first double to add
1425   input y a.In2 "second double to add
1426   input z b.In2 "third double to add"
1427   # Output definition
1428   output result b.Out "output"
1429 endefine
1430 \end{verbatim}
1431 \end{file}
1432
1433 Lines starting with a \texttt{\#} character or a \texttt{\//\//} character are ignored, they 
1434 are considered as comments by the interpreter.
1435 To use this file in \bbStudions, click on the \texttt{include} button, and browse your filestore to find the file.
1436
1437 \begin{verbatim}
1438 > include bbAdd3.bbs
1439 > help Add3
1440 Complex Black Box <user::Add3>
1441  adds 3 doubles
1442  By : myself
1443  * Inputs : 
1444     'x'      <double> : first double to add
1445     'y'      <double> : second double to add
1446     'z'      <double> : third double to add
1447  * Outputs : 
1448     'result' <double> : output
1449  * Boxes : 
1450     'a' <std::Add>
1451     'b' <std::Add>
1452 >
1453 and so on ...
1454 \end{verbatim}
1455
1456 If the file has the \texttt{bbs} extension, you can ommit it and just type :
1457 \begin{verbatim}
1458 > include Add3
1459 \end{verbatim}
1460
1461 \subsection{Creating complex black boxes that use complex black boxes}
1462 \label{bbi-complex-complex-black-boxes}
1463
1464
1465 Of course, you can include script files in other script files, 
1466 like in the following example :
1467
1468 \begin{file}{bbAdd4.bbs}
1469 \begin{verbatim}
1470 # Defines the Add4 black box which adds 4 doubles 
1471 include Add3
1472
1473 define Add4
1474   author "myself"
1475   description "adds 4 doubles"
1476   new Add3 a
1477   new Add b
1478   connect a.Out b.In1
1479   input In1 a.In1 "first double to add
1480   input In2 a.In2 "second double to add
1481   input In3 a.In3 "third double to add"
1482   input In4 b.In2 "fourth double to add"
1483   output Out b.Out "output"
1484 endefine
1485 \end{verbatim}
1486 \end{file}
1487
1488
1489 The inner boxes have they own entries (In1, In2, In3 for box a, In1, In2 for box b )\\
1490 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
1491 care neither about the inner boxes name, nor about the names of their Inputs.\\
1492 The writer of the complex box has the ability to give these inputs a meaningfull name !
1493 \begin{verbatim}
1494   input In3 a.In3 "third double to add"
1495   input In4 b.In2 "fourth double to add"
1496 \end{verbatim}
1497
1498
1499 \subsection{Naming Conventions}
1500 \label{bbi-Naming Conventions}
1501
1502
1503 % ==========================================
1504 %\hrule
1505 %\paragraph{Naming Conventions}
1506 %\hrule
1507
1508 %\hrule
1509 % ==========================================
1510 \begin{itemize}
1511 \item
1512 File names : 
1513 For consistency reasons, you are requested to prepend \texttt{bb}, and postpone an extention \texttt{.bbs},
1514 to the names of the files that hold a \texttt{complex black box} definition.
1515
1516 For example, the \texttt{Add3} complex box we previously worked on 
1517 can be defined in the \texttt{bbAdd3.bbs} file.
1518 \item
1519 Search Paths :
1520 For consistency reasons, the names of dynamic libraries holding the packages start by \texttt{bb}.
1521 For instance, the package \texttt{wx} will be in the library \texttt{bbwx.dll} (Windows) or \texttt{libbbwx.so}
1522 (Linux).
1523
1524
1525 \end{itemize}
1526 % ==========================================
1527 \hrule
1528
1529 \paragraph{Summary}
1530 %\hrule
1531 \begin{itemize}
1532 \item The \texttt{include} command tells the interpreter to include a script file.
1533 \item Lines starting with a \texttt{\#} or with a \texttt{\//\//} are considered as comments by the interpreter.
1534 \item Lines between a line starting with a \texttt{\//*} an a line ending with a \texttt{*\//} are considered as comments by the interpreter.
1535 \end{itemize}
1536
1537 \hrule
1538 % ==========================================
1539
1540 % ==========================================
1541 \subsection{Creating command line applications}
1542 \label{bbi-command-line-app}
1543 % ==========================================
1544
1545 Now that you know how to create complex black boxes 
1546 (with \texttt{define/endefine}), think 
1547 back to the \texttt{workspace} object. 
1548 Remember that it is also 
1549 a \texttt{complex black box}. 
1550 Actually, when you type interpreter commands 
1551 outside a \texttt{define/endefine} block, 
1552 you progressively define the \texttt{workspace} 
1553 complex black box.
1554 You can think of it like if at start the interpreter
1555 was issuing a command \texttt{'define workspace'} 
1556 and then letting you define the interior of the box 
1557 \texttt{workspace}.
1558
1559 Remember that the command \texttt{inputs} 
1560 allows to define an input of a complex box. 
1561 Now, if you use the command \texttt{input} 
1562 outside a \texttt{define/endefine} block then 
1563 it defines an input of the \texttt{workspace} box, 
1564 that is an input of the \emph{main program}. 
1565 This input will then be connected to the 
1566 parameters that the user passes to the command line.
1567
1568 For example, consider the script : 
1569
1570 \begin{file}{add.bbs}
1571 \begin{verbatim}
1572 load std
1573 new Add a
1574 input x a.In1 "first number to add"
1575 input y a.In2 "second number to add"
1576 print "x+y=$a.Out$"
1577 \end{verbatim}
1578 \end{file}
1579
1580 The third and fourth lines define two inputs \texttt{x} 
1581 and \texttt{y}. When you execute this script, 
1582 you can pass these two arguments on the command line, 
1583 like this :
1584
1585 \begin{verbatim}
1586 > bbi add x=1 y=1
1587 x+y=2
1588 \end{verbatim}
1589
1590 You can also invoke \bbi the option \texttt{-h}, 
1591 which gives help on the \texttt{workspace} box :
1592
1593 \begin{verbatim}
1594 > bbi add -h
1595  User's workspace
1596  By : bbi (internal)
1597  * Inputs : 
1598     'x' <double> : first number to add
1599     'y' <double> : second number to add
1600 \end{verbatim}
1601
1602 To get a better help, use the \texttt{description} 
1603 and \texttt{author} commands :
1604
1605 \begin{file}{add.bbs}
1606 \begin{verbatim}
1607 description "Adds two numbers"
1608 author "foo@bar.com"
1609 load std
1610 new Add a
1611 input x a.In1 "first number to add"
1612 input y a.In2 "second number to add"
1613 print "x+y=$a.Out$"
1614 \end{verbatim}
1615 \end{file}
1616
1617 Now if you ask for help on the \texttt{add} script, you get :
1618
1619 \begin{verbatim}
1620 > bbi add -h
1621  Adds two numbers
1622  By : foo@bar.com
1623  * Inputs : 
1624     'x' <double> : first number to add
1625     'y' <double> : second number to add
1626 \end{verbatim}
1627
1628 Rather than getting the inputs of a script 
1629 from the command line, you can ask \bbi to 
1630 prompt the user for the values, using the \texttt{-t}
1631 commutator :
1632
1633 \begin{verbatim}
1634 > bbi add -t
1635 x=[the program waits for user answer]2
1636 y=[the program waits for user answer]5
1637 x+y=7
1638 \end{verbatim}
1639
1640 You can also use the \texttt{-g} commutator. 
1641 \bbi then prompts the user in graphical mode, 
1642 displaying a dialog box for each input,
1643 like in fig. \ref{bb-input-dialog-box}.
1644
1645 \begin{figure}[!ht]
1646 \caption{\label{bb-input-dialog-box}Input dialog box}
1647 \begin{center}
1648 \includegraphics[width=0.6\textwidth]{enter-the-value-of-x.png}
1649 \end{center}
1650 \end{figure}
1651
1652 Note that for both \texttt{-t} and \texttt{-g} options, 
1653 the input from the user is a \texttt{string} and 
1654 \bbi converts it to the right input type using 
1655 an \texttt{adaptor}, hence the right adaptors must be loaded.
1656
1657 % ==========================================
1658 \hrule
1659 \paragraph{Summary}
1660 %\hrule
1661 \begin{itemize}
1662 \item The \texttt{input}, \texttt{description} and \texttt{author} commands,
1663 when they are used outside a \texttt{define/endefine} block allow 
1664 to define the inputs, description and author of the main program.
1665 \item Inputs of the main program can be passed on the command line 
1666 using the syntax \texttt{<input-name>=<value>}. 
1667 No white space is allowed, if the value or the input name 
1668 contains white spaces, enclose them 
1669 between double quotes, e.g. \texttt{"parameter with white spaces = gnu's not unix"}.
1670 \item The \texttt{-h} option of \bbi prints help on the main program.
1671 \item The \texttt{-t} option of \bbi orders the program to prompt for its inputs in text mode.
1672 \item The \texttt{-g} option of \bbi orders the program to prompt for its inputs in graphical mode.
1673 \end{itemize}
1674 \hrule
1675 % ==========================================
1676
1677 % ==========================================
1678 \subsection{Using graphical interface boxes (widget boxes)}
1679 \label{bbi-widget}
1680 % ==========================================
1681
1682 % ==========================================
1683 %\subsubsection{Overview}
1684 %\label{bbi-overview}
1685 % ==========================================
1686
1687 Basic graphical interface components are provided in the package \texttt{wx}, 
1688 such as buttons, sliders, file open/save dialogs, etc.
1689
1690 As first example, type the following commands in \bbi :
1691 \begin{verbatim}
1692 > load wx 
1693 > new InputText t
1694 > print $t.Out$\n
1695 \end{verbatim}
1696
1697 When you type \texttt{enter} after the last line, 
1698 a window pops up in which you can entrer a text.
1699 When you close the window, the text you entered is printed by 
1700 the \texttt{print} command.
1701
1702 Type \texttt{help wx}, you get something like :
1703 \begin{verbatim}
1704  Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
1705  Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
1706  Black boxes : 
1707    ColourSelector        : Colour Selector dialog (bbfication of wxColourSele...
1708    ColourSelectorButton  : A button which displays a colour picker dialog whe...
1709    CommandButton         : Button which executes bbi commands
1710    DirectorySelector     : Pops up a directory selection dialog (wxDirDialog)
1711    FileSelector          : Pops up a file selection dialog for reading or sav...
1712    InputText             : A zone in which the user can enter a text (wxTextC...
1713    LayoutLine            : LayoutLine widget (wxBoxSizer)
1714    LayoutSplit           : Widget which splits a window in two fixed size par...
1715    LayoutTab             : LayoutTab widget (wxNotebook)
1716    OutputText            : Text zone to be inserted into a window (wxStaticTe...
1717    RadioButton           : RadioButton group widget 0-9 entries
1718    Slider                : Slider widget (wxSlider)
1719 \end{verbatim}
1720
1721 You can reproduce the same experiment as above using a 
1722 \texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}..
1723
1724
1725 %There are two kinds of widgets : ``terminal'' widgets and ``container'' widgets.
1726 %The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets 
1727 %are ``terminal'' widgets. 
1728 %``container'' widgets are of another kind : they are 
1729 % ==========================================
1730 %\subsubsection{Layout widgets}
1731 %\label{bbi-layout-widgets}
1732 % ==========================================
1733
1734 There is a special kind of widget, called '\texttt{Layout}', designed to  
1735 contain other widgets in order to build larger dialog boxes. 
1736
1737 For example, the \texttt{LayoutSplit} widget is a container which 
1738 ``splits'' a window into two parts, either horizontally or vertically, 
1739 each part including another widget. 
1740 The initial size of the two parts can be fixed by the input 'Proportion' 
1741 and be adjusted by the user thanks to a ``handle''.
1742
1743 The example \texttt{exampleLayoutSplit} demonstrates its use. 
1744 Run it : it displays a window with two sliders. 
1745 Move the sliders and close the window. 
1746 Now look at the source file to see how this is done :
1747
1748 \begin{file}{scripts/test/testSplit.bbs}
1749 \begin{verbatim}
1750 load wx
1751
1752 new Slider s1
1753 new Slider s2
1754
1755 new LayoutSplit s
1756 connect  s1.Widget s.Widget1
1757 connect  s2.Widget s.Widget2
1758
1759 exec s
1760 \end{verbatim}
1761 \end{file}
1762
1763 First, the two sliders \texttt{s1} and \texttt{s2} are created.
1764 A \texttt{LayoutSplit} box \texttt{s} is also created. 
1765 The \texttt{connect} commands then ``includes'' the sliders in the 
1766 split widget. 
1767 The input \texttt{Widget} is common to all widget boxes : 
1768 every widget can be inserted into another widget. 
1769 The outputs \texttt{Widget1},\texttt{Widget2}  are specific of \emph{layout} 
1770 widgets 
1771 (in \bbi type \texttt{help Slider} : 
1772 you will see the output \texttt{Widget}; 
1773 type \texttt{help LayoutSplit} : 
1774 you will see the inputs \texttt{Widget1} and \texttt{Widget2} 
1775 and the output \texttt{Widget}). 
1776 When you connect the \texttt{Widget} output of a box  
1777 to the \texttt{Widget}i input of a layout widget, 
1778 you order to include the widget in the layout.
1779 Of course, the order of connection is important. 
1780 In our case, the slider \texttt{s1} is included first, 
1781 then the slider \texttt{s2} : \texttt{s1} will be placed 
1782 on top of \texttt{s2} (the \texttt{LayoutSplit} box is 
1783 implemented that way, but this is arbitrary choice).
1784
1785 Right now, there are only \emph{three} layout widgets in the \texttt{wx} package : 
1786 \begin{itemize} 
1787 \item {the \texttt{LayoutSplit} widget} we just described
1788
1789 \item {the \texttt{LayoutLine} widget} can have multiple children 
1790 (\texttt{Widget1}, \texttt{Widget2},\dots \texttt{Widget9} inputs) and 
1791 divides its window into as much parts as children, 
1792 each part of equal size. 
1793 The orientation of the \texttt{LayoutSplit} or of the \texttt{LayoutLine}  can be changed by the input \texttt{Orientation}.
1794 With only those two layout widgets you can already create 
1795 complex dialog boxes 
1796 (of course layouts can be nested, which leads to tree-like 
1797 structures of widgets). \\
1798 See the script \texttt{exampleComplexLayoutSplit\_In\_LayoutSplit} for an example.
1799
1800 \item {The \texttt{LayoutTab}  widget} arranges its children 
1801 in different pages or 'tabs' (\texttt{wxNotebook}-based).
1802 The label of each page is the name of the widget it contains.
1803
1804 \end{itemize}
1805
1806
1807 %=====> TODO \\
1808
1809
1810 %One word about a special widget in the package \texttt{wx} : 
1811 %the \texttt{Button}... to be continued.
1812
1813 % ==========================================
1814 \subsection{Deeper in the boxes}
1815 \label{bbi-deep-box}
1816 % ==========================================
1817
1818 \subsubsection{Default and mandatory inputs and outputs}
1819 \begin{itemize}
1820 \item Any \texttt{atomic} black box has two default Inputs, which are created by the system :
1821 \begin{itemize}
1822   \item {\bf\emph{BoxExecute}}     : Any signal received by this input executes the box
1823   \item {\bf\emph{BoxProcessMode}} : Sets the processing mode of the box :
1824   \begin{itemize}
1825     \item {\bf\emph{Pipeline}} :% bbBackwardUpdate() calls Process() only if Status == MODIFIED \\
1826                                  The box executes itself only when an input was changed (normal pipeline processing).
1827     \item {\bf\emph{Reactive}} : %bbSetModifiedStatus() calls bbUpdate() \\
1828                                  Re-processes immediately when \emph{any input} changes.\\
1829                                  To be more selective, better use 
1830         '\texttt{connect A.BoxChange B.BoxExecute}'.    
1831     \item {\bf\emph{Always}}   :% bbUpdate() always calls Process. \\
1832                                  Usefull for 'sources', that must be processed, even when no input changed (e.g. : FileSelector, ColorSelector)\\
1833                                  This one is not end user intended (for Package developer only)
1834   \end{itemize}   
1835 \end{itemize}
1836 \item And one default output :
1837 \begin{itemize}
1838   \item {\bf\emph{BoxChange}}  : Signals any modification of the box. This output may be connected if necessary to the \emph{BoxExecute} 
1839   input of an other box : each time the boxes changes (e.g. a Slider is moved) the box it is connected to will be forced to update.
1840 \end{itemize}
1841
1842 If you create complex boxes, it is a good idea to define those inputs and outputs to be able 
1843 to force the execution of your complex box or be aware of its changes...
1844
1845 \item Any {\bf 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 :  
1846 \begin{itemize}
1847   \item {\bf\emph{WinHeight}} : Height of the window 
1848   \item {\bf\emph{WinWidth}}  : Width of the window  
1849   \item {\bf\emph{WinTitle}}  : Title of the window
1850   \item {\bf\emph{WinClose}}  : Any received signal closes the window
1851   \item {\bf\emph{WinHide}}   : Any received signal hides the window
1852   \item {\bf\emph{WinDialog}} : When set to 'true', creates a \emph{dialog window}, that blocks the pipeline until it is closed (\emph{modal})   
1853 \end{itemize}
1854
1855 If you define a complex widget box, it is a good idea to define these inputs to be able 
1856 to customize your window settings.
1857
1858 \item Any {\bf widget} box has one mandatory Output  :
1859
1860 \begin{itemize}
1861   \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}, then the box  will create its own window (frame or dialog) on execution. If it's connected to the \texttt{Widget}\texttt{\emph{i}} of a \texttt{Layout box}, 
1862      it will be embedded in its parent window.
1863 \end{itemize}    
1864
1865 If you define a complex widget box, it is a good idea to use this standard name for your window output
1866
1867 \item Any {\bf Layout} box (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has one or more mandatory Inputs :
1868 \begin{itemize}
1869   \item {\bf\emph{Widget}}\texttt{i} : e.g. a \emph{LayoutSplit} box (Widget which splits a window in two resizeable parts) 
1870        has two Input parameters \emph{Widget1} and \emph{Widget2}, used to embed the child windows.\\
1871        e.g. a  \emph{LayoutLine} divides the window in up to 9 (depending on the number of inputs \emph{Widget}i) fixed size parts.  
1872 \end{itemize} 
1873
1874 If you define a complex layout box, it is a good idea to use these standard names for your 
1875 sub-windows inputs.
1876
1877 \end{itemize}
1878
1879
1880 % ==========================================
1881 %\subsection{More on ...}
1882 %\label{bbi-more-on}
1883 % ==========================================
1884
1885 % ==========================================
1886 %\subsubsection{Black box packages}
1887 %\label{bbi-more-on-packages}
1888 % ==========================================
1889 %There are various others user-intended packages :
1890
1891 %\begin{verbatim}
1892 %---> Were moved in a 'Reference Manual' ?\\
1893 %---> Any suggestion welcome!
1894 %\end{verbatim}
1895
1896 %\begin{itemize}
1897 %\item{vtk} \\
1898 %\item{itk} \\
1899 %\item{...} \\
1900 %\end{itemize}
1901 % ==========================================
1902 %\subsubsection{Pipeline processing}
1903 %\label{bbi-more-on-pipeline-processing}
1904 % ==========================================
1905 %\begin{itemize}
1906 %\item the ``control'' mechanism in bbi.
1907
1908 %When a box is requested to update itself, it asks (recursively) each one of its inputs if it was modified.\\
1909 %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.
1910
1911 %(switch exec commands, e.g. Button)
1912 %\item the role of ProcessMode to update widgets.
1913 %\end{itemize}
1914
1915 %\subsubsection{Advanced issues}
1916 %\paragraph{Reducing the number of inputs of a box}
1917
1918 % ==========================================
1919 %\subsubsection{Errors}
1920 %\label{bbi-more-on-errors}
1921
1922 % ==========================================
1923
1924
1925 % ==========================================
1926 %\vspace{0.5cm}
1927 \hrule 
1928 \newpage
1929 \section{Using third party Package}
1930 \label{Third_Party_Package}
1931 % ==========================================
1932 % ==========================================
1933 \subsection{Plugging in a Package}
1934 \label{Plugging_in_a_Package}
1935 % ==========================================
1936
1937 \bbStudio makes it easy for you : in the menu \texttt{Tools} just click on the 
1938 option \texttt{Plug Package}. You will be asked to '\texttt{Select
1939 package directory}'. Browse untill you find the install or the build directory,
1940 depending whether you installed the package or not.
1941
1942 \bbStudio will update the configuration file, generate the 'Package
1943 documentation', and update the 'Boxes Lists'.
1944
1945 You will be able to use the new package just as you did for any other \bbtk
1946 canonical Package.
1947
1948 % ==========================================
1949 \subsection{Hard incorporating of a Package}
1950 \label{Hard_incorporating_of_a_Package}
1951 % ==========================================
1952
1953 If the Package you want to use is supplied in a non standard way (e.g. : you
1954 where given one ore more dynamic libraries (\texttt{.dll} or \texttt{.so}), and/or
1955 one or more directories containing \bbtk scripts (\texttt{.bbs})
1956 you can edit your \bbtk configuration and add the appropriate 
1957 paths, see \ref{The_configuration_file}.
1958
1959 %\end{itemize}
1960 % ==========================================
1961 \subsection{Updating the documentation}
1962 \label{Updating_the_documentation}
1963 % ==========================================
1964 You may add your own boxes (simple boxes, if you are aware enough in \CPP
1965 language, or complex boxes if you are aware enough in bbtk scripting).
1966
1967 To update the html help of this package,
1968 use the option \texttt{Regenerate package doc} 
1969 in the menu \texttt{Tools} of \texttt{bbStudio}.
1970 You'll be prompted for the Package name. 
1971 Avoid using the \texttt{-a} option (Regenerate all), since it's time consumming.
1972
1973 To update html boxes lists with the new boxes,
1974 use the option \texttt{Regenerate Boxes Lists} 
1975 in the menu \texttt{Tools} of \texttt{bbStudio}.
1976
1977 % ==========================================
1978 \subsection{Using the package}
1979 \label{Using_the_package}
1980 % ==========================================
1981
1982 The only thing you have to do is to \texttt{include} or \texttt{load} the package, 
1983 within a script, or from the \texttt{Command} part, 
1984 and enjoy the black boxes it contains.
1985
1986 % ==========================================
1987 %\subsection{Packages you'll probably want to use }
1988 %\label{Packages_you_ll_want_to_use}
1989 % ==========================================
1990 %\begin {itemize}
1991 %\item{\texttt{creaLib}} \\
1992 %a.k.a \texttt{crea}. It's a set of 'low level' utilities, needed by other
1993 %packages (an, sure,  useful as well for people that doesn't use bbtkns.
1994 %\item{\texttt{creaContours}} \\
1995 %Provides sophisticated widgets for managing 3D R.O.I. (Regions of interest)
1996 %\item{\texttt{creaImageIO}} \\
1997 %Allows browsing, selectionning, ordering directories containing images of almost any type
1998 %(including DICOM)
1999 %\end {itemize}
2000 %\newpage
2001  
2002 % ==========================================
2003 %\vspace{0.5cm}
2004 \hrule
2005 \newpage
2006 \section{Using black boxes in \CPP programs}
2007 \label{cpp}
2008 % ==========================================
2009
2010 A very useful feature is that you may use any widget 
2011 black box within a \CPP program 
2012 without worrying about writing a \wx main application.\\
2013
2014 Let's look a the following bbs script :
2015
2016 \begin{verbatim}
2017 # Load the packages
2018 load std
2019 load wx
2020
2021 # Create the Objects
2022 new Slider     slider
2023 new OutputText text
2024 new LayoutLine layout
2025
2026 # Graphical pipeline
2027 connect slider.Widget    layout.Widget1
2028 connect text.Widget      layout.Widget2
2029
2030 # Execution pipeline
2031 connect slider.BoxChange text.BoxExecute
2032 connect slider.Out       text.In
2033
2034 # Go!
2035 exec layout
2036 \end{verbatim}
2037
2038 User wants to create a slider and an output text, within a LayoutLine, 
2039 and display the slider value in the output text.
2040 Think about the (little!) nightmare to code the same, in 'raw C++', using wxWidgets.
2041
2042 The following \CPP code does the same :
2043
2044 \begin{verbatim}
2045 #include <bbtkFactory.h>
2046 #include <bbwxSlider.h>
2047 #include <bbwxOutputText.h>
2048 #include <bbwxLayoutLine.h>
2049
2050 int main(int argv, char* argc[])
2051 {
2052   try
2053     {
2054       // we need to intanciate a bbtk::Factory to be aware of the adaptors
2055       bbtk::Factory::Pointer factory = bbtk::Factory::New();
2056       
2057       // Load the packages
2058       // ----------------  
2059       factory->LoadPackage("std");
2060       factory->LoadPackage("wx");
2061       
2062       // Create the Objects
2063       // ------------------      
2064       bbwx::Slider::Pointer     slider   = bbwx::Slider::New("slider");
2065       bbwx::OutputText::Pointer text     = bbwx::OutputText::New("text");
2066       bbwx::LayoutLine::Pointer layout   = bbwx::LayoutLine::New("layout");
2067       
2068       // Graphical pipeline
2069       bbtk::Connection::Pointer c1       = bbtk::Connection::New(slider,"Widget",
2070                                                                  layout,"Widget1");
2071                                                            
2072       bbtk::Connection::Pointer c2       = bbtk::Connection::New(text,"Widget",
2073                                                                  layout,"Widget2");
2074                                                                                                                                                                            
2075       // Execution pipeline
2076       // ------------------
2077       
2078       // We have to pass the 'factory', in order to call automatically an adaptor,
2079       // if necessary.
2080       bbtk::Connection::Pointer s2t      = bbtk::Connection::New(slider,"Out",
2081                                                                  text,"In",
2082                                                                  factory);      
2083       bbtk::Connection::Pointer c3       = bbtk::Connection::New(slider,"BoxChange",
2084                                                                  text,"BoxExecute");      
2085       layout->bbSetInputWinDialog(true);
2086       
2087       // Go!
2088       // ---     
2089       layout->bbExecute();
2090
2091     }
2092   catch (bbtk::Exception e)
2093     {
2094       bbtk::MessageManager::SetMessageLevel("Error",1);
2095       e.Print();
2096     }
2097 }
2098
2099 In this code, we use the headers of the \texttt{bbwx} \CPP library, 
2100 which define the black boxes of the \texttt{wx} package. 
2101
2102 to be continued ...
2103
2104 \end{verbatim}
2105
2106 % ==========================================
2107 \hrule
2108 \newpage
2109 \section{\bbs language reference}
2110 \label{bbi-reference}
2111 % ==========================================
2112
2113 % ==========================================
2114 \subsection{Pipeline creation and execution related commands}
2115 \label{bbi-reference-creation-execution}
2116 % ==========================================
2117 % See table \ref{bbi-reference-box}
2118
2119 % ==========================================
2120 \begin{table}[!ht]
2121 \caption{\label{bbi-reference-box} \bbs pipeline creation and execution related commands.}
2122 \small
2123 \begin{tabular}{|lcm{6cm}|}
2124 \hline
2125 Command & Parameters & Effect \\ \hline
2126
2127 \texttt{new} & \texttt{<box-type>} \texttt{<box-name>}& 
2128 Creates a box of type \texttt{box-type} and name  
2129 \texttt{box-name}.\\ \hline
2130
2131 \texttt{newgui} & \texttt{<box-name>} \texttt{<gui-box-name>} &
2132 Automatically creates a graphical user interface with name \texttt{gui-box-name}
2133 for the black box \texttt{box-name} and connects it to the box inputs\\ \hline 
2134
2135 \texttt{delete} & \texttt{<box-name>} & 
2136 Destroys the box named \texttt{box-name}\\ \hline 
2137
2138 \texttt{connect} & \texttt{<box1.output>} \texttt{<box2.input>} & 
2139 Connects the output 
2140 \texttt{output} of the box named \texttt{box1} 
2141 to the input \texttt{input} of the box named \texttt{box2} \\ \hline 
2142
2143 \texttt{set} & \texttt{<box.input>} \texttt{<value>} &
2144 Sets the input \texttt{input} of 
2145 the box named \texttt{box} to the value \texttt{value}.
2146 An \texttt{adaptor} must exist
2147 in the packages loaded which converts a \texttt{std::string} 
2148 to the type of the input \texttt{input}. \\ \hline 
2149
2150 \texttt{exec} & \texttt{<box-name>} & 
2151 Executes the box named \texttt{box-name}.
2152 If needed the boxes 
2153 connected to its inputs 
2154 are also processed recursively (pipeline processing).\\ \hline 
2155 & \texttt{freeze} & 
2156  Allows to block execution commands while keeping definition commands active (this one is not for end user)\\ \hline 
2157 & \texttt{unfreeze} & 
2158  Turns back to 'normal' mode (this one is not for end user).\\ \hline 
2159 \end{tabular}
2160 \end{table}
2161 % ==========================================
2162
2163 \newpage
2164
2165 % ==========================================
2166 \subsection{Package related commands}
2167 \label{bbi-reference-package}
2168
2169 \begin{table}[!ht]
2170 \caption{\label{tabbbi-reference-interpreter_1}\bbs package related commands. }% (part 1).}
2171 \small
2172 \begin{tabular}{|lcm{6cm}|}
2173 \hline
2174 Command & Parameters & Effect \\ \hline
2175
2176
2177 \texttt{include} & \texttt{<package-name>} & 
2178 Loads the package \texttt{package-name} and includes all its complex box definition scripts. \\ \hline 
2179
2180 \texttt{load} & \texttt{<package-name>} & 
2181 Loads the atomic black boxes of package \texttt{package-name}.
2182 Loads the dynamic library but not the complex boxes defined in the scripts shipped with the package. 
2183 Use it only if you know that you won't work with its complex black boxes \\ \hline 
2184
2185 \texttt{unload} & \texttt{<package-name>}& 
2186 Unloads the package \texttt{package-name}. 
2187 The package must have been previously loaded. 
2188 No box of a type defined in this package must still exist.\\ \hline 
2189
2190 \texttt{reset} & - & Deletes all boxes and unloads all packages so 
2191 that the interpreter gets back to its initial state \\ \hline 
2192
2193
2194 \texttt{package} &  \texttt{<package-name>} &  
2195 All complex black boxes definitions until the next \texttt{endpackage} 
2196 will be stored into the package \texttt{package-name}  \\ \hline 
2197
2198 \texttt{endpackage} & - & 
2199 Closes a \texttt{package} command  \\ \hline 
2200
2201
2202 \end{tabular}
2203 \end{table}
2204 \newpage
2205
2206 % ==========================================
2207 \subsection{Interpreter related commands}
2208 \label{bbi-reference-interpreter}
2209 % ==========================================
2210 %See table \ref{tabbbi-reference-interpreter_1} and \ref{tabbbi-reference-interpreter_2}
2211 % ==========================================
2212 \begin{table}[!ht]
2213 \caption{\label{tabbbi-reference-interpreter_1}\bbs intepreter related commands. }% (part 1).}
2214 \small
2215 \begin{tabular}{|lcm{6cm}|}
2216 \hline
2217 Command & Parameters & Effect \\ \hline
2218
2219
2220 \texttt{help} & - & 
2221 Prints help on available commands \\ \hline 
2222
2223 & \texttt{<command-name>} & 
2224 Prints help on the command \texttt{command-name} \\ \hline 
2225
2226 & \texttt{packages} & 
2227 Prints help on available packages and their box types 
2228 (without description)\\ \hline 
2229
2230 & \texttt{<package-name>} & 
2231 Prints help on the package \texttt{package-name} and its boxes 
2232 (with brief description). 
2233 The package must have been previously loaded \\ \hline 
2234
2235 & \texttt{<box-type>} & 
2236 Prints help (with full description) on the type of box 
2237 \texttt{box-type}. 
2238 The box type must belong to a package which has been previously loaded \\ \hline 
2239
2240 \texttt{message}
2241 & - & 
2242 Prints information on available kinds of messages and their current level\\ \hline 
2243
2244  & \texttt{<kind>} \texttt{<level>} & 
2245 Sets the level of verbosity of the interpreter for the kind of messages 
2246 \texttt{kind} to \texttt{level}.\\ \hline 
2247
2248
2249 \texttt{include} & \texttt{<file-name>} & 
2250 Includes and executes the content of the file named \texttt{file-name} 
2251 exactly like if you were typing its content at the place were the 
2252 \texttt{include} command is. \\ \hline 
2253
2254 \texttt{print} & \texttt{<string>} & 
2255 Prints the string after substituting each token of the form \texttt{\$box.output\$} by the adaptation to string of the value of the 
2256 output \texttt{output} of the box named \texttt{box}. 
2257 An \texttt{adaptor} must exist
2258 in the packages loaded which converts 
2259 the type of the output \texttt{output}
2260 to a \texttt{std::string}.
2261 \\ \hline 
2262
2263 \texttt{graph} & ... & 
2264 Generates the html doc including the pipeline graph for a given complex box \\ \hline
2265
2266 \texttt{index} & ... & 
2267 Generates the html index of currently loaded boxes types \\ \hline
2268
2269 \texttt{config} & - & Displays the configuration parameters\\ \hline 
2270
2271
2272 \texttt{debug} & \texttt{<debug-directive>} & 
2273 [expr|-C|-D] 
2274   Prints debug info on living bbtk objects containing the string \texttt{expr} (default expr=''). 
2275          \texttt{-C} checks the factory integrity.
2276          \texttt{-D} turns on objects debug info after main ends\\ \hline 
2277
2278 \texttt{quit} & - & Exits the interpreter\\ \hline 
2279
2280 \end{tabular}
2281 \end{table}
2282 % ==========================================
2283
2284 \newpage
2285
2286 % ==========================================
2287 \subsection{Complex black box definition related commands}
2288 \label{bbi-reference-black-box-definition}
2289 % ==========================================
2290
2291 %See table \ref{bbi-reference-complex-box} 
2292 % ==========================================
2293 \begin{table}[!ht]
2294 \caption{\label{bbi-reference-complex-box} \bbs complex black box definition related commands.}
2295 \small
2296 \begin{tabular}{|lcm{6cm}|}
2297 \hline
2298 Command & Parameters & Effect \\ \hline
2299
2300
2301 \texttt{define} & \texttt{<box-type>} [\texttt{<package-name>}] & 
2302 Starts the definition of a complex black box of type
2303 \texttt{box-type}. If \texttt{<package-name>} is provided then includes the 
2304 box in the given package (otherwise it is defined in the current package, 
2305 i.e. \texttt{user} if outside a \texttt{package/endpackage} block). \\ \hline 
2306
2307 \texttt{endefine} & - & 
2308 Ends the definition of a complex black box type\\ \hline 
2309
2310 \texttt{author} & \texttt{<string>} & 
2311 Concatenate the string to the author string 
2312 of the current complex black box.\\ \hline 
2313
2314 \texttt{description} & \texttt{<string>} & 
2315 Concatenate the string to the description of the current complex black box. 
2316 \\ \hline 
2317
2318 \texttt{category} & \texttt{<string>} & 
2319 Specifies the \texttt{categories} of the current complex black box. 
2320 The categories must be separated by semicolons, e.g. "\texttt{widget;image}"\\ \hline 
2321
2322 \texttt{kind} & \texttt{<box kind>} & 
2323 Specifies the \texttt{kind} of the current complex black box 
2324 ( ADAPTOR, DEFAULT\_ADAPTOR, WIDGET\_ADAPTOR, DEFAULT\_WIDGET\_ADAPTOR )\\ \hline 
2325
2326 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} & 
2327 Defines a new input for the current complex black box, 
2328 named \texttt{name}. 
2329 It is defined as corresponding to 
2330 the input \texttt{input} of the box \texttt{box}.
2331  
2332 \texttt{<help>} is the help string for the new input.
2333 The box \texttt{box} must already have been created in the complex box 
2334 and of course have an input named \texttt{input}.\\ \hline 
2335
2336 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} & 
2337 Defines a new output for the current complex black box, 
2338 named \texttt{name}. 
2339 It is defined as corresponding to 
2340 the output \texttt{output} of the box \texttt{box}. 
2341 \texttt{<help>} is the help string for the new output.
2342 The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}. \\ \hline 
2343
2344 \end{tabular}
2345 \end{table}
2346
2347 %\newpage
2348 Note : if outside a \texttt{define/endefine} block then the current complex black box 
2349 is '\texttt{user::workspace}', that is the main program equivalent 
2350 (this is how applications are documented).
2351 This remark holds for all complex black box related commands.
2352
2353
2354
2355
2356
2357
2358
2359
2360 % ==========================================
2361 % ==========================================
2362 % ==========================================
2363 % ==========================================
2364 % ==========================================
2365 % ==========================================
2366 % ==========================================
2367 % ==========================================
2368 % ==========================================
2369 % ==========================================
2370 %\hrule
2371 \newpage
2372 \section{Install and run time issues}
2373 % ==========================================
2374
2375
2376
2377
2378 %%==============================================================================================
2379 %%==============================================================================================
2380 \subsection{\bbtk configuration file}
2381 \label{The_configuration_file}
2382 %%==============================================================================================
2383 %%==============================================================================================
2384
2385 At start, \bbtk applications (\bbStudio, \bbi) try 
2386 to open an \texttt{xml} 
2387 configuration file named \texttt{bbtk\_config.xml}. 
2388 The search order is 
2389 \begin{enumerate}
2390 \item The current directory
2391 \item The subdir \texttt{.bbtk} of the user's home directory. 
2392 \begin{itemize} 
2393 \item On \texttt{Unix}, the home directory is the
2394 one stored by the environnement variable \texttt{HOME}, 
2395 typically \texttt{/home/username}.
2396 \item On \texttt{Windows}, the home directory is 
2397 the user's profile directory stored by the environnement 
2398 variable \texttt{USERPROFILE}, 
2399 typically \texttt{C:$\backslash$ Documents and Settings$\backslash$ username}.
2400 \end{itemize}
2401 \item If none of these two paths contains the file then it creates 
2402 a new one in the \texttt{.bbtk} directory. 
2403 \end{enumerate}
2404
2405
2406 Information on \bbtk configuration is 
2407 obtained in \bbStudio by clicking on the 
2408 \texttt{Config} button of the \texttt{Command} part toolbar.
2409
2410 If you did not installed other packages than the ones 
2411 provided by \bbtk, you get something like :
2412
2413 \begin{verbatim}
2414  =============
2415  Configuration
2416  =============
2417  bbtk_config.xml    : [/home/guigues/.bbtk/bbtk_config.xml]
2418  Documentation Path : [/usr/local/bin/../share/bbtk/doc]
2419  Data Path          : [/usr/local/bin/../share/bbtk/data]
2420  Temp Directory     : []
2421  File Separator     : [/]
2422  BBS Paths   
2423  --- [.]
2424  --- [/usr/local/bin/../share/bbtk/bbs]
2425  PACKAGE Paths : 
2426  --- [.]
2427  --- [/usr/local/bin/../lib]
2428 \end{verbatim}
2429
2430 The first line let you know which configuration file is currently used.
2431
2432 You can open this file using \bbStudio menu \texttt{Files$>$Open bbtk Config file}.
2433
2434 You will get something like :
2435
2436 \begin{verbatim}
2437 <?xml version=\"1.0\" encoding=\"iso-8859-1\"?>
2438 <config>
2439   <bbs_path>     </bbs_path>
2440   <package_path> </package_path> 
2441 </config>
2442 \end{verbatim}
2443
2444 The \texttt{xml} tags \texttt{bbs\_path} and \texttt{package\_path} 
2445 allow to set additionnal directories in which to search 
2446 for \bbs files and packages dynamic libraries.
2447
2448 For example, if you add the line :
2449 \begin{verbatim}
2450   <bbs_path> /home/guigues/bbs </bbs_path>
2451 \end{verbatim}
2452
2453 Then the interpreter will search for \bbs in the folder \texttt{/home/guigues/bbs}, 
2454 which allows a command like \texttt{'include bbMyBox.bbs'} to work if 
2455 the folder \texttt{/home/guigues/bbs} contains the file \texttt{bbMyBox.bbs}.
2456
2457 The same, the \texttt{xml} tag \texttt{<package\_path>} let you 
2458 set additional path in which to find a package dynamic library, 
2459 hence allowing to load additionnal packages with the \texttt{'load'} command.
2460
2461 All \bbs and package paths are summmarized in the 
2462 information output when pressing 'Config' in \bbStudio. 
2463 You can see that two \bbs paths are always set :
2464 \begin{itemize}
2465 \item The current directory (\texttt{.})
2466 \item The \bbs folder of \bbtk 
2467 \end{itemize}
2468 Also, two package paths are always set :
2469 \begin{itemize}
2470 \item The current directory (\texttt{.})
2471 \item The libraries folder of \bbtk 
2472 \end{itemize}
2473
2474 Additional paths set in your \texttt{bbtk\_config.xml} are added after those standard paths.
2475 Note that the order displayed is the one in which the folders are searched when 
2476 \texttt{include} or \texttt{load} commands are issued.
2477
2478
2479 %%==============================================================================================
2480
2481 \subsection{Misc}
2482 \begin {itemize}
2483 %\item{make} \\
2484 %For some strange reasons (?!?), at \texttt{cmake} time, 
2485 %you may be warned that an error occured while documentation generation.\\
2486 %Take it easy, \texttt{make} again!\\
2487
2488 \item{\bbStudio} is written using the Advanced User Interface library of wxWidgets.
2489 If, after some hazardous floating/docking operations onto the frame, you feel
2490 very unhappy with the result, just remove from the hidden directory
2491 \texttt{.bbtk} the file named \texttt{bbStudio.aui}. \\ 
2492
2493  
2494 \end {itemize}
2495
2496
2497
2498 \end{document}
2499