{\Huge Reference Manual}
\vspace{1cm}
-\bbtk version 1.0
+\bbtk version \bbtkVersion
\vspace{0.5cm}
\begin{verbatim}
---> Should be moved in a 'Reference Manual' ?\\
---> Any suggestion welcome!
+
+--> The following is just the concatenation of various parts, removed from different 'manuals', and wainting for
+their new affectation.
\end{verbatim}
\section{aaa}
+% ==========================================
+\subsubsection{complex black box definition related commands}
+\label{bbi-reference-black-box-definition}
+% ==========================================
+
+See table \ref{bbi-reference-complex-box}
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{bbi-reference-complex-box} \bbi complex black box definition related commands.}
+\small
+\begin{tabular}{|lcm{6cm}|}
+\hline
+Command & Parameters & Effect \\ \hline
+
+
+\texttt{define} & \texttt{<box-type>} &
+Starts the definition of a complex black box of type
+\texttt{box-type}\\ \hline
+
+\texttt{endefine} & - &
+Ends the definition of a complex black box type\\ \hline
+
+\texttt{author} & \texttt{<string>} &
+Sets the author(s) of the complex black box currently being defined \\ \hline
+
+\texttt{description} & \texttt{<string>} &
+Sets the description of the complex black box currently being defined \\ \hline
+
+\texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
+Defines a new input for the current complex black box,
+named \texttt{name}.
+It is defined as corresponding to
+the input \texttt{input} of the box \texttt{box}.
+
+\texttt{<help>} is the help string for the new input.
+The box \texttt{box} must already have been created in the complex box
+and of course have an input named \texttt{input}.\\ \hline
+
+\texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
+Defines a new output for the current complex black box,
+named \texttt{name}.
+It is defined as corresponding to
+the output \texttt{output} of the box \texttt{box}.
+\texttt{<help>} is the help string for the new output.
+The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}. \\ \hline
+
+
+\end{tabular}
+\end{table}
+
+% ==========================================
+\subsubsection{Interpreter related commands}
+\label{bbi-reference-interpreter}
+% ==========================================
+See table \ref{tabbbi-reference-interpreter_1} and \ref{tabbbi-reference-interpreter_2}
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{tabbbi-reference-interpreter_1}\bbi intepreter related commands (part 1).}
+\small
+\begin{tabular}{|lcm{6cm}|}
+\hline
+Command & Parameters & Effect \\ \hline
+
+\texttt{author} & \texttt{<author-name>} &
+Adds the string \texttt{<author-name>} to the author information of the black box being defined \\ \hline
+
+\texttt{category} & \texttt{<category-name>} &
+ Adds the string \texttt{<category-name>} to the category information of the black box being defined \\ \hline
+
+\texttt{help} & - &
+Prints help on available commands \\ \hline
+
+& \texttt{<command-name>} &
+Prints help on the command \texttt{command-name} \\ \hline
+
+& \texttt{packages} &
+Prints help on available packages and their box types
+(without description)\\ \hline
+
+& \texttt{<package-name>} &
+Prints help on the package \texttt{package-name} and its boxes
+(with brief description).
+The package must have been previously loaded \\ \hline
+
+& \texttt{<box-type>} &
+Prints help (with full description) on the type of box
+\texttt{box-type}.
+The box type must belong to a package which has been previously loaded \\ \hline
+
+& \texttt{<debug-directive>} &
+[expr|-C|-D]
+ Prints debug info on living bbtk objects containing the string \texttt{expr} (default expr='').
+ \texttt{-C} checks the factory integrity.
+ \texttt{-D} turns on objects debug info after main ends\\ \hline
+
+\texttt{include} & \texttt{<file-name>} &
+Includes and executes the content of the file named \texttt{file-name}
+exactly like if you were typing its content at the place were the
+\texttt{include} command is. \\ \hline
+
+\texttt{load} & \texttt{<package-name>} &
+Loads the package \texttt{package-name} (use it only if you know that you won't work with complex black boxes) \\ \hline
+
+\texttt{include} & \texttt{<package-name>} &
+Loads the package \texttt{package-name} and includes all the complex black boxes that comes with it \\ \hline
+
+\texttt{kind} & \texttt{<box kind>} &
+Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline
+\end{tabular}
+\end{table}
+
+
+
+%
+% This arbitrary part1/part2 is to avoid to have all the tables at the end of the docoment ...
+%
+
+\begin{table}[!ht]
+\caption{\label{tabbbi-reference-interpreter_2}\bbi intepreter related commands (part 2).}
+\small
+\begin{tabular}{|lcm{6cm}|}
+\hline
+Command & Parameters & Effect \\ \hline
+\texttt{unload} & \texttt{<package-name>}&
+Unloads the package \texttt{package-name}.
+The package must have been previously loaded.
+No box of a type defined in this package must still exist.\\ \hline
+
+\texttt{message} & \texttt{<category>} \texttt{<level>} &
+Sets the level of verbosity of \bbi for the category of messages
+\texttt{category} to \texttt{level}.\\ \hline
+%See \ref{verbosity}.
+
+\texttt{config} & - & Displays the Configuration parameters\\ \hline
+
+\texttt{reset} & - & Deletes all boxes and unloads all packages so
+that \bbi gets back to its initial state \\ \hline
+
+\texttt{quit} & - & Exits the interpreter (Don't use it under \bbStudions)\\ \hline
+
+\end{tabular}
+\end{table}
\subsection{ccc}
\vspace{0.5cm}
-Last modified on : October 9, 2008 \\
+Last modified on : October 12, 2008 \\
Generated on : \today
\vspace{0.5cm}
\newpage
% ==========================================
\hrule
-\section{What is {\bf bbtk} ?}
+\section{What is bbtk ?}
% ==========================================
\BBTK(\bbtkns) is a set of tools
(\CPP libraries and executables)
%author, description, inputs, outputs, and so on).
\item \bbCreatePackage allows to create the basic file architecture
to start the development of a new black box package.
+ \item \bbCreateBlackbox allows to create the basic file architecture
+ to start the development of a new black box, that will be included in an already existing package.
\item \texttt{bbs2cpp} translates a \texttt{.bbs} script into a \CPP file.
- \item \texttt{bbc} that
+ \item \texttt{bbc} that interprets (i.e. : executes) a \texttt{.bbs} script.
\end{itemize}
\item A full {\bf\emph{documentation}} printable (pdf), browsable (html), queryable thru keywords.
\end{itemize}
You can see four parts : \texttt{Files}, \texttt{Messages},
\texttt{Command}, \texttt{Help}.\\
-The stuff is written using the Advanced User Interface library of wxWidgets,
+The stuff is written using the Advanced User Interface library of wxWidgets
+(a.k.a. AUI),
whose 'docking manager' allows windows and toolbars to be floated/docked
onto a frame.\\
Please don't use this feature at learning time (the snapshots of this document
\begin{figure}[!ht]
\caption{\label{lowertoolbar}The lower tool bar}
\begin{center}
-\includegraphics[width=0.7\textwidth]{lowertoolbar.png}
+\includegraphics[width=0.7\textwidth]{lowertoolbar2.png}
\end{center}
\end{figure}
- \begin{itemize}
- \item {\bf\emph{New file}} : Create a new file to hold a script
- \item {\bf\emph{Open file}} : Open an already existing file holding a script
- \item {\bf\emph{Close file}} : Close a file holding a script
- \item {\bf\emph{Save file}} : Save he current file (if modified)
- \item {\bf\emph{Save file as}} : Save he current file under a different name
- \item {\bf\emph{Run file}} : Execute the script you just loaded/modified/written
- \item {\bf\emph{cursor position}} : column number : line number
- \end{itemize}
+% \begin{itemize}
+% \item {\bf\emph{New file}} : Create a new file to hold a script
+% \item {\bf\emph{Open file}} : Open an already existing file holding a script
+% \item {\bf\emph{Close file}} : Close a file holding a script
+% \item {\bf\emph{Save file}} : Save he current file (if modified)
+% \item {\bf\emph{Save file as}} : Save he current file under a different name
+% \item {\bf\emph{Run file}} : Execute the script you just loaded/modified/written
+% \item {\bf\emph{cursor position}} : column number : line number
+% \end{itemize}
\subsubsection{'Messages' part}
\item{misc}
\end {itemize}
\end {itemize}
+
+% ==========================================
+\subsubsection{The Package Browser}
+\label{Package_Browser}
+% ==========================================
+
+
+You can run it using the tool bar of the 'Command' part.
+
+See figure \ref{imPackage_Browser}.
+
+\begin{figure}[!ht]
+\caption{\label{imPackage_Browser}The Package Browser}
+\begin{center}
+\includegraphics[width=0.6\textwidth]{Package_Browser.png}
+\end{center}
+\end{figure}
+
+It allows you to query informations about what you can find in the packages (boxes and applications), using several criterions
+(warning : it's case sensitive, i.e \texttt{Button} will give different results thn \texttt{button} ...)
+\begin {itemize}
+\item Pakages :\\
+All the boxes and applications held in a given package (e.g. \texttt{wxvtk}, \texttt{std}, ...)
+\item Name :\\
+You can query on a subpart of the name of a box or an application (e.g. \texttt{DICOM})
+\item Description :\\
+You can query on a substring of the description of a box or an application (e.g. \texttt{utton} : user wants to get all
+the\texttt{Button} as well as the \texttt{button} )
+\item Category :\\
+You can query on a sub part of the category name of a box or an application (e.g. \texttt{3D})
+\item Input Type :\\
+You can query all the boxes or applications that have at least one Input entry of the given type (e.g. \texttt{int})
+\item Output Type :\\
+You can query all the boxes or applications that have at least one Output entry of the given type (e.g. \texttt{int})
+\item Input Nature :\\
+You can query all the boxes or applications that have at least one Input entry of the given nature (e.g. \texttt{signal})
+\item Output Nature :\\
+You can query all the boxes or applications that have at least one Output entry of the given nature (e.g.
+\texttt{signal},\texttt{file name})
+\end {itemize}
+
+
+All these criterions are \emph{AND}ed while the query process.\\
+You can get the whole description of a given box or application clicking on its name.
+
+\newpage
% ==============================================
\subsection{The Menu}
% ==============================================
-TODO
+At last, let's have a look at \bbStudio menu.(See figure \ref{themenu})
+\begin{figure}[!ht]
+\caption{\label{themenu}The bbStudio menu}
+\begin{center}
+\includegraphics[width=0.7\textwidth]{themenu.png}
+\end{center}
+\end{figure}
+
+\begin {itemize}
+ \item{File}
+ \begin {itemize}
+ \item{Open bbtk config}
+ \item{Quit}
+ \end {itemize}
+ \item{Tools}
+ \begin {itemize}
+ \item{Create package}
+ Provides a graphical interface to help Package developper to create a new void package.
+ \item{Create black box}
+ Provides a graphical interface to help Package developper to create a new void black box, and add it to an already existing package.
+ \item{Show last image graph}
+ \item{Regenerate package doc}
+ If user was supplied new black boxes, and added them to an already existing package, he can update the package documentation, in order to benefit all the features of the Help mechanisms.
+ \item{Regenerate boxes list}
+ User wants to update only boxes list (quicker)
+ \item{Regenerate all}
+ User wants to rebuild the whole documentation.
+ \end {itemize}
+ \item{Options}
+ \begin {itemize}
+ \item{Reset before running} Before running, all the already boxes are destroyed, all the already loaded packages are unloaded (this is the recomended option).
+ \end {itemize}
+ \item{Windows}
+ User may decide, for any reason of his own, to hide one or more pannels:
+ \begin {itemize}
+ \item{Show 'Files' panel}
+ \item{Show 'Help' panel}
+ \item{Show 'Command' panel}
+ \item{Show 'Messages' panel}
+ \item{Launch Package browser} The package browser is a stand alone application. This can be achieved, too, using the lower tool bar, button 'Start Package Browser'
+ \item{}
+ \end {itemize}
+ \item{About}
+ \begin {itemize}
+ \item{About}
+ \end {itemize}
+\end {itemize}
% ==========================================
\section{bbs scripting}
% ==========================================
% ==========================================
-\subsection{Using an already existing}
+\subsection{Using an already existing script}
% ==========================================
+Using the lower toolbar (see figure : \ref{lowertoolbarsmall}), open the file
+holding the script.
+
+\begin{figure}[!ht]
+\caption{\label{lowertoolbarsmall}The lower tool bar}
+\begin{center}
+\includegraphics[width=0.7\textwidth]{lowertoolbar.png}
+\end{center}
+\end{figure}
+
+ You'll see it, in the '\texttt{Files}' part.\\ \\
+ You may run it, using the lower toolbar. \\
+ \texttt{WARNING :} if the script contains one or more \texttt{LayoutSplit}
+ object, you will have to resize the sub windows. \\ \\
+ You may modify, save or save-as the current script, using the lower toolbar.\\ \\
+ You may have a look at the graphical representation of the pipeline (sorry,
+ right now, to modify the pipeline, you have to modify the script;
+ you cannot modify grapically the pipeline; Work in progress...)
+
+
% ==========================================
-\subsection{Creating and executing black boxes}
+\subsection{Inside black boxes}
% ==========================================
-You'll get as well the same information in the 'Help' Part, in html format (see figure : \ref{HelpAdd}) :
+After loading the package it belongs to, you can ask information about a given black box :\\
+In the \texttt{Command part}, type \texttt{help} + black box name, e.g. \\
+\begin{verbatim}
+> help Add a
+\end{verbatim}
+Have a look to the 'Help' Part (see figure : \ref{HelpAdd}) :
\begin{figure}[!ht]
\caption{\label{HelpAdd}The html Help}
\end{center}
\end{figure}
-Like previously,
-the \texttt{std::} prepended to the name \texttt{Add}
+The \texttt{std::} prepended to the name \texttt{Add}
means that the box \texttt{Add}
belongs to the \texttt{std} package.
Then comes a description
\texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}.
See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
-There are two kinds of widgets : ``terminal'' widgets and ``container'' widgets.
-The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets
-are ``terminal'' widgets.
-``container'' widgets are of another kind : they are designed to
+
+%There are two kinds of widgets : ``terminal'' widgets and ``container'' widgets.
+%The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets
+%are ``terminal'' widgets.
+%``container'' widgets are of another kind : they are
+There is a special kind of widget, called '\texttt{Layout}', designed to
contain other widgets in order to build larger dialog boxes.
For example, the \texttt{LayoutSplit} widget is a container which
``splits'' horizontally a window into two parts,
\subsubsection{pipeline creation and execution related commands}
\label{bbi-reference-creation-execution}
% ==========================================
-
+ See table \ref{bbi-reference-box}
% ==========================================
\begin{table}[!ht]
\subsubsection{Interpreter related commands}
\label{bbi-reference-interpreter}
% ==========================================
-
+See table \ref{tabbbi-reference-interpreter_1} and \ref{tabbbi-reference-interpreter_2}
% ==========================================
\begin{table}[!ht]
-\caption{\label{bbi-reference-interpreter}\bbi intepreter related commands.}
+\caption{\label{tabbbi-reference-interpreter_1}\bbi intepreter related commands (part 1).}
\small
\begin{tabular}{|lcm{6cm}|}
\hline
\texttt{kind} & \texttt{<box kind>} &
Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline
+\end{tabular}
+\end{table}
+%
+% This arbitrary part1/part2 is to avoid to have all the tables at the end of the docoment ...
+%
+
+\begin{table}[!ht]
+\caption{\label{tabbbi-reference-interpreter_2}\bbi intepreter related commands (part 2).}
+\small
+\begin{tabular}{|lcm{6cm}|}
+\hline
+Command & Parameters & Effect \\ \hline
\texttt{unload} & \texttt{<package-name>}&
Unloads the package \texttt{package-name}.
The package must have been previously loaded.
\texttt{message} & \texttt{<category>} \texttt{<level>} &
Sets the level of verbosity of \bbi for the category of messages
\texttt{category} to \texttt{level}.\\ \hline
-%See \ref{verbosity}.
+%See \ref{verbosity}.
\texttt{config} & - & Displays the Configuration parameters\\ \hline
\end{table}
% ==========================================
-
+\newpage
% ==========================================
\subsubsection{complex black box definition related commands}
\label{bbi-reference-black-box-definition}
% ==========================================
+See table \ref{bbi-reference-complex-box}
% ==========================================
\begin{table}[!ht]
\caption{\label{bbi-reference-complex-box} \bbi complex black box definition related commands.}
%\vspace{0.5cm}\hrule \\
-\section{The Package Browser}
-\label{Package_Browser}
-% ==========================================
-
-
-You can run it using the tool bar of the 'Command' part.
-
-See figure \ref{Package_Browser}.
-
-\begin{figure}[!ht]
-\caption{\label{Package_Browser}The Package Browser}
-\begin{center}
-\includegraphics[width=0.6\textwidth]{Package_Browser.png}
-\end{center}
-\end{figure}
-
-It allows you to query informations about what you can find in the packages (boxes and applications), using several criterions
-(warning : it's case sensitive, i.e \texttt{Button} will give different results thn \texttt{button} ...)
-\begin {itemize}
-\item Pakages :\\
-All the boxes and applications held in a given package (e.g. \texttt{wxvtk}, \texttt{std}, ...)
-\item Name :\\
-You can query on a subpart of the name of a box or an application (e.g. \texttt{DICOM})
-\item Description :\\
-You can query on a substring of the description of a box or an application (e.g. \texttt{utton} : user wants to get all
-the\texttt{Button} as well as the \texttt{button} )
-\item Category :\\
-You can query on a sub part of the category name of a box or an application (e.g. \texttt{3D})
-\item Input Type :\\
-You can query all the boxes or applications that have at least one Input entry of the given type (e.g. \texttt{int})
-\item Output Type :\\
-You can query all the boxes or applications that have at least one Output entry of the given type (e.g. \texttt{int})
-\item Input Nature :\\
-You can query all the boxes or applications that have at least one Input entry of the given nature (e.g. \texttt{signal})
-\item Output Nature :\\
-You can query all the boxes or applications that have at least one Output entry of the given nature (e.g.
-\texttt{signal},\texttt{file name})
-\end {itemize}
-
-
-All these criterions are \emph{AND}ed while the query process.\\
-You can get the whole description of a given box or application clicking on its name.
-
% ==========================================
%\vspace{0.5cm}\hrule \\
\label{Third_Party_Package}
% ==========================================
-You will have to update the \emph{bbtk\_config.xml} file.\\
-To know where it is stored, just click on \texttt{Config} button of the \texttt{Command} part toolbar.
+% ==========================================
+\subsection{The configuration file}
+\label{The_configuration_file}
+% ==========================================
+
+First, have a glance at the Configuration, just clicking on \texttt{Config} button of the \texttt{Command} part toolbar.
You'll get something like :
(depending on who you are, and whether \texttt{bbStudio} is installed or not.)\\
-Just use your favourite text editor to add :
-\begin{itemize}
-\item
- at the end of the \texttt{BBS Paths} part
- the name of the directory that contains the \texttt{.bbs} scripts of the package you
-want to use,
-\item at the end of the \texttt{PACKAGE Paths} part
- the name of the directory that contains the dynamic libraries (\texttt{.dll} or \texttt{.so}) of the package
-\end{itemize}
+Note the two main parts : \texttt{BBS Paths} and \texttt{PACKAGE Paths}
+
+To use a third party Package, you will have to update the \emph{bbtk\_config.xml} file.\\
+
+Just use the \texttt{Open bbtk Config file} option of the \texttt{Files} of the \bbStudio menu.
+
+You will get something like :
+\begin{verbatim}
+<config>
+ <description> Sets the search directories in the build tree </description>
+ <url> </url>
+ <bbs_path> /home/jpr/Creatis/bbtk/binLIN/share/bbtk/bbs </bbs_path>
+ <package_path> /home/jpr/Creatis/bbtk/binLIN/bin </package_path>
+# For windows
+ <package_path> /home/jpr/Creatis/bbtk/binLIN/bin\Debug </package_path>
+ <package_path> /home/jpr/Creatis/bbtk/binLIN/bin\Release </package_path>
+#
+ <data_path> </data_path>
+#
+ <default_temp_dir> /home/jpr/Creatis/bbtk/binLIN </default_temp_dir>
+</config>
+\end{verbatim}
+%\begin{itemize}
+%\item {
+After the already existing tags
+%bbs\_path
+\texttt{bbs\_path}
+ (i.e. the lines begining by
+ \texttt{bbs\_path}
+ %bbs_path
+and ending by
+\texttt{/bbs\_path})
+
+%/bbs_path})
+ add a new one with the name of the directory that contains the
+ \texttt{.bbs} scripts of the package you
+want to use.\\
+x
+%\item {
+After the already existing tags \texttt{package\_path} (i.e. the lines begining by \texttt{package\_path}
+ and ending by \texttt{/package\_path})
+ add a new one with the name of the directory that contains the the dynamic libraries
+ (\texttt{.dll} or \texttt{.so}) of the package you want to use.
+
+%\end{itemize}
+% ==========================================
+\subsection{Updating the documentation}
+\label{The_configuration_file}
+% ==========================================
If you want (and sure you will) to be able to use the Help tools as well on the features provided by this package, you must use the
-option \texttt{Generate index} in the menu \texttt{Tools} of the \texttt{Files} part toolbar.
+option \texttt{Regenerate package doc} in the menu \texttt{Tools} of \texttt{bbStudio}.
+
+% ==========================================
+\subsection{Using the package}
+\label{Using_the_package}
+% ==========================================
+
+The only thing you have to do is to \texttt{load} the package, within the script, or from the
+\texttt{Command} part, and enjoy the black boxes it contains.
+
% ==========================================
%\vspace{0.5cm}\hrule \\
\section{Using black boxes in \CPP programs}
User wants to create a slider and an output text, within a layoutline, and display the slider value in the output text.\\
Think about the (little!) nightmare to code the same, in 'raw C++', using wxWidgets.\\
-Using \bbtk you just 'convert' the script :
+Using the standalone application \bbc you just 'convert' the script :
\begin{verbatim}
#include <bbwxSlider.h>
%\bibliography{all}
+\section{Install and run time issues}
+
+\bbStudio is written using the Advanced User Interface library of wxWidgets.
+If, after some hazardous floating/docking operations onto the frame, you feel
+very unhappy with the result, just remove from the hidden directory
+\texttt{.bbtk} the file named \texttt{bbStudio.aui}. \\ \\
+
+
+ \texttt{WARNING :} if the script contains one or more \texttt{LayoutSplit}
+ object, you will have to resize the subwindows. \\
%\section{Conclusion}
projects / bbtk.git / commitdiff
