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