\documentstyle[12pt,a4wide,psfig]{article} \title{DEveloppement soft} \author{L. Michel} \date{Edition 1.0 decembre 1990} \begin{document} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TITRE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{titlepage} { \hoffset=0.truein \hsize=5.25truein \vsize=10.25truein \font\small=cmssbx10 at 14.4truept \font\medium=cmssbx10 at 17.28truept \font\large=cmssbx10 at 20.74truept \hrule height 0pt \parindent=0pt %\parskip=0pt \hskip 3.9truein \large \par \vskip .5truein \large Eurogam project \hskip 5cm EDOC119\par \vskip 1.5truein \hrule height 2pt \vskip 20pt \large Developpement graphique\par \vskip .5truein \small DISPLAY MODULE - ANALYSIS MODULES\par \vskip 20pt \hrule height 2pt \vskip 1truein \medium Edition 1.0\par \vskip 3pt 20 February 1991\par \vfill \small G.ZEHNACKER et L. MICHEL\par \vskip 30pt \medium Centre de Recherches Nucl\'{e}aires de Strasbourg (SATD)\par \vskip 5pt CNRS-IN2P3 France\par \vskip 5pt } \end{titlepage} \begin{abstract} The users of the future softwares for data analysis need to use her own treatment modules. We must then imagine a display kernel which uses functions coming from different external libraries. The interface between the external libraries and the kernel don't must need modification of one or the other. We propose in this document a method to do that, using a X toolkit for the kernel and executable files for the user's functions, the both communicating trough the UNIX shell. \end{abstract} \section{Display module - analysis modules.} \hskip 1cm Some applications must be able to display spectra and to analyse them. The software used for display and manage images must be very secure. We think that it must be written like a graphic kernel, tested in detail, and not modifiable. This kernel will be used in some different applications for the data analysis and the experience control. This way, the method for manipulate images will be known by each user, and well-known for its reliability. The application doesn't only manipulate images but also do calculations on data. These other functions are specific to each application (and user ?) and then, must be easly linkable to the graphic kernel. They must be callable from other contexts that our display software and then they must be stored in external librairies. \section{Using the shell} \hskip 1cm The external functions must have a specific format to be used in different contexts. The most simple way to call functions is to use the shell on an alphanumeric terminal. In this case, the functions must be executable files using the standard input and output. Her callback from the shell is the better way to debug them and to write small applications. The Unix system has a lot of abilities to interface the shell and the applications. So we think that the external functions must be callable from the shell, and from our applications trought the shell. Then they will be callable without specific adaptation by all the applications runing under Unix. \section{Calling external functions} \subsection{The five steps to call external functions} \hskip 1cm The call by an application of an external function has five steps needing each a specific treatment (see Fig 1): \begin{itemize} \item Select the function. \item Set the paramters of the function. \item Call the function. \item Get the results of the function. \item Do the graphic interpretation of the results. \end{itemize} \begin{figure} \psfig{figure=edoc119_fig1.ps,width=15cm,height=8cm} \end{figure} \subsection{Selecting the function} \hskip 1cm The external functions are called from menu items. The contenu of a menu and its label are set up specifically for the external functions library. Four menus (help, storage, image and data-base) are managed directly by the graphic kernel. The other menus call external functions. \subsection{Setting the paramters} \hskip 1cm Each external function has specific arguments, with a specific format, in a specific order. The calling application must know this format and then sets from the user requsts the corresponding command line. Our idea is to do that with dialog boxes having an active object associated with each argument (for more details, see section 4.2). \subsection{Calling the function} \hskip 1cm The call of the functions must use characters strings sent to the shell. The process must have its output redirected to the calling program. That can be done by a Unix pipe (see example section 3.5). \subsection{Getting the results} \hskip 1cm The called function is connected to the calling programm by a Unix pipe. So the results can be read by the calling programm on the stream associated to the pipe. \begin{tabbing} Example:\hskip 1cm \= \it char \hskip 1cm \= \it *command\_line = "function\_name arg1 arg2 arg3";\\ \> \it FILE \> \it *pipe, *popen();\\ \> \it char \> \it result\_string[RESULT\_SIZE];\\ \> \> .\\ \> \> .\\ \> \it pipe = popen(command\_line , "r");\\ \> \it while( fgets(result\_string,RESULT\_SIZE,pipe) ) parse\_result(result\_string);\\ \> \> .\\ \> \> .\\ \end{tabbing} \rm The command line is merged in the string \it *command\_line \rm from the name of the function (selected in a menu) and the parameters set in a dialog box. This command is sent to the shell by the callback \it popen \rm, which starts up the function with its output connected on the stream \it pipe \rm. That calling programm reads the result strings on this stream with the function \it fgets \rm. The results are sent to the appropriate graphic routine which is selected by the \it parse\_result \rm function (for more details, see subsection ...). \subsection{Doing the graphic interpretation} \hskip 1cm Some external functions return single values which must be just displayed in characters what doesn't set problem. But some other functions return complex results such as spectra, peaks descriptors or peaks fits. In this case, the calling program (graphic kernel) must be able to interpret graphically these values. It must draw the spectra, the peaks or the fits from the returned values. The problem is that the user's functions (external) doesn't describe the same objects with the same formats. In consequence, the graphic kernel must have a library of functions able to interpret the results in the currentest formats. If a user want to add a new function which returns data with a new format, then a specific function will must be added to the graphical kernel to interpret the results. When an user sets up his graphic kernel with his library, he must specify for each external function the routine which must be called to interpret the results (for more details, see subsection 4.4). \section{Structure of the graphic kernel} \subsection{A parametrable kernel} \hskip 1cm The manipulation of the image, the access to the file system and the graphic interpretation are done by the graphic kernel. The same graphic kernel must be used with different libraries of external functions without modification. That can be done if the graphic kernel is set up at its start up. This setup defines the contenu of the menu bar and the menu items, the features of the associated dialog boxes and the associated routine for the graphic interpretation of the results. All these informations can be written in an ASCII file associated to each library. In the following subsections we will define the most important features of these files. \subsection{Setting the dialog boxes} \hskip 1cm Each call to an external function is parametred with a dialog box handler, which read the arguments in the box and merges the command line. The features of the dialog boxe depend on the external functions, they must be set up from the configuration file. Our idea is to authorize the use of a limited set of active objects (widget such as setting, line edit and list) and to associate a single argument to each one. The look of the dialog boxe is realized by the graphic kernel from the list of active objects. The setup file gives for each dialog boxe some general parameters (movable, resizable, focused,..) and a list of objects with their own parameters. The graphic kernel reads this file when it starts up, and then creates the set of boxes. All the boxes have some common objects which doesn't be defined in the setup file. This objects are three buttons (OK, Cancel and Help) and an line editor in which is written the command line. We suggest to set three areas (see Fig 2) in a dialog box (each area can correspond to a XView control area, if XView is used). In the area on the top of the boxe is written the name of the command, and its menu. In the area of the bottom of the boxe are set the common objects (buttons, command line). In the middle of the boxe are set the user's dependents objects. \begin{figure} \psfig{figure=edoc119_fig2.ps,width=15cm,height=7cm} \end{figure} The user can set just three classes of object: the setting, the line edit and the list. Each class has a reserved part of the middle area. The size of these parts depends on the number of items inside. If it is no object, the part has a null size. The size of the boxe (see Fig 3)depends on the number of objects. To create the boxe, the graphic kernel calculates the size of each part, next, the size of the central area and then, pastes the three areas on a base window. \begin{figure} \psfig{figure=edoc119_fig3.ps,width=15cm,height=8cm} \end{figure} Each dialog boxe is described in memory by a structure which type is not yet defined (see subsection ...). So a unique routine can handle all the dialog boxes and return their command lines. \subsection{Setting the menu bar} \hskip 1cm The menu bar is empty, except four buttons, when the graphic kernel starts. Four menus are managed by the kernel: the File menu, which permits the acces to the file systems, the Image menu, which permits the manipulation of the images and the help and the data-base menu. Some internal functions can be called from command buttons without use a menu (see EDOC 112). The other menus, empty when the applicvation starts, are filled in from the setup file. At the begining of this file, the label of each menu is written. The item label, and its menu name is specified at the begining of the definition of each dialog boxe. The menu bar is set up during the analysis of the set up file. \subsection{Interpreting the results} We have seen (subsection 3.6) that the graphic kernel has some routines which interpret graphically specific result formats. All the results are passed to these routine by the string read on the pipe (see subsection 3.5). The problem is then to select the appropriate routine from the definition of the external callback written in the setup file. The graphic interpretation routine can be indentified by an integer or a string in the setup file. That value belongs to the structure defining the callback and is used by the \it parse\_result \rm function (see subsection 3.5) to switch to the good routine. Its also possible to set a pointer in that structure pointing to the interpretation routine (see following example). \begin{tabbing} Example:\hskip 1cm \= \it typedef struct \{ \= \it Dialog \hskip 1cm \= \it dialog;\\ \> \> \it Menu \> \it menu;\\ \> \> \it int \> \it *interp\_fct(); \} Callback\_def;\\ \> \it Callback\_Def \> \it callback\_def;\\ \> \it .\\ \> \it .\\ \> \it init\_callback(callback\_def); /* init the callback\_def struct */\\ \> \it \> .\\ \> \it extern\_callback(Callback\_Def callback\_def) \{\\ \> \it char \hskip 1cm \> \it *command\_line[MAX\_LGTH\_CMD];\\ \> \it FILE \> \it *pipe, *popen();\\ \> \it char \> \it result\_string[RESULT\_SIZE];\\\\ \> \it dialog\_handle(callback\_def, command\_line);\\ \> \it pipe = popen(command\_line , "r");\\ \> \it while( fgets(result\_string,RESULT\_SIZE,pipe) ) callback\_def.interp\_fct(result\_string);\\ \> \it \> .\\ \> \it \> .\\ \> \it \} \\ \> \it .\\ \> \it .\\ \end{tabbing} \rm Each external callback is described by a structure of type \it Callback\_Def \rm which contains the definition of the dialog box, the reference of the menu and a pointer to the graphic interpretation function. When the function is selected from its menu, the routine \it extern\_callback \rm is called to manage the callback. It first calls the dialog handler \it dialog\_handle \rm which merge the command line in the string \it command\_line \rm. After read the result string the graphic interpretation routine \it callback\_def.interp\_fct \rm pointed in the \it callback\_def \rm is called. \subsection{The setup file} \hskip 1cm We have now enough elements for define the most important features of the setup file. The external callbacks have three levels of definition: \begin{itemize} \item \it The menus: \rm Which specify the menu labels and the menu items. \item \it The dialog boxes. \rm Which specifies the graphic options, the graphic interpretation routine and the structure of the command line. \item \it The graphic objects. \rm Which specifies for each object the graphic options and the associate argument, \end{itemize} \vskip 1cm Example of syntax for the setup file: \begin{tabbing} \hskip 1cm \= \hskip 1cm \=\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it \# \> \>SETUP FILE \\ \it \# \\ \it \# \> SYNTAX PROTOTYPE\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it \# definition of the first menu.\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it MENU LabelMenu1 Pinable Movable\\ \> \it LabelItem1 LabelItem2 . . . LabelItemN\\\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it \# definition of the 2nd menu.\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \> .\\ \> .\\ \> .\\ \> .\\\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it \# definition of the Mth menu.\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it MENU LabelMenuM NoPinable Fixed \\ \hskip 1cm \= \it LabelItem1 LabelItem2 . . LabelItemK\\\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it \# definition of the 1st dialog box\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it DIALOG LabelMenu1:LabelItem1 Resizable Movable Focusable NonEditabelCommandLine\\ \> \it OBJECT\_SETTING LabelSetting1 ExclusiveChoise\\ \> \> \it LabelItem1 LabelItem2 ... LabelItemN \\ \> \it OBJECT\_SETTING LabelSetting2 NonExclusiveChoise default=OldValue\\ \> \> \it LabelItem1 LabelItem2\\ \> \it OBJECT\_LINEDIT LabelLinedit1 NumericOnly ChanelClick\\ \> \it OBJECT\_LINEDIT LabelLinedit2 NumericOnly ChanelClick\\ \> \it OBJECT\_LINEDIT LabelLinedit3 AlphaNumeric Default="-1"\\ \> \it OBJECT\_LIST LabelList1 ReadOnly ExclusiveChoise\\ \> \> \it Item1 Item2 ... ItemN \\ \> \it GRAPH\_INTER\_ROUTINE DrawPeakFromGaussienne\\ \> \it COMMAND\_LINE LabelLinedit1 LabelLinedit2 LabelSetting1 LabelSetting2 LabelList1 LabelLinedit3\\\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it \# definition of the 2nd dialog box\\ \it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \it DIALOG LabelMenu1:LabelItem2\\ \> .\\ \> .\\ \> .\\ \> .\\\\ \end{tabbing} \vskip 1cm The configuartion file has one definition for one object per line. If a definition line is too long for the text editor it's possible to cut it in several parts with a $\\$ at the end of each one. The structure of a definition line is : \it \begin{tabbing} \hskip 1cm \= [type of object]$<$blank$>$[label of object]$<$blank$>$[options li\\ \>$<$tabulation$>$[items list] \end{tabbing} \rm Each field can be set by a keyword. The following list gives just some examples, the global set of keywords will be defined later: \begin{tabbing} \hskip 1cm \= \hskip 3cm \= \\ \> \it [type of object] \> \rm Keyword giving the class of the defined object:\\\\ \> \bf MENU : \rm Definition of the items and the label of a menu.\\ \> \bf DIALOG : \rm General definition of a dialog boxe.\\ \> \bf OBJECT\_SETTING : \rm Definition of a setting included in a dialog boxe.\\ \> \bf OBJECT\_LINEDIT : \rm Definition of a linedit included in a dialog boxe.\\ \> \bf OBJECT\_LIST : \rm Definition of a list included in a dialog boxe.\\ \> \bf GRAPH\_INTER\_ROUTINE : \rm Definition of the internal routine used \\ \> \rm for the graphic interpretation.\\ \> \bf COMMAND\_LINE : \rm Order of the arguments in the command line.\\\\ \> \it [Label of object] \> \rm The label can be a string (between "") or a\\ \> \> \rm menu label (menulabel:itemlabel:...)\\\\ \> \it [options list] \> \rm Keywords, separeted by a blank, defining the mode\\ \> \> \rm of use of the defined object:\\\\ \> \bf Pinable (NoPinable) : \rm The menu or the dialog can be pined on the screen.\\ \> \bf Movable (Fixed) : \rm The menu or the dialog can be moved on the screen.\\ \> \bf Focused (Unfocused): \rm The events are focused on the dialog.\\ \> \bf Resizable : \rm The dailog can be resized.\\ \> \bf EditableCmdLine : \rm The user can write directly the commandline.\\ \> \bf Editable (ReadOnly): \rm The object can be set by the user.\\ \> \bf ExculsiveChoise : \rm The list or the setting can select a single item.\\ \> \bf Default=value: \rm Definition of the default value for an object Value can.\\ \> \rm be a string (between ""), a number for a setting or a keyword (OldValue).\\ \> \bf Default=OldValue: \rm the default value is the est value of the last call)\\. \> \bf NumericOnly : \rm The linedit or the list can be set just with numeric values.\\ \> \bf AlphaNumeric : \rm The linedit or the list can be set with all characters.\\ \> \bf ChannelClick : \rm The line edit or the list can be set with a channel number\\ \> \rm selected with the mouse in a draw of a spectrum.\\\\ \> \it [items list] \> \rm Used for the objects having several items (list, setting, menu).\\ \> \> \rm The items list is written on the line under the object definition.\\ \> \> \rm Its line gegin with a tabulation character.\\ \end{tabbing} \rm At the begining of the file are defined the menus. After, all the dialog boxes associated with each menu item are described. All the words are user's defined strings if written between "", or keywords known by the graphic kernel. \subsection{Structure of a callback in memory} \hskip 1cm Data structures describing the interface between the kernel and the external functions are created by the module of initialisation of the graphic kernel during its initialisation (see Fig 4). \begin{figure} \psfig{figure=edoc119_fig4.ps,width=15cm,height=8cm} \end{figure} Each class of active object is defined by a specific structure type (see the following code lines). This structure gives the number of objects, a list of pointers on these objects, the place of each associated argument in the command line and the of options. The list of pointers and positions ever can contain the maximum number of items (MAX\_XXX). That takes up uselessly a little bit of memory, but not so much to justify the use of dynamic allocation. \begin{tabbing} LIST STRUCTURE: \= \it typedef struct \{ \= \it int \hskip 1cm \= \it nb\_obj;\\ \> \> \it XSetting \> \it *ptr\_obj[MAX\_SETTING]; \\ \> \> \it Option \> \it option\_list;\\ \> \> \it int \> \it posit[MAX\_SETTING];\} Setting;\\\\ \> \it typedef struct \{ \> \it int \> \it nb\_obj;\\ \> \> \it XLinedit \> \it *ptr\_obj[MAX\_LINEDIT];\\ \> \> \it Option \> \it option\_list;\\ \> \> \it int \> \it posit[MAX\_LINEDIT];\} Linedit;\\\\ \> \it typedef struct \{ \> \it int \> \it nb\_obj;\\ \> \> \it XList \> \it *ptr\_obj[MAX\_LIST]; \\ \> \> \it Option \> \it option\_list;\\ \> \> \it int \> \it posit[MAX\_LIST];\} List;\\\\ \end{tabbing} \rm A callback is defined by a structure type (see the following code lines) which contains the definition of the active objects (see above), the pointer to the menu item at which the callback is connected and the pointer to the routine of graphic interpretation of the results. The use of the routine of graphic interpretation is explained in the subsection 4.4. \begin{tabbing} CALLBACK STRUCTURE: \= \it \#define \hskip 1cm MAX\_OBJ MAX\_SETTING + MAX\_LINEDIT + MAX\_LIST\\\\ \> \it typedef struct \{ \= \it Setting \= \it setting;\\ \> \> \it Linedit \> \it linedit;\\ \> \> \it List \> \it list;\\ \> \> \it XMenu \> \it menuitem;\\ \> \> \it XObj \> \it cmd\_line[MAX\_OBJ];\\ \> \> \it int \> \it *interp\_fct(); \} Callback\_Def;\\\\ \end{tabbing} \rm We discuss here only on the principle of the data representations. The details of the structures will be explain later. Notably, the structure of the options list and XObjects types, which depend on the used X toolkit. \section{Conclusion} \hskip 1cm We have described in this document how making a user's configurable analysis appliaction using the concepts of the currentest XToolkits (the widgets). We think that the user's functions doesn't call graphic routines. For this reason, we put all the graphic functions in our graphic kernel. This way, the user's functions are callable in all contexts and the reliability of the graphic management is assumed. The interface between our kernel and the user's functions is realized with an ASCII file easy to read and to write. The look of the dialog boxes is automatically created by the graphic kernel, it doesn't figure in the configuration file. It seems interesting to us to integrate the method developped in this document in other applications that the data analyser. \end{document}