\documentstyle[12pt,a4]{article}
\title{DEveloppement soft}
\author{G.Zehnacker}
\date{Edition 1.0 decembre 1990}
\begin{document}

\begin{titlepage}
{

\hoffset=1truein
\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
EDOC116\par
\vskip 1.5truein
\hrule height 2pt
\vskip 20pt
\large
Developpement logiciel\par
\vskip .5truein
DEVGUIDE: a graphical interface editor\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\rm
\small
\begin{tabbing}
edition \=: 1.0\\
date    \>: February1991\\
auteurs \>: L. Michel G. Zehnacker\\
\end{tabbing}
\vfill
\bf
\medium
Centre Recherches Nucleaires Strasbourg \par
\vskip 5pt
CNRS-IN2P3 France
\par
\vskip .5truein

}
\end{titlepage}

\vskip 15cm
\begin{abstract}
	\hskip 1cm This document describe the abilities of the OpenWindow 
	Developper's Guide  (\it DevGuide \rm).

	The first section describes the abilities of \it DevGuide \rm, the 
	second section describes how generate C code from a \it DevGuide \rm 
	file. The third 
	section gives some suggestions for an easy use of Devguide in the 
	Eurogam project.
\end{abstract}

\section{The usage of DevGuide}
\subsection{What does make DevGuide ?}

	\hskip 1cm \it DevGuide \rm is used to create user interfaces that 
	comform to 
	the \it OPENLOOK \rm User Interface as it is implemented in OpenWindow. 
	\it DevGuide \rm is a Graphical User Interface Editor.

	The graphical interface is composed with the standard \it XView \rm 
	objects set. 
	The objects are manipulated (size, position, ...) directly by the 
	mouse from the \it DevGuide \rm window to the screen model. After to be 	put on the screen model, the objects parameters are set by specific 
	dialog boxes (event filter, graphicals options, callback routine 
	name,...).

	The screen model is stored as an ASCII file (\it .G \rm extension) 
	describing  each \it XView \rm object. The file format is specific to
	\it DevGuide \rm.

	The screen model can be dynamically tested under the control of 
	\it DevGuide \rm (open menus, edit text,....). !some objects can be 
	connected to a callback routine which name is user's defined.

	It's possible to associate with the model an help text, edited under the 	control of \it DevGuide \rm, what will be called automatically by the
	"help key" when the application will be runing.

\subsection{What doesn't make DevGuide ?}

	\hskip 1cm \it DevGuide \rm doesn't generate C or C++ code. The 
	parameters defining the objects are static, except the label of certains 	objects class which can be set from a file.
	
	\it DevGuide \rm doesn't create new object class. It doesn't manipulate 
	user's defined objects. May be user's defined objects can be inserted 
	in the storage file initially created by \it DevGuide \rm. We haven't 
	verified this ability.

\subsection{The ".G" file}

	\hskip 1cm The window created by \it DevGuide \rm are stored in an 
	ASCII file named \it xxxx.G \rm where \it xxxx \rm is the application 
	name.

	In this file, each object is described by its name, its geometric 
	characteristics, its callback routine name and some configuration flags.	The file can be easily modified by a text editor.

	The file is written by \it DevGuide \rm for store an interface, it's 
	read by it for edit an old interface.

	The C code is created by a compiler (\it gxv \rm) from the \it .G \rm 
	file. The following example show the definition of a button in a 
	\it .G \rm file.
\it
\begin{tabbing}
\hskip 1cm(\\
\hskip 1cm:type\hskip 2cm   \=:button\\
\hskip 1cm:name             \> Bouton1\\
\hskip 1cm:owner            \> Controle-area1\\
\hskip 1cm:help             \> ""\\
\hskip 1cm:x                \> 170\\
\hskip 1cm:y                \> 62\\
\hskip 1cm:constant-width   \> nil\\
\hskip 1cm:button-type      \> :normal\\
\hskip 1cm:width            \> 58\\
\hskip 1cm:heigth           \> 20\\
\hskip 1cm:foreground-color \> "darkblue"\\
\hskip 1cm:label            \> "quitte"\\
\hskip 1cm:label-type       \> :string\\
\hskip 1cm:menu             \> nil\\
\hskip 1cm:notify-handler   \> quittecallbackroutine\\
\hskip 1cm:event-handler    \> nil\\
\hskip 1cm:events           \> ()\\
\hskip 1cm:user-data        \> ()\\
\hskip 1cm)
\end{tabbing}
\rm

\section{The "gxv" compiler: the C code generation}
\subsection{what does make the "gxv" compiler ?}

	\hskip 1cm The \it gxv \rm compiler creates C files from a  \it .G \rm 
	file created by
	\it DevGuide \rm. The generated source code uses the \it XView \rm 
	toolkit. They make the creation of the graphics objects, the 
	configuration of the XEvent main loop and the entry point of the 
	callback routines.
	A makefile is also created to compile the set of source files.

	An application is described by one \it appl.G \rm file from which the 
	\it gxv \rm compiler writes four source files:

\begin{tabbing}
\hskip 1cm - \it appl\_ui.h \rm\hskip 2cm\= definition of the specifics data 
					structures.\\
\hskip 1cm - \it appl\_ui.c  \rm   	\> creation of the graphics objects.\\
\hskip 1cm - \it appl\_stubs.c \rm 	\> mainloop and callback routines.\\
\hskip 1cm - \it Makefile  \rm     	\> file used for manage the compilation.					\\
\end{tabbing}

	A version of \it gxv \rm (\it gxv \rm+) create C++ file, but we don't u
	se it actually.

\subsection{The "appl\_ui.h" file}
	
	\hskip 1cm The \it appl\_ui.h \rm file is a classical header file in C 
	langage.
	It contains the prototypes of the functions which create the Xviews 
	objects and the definition of a data structure pointing on this objects.

\subsection{The "appl\_ui.c"file}
	
	\hskip 1cm The \it appl\_ui.c \rm file regroups all the functions which 
	create 
	and set up the \it XView \rm objects. This file depends just on the 
	screen model edited by \it DevGuide \rm. It must not be modified while t
	he \it appl.G \rm is not modified.

\subsection{The "appl\_stubs.c" file}
	
	\hskip 1cm The \it appl\_stubs.c \rm file contains the main function 
	and the callback routines. 
	The main function calls the routines of creation and
	initialization of the objects and starts the main loop. The callback 
	routines have their names defined in the \it appl.G \rm file. They just 
	send a message on the screen, on "stderr stream", when are called. 
	This message 	writes the name of the routine and the statement of 
	the control object if necessary.  
	This is very useful to test the graphical interface before write the 
	user's code. 
	
	The user's code must be inserted in these routines. Each modification 
	of the interface using the \it appl.G \rm file requires a new 
	compilation by \it gxv \rm, that creates a new set of source files and t
	hen deletes the user's code in \it appl\_stubs.c \rm. We propose a 
	method to avoid this restriction of the use of \it DevGuide \rm in the 
	section 3.

\subsection{The "Makefile"}

	The compilation of the \it application uses the \it make \rm utility. 
	\it Gxv \rm create a make file named \it Makefile \rm.

\section{How make a modifiable interface by "DevGuide" ?}
\subsection{Classical cycle for the creation of an application.}

	\hskip 1cm The standard cycle to create an \it application with an 
	graphical interface by \it DevGuide \rm is the following:

\begin{itemize}
\item	Edit the graphical interface by \it DevGuide \rm\\
\item	Test the graphical interface under control of \it DevGuide \rm.\\
\item	Create a \it appl.G \rm file describing the interface, where 
	\it appl \rm is the name of the application.
\item	Compile the \it appl.G \rm file to write the set of source code files.
\item	Make the executable file of the interface.
\item	Test the interface, and make a new cycle if some modifications 
	are necessary.
\item	Insert the user code in the \it appl\_stubs.c \rm file.
\item 	Compile the entire application.
\end{itemize}

	This way, it's difficult to modify the graphical interface after 
	the insertion of the user code in the \it appl\_stubs.c \rm file, 
	because the use of \it gxv \rm erases it. Then the programmer must 
	rewrite his routines in the \it appl\_stubs.c \rm file.

\subsection{Cycle for the creation of an adaptable application.}

	\hskip 1cm The following method results of the personnal test of 
	devGuide done in Strabourg.

	After a modification of the \it appl.G \rm file, \it gxv \rm doesn't 
	write a new makefile. So it's possible to modify it by inserting 
	sources filename containing the code of the user's routines.
	This routines are called from the modified callback routines created by
	\it gxv \rm.

	The graphical objects are defined in the \it appl\_ui.c \rm. So after a 
	modification of the \it appl.G \rm file, just \it appl\_ui.c \rm will 
	be changed. If new callback routines are created, they must be added 
	to the \it appl\_stubs.c \rm.

	Then, for keep the user's code in the \it appl\_stubs.c \rm file it's 
	possible to change its name (example: \it mv appl\_stubs.c  
	appl\_kern.c \rm) with the appropriarte modification in  \it Makefile 
	\rm, so the new \it appl\_stubs.c \rm will  be ignored at the 
	compilation. In this case, the new callback routines written by \
	it gxv \rm (empty routines) must be added to the \it appl\_kern.c 
	\rm file.

	The new cycle to create an application with an graphical
	interface by \it DevGuide \rm is the following:

\begin{itemize}
\item	Edit the graphical interface by \it DevGuide \rm\\
\item	Test the graphical interface under control of \it DevGuide \rm.\\
\item	Create a \it appl.G \rm file describing the interface, where \it 
	appl \rm,is the name of the application.
\item	Compile the \it appl.G \rm file to write the set of source code files.
\item	Make the executable file of the interface.
\item	Test the interface, and make a new cycle if some modifications are 
	necessary.
\item	Insert the user code in the \it appl\_stubs.c \rm and change its name.
\item	Create if necessary the user's source files.
\item	Modify the \it Makefile \rm.
\item 	Compile the entire \it application.
\item	Insert in the \it appl\_kern.c \rm (former \it appl\_stubs.c \rm) 
	the new callback routine if necessary.
\end{itemize}

\subsection{Modification of the graphical objects}

	\hskip 1cm Each object is created (call \it xv\_create \rm) with its 
	attributs set by \it DevGuide \rm. The \it XView \rm toolkit
	permits to change dynamically the values of the attributs (call 
	\it xv\_set \rm). Then it's possible to change the control labels or
	the menu item list without use \it DevGuide \rm.
	It's also possible to create dynamically new control objects if they
	handler routines exist. But, in this case, the new object will be not
	included in the data structure created by \it gxv \rm.

\subsection{Name of the variables describing the graphical objects}
	
	\hskip 1cm \it Gxv \rm creates a data structure describing the graphical
	object. Each field of this stucture pointes an object out. The name of 
	each field is the same as the name of the object. Then, , it's easy to 
	point an object out in the user's code without read the data 
	structure. The programmer needs just the name of the objects defined
	by \it DevGuide \rm.

	Example: How point a button out ?
\begin{tabbing}
\hskip 2cm name of the application:	\= \it Appl\rm\\
\hskip 2cm name of the base window:	\> \it Base\rm\\
\hskip 2cm name of the button:		\> \it Quitte\rm\\
\hskip 2cm name of the button identfier	\> \it Appl\_Base->Quitte\\
\end{tabbing}

\subsection{Proposition for the syntax}

	\hskip 1cm It can be interesting to use an homogeneous syntax for 
	name the graphic objects. We Propose 2 rules for name it:
\begin{itemize}
\item 	Each object must have a name corresponding to its function. This name
	is written with lowercase characters except for the 1st letter of each 
	word. Example: name of a control area which command a zoom: \it 
	ZoomControl \rm. This syntax is homogeneous with the \it atoms \rm of
	X11.
\item	The name of the objets must not use the "\_" character, because it's 
	used by \it gxv \rm to merge the variable name.
\end{itemize}

	Objects must not have long name because \it gxv \rm merge they for name 	the variables.
	
\end{document}