have been written by different persons, using different libraries, etc.
\end{itemize}
+
+% ==========================================
+\hrule
+\paragraph{Summary}
+%\hrule
+A \texttt{black box}:
+\begin{itemize}
+ \item has a name (this is actually a type name),
+ \item has a description and an author,
+ \item belongs to categories (keywords that allow to index it
+into automated documentation, and that are specified in the box definition),
+ \item has inputs and outputs that in turn have their:
+ \begin{itemize}
+ \item names,
+ \item types (any C++ type),
+ \item descriptions,
+ \end{itemize}
+ \item does something and can be executed, i.e. outputs are updated according to inputs.
+\end{itemize}
+A \texttt{package}:
+\begin{itemize}
+ \item is a ``plug-in'' in the \bbtk framework,
+ \item has a name
+ \item has a description and an author.
+ \item contains:
+ \begin{itemize}
+ \item a dynamic library (dll/so/dylib) that contains compiled
+black boxes (e.g.: dynamic library name of the package `std' is `bbstd.dll', `libbbstd.so' or `libbbstd.dylib' depending on the platform),
+ \item bbs scripts: script-defined boxes, examples, applications,
+ \item data: test data, resources.
+ \end{itemize}
+ \item is automatically documented.
+\end{itemize}
+\hrule
+% ==========================================
+
% ==========================================
\subsubsection{\bbtk components}
% ==========================================
\item {\bf\emph{wxvtk}}: widget boxes based on the \vtk library (2D and 3D visualization and
interaction).
%\item {\bf\emph{creaImageIO}}: Provides hight level widgets to read images, including DICOM.
- \item {\bf\emph{toolsbbtk}}: Tools for bbtk administration and package development.
+ \item {\bf\emph{itkvtk}}: adaptors permitting to connect \itk boxes to \vtk boxes and conversely.
+ \item {\bf\emph{kw}}: widgets based on \texttt{KWWidgets} library (medical-image oriented:
+slicer, transfer function editors, etc.).
+ \item {\bf\emph{demo}}: some black-box based demos.
+ \item {\bf\emph{appli}}: some black-box based standalone applications.
+ \item {\bf\emph{toolsbbtk}}: tools for bbtk administration and package development.
\end{itemize}
\item A {\bf\emph{development environment}}, called \bbStudio, which provides:
\begin{itemize}
\end{itemize}
\end{itemize}
\item A standalone {\bf\emph{interpreter}}, called \bbins, which allows to
- execute \bbs scripts or commands.
+ execute \bbs scripts.
\item {\bf\emph{Various development utilities}}:
\begin{itemize}
\item \bbfy generates the \CPP code of a black box from a
% ==========================================
Read this \texttt{Users' Guide} if you want to learn how to use
-\bbtk development environnement (\bbStudions) and how to write black box scripts.\\
+\bbtk development environnement \bbStudio and how to write black box scripts.\\
If your aim is to write your own Packages and Black Boxes, you have to read the
\texttt{Package Developper's Guide}.
If you load a file holding a script, it will be displayed in this area, and you will be
able to modify it, to save it, to save-as it and to run it, using the respective
-lower-toolbar buttons (see figure \ref{lowertoolbar})
+lower-toolbar buttons (see figure \ref{lowertoolbar}).
\begin{figure}[!ht]
\caption{The 'Files' lower toolbar}
one single line area (\texttt{Command}), at the bottom, in which you can enter your commands, and
a multiple line zone (\texttt{Messages}) in which the command interpreter prints out the result of your commands.
%The upper part contains the script editor; we shall not use it right now, you may reduce it.
-Command-line help for the black box scripting language \bbsns (see \ref{Scripting}) can be obtained in this zone. \par
+Command-line help for the black box scripting language \bbs (see section \ref{Scripting}) can be obtained in this zone. \par
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
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
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
to store other black boxes.
Any black box you create in \bbStudio is stored
in \texttt{workspace}
-(this will be explained in details in sections
-\ref{bbi-writing-scripts} and
-\ref{bbi-command-line-app}).
+(see also section \ref{bbi-command-line-app}).
If you type \texttt{'help workspace'}, you get:
\begin{verbatim}
> help Add
\end{verbatim}
-{\bbStudions} displays the appropriate html page in the 'Help' part (see figure : \ref{HelpAdd}), and the following text in the 'Message' part:
+\bbStudio displays the appropriate html page in the 'Help' part (see figure : \ref{HelpAdd}), and the following text in the 'Message' part:
\begin{verbatim}
Black Box <std::Add>
Adds its inputs
the author(s) of the box (usually e-mail address(es)) and
the categories to which the box belongs,
the lists of inputs and outputs of the box.
-For each input or output, \bbi provides
-its \emph{name} ,
+For each input or output, the help provides
+its \emph{name},
its \emph{type} (between \texttt{<} and \texttt{>}, e.g. \texttt{<Int>})
and a description.
Remark that the box \texttt{Add} is not a 'complex' black box
'a' <std::Add>
\end{verbatim}
-This means that \bbi workspace now contains a black box named \texttt{a},
+This means that the user's workspace now contains a black box named \texttt{a},
of type \texttt{std::Add}. If you type:
\begin{verbatim}
> help workspace
> include wx
> include itk
> include wxvtk
+> include itkvtk
> new FileSelector fileDialog
> new ImageReader reader
> connect reader.Out viewer.In
> connect slider.Out viewer.Slice
> connect slider.BoxChange viewer.BoxExecute
-
> exec viewer
\end{verbatim}
Once you have defined a new type of complex box, you
may like to reuse it. To do this, you can simply
write the \bbs commands defining the new box
-into a text file and afterwards include that file in \bbins.
+into a text file and afterwards include that file anywhere you need.
Doing this, you start writing \bbs scripts.
The conventional (and mandatory) extension for such scripts is \texttt{bbs}
(black box script).
If the file has the \texttt{bbs} extension, you can omit it and just type:
\begin{verbatim}
-> include Add3
+> include bbAdd3
\end{verbatim}
-provided that {\bbStudions} knows the path to the desired \texttt{bbs} file.
-See the section \ref{The_configuration_file} to learn about the configuration file and the way to add a new path to it. Note that, if you modify the configuration file, you will have to close {\bbStudions} and run it again, so that the new configuration be taken into account.
+provided that \bbStudio knows the path to the desired \texttt{bbs} file.
+See the section \ref{The_configuration_file} to learn about the configuration file and the way to add a new path to it. Note that, if you modify the configuration file, you will have to close \bbStudio and run it again, so that the new configuration be taken into account.
\subsection{Creating complex black boxes that use complex black boxes}
\label{bbi-complex-complex-black-boxes}
% ==========================================
% ==========================================
-\subsection{Creating command line applications}
+\subsection{Creating and using command-line applications}
\label{bbi-command-line-app}
% ==========================================
-Now that you know how to create complex black boxes
-(with \texttt{define/endefine}), think
-back to the \texttt{workspace} object.
+Command-line applications are those that can be executed by typing, in a console, the name of the application and the values of its parameters. The Linux users are very familiar with this way of working, while the Windows users are not, since they are used to execute the applications by clicking on the corresponding icons. Nevertheless, the command-line execution of the applications is feasible (although not very useful) in Windows. You just need to invoke the black ``console'' available either via \texttt{Start > Execute > cmd}, or via \texttt{Start > Programs > Accessories > Invoke commands}. Furthermore, command-line execution of applications is very useful in both environments in such cases as batches.
+
+So, you already know how to write script files that define complex black boxes
+(with \texttt{define/endefine}), and how to include them in (more) complex black boxes. You can imagine these definitions as though they were a kind of ``functions'' that can be ``called'' by a program (actually, these are rather ``classes'' that can be instanciated, according to the object-oriented programming concepts). The question now is how to write the ``main program'' to be executed directly from the console by typing:
+\begin{verbatim}
+> bbi <application-name>
+\end{verbatim}
+Note that this execution mode invokes the interpreter \texttt{bbi} and passes the name of the application to the interpreter.
+
+Let us think back of the \texttt{workspace} object.
Remember that it is also
a \texttt{complex black box}.
-Actually, when you type interpreter commands
-outside a \texttt{define/endefine} block,
+Actually, when you write \bbs commands
+outside of a \texttt{define/}\texttt{endefine} block,
you progressively define the \texttt{workspace}
complex black box.
-You can think of it like if at start the interpreter
+You can think of it as though at start the interpreter
was issuing a command \texttt{'define workspace'}
and then letting you define the interior of the box
\texttt{workspace}.
-Remember that the command \texttt{inputs}
+Remember that the command \texttt{input}
allows to define an input of a complex box.
Now, if you use the command \texttt{input}
outside a \texttt{define/endefine} block then
This input will then be connected to the
parameters that the user passes to the command line.
-For example, consider the script :
+For example, consider the script:
\begin{file}{add.bbs}
\begin{verbatim}
The third and fourth lines define two inputs \texttt{x}
and \texttt{y}. When you execute this script,
-you can pass these two arguments on the command line,
-like this :
+you can pass these two arguments in the command-line,
+like this:
\begin{verbatim}
> bbi add x=1 y=1
x+y=2
\end{verbatim}
-You can also invoke \bbi the option \texttt{-h},
-which gives help on the \texttt{workspace} box :
+You can also note that, in the command-line context, you can invoke \bbi with the option \texttt{-h},
+which gives help on the \texttt{workspace} box:
\begin{verbatim}
> bbi add -h
'y' <double> : second number to add
\end{verbatim}
-To get a better help, use the \texttt{description}
-and \texttt{author} commands :
-
+This is particularly useful to learn about the usage of the application, namely about the inputs that are to be set at execution. To improve the help provided, use the \texttt{description}
+and \texttt{author} commands in the script file defining the application:
+\\
+\\
\begin{file}{add.bbs}
\begin{verbatim}
description "Adds two numbers"
Note that for both \texttt{-t} and \texttt{-g} options,
the input from the user is a \texttt{string} and
\bbi converts it to the right input type using
-an \texttt{adaptor}, hence the right adaptors must be loaded.
+an \texttt{adaptor}, hence the right adaptors must be previously loaded.
% ==========================================
\hrule
Basic graphical interface components are provided in the package \texttt{wx},
such as buttons, sliders, file open/save dialogs, etc.
-As first example, type the following commands in \bbi :
+As first example, type the following commands in \bbStudio :
\begin{verbatim}
-> load wx
-> new InputText t
-> print $t.Out$\n
+> include wx
+> new DirectorySelector d
+> print $d.Out$
\end{verbatim}
-When you type \texttt{enter} after the last line,
-a window pops up in which you can entrer a text.
-When you close the window, the text you entered is printed by
+When you hit the \texttt{enter} key after the last line,
+the usual directory-selection window pops up.
+When you validate your selection, the directory name you selected, preceded by the corresponding path, is printed by
the \texttt{print} command.
+Note that you can determine a default directory by setting the appropriate input as follows:
+\begin{verbatim}
+> set d.DefaultDir <directory-name>
+\end{verbatim}
-Type \texttt{help wx}, you get something like :
+Now, type \texttt{help wx}, you get something like:
\begin{verbatim}
Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
- Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
+ Basic graphical interface elements (sliders, buttons ...) based ...
Black boxes :
- ColourSelector : Colour Selector dialog (bbfication of wxColourSele...
- ColourSelectorButton : A button which displays a colour picker dialog whe...
+ ColourSelector : Colour Selector dialog (bbfication of ...
+ ColourSelectorButton : A button which displays a colour picke...
CommandButton : Button which executes bbi commands
- DirectorySelector : Pops up a directory selection dialog (wxDirDialog)
- FileSelector : Pops up a file selection dialog for reading or sav...
- InputText : A zone in which the user can enter a text (wxTextC...
+ DirectorySelector : Pops up a directory selection dialog (...
+ FileSelector : Pops up a file selection dialog for re...
+ InputText : A zone in which the user can enter a t...
LayoutLine : LayoutLine widget (wxBoxSizer)
- LayoutSplit : Widget which splits a window in two fixed size par...
+ LayoutSplit : Widget which splits a window in two fi...
LayoutTab : LayoutTab widget (wxNotebook)
- OutputText : Text zone to be inserted into a window (wxStaticTe...
+ OutputText : Text zone to be inserted into a window...
RadioButton : RadioButton group widget 0-9 entries
Slider : Slider widget (wxSlider)
\end{verbatim}
-You can reproduce the same experiment as above using a
-\texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}..
+You can reproduce the same experiment as above using for example
+a \texttt{FileDialog} rather than a \texttt{DirectorySelector}.
+
+If you choose to reproduce the experiment with:\\
+\texttt{> new InputText t} (or \texttt{new Slider s}),
+
+you will have to precede the command:\\
+\texttt{> print \$t.Out\$} (or \texttt{print \$s.Out\$})
+
+by the following command:\\
+\texttt{> set t.WinDialog true} (or \texttt{set s.WinDialog true} respectively).
+This blocks the pipeline until the widget is closed. Also note that the corresponding widgets do not have a validation button. Therefore, you will have to close them by clicking in the appropriate corner.
%There are two kinds of widgets : ``terminal'' widgets and ``container'' widgets.
%The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets
and be adjusted by the user thanks to a ``handle''.
The example \texttt{exampleLayoutSplit} demonstrates its use.
-Run it : it displays a window with two sliders.
+Run it: it displays a window with two sliders.
Move the sliders and close the window.
-Now look at the source file to see how this is done :
+Now look at the source file to see how this is done:
\begin{file}{scripts/test/testSplit.bbs}
\begin{verbatim}
First, the two sliders \texttt{s1} and \texttt{s2} are created.
A \texttt{LayoutSplit} box \texttt{s} is also created.
-The \texttt{connect} commands then ``includes'' the sliders in the
+The \texttt{connect} commands then ``include'' the sliders in the
split widget.
-The input \texttt{Widget} is common to all widget boxes :
+The input \texttt{Widget} is common to all widget boxes:
every widget can be inserted into another widget.
-The outputs \texttt{Widget1},\texttt{Widget2} are specific of \emph{layout}
+The outputs \texttt{Widget1}, \texttt{Widget2} are specific of \emph{layout}
widgets
-(in \bbi type \texttt{help Slider}:
+(in \bbStudio type \texttt{help Slider}:
you will see the output \texttt{Widget};
type \texttt{help LayoutSplit}:
you will see the inputs \texttt{Widget1} and \texttt{Widget2}
\texttt{-C} checks the factory integrity.
\texttt{-D} turns on objects debug info after main ends\\ \hline
-\texttt{quit} & - & Exits the interpreter\\ \hline
+\texttt{quit} & - & Stops the interpretation of the current script\\ \hline
\end{tabular}
\end{table}
git://git.creatis.insa-lyon.fr / bbtk.git / commitdiff