\documentstyle[12pt,a4wide,psfig]{book} \title{DEveloppement soft} \author{L. Michel} \date{Edition 1.0} \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 4cm EDOC123\par \vskip 1.5truein \hrule height 2pt \vskip 20pt \large Developpement graphique\par \vskip .5truein \small USING THE EXTERNAL CALLBACK PACKAGE (V1-00)\par \vskip 20pt \hrule height 2pt \vskip 1truein \medium Edition 1.0\par \vskip 3pt June 1991\par \vfill \small 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} \tableofcontents %%%%%%%%%%%%%%%%%% chapitre 1 USER's GUIDE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{USER'S GUIDE} %%%%%%%%%%%%%%%%%% section 1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{What does the ECP do ?} \hskip 7mm The user of a graphic interface program very often needs to add specific functions to it, keeping the features of the interface. The problem is that such programs are very large and elaborate, and a modifiaction needs then a good knowledge of its structure and of the graphical langage. They are certainly interesting things but which doesn't correspond necessarily to the preoccupation of any user. A solution is to give to the graphical application the ability to call external programs. The user will have then just to write his program (or take an existing one), the appplication managing to call it using its graphical features. That's done by the ECP (External Callback Package) The External Callback Package is a library, based on the Xview toolkit, useful to integrate external routines in a graphic application without compilation. The external routine is a short program, callable from the shell, getting its arguments directly from the command line (without dialog) and returning its results on \it stdout \rm. The ECP uses a resource file \it (filename.cback) \rm describing the extern routines to create a the menu bar and its dialog boxes. When a menu item is selected, the corresponding dialog box is opened to set the parameters of that external routine (see Fig 1). It can then be call, by clicking on the \it run \rm button. \begin{figure}[ht] \psfig{figure=fig1.ps,width=16cm,height=7cm} \end{figure} The user has just to know the syntax of the resource file (less than 30 words) to integrate his routines. The strings returned by the external routine can be interpreted graphically by a specific function of the graphic application, indicated by the user in the resource file. %%%%%%%%%%%%%%%% syntaxe des fichier .cback %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Writting a resource file.} \subsection{Syntax principles} \hskip 7mm When starting, the application reads a resource file giving it the useful informations on the external callback to integrate. This file must have the suffix \it .cback \rm. Its prefix must be put (V1-00) at the first position in the arg-list. If the graphic application haven't got resource file, a fatal error is generated. The syntax of the resource file is very simple. The most useful options are taken by default and the logical links between the objects are implicit. Just the description of each object has to be written in the resource file. \subsubsection{RESOURCE LINE} \hskip 7mm A resource line can be more long than an file line. The fields can be separated with tabulations spaces or new line characters. The resource line ever has the same structure for all the objects:\\ \it $<$OBJECT IDENTIFIER$>$ $<$LABEL$>$ $<$OPTIONS LIST$>$ $<$LIST$>$ \rm \begin{itemize} \item \it $<$OBJECT IDENTIFIER$>$: \rm Keyword (upper case letters) identifying the type of object. This word marks the begining of a resource line. \item \it $<$LABEL$>$: \rm The label of the object must be written between "", otherwise, it will be interperted like an option. \item \it $<$OPTIONS LIST$>$: \rm List of keywords (see glossary) defining the options of the object. \item \it $<$LIST$>$: \rm List of words between "" or keywords associated with the object. \end{itemize} EXAMPLE: \it OBJECT\_LIST "spectra" ReadOnly "spectr1" "spectr2" "spectr3" \rm is a resource line defining a scrolling list, named \it spectra \rm being read only and having 3 items: \it spectr1 \rm, \it spectr2 \rm and \it spectr3 \rm. \subsubsection{COMMENTS} \hskip 7mm A comment line begins with a \#. It`s impossible to insert comments into a resource line.\\[2ex] EXAMPLE: \it \# this is a comment \hskip 7mm \rm will be read like a comment. \it OBJECT\_LIST \hskip 7mm \# this is a comment $>$ \rm will generate an error. \subsubsection{FILE STRUCTURE} \hskip 7mm The resource fle contains the definitions of the menu bar and of each dialog box. The menu bar must be defined before the dialog boxes. The order of dialog boxes descriptions is free. \\[2ex] EXAMPLE: structure of a resource file: \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# structure of a resource file\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\\\ \>\it \# defining the menus\\ \>\it MENU \rm .. 1st menu definition ....\\ \>\it .....................\\ \>\it .....................\\ \>\it MENU \rm .. last menu definition ....\\ \>\it \# defining the dialog boxes\\ \>\it DIALOGUE\\ \>\rm .. 1st dialog box definition ....\\ \>\it END\_DIALOGUE\\ \>\it .....................\\ \>\it .....................\\ \>\it DIALOGUE\\ \>\rm .. last dialog box definition ....\\ \>\it END\_DIALOGUE\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of the resource file\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize The ECP will first create the menu bar, and after it'll look for the corresponding dialog box in the resource file. If it finds a menu item without dialog box, or a dialog box without associated menu item, it generates an error. \subsection{CREATING THE MENU BAR} \hskip 7mm The ECP can create a menu bar up to 10 buttons wich will be laid out in the control area (be careful with the size of the control area). Each menu is associated with a button (ECP V1-00 don't work with popup). The label of an object button will be at once its name on the screen and its ECP identifier. A menu object can just have one option, \it pinable \rm , which permits to keep the menu displayed on the screen (see the OpenLook GUI).\\ CAUTION: don't use this option with the ECP V1-00, the selection of an item in a pined menu will cause a fatal error. The menu definition must begin with the keyword MENU The list associated with a menu represents its items. They must be written between "". The maximum length of that list is unfixed. The ECP can not associate a menu with a menu item. The menu tree has got just one level.\\[2ex] EXAMPLE: Definition of the menu bar in a \it .cback \rm file. That menu bar has got two buttons, \it UNIX \rm and \it OTHER \rm (All the following examples will show how to realize the UNIX menu). \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Definition of a menu of command UNIX\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it MENU "UNIX"\\ \>\it \hskip 7mm "file list" "file copy" "file read" "file archive"\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Definition of an other menu\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it MENU "OTHER"\\ \>\it \hskip 7mm "other1" "other2" "other3"\\ \>\it .....................\\ \>\it .....................\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of the resource file\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize \subsection{Creating a dialog box} \hskip 7mm The ECP draws the dialog box from the informations of the resource file. An active object corresponds to each argument. Each kind of active object has a specific control area. The dialog box will ever have at least one control area where are the command buttons and the linedit of the comand line (see Fig2). \begin{figure}[ht] \psfig{figure=fig2.ps,width=16cm,height=7cm} \end{figure} There are 3 kinds of active objects: \begin{itemize} \item LINEDITS: useful to edit a string. \item SETTING: useful to select an option. \item LIST: useful to select a string from a list. \end{itemize} Let's build a dialog box corresponding to the \it file archive \rm item (UNIX command "tar") in the menu \it UNIX \rm of the previous example. The \it tar \rm command needs the name of the device, the name of the files to archive and the options: \begin{itemize} \item The name of the device will be selected from a list. \item The name of the file will be set from a linedit. \item The options will be selected from a setting. \end{itemize} \subsubsection{CREATING THE BLOCK OF A DIALOG BOX DESCRIPTION} \hskip 7mm The description of the dialog box must begin with \it DIALOGUE \rm followed with \it"label" \rm and terminate with \it END\_DIALOGUE \rm. The label must have this form: \it "Menu:Label" \rm \begin{itemize} \item The "" means that it's not a keyword but a label. \item The : character separates the 2 fields. \item \it Menu \rm is the label of the menu. \item \it Label \rm is the label of the menu item. \end{itemize} The following resource lines show the syntax of the description block of a dialog box: \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of dialog box description\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it DIALOGUE "UNIX:file archive"\\ \>\rm .. dialog box definition (see later) ...\\ \>\it END\_DIALOGUE\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of dialog box description\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize \subsubsection{CREATING THE SETTING OBJECT} \hskip 7mm The setting object will be used to set the option of the \it tar \rm command (read, write or extract). Its definition begins with the keyword \it OBJECT\_SETTING \rm, followed with its label \it "option" \rm (an object label has up to 8 characters). There are no option in this example. This setting will have three items: \it read \rm, \it write \rm and \it extr. \rm (an item label has up to 5 characters). Each item ever has the same structure as the label of the dialog box (see previous section). The first fields is the button label and the second fields is the associated argument of the command line: \it "button label:arg" \rm.\\[2ex] EXAMPLE: The argument associated with the \it read \rm option is \it -tvf \rm (see the UNIX command syntax). The item will be then written \it "read:-tvf" \rm. In this way, the argument \it -tvf \rm will be add to the command line when the button \it read \rm of the setting will be selected. \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of the setting definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it OBJECT\_SETTING "option"\\ \>\it \hskip 7mm "write:-cvf" "read:-tvf" "extr.:-xvf"\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of the setting definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize \subsubsection{CREATING THE LINEDIT OBJECT} \hskip 7mm The linedit object will be used to set the name of the files to archive. It won't have a default value. Its definition begins with the keyword \it OBJECT\_LINEDIT \rm, followed with its label \it "file" \rm. There are no option in this example.\\[2ex] EXAMPLE: The string which will be set in the linedit will be add to the command line. \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of the linedit definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it OBJECT\_LINEDIT "file"\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of the linedit definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize \subsubsection{CREATING THE LIST OBJECT} \hskip 7mm The list object will be used to set the name of the archive file. Its definition begins with the keyword \it OBJECT\_LIST \rm, followed of its label \it "tarfile" \rm. On our example, we suppose that the list of tar files is given by the system, so the user can not add or delete a new one. So we will put to the list the \it ReadOnly \rm option. The list of tar files will be the list associated to the list od this object.\\[2ex] EXAMPLE: The string which will be selected in the list will be add to the command line. \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of the list definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it OBJECT\_LIST "tarfile"\\ \>\it \hskip 7mm "/dev/fd0" "/dev/rst0" "/dev/rst1"\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of the list definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize \subsubsection{SETTING THE COMMAND LINE} \hskip 7mm The definition of the command begins with thew keyword \it COMMAND\_LINE \rm followed with a list having the same structure as the command line. The \it tar \rm command line has this form: \it tar option tarfile filename \rm. \begin{itemize} \item \it tar \rm is the command name. It never will be edited, so we put it in a constant string: \it "tar " \rm> Notice that the constant string must be terminated with a space to be separated of the next argument. \item \it option \rm is got from the first setting (first definition). It will be symbolized in the command line by this 2 fields keyword: \it Setting:1 \rm where the 1st field (\it Setting \rm) indicates the kind of the active object giving this argument, and the 2nd field indicating its definition position. \item \it tarfile \rm is got from the first list. It will be symbolized in the list by this item: \it Liste:1 \rm (\it Liste \rm is a keyword) \item \it filename \rm is got from the first linedit. It will be symbolized in the linedit by this item: \it Linedit:1 \rm (\it Linedit \rm is a key word) \end{itemize} The command line is made with constant strings and references to defined active objects. The constant strings will ever be written in the command line, the other arguments taking the same value as their associated active objects.\\[2ex] EXAMPLE:Command line of the \it tar \rm command: \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of the command line definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it COMMAND\_LINE "tar " Setting:1 Liste:1 Linedit:1\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of the command line definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize \subsubsection{SETTING THE GRAPHIC INTERPRETATION ROUTINE} All the graphic applications using the ECP must have a list of routines interpreting the strings returned from the external callbacks. These routines are specific to the application and we won't discuss here about they (see further PROGRAMMER'S GUIDE). This list is given with the application documentation. Each dialog box must yet be associate with a such routine. This declaration must begin with the keyword \it GRAPH\_INTER\_ROUTINE \rm followed with the name of this routine, held keyword. \\ [2ex] EXAMPLE: We suppose that the application has a graphic routine named \it display\_string \rm which displays in a window the strings read from the standard output (callback output). \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of the graphic interpretation routine definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it GRAPH\_INTER\_ROUTINE display\_string\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of the command line definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize \subsection{Using the dialog box} \subsubsection{THE COMPLETE DEFINITION OF THE DIALOG BOX} The following extract of the resource file shows the complete defintion of the dialog box setting the \it tar \rm command. \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of dialog box description\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it DIALOGUE "UNIX:file archive"\\ \>\it \hskip 7mm OBJECT\_LINEDIT "file"\\ \>\it \hskip 7mm OBJECT\_SETTING "option"\\ \>\it \hskip 14mm "write:-cvf" "read:-tvf" "extr.:-xvf"\\ \>\it \hskip 7mm OBJECT\_LIST "tarfile"\\ \>\it \hskip 14mm "/dev/fd0" "/dev/rst0" "/dev/rst1"\\ \>\it \hskip 7mm GRAPH\_INTER\_ROUTINE display\_string\\ \>\it \hskip 7mm COMMAND\_LINE "tar " Setting:1 Liste:1 Linedit:1\\ \>\it END\_DIALOGUE\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of dialog box description\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize When the item \it file archive \rm will be selected in the menu \it UNIX \rm, this dialog box (see fig3) appears. Notice that just one dialog can be open at once. \begin{figure}[ht] \psfig{figure=fig3.ps,width=16cm,height=7cm} \end{figure} All the modification in an active object is transmitted to the command line, but the opposite isn't true. The \it tar \rm will be executed clicking on the \it run \rm button. The dialog box will be closed after the command is terminate. The \it canel \rm button closes the box without execution of the callback. The \it help \rm button doesn't work in the version V1-00. \section{Digest of the resource file syntax} \subsection{objects identifier} \hskip 7mm The following figure shows all the ECP identifier:\\[1ex] \begin{tabular}{|r|c|c|} \hline objects & ECP identifier & commandline identifier \\ \hline menus & MENU & (no menu in cmdline) \\ \hline dialog & DIALOGUE (END\_DIALOGUE) & (no dialog in cmdline) \\ \hline setting & SETTING\_OBJECT & Setting \\ \hline linedit & LINEDIT\_OBJECT & Linedit \\ \hline list & LIST\_OBJECT & Liste \\ \hline \end{tabular} \\[2ex] \hskip 7mm Tab 1: ECP identifiers.\\[2ex] The \it menu \rm and \it dialog \rm objects can not be referenced in the command line. The \it dialog \rm object has 2 ECP identifier (begining and end of definition). \subsection{options availables} \hskip 7mm The following figure shows all the ECP options available for each type of object:\\[1ex] \small \begin{tabular}{|r|c|c|c|c|c|} \hline & MENU & DIALOGUE & SETTING & LINEDIT & LIST \\ \hline NonResizable & & NI & & & \\ \hline NonMovable & & NI & & & \\ \hline Pinable & NI & & & & \\ \hline Focused & & NI & & & \\ \hline NonExclusiveChoice & & & OK & & OK \\ \hline Default & & & NI & NI & NI \\ \hline NumericOnly & & & & OK & \\ \hline XChanelClick & & & & OK & \\ \hline YChanelClick & & & & OK & \\ \hline ZChanelClick & & & & OK & \\ \hline WChanelClick & & & & OK & \\ \hline ReadOnly & & & & OK & OK \\ \hline SystemDefaultList & & & & & OK \\ \hline NonEditableCommandline & & NI & & & \\ \hline NoSeparator & & & OK & OK & OK \\ \hline \end{tabular} \scriptsize \\[2ex] \hskip 7mm NI: option no implemented \hskip 7mm OK: option available for this object \normalsize \\[1ex] Tab 2: Available options. \subsubsection{OPTION \it NonExclusivChoice \rm} This option permits to select several items in a \it setting \rm or in a \it list \rm. In this way, the argument associated with that object becomes a list instead a single string. \subsubsection{OPTION \it NumericOnly \rm} The \it NumericOnly linedit \rm accepts only characters with numerical value. Its value can be increased or decreased with small buttons. This option is useful to ensure to have numeric argument. \subsubsection{OPTION \it XChanelClick \rm} With these options X(Y,Z or W)ChanelClick permits to set a value in an \it linedit \rm object without editing. A dialog box can have up to 4 (x, y, z and w) ring buffers of linedits identifiers, having each one a function setting the current object with a value, and setting the current position to the next object. These function must be call from the graphic application. So, this option can not be used with an application providing not it (see the documentation). This option is very usefull to get value directly from another window (such as a chanel number). The value sent to the \it linedit \rm is set by the application. The ECP just receives it, and puts it in the current object of the ring buffer. \subsubsection{OPTION \it ReadOnly \rm} The \it readonly \rm objects (\it linedit \rm or \it list \rm) vorbiden to editing its values. It's very useful for a \it list \rm set by a system call (see the \it SystemDefaulList \rm option) or for a linedit using a \it ChanelClick \rm option. \subsubsection{OPTION \it SystemDefaulList \rm} This option permits to set a \it list \rm with the results of a UNIX command (or any program). That command must be written as first item of the associated list, the other item being ignored. The UNIX command is executed once when the application is starting and the \it list \rm kepp these value while all its execution.\\[2ex] EXAMPLE: Creating a list filled the \it ls *.c \rm command: \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of the list definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it OBJECT\_LIST "files" SystemDefaulList\\ \>\it \hskip 7mm "ls *.c"\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of the list definition\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize The \it list \rm af that dialog box will ever be set with the list of the C files. \subsubsection{OPTION \it NoSeparator \rm} This option supresses the space betwenn 2 arguments. It's useful to merge a pathname or several options. If The \it NoSeparator \rm option is used with the "NonExclusiveChoice", all the elements of the list will sticked up, as well as the following argument. To avoid that, it's necessary to put a constant string \it " " \rm between the both identifiers. in the command line.\\[2ex] EXAMPLE: The folowing example defines a dialog box interfacing the UNIX command \it ls \rm. The \it setting \rm sets the options which must be stick on. The available files are put in the \it list \rm with the option \it SystemDefaultList \rm \scriptsize \begin{tabbing} \hskip 7mm \=\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# Begining of dialog box description\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it DIALOGUE "UNIX:list file"\\ \>\it \hskip 7mm OBJECT\_LIST "file" ReadOnly SystemDefaultList\\ \>\it \hskip 14mm "ls"\\ \>\it \hskip 7mm OBJECT\_SETTING "option" NonExclusiveChoice NoSeparator\\ \>\it \hskip 14mm "a:all" "mode:l" "size:s"\\ \>\it \hskip 7mm GRAPH\_INTER\_ROUTINE display\_string\\ \>\it \hskip 7mm COMMAND\_LINE "ls " "-" Setting:1 " " Liste:1 \\ \>\it END\_DIALOGUE\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \>\it \# end of dialog box description\\ \>\it \#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\\ \end{tabbing} \normalsize The constant string, " ", between \it Setting:1 \rm and \it Liste:1 \rm in the \it command line \rm definition separates the option group and the name of the file to list. \subsection{Geometric limits of the ECP objects} \hskip 7mm The following tab shows the limits of the definition of the ECP objects. These values are verified when reading the resource file, but it's advised to respect these values writting it. \\[1ex] \small \begin{tabular}{|r|c|c|c|c|c|} \hline & MENU & DIALOGUE & SETTING & LINEDIT & LIST \\ \hline max number & 10 & -- & 3 & 5 & 1 \\ \hline label length & 32 & 8 & 8 & 8 & 8 \\ \hline item number & undef. & no item & 5 & no item & 256 \\ \hline item label length & 32 & no item & 5 & no item & 24 \\ \hline \end{tabular} \normalsize \\[2ex] Tab 3: Geometric limits of the ECP objects. \newpage %%%%%%%%%%%%%%%%%% GLOSSAIRE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Glossary} \begin{itemize} \item \bf AllOption : \rm (option - all objects) Sets all the options (Should not use this) \item \bf COMMAND\_LINE : \rm (object identifier) Identifies the structure of the command line. \item \bf Default : \rm (option - unimplemented) Sets the object's default value when opening the dialog box . \item \bf DIALOGUE : \rm (object identifier) Marks the begining of a dialog box definition. \item \bf END\_DIALOGUE : \rm (object identifier) Marks the end of a dialog box definition. \item \bf Focused : \rm (option - unimplemented) Focused all the X Events to the opened dialog box. \item \bf GRAPH\_INTER\_ROUTINE : \rm (object identifier) Identifies the name of the gra\-phic interpretation routine. \item \bf Linedit : \rm (argument identifier) Identifies a command line argument associated with a linedit object. \item \bf Liste : \rm (argument identifier) Identifies a command line argument associated with a list object. \item \bf MENU : \rm (object identifier) Marks the begining of a menu definition. \item \bf NonEditableCommandline : \rm (option - DIALOGUE) The command line is readonly. \item \bf NonExclusiveChoice : \rm (option - SETTING, LIST) Several items can be selected. \item \bf NonMovable : \rm (option - unimplemented) The dialog box can't be moved \item \bf NonResizable : \rm (option - unimplemented) The dialog box can't be resized. \item \bf NoSeparator : \rm (option - LINEDIT, LIST, SETTING) The argument won't be separated of the following. \item \bf NumericOnly : \rm (option - LINEDIT) The linedit will accept only the numeric values. \item \bf OBJECT\_LINEDIT : \rm (object identifier) Identifies the definition of a linedit object. \item \bf OBJECT\_LIST : \rm (object identifier) Identifies the definition of a list object. \item \bf OBJECT\_SETTING : \rm (object identifier) Identifies the definition of a setting object. \item \bf Pinable : \rm (option - unimplemented) The menu can be pined on the screen. \item \bf ReadOnly : \rm (option - LIST, SETTING) The object is read only. \item \bf Setting : \rm (argument identifier) Identifies a command line argument associated with a setting object. \item \bf SystemDefaultList : \rm (option - LIST) The list will be initialized with a Unix command (for the version V1-00, the initialization is done once while the application starts). \item \bf WChanelClick : \rm (option - LINEDIT, LIST) The linedit can be set from an X-Event external of the dialog box, it will be stored in the W ring buffer. \item \bf XChanelClick : \rm (option - LINEDIT, LIST) The linedit can be set from an X-Event external of the dialog box, it will be stored in the X ring buffer. \item \bf YChanelClick : \rm (option - LINEDIT, LIST) The linedit can be set from an X-Event external of the dialog box, it will be stored in the Y ring buffer. \item \bf ZChanelClick : \rm (option - LINEDIT, LIST) The linedit can be set from an X-Event external of the dialog box, it will be stored in the Z ring buffer. \end{itemize} %%%%%%%%%%%% chapitre PROGRAMMER's GUIDE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{PROGRAMER'S GUIDE} \section{What does the ECP do?} \hskip 7mm Integrate the ECP into a Xview application give it the ability to run any external program. The ECP includes a parser which reads a resource file an create some Xview objects from it, and an event manager which is called everytime a event is detected on an ECP object. These both controls don't disturb the execution of the rest of the graphic program. %%%%%%%%%%%%% section 2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Integrating the ECP in your Xview application.} \subsection{Integrating the ECP calls in your C code} \subsubsection{Structure of the main loop} \hskip 7mm The ECP must be called before starting the main loop of the Xview application. It creates then the Xview objects. The main function in a classical Xview application has three steps: \scriptsize \begin{tabbing} \hskip 7mm \=\it /**********************************************************\\ \>\it * \hskip 1cm classical xview main function\\ \>\it ***********************************************************/\\ \>\it main() \{\\ \>\it \hskip 7mm /* parsing the command line */\\ \>\it \hskip 7mm xv\_init( ..................);\\ \>\it \hskip 7mm /* init. the xview objects */\\ \>\it \hskip 7mm object\_initialize(.........);\\ \>\it \hskip 7mm /* Starting the main loop */\\ \>\it \hskip 7mm xv\_main\_loop(.........);\\ \>\it \}\\ \end{tabbing} \normalsize Using the ECP adds 2 steps to that main function: \scriptsize \begin{tabbing} \hskip 7mm \=\it /**********************************************************\\ \>\it * \hskip 1cm Xview main function integrating the ECP\\ \>\it ***********************************************************/\\ \>\it main() \{\\ \>\it \hskip 7mm /* parsing the command line */\\ \>\it \hskip 7mm xv\_init( ..................);\\ \>\it \hskip 7mm /* init. the xview objects */\\ \>\it \hskip 7mm object\_initialize(.........);\\ \>\it \hskip 7mm /* creating the list of graph. interpreation routine */\\ \>\it \hskip 7mm set\_routine\_list();\\ \>\it \hskip 7mm /* creating the dialog boxes from the .cback file */\\ \>\it \hskip 7mm set\_callback(filename,base\_window,ctrl\_area,x0,y0);\\ \>\it \hskip 7mm /* Starting the main loop */\\ \>\it \hskip 7mm xv\_main\_loop(.........);\\ \>\it \}\\ \end{tabbing} \normalsize The \it set\_routin\_list() \rm function has to be written by the programer to give to the ECP a list of routines available to process the strings returned from the callbacks (see further). The \it set\_callback(...) \rm function is a ECP callback which parses the resource file and creates the dialog boxes. \subsubsection{Setting the graphic interpretation routines list} \hskip 7mm The program using the ECP must have at least one graphic interpretation routine which will receive the strings returned from the external callback and will process them (see further how to write it): \scriptsize \begin{tabbing} \hskip 7mm \=\it /**********************************************************\\ \>\it * declaration af a graphic interpretation routine\\ \>\it ***********************************************************/\\ \>\it void gph\_routine(char* command\_line)\{\\ \>\it ...............................\\ \>\it ...............................\\ \>\it ...............................\\ \>\it \} \end{tabbing} \normalsize The parameter is always the command line edited in the dialog box. These routines must be put in a list internal to the ECP. They are referenced by a string (their names) and a pointer in a structure defined in the \it cback\_anal.h \rm file: \scriptsize \begin{tabbing} \hskip 7mm \=\it typedef struct \{ \= char* nom; /* symbolic name of the function*/\\ \>\it \> void (*ptr)(char*); /* pointer to the function */\\ \>\it \> \} fct\_id; \end{tabbing} \normalsize The string will be use to identify the function invoqued in the resource file after the \it GRAPH\_INTER\_ROUTINE \rm identifier. The pointer will be use to set this routine like the notify procedure of the \it run \rm button of a dialog box. The ECP function \it void add\_routine\_list(int*, int) \rm must be called to append a routine to the list. The first parameter is a pointer to the structure \it fct\_id \rm, the second is the length of this array (2 integers). The following C code extract shows how to create the routines list: \scriptsize \begin{tabbing} \hskip 7mm \=\it/**********************************************************\\ \>\it * Prototypes of the graphic interpretation routines\\ \>\it ***********************************************************/\\ \>\it void gph\_routine1(char*);\\ \>\it void gph\_routine2(char*);\\ \>\it void gph\_routine3(char*);\\ \>\it ........................\\ \>\it ........................\\ \>\it /**********************************************************\\ \>\it * \hskip 1cm Xview main function integrating the ECP\\ \>\it ***********************************************************/\\ \>\it main() \{\\ \>\it \hskip 7mm ........................\\ \>\it \hskip 7mm ........................\\ \>\it \hskip 7mm /* creating the list of graph. interpreation routine */\\ \>\it \hskip 7mm set\_routine\_list();\\ \>\it \hskip 7mm ........................\\ \>\it \hskip 7mm xv\_main\_loop(.........);\\ \>\it \hskip 7mm \}\\ \>\it ........................\\ \>\it ........................\\ \>\it ........................\\ \>\it void set\_routine\_list()\{\\ \>\it \hskip 7mm union \{ \= fct\_id;\\ \>\it \> int tab$[$2$]$; \} id;\\ \>\it \hskip 7mm /* adding the first routine */\\ \>\it \hskip 7mm id.id.nom = "routine1";\\ \>\it \hskip 7mm id.id.ptr = routine1;\\ \>\it \hskip 7mm add\_routine\_list(id.tab,2);\\ \>\it \hskip 7mm /* adding the second routine */\\ \>\it \hskip 7mm id.id.nom = "routine2";\\ \>\it \hskip 7mm id.id.ptr = routine2;\\ \>\it \hskip 7mm add\_routine\_list(id.tab,2);\\ \>\it \hskip 7mm /* adding the third routine */\\ \>\it \hskip 7mm id.id.nom = "routine3";\\ \>\it \hskip 7mm id.id.ptr = routine3;\\ \>\it \hskip 7mm add\_routine\_list(id.tab,2);\\ \>\it \hskip 7mm \}\\ \>\it ........................\\ \>\it ........................\\ \>\it ........................\\ \end{tabbing} \normalsize \subsubsection{Setting the external callbacks} \hskip 7mm The application using the ECP must be associated with a resource file (\it filename.cback \rm) defining the callback. The file is read by the ECP library which creates the Xview objects. This is processed by the \it void set\_callback(char* filename,Xv\_opaque base,Xv\_opaque control,int x0,int y0) \rm function. \it filename \rm is the prefix of the resource file. The suffix, \it .cback, \rm is added by the ECP. If \it set\_callback \rm doesn't find this file, a fatal error is generated and the program exits. \it base \rm is the Xview identifier of the base window of the application. The dialog boxes will be daughter of that window. \it control \rm is the Xview identifier of the control area where will be drawn the menu bar. It's horizontal, and can have up to 10 buttons. The ECP V1-00 accepts just one menu bar. \it x0 \rm and \it y0 \rm are the coordonates of upper left corner of the left button of the menu bar. \section{Writting the graphic interpretation routine} \hskip 7mm These routines (see above) must be written by the programer (in a next version, a library of standard routine will be available). They must first run the external callback, and then process the strings returned. \subsubsection{Running the external routine} \hskip 7mm The easiest way to run an external routine is to use the \it system(char* cmdline) \rm system call. That is useful if the callback returns nothing.\\[2ex] EXAMPLE: A simple graphic interpretation routine. \scriptsize \begin{tabbing} \hskip 7mm \=\it/**********************************************************\\ \>\it * simple graphic interpretation routines\\ \>\it ***********************************************************/\\ \>\it void gph\_routine1(char* str)\{\\ \>\it \hskip 7mm system(str);\\ \>\it \hskip 7mm \};\\ \end{tabbing} \normalsize \it str \rm is the command line edited in the dialog box. The routine returns at the end of the callback but does nothing else. If the external callback returns strings, the \it grph\_routine \rm must read them with a pipe. That can be done with the \it popen \rm standard call.\\[2ex] EXAMPLE: Piping an external callback: \scriptsize \begin{tabbing} \hskip 7mm \=\it/**********************************************************\\ \>\it * a graphic interpretation routines using a pipe\\ \>\it ***********************************************************/\\ \>\it void gph\_routine1(char* str)\{\\ \>\it \hskip 14mm FILE* pp;\\ \>\it \hskip 14mm buffer$[$MAX\_LINE\_LENGTH$]$;\\ \>\it \hskip 7mm /* creating the pipe with the external callback */\\ \>\it \hskip 7mm if( (pp = popen(str,"r")) == NULL )\{\\ \>\it \hskip 14mm fprintf(stderr,"cannot open the pipe");\\ \>\it \hskip 14mm exit(1);\\ \>\it \hskip 14mm \}\\ \>\it \hskip 7mm /* reading the pipe */\\ \>\it \hskip 7mm while( fgets(buffer,MAX\_LINE\_LENGTH,pp) ) \{\\ \>\it \hskip 14mm ................................\\ \>\it \hskip 14mm /* processing the read strings */\\ \>\it \hskip 14mm ................................\\ \>\it \hskip 14mm \}\\ \>\it \hskip 7mm return;\\ \>\it \hskip 7mm \}\\ \end{tabbing} \normalsize Note that the call of these routines are done by the ECP from its list. The programer never needs to read anything in a dialog box, or to process an event occured in it. \subsubsection{Processing the returned strings} \hskip 7mm The processing of the returned strings depends completely on the application, but we are going to see 1 example corresponding to a current case.\\[2ex] EXAMPLE: Writting the result into a textedit panel. (The textedit panel is an Xview object). Using the textedit panel, the programer must be careful to avoid buffer overflows (see the Xview documentation) ! \scriptsize \begin{tabbing} \hskip 7mm \=\it/**********************************************************\\ \>\it * a graphic interpretation routines using a pipe\\ \>\it ***********************************************************/\\ \>\it void gph\_routine1(char* str)\{\\ \>\it \hskip 14mm FILE* pp;\\ \>\it \hskip 14mm buffe$[$MAX\_LINE\_LENGTH$]$;\\ \>\it \hskip 7mm /* creating the pipe with the external callback */\\ \>\it \hskip 7mm if( (pp = popen(str,"r")) == NULL )\{\\ \>\it \hskip 14mm fprintf(stderr,"canot open the pipe");\\ \>\it \hskip 14mm exit(1);\\ \>\it \hskip 14mm \}\\ \>\it \hskip 7mm /* reading the pipe */\\ \>\it \hskip 7mm while( fgets(buffer,MAX\_LINE\_LENGTH,pp) ) \{\\ \>\it \hskip 14mm /* inserting a new line */\\ \>\it \hskip 14mm textsw\_insert(texwin\_id,buffer,strlen(buffer));\\ \>\it \hskip 14mm \}\\ \>\it \hskip 7mm return;\\ \>\it \hskip 7mm \}\\ \end{tabbing} \normalsize \it textwin\_id \rm is the Xview identifier (\it Xv\_opaque \rm) of the textedit subwindow. \section{Using the ring buffers} \hskip 7mm Each dialog box can have up to 4 ring buffers (X, Y, Z and W) used to set a value into an active objects directly from your application. That value must be an integer. Just the \it linedit NumericOnly \rm objects can be set with the ring buffers in V1-00. The ring buffers are built from the objects having the option X\_ChanelClick (Y\_, Z\_, or W\_). The ECP function \it chanelclick\_x(Event* event, int value) (\_y, \_z or \_w) \rm sets the value \it value \rm into the current object of the buffer, and then puts the following object like current object (see Fig 4). \it event \rm is a pointer to the Xview event which induces that call (\it event \rm isn't used in V1-00). \begin{figure}[ht] \psfig{figure=fig4.ps,width=16cm,height=7cm} \end{figure} This feature is very useful to put a chanel number into a linedit directly clicking in the drawable window.\\[2ex] EXAMPLE: Notify procedure called when a mouse event is detected on a canvas. It puts into the X and Y ring buffers the coordonates of the mouse cursor when clicking. \scriptsize \begin{tabbing} \hskip 7mm \=\it /**********************************************************\\ \>\it * click on the canvas notify proc\\ \>\it ***********************************************************/\\ \>\it void click\_in\_canvas\_proc(Xv\_window w, Event* ev, Notify\_arg arg Notify\_event\_type type)\{\\ \> \\ \>\it \hskip 7mm /* works only if event = BUTTON\_SELECT (right) release */\\ \>\it \hskip 7mm if( even\_is\_up(ev) \&\& (event\_action(ev)= ACTION\_SELECT) )\{\\ \>\it \hskip 14mm /* setx the X and Y ring buffers */\\ \>\it \hskip 14mm chanelclick\_x(event, event\_x(ev) );\\ \>\it \hskip 14mm chanelclick\_y(event, event\_x(ev) );\\ \>\it \hskip 14mm \}\\ \>\it \hskip 7mm return notify\_next\_event\_func(w,(Notify\_event)ev,arg,type);\\ \>\it \hskip 7mm \}\\ \end{tabbing} \normalsize If it isn't opened dialog box or if the dialog box haven't got ring buffer, the procedure does nothing. \newpage \section{The ECP functions} %%%%%%%%%%% appel: SET_CALLBACK %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Procedure: \em set\_callback(...)} \subsubsection{Prototype} \it \#include $<$cback\_lib.h$>$\\ void set\_callback(char *filename, Xv\_opaque base, Xv\_opaque control , int x0, int Y0) \begin{itemize} \item \it filename \rm is the prefix of the resource file name. The suffix \it ".cback" \rm will be added by \it set\_callback. \item \it base \rm is the XView identifier of the application base window. \item \it control \rm is the XView identifier of the control area where will be drawn the menu bar. \item \it x0 \rm is the abcisse of the upper left corner of the first button of the menu bar, relative to the upper left corner of the control area. \item \it Y0 \rm is the ordonate of the upper left corner of the first button of the menu bar, relative to the upper left corner of the control area. \end{itemize} \subsubsection{Description} \hskip7mm \it Set\_callback() \rm reads the resource file \it filename.cback \rm and then creates the menu bar and the dialog boxes. After the compilation of each definition, the object (menu or dialog box) is created and associated with notify procedures internal to the ECP. The list of the graphic interpretation routines must be set (see next page, the \it add\_\-routine\_list(...) \rm procedure) before calling \it set\_callback(...)\rm . Messages indicating what \it set\_callback(...) \rm is doing are displayed on \it stderr \rm while compilating. \it Set\_callback(...) \rm returns a message and exits, if an error is detected in the resource file. \newpage %%%%%%%%%%%% appel ADD_ROUTINE_LISTE %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Procedure: \em add\_routine\_list(...) } \subsubsection{Prototype} \it \#include $<$cback\_lib.h$>$\\ void add\_routine\_list(int* id, int taille) \begin{itemize} \item \it id \rm is a pointer to the routine identifier. This routine is defined in a structure \it typedef \{char* nom; void (*ptr)(char*)\} fct\_id; \rm where \it nom \rm is the name of the routine and \it ptr \rm the pointer on it (prototype: \it void fct(char*)\rm ). The array \it id[taille] \rm includes the same data as the \it fct\_id \rm structure (use \it union \{fct\_id f\_id; int id[2]\};\rm). \item \it taille \rm is the size of the \it id \rm array. taille = sizeof(\it fct\_id\rm)/sizeof(\it int \rm) (= 2 in V1-00). \end{itemize} \subsubsection{Description} \hskip 7mm \it Add\_routine\_list(...) \rm adds the function defined \it id \rm to the list of the available routines for the graphic interpretation of the callbacks results. This array (8 bytes) corresponds to a structure (\it fct\_id \rm) having a pointer (4 bytes) to the name of the routine and a pointer on this routine (4 bytes). This list of the routines must be set before begining the compilation of the resource file, in way to be able to associate a routine with each dialog box. The name of the routine, in the \it fct\_id \rm structure, must be the same as the name declared in the resource file, the parser selecting the good routine by comparison between these names. \newpage %%%%%%%%%%%% appel CHANNEL_CLICK %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Procedure: \em chanelclick\_x(...) } \subsubsection{Prototype} \it \#include $<$cback\_lib.h$>$\\ Xv\_opaque chanelclick\_x(Event* event, int val)\\ Xv\_opaque chanelclick\_y(Event* event, int val)\\ Xv\_opaque chanelclick\_z(Event* event, int val)\\ Xv\_opaque chanelclick\_w(Event* event, int val) \begin{itemize} \item \it event \rm is a pointer on the XView event provocating this call. \item \it val \rm is the numeric value which will be set in the Xview active object of the opened dialog box. \end{itemize} \subsubsection{Description} \hskip 7mm \rm A dialog box can have up to 4 (x, y, z, w) ring buffers of active objects (linedit, list or setting) which can be then set directly from an Xview event detected outside of it. The routine \it chanelclick\_x[\_y \_z \_w](...) \rm must be call to set the current object of the ring buffer with the numeric value \it val \rm . This feature is very useful to select chanel numbers directly from a drawable window. \newpage %%%%%%%%%%%% appel MENU_PROC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Procedure: \em menu\_proc(...)} \subsubsection{Prototype} \it \#include $<$cback\_lib.h$>$\\ void menu\_proc(Menu\_item item, Menu\_generate op) \begin{itemize} \item \it item \rm is the Xview identifier of the opened menu. \item \it op \rm indicates the condition in which this routine is called. \end{itemize} \subsubsection{Description} \hskip 7mm \rm This routine is called when an X\_Event is detected in the ECP menu bar. It opens the dialog box corresponding to the selected menu item if neither box is already opened. The dialog box is drawn in the upper left corner of the screen, and the mouse cursor is put on the pine. Its old position will be restored at the box shutting. \it menu\_proc(...) \rm can just be called if an ECP menu is opened because it needs the X\_view identifier of the selected menu item to determine the corresponding dialog box. \subsubsection{bug} \hskip 7mm \it menu\_proc(...) \rm generates a fatal error (segmentation fault) if invoked from a pined menu. \\[2ex] DON'T USE THE \it PINABLE \rm OPTION WITH THE ECP V1-00. \newpage %%%%%%%%%%%% appel HELP_BUTTON %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Procedure: \em help\_button(...)} \subsubsection{Prototype} \it \#include $<$cback\_lib.h$>$\\ void help\_button(Panel\_item panel, Event* event) \begin{itemize} \item \it panel \rm is the Xview identifier of the panel where the event were detected. \item \it event \rm is a pointer to the Xview event provocating this call. \end{itemize} \subsubsection{Description} \hskip 7mm \rm This routine is called when an X\_Event is detected in the \it help button \rm of the opened dialog box. The both arguments are not used, \it help\_button(...) \rm can then be called explicitly uncarefully. \subsubsection{bug} \it help\_button \rm does nothing in the ECP V1-00. \newpage %%%%%%%%%%%% appel RUN_BUTTON %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Procedure: \em run\_button(...)} \subsubsection{Prototype} \it \#include $<$cback\_lib.h$>$\\ void run\_button(Panel\_item panel, Event* event) \begin{itemize} \item \it panel \rm is the Xview identifier of the panel where the event were detected. \item \it event \rm is a pointer to the Xview event provocating this call. \end{itemize} \subsubsection{Description} \hskip 7mm \rm This routine is called when an X\_Event is detected in the \it run button \rm of the opened dialog box. Its graphic interpretation routine is then called with the edited command line as argument. When this routine returns, the dialog box is then closed calling \it cancel\_button(...) \rm and the mouse cursor is put on its old position (before opening). The both arguments of \it run\_button(...) \rm are not used, \it run\_button(...) \rm can then be called explicitly if a dialog box is opened. \newpage %%%%%%%%%%%% appel CANCEL_BUTTON %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Procedure: \em cancel\_button(...)} \subsubsection{Prototype} \it \#include $<$cback\_lib.h$>$\\ void cancel\_button(Panel\_item panel, Event* event) \begin{itemize} \item \it panel \rm is the Xview identifier of the panel where the event were detected. \item \it event \rm is a pointer to the Xview event provocating this call. \end{itemize} \subsubsection{Description} \hskip 7mm \rm This routine is called when an X\_Event is detected in the \it cancel button \rm of the opened dialog box. It closes the opened dialog box and put the mouse cursor on its old position (before opening). The both arguments of \it cancel\_button(...) \rm are not used, \it cancel\_button(...) \rm can then be called explicitly if a dialog box is opened. \newpage %%%%%%%%%%%% appel GET_VERSION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Procedure: \em get\_version()} \subsubsection{Prototype} \it \#include $<$cback\_lib.h$>$\\ void get\_version() \subsubsection{Description} \hskip 7mm \it get\_version() \rm prints on \it stderr \rm a message indicating the ECP version number. \end{document}