%****************************************************************************/
%
% File:		dev_gui.tex
%
% Project:	xdevmenu application documentation
%
% Description:	"dev_gui.c" section
%
% Author(s):	Faranguiss Poncet
%
% Original:	March 1991
%
%
% $Header: /cvsroot/taco/taco/system/xdevmenu/doc/dev_gui.tex,v 1.2 2003/12/17 14:24:25 jkrueger1 Exp $
%
% Copyright (c) 1990 by European Synchrotron Radiation Facility, 
%                       Grenoble, France
%
%		       All Rights Reserved
%
%****************************************************************************/
This module is in charge of all graphical representation of the devices and
also the graphical representation of the parameters of the device commands.

In this module we find functions to display an opened device (represented by
an icon), to highlight a selected device, to display and prompt an input
parameter, to display an output parameter, and also to display an error in the 
out and error window.

This module contains several data structure definitions.

\paragraph{Internal data structures and variables : }

\begin{itemize}
\item {\bf dev\_icon\_structure : } 
the most important data structure defined in this module is "dev\_icon\_structure". 
This data structure is used to make the correspondence between a device and its 
associated icon and out and error window on the screen. 
The device is represented in the data structure by its name. The icon associated
with the device is represented by three widget ids. An icon is a collection
of two pushbuttons\footnote[1]{OSF/MOTIF concept : see OSF/MOTIF programmer's
guide} one with a string label and the other one with a pixmap
label. These two pushbuttons are grouped within a row-column\footnotemark[1]
widget. Therefore to identify completely the icon we need the row-column widget
id, string pushbutton widget id and the pixmap pushbutton widget id. 
In order to have the output arguments of an executed command and the errors
received from the device servers together in the same paned window\footnotemark[1], 
the dialogue shell\footnotemark[1] widget id, the paned window\footnotemark[1] widget 
id and the two scrolled text\footnotemark[1] widget ids for the
output arguments and error messages are also needed in this data structure.
This data structure is then used in an array in which each entry corresponds to one
device. This array is named "dev\_icon\_table" in the code.

\item {\bf cmd\_gui\_struct : } 
the second data structure is used to pass all the information necessary for the execution 
of a command to a callback procedure.  The information contained within this structure is~: 
the device name, the command name, the data type of the input argument and the reference of 
the widget containing the value of the input argument.

\item {\bf gui\_out\_3\_fields\_struct : } 
the third data structure is used to transform the value of data made of two or three fields 
to two or three string fields. This data structure is particularly used when we want to display the
value of an output data structure (2 or 3 fields only). In that case we
transform it first into "gui\_out\_3\_fields\_struct" data structure before
displaying it in the top part of the paned window.

\item {\bf dev\_icon\_table : } 
this is the table which makes the correspondence between one device and its associated icon.

\item {\bf current\_selected\_device\_index : } 
the index into the "dev\_icon\_table" of the selected device. 
\end{itemize}

%\xs{1}

%\sy{1}	{show\_opened\_device}
\paragraph*{show\_opened\_device : }

This function is called by the "xdevmenu.c" module when the user selects a
device. 

This function creates an icon for each opened device. An icon is a
collection of a row-column\footnotemark[1]
widget, a pushbutton\footnotemark[1] widget with pixmap
label and another pushbutton widget with string label. 
It creates also a window used for the display of all the executed commands for
this device together with the possible errors received from this device server.
This window is made of a paned window\footnotemark[1].
Then the references of the three widgets and the name of the opened device are inserted
in the "dev\_icon\_table".

What is very important to notice is the names attributed to the widgets. For
each device the function asks for its type. This type is given in a string form.
Then the row-column widget name is made by appending the device type string with
"\_rc" string. Similarly for the pixmap and string pushbutton, the name is made
by appending the device type string with "\_pixmap" for the pixmap pushbutton
and with "\_label" for string pushbutton.

This naming convention allows the definition in the resource file of the 
application a different bitmap name for each type of device. Therefore the image of the
icon can vary from one device type to another.

\paragraph*{show\_list\_cmd\_names : }

This function is called by the "xdevmenu.c" module when the user has selected
the "execute command" function in the "edit" pulldown
menu\footnote[1]{OSF/MOTIF concept : see OSF/MOTIF programmer's guide}.

This function is in charge of displaying the command names available for
the selected device in a selection dialogue window\footnotemark[1].
The selection dialogue window
is not created by this function. It is created at the initialisation of the
application by "xdevmenu.c" module using the UIL file.

This function modifies the list of items associated
with the selection dialogue, by the list of commands which is passed as an
input argument.

This function has three input parameters~: the reference to the selection
dialogue widget, the number of commands, and an array of command names.

\paragraph*{show\_cmd\_in\_param : }

This function is called by the "xdevmenu.c" module when the user has asked
for the execution of a command if that command has an input parameter.

This function is in charge of creating a dialogue window\footnotemark[1]
in which it puts a widget
representing the input parameter. The type of this widget depends on the
data type of the input parameter (integer, float, string, ...).

This widget provides the user with the means to give a value to the input
argument.

The input parameters for "show\_cmd\_in\_param" are~: the device name,
the command name, the name of the input argument for that command and the
data type of the input argument.

\paragraph*{show\_cmd\_out\_param : }

This function is called in a callback procedure when a command has been
executed successfully on a device. This function is in charge of displaying
the output parameters of a command.

The difference between this function and the "show\_cmd\_in\_param" function
is that in this function we convert every data type to one or several strings
and then another function (gui\_display\_arg\_out) is called to display them
to the user. 

\paragraph*{remove\_selected\_device : }

This function is called by "xdevmenu.c" module when the connection to a device
has been closed, in order to remove its associated icon.

Therefore, this function looks for the device in the "dev\_icon\_table" using
the useful variable "current\_selected\_device\_index". It then destroys the
seven widgets stored at that index in the table and finally it frees the
table entry.


