Gabriele Cosmo
488 lines
18 KiB
Plaintext
488 lines
18 KiB
Plaintext
Written by: Simon Prior
|
|
Date: 25/08/97
|
|
|
|
GUI
|
|
----
|
|
|
|
The purpose of this program is to be the first XVT/Geant4 GUI prototype.
|
|
|
|
Basic idea: Construct a prototype GUI which interacts with Geant 4.
|
|
|
|
Future use: After initial investigation into how XVT can interact etc with
|
|
Geant, seeing what features I can use/exploit, it should be
|
|
possible for future XVT GUI developers to build on the work
|
|
done adding functionality and design ideas thus constructing one
|
|
possible GUI for use with Geant 4. It should be different in
|
|
design/features offered from other implementations so as to
|
|
promote the use of XVT with Geant4 which will cost money (as XVT is
|
|
not free) rather than the use of say TCL which is free.
|
|
|
|
Discoveries and implementation specifics :
|
|
|
|
For this part I shall go through the files which I have edited and
|
|
explain each part - the idea as well as implementation details.
|
|
|
|
I will give an abstract view to show my overall idea and then a
|
|
detailed one which will highlight implementation specifics.
|
|
|
|
The two files that do all the work regarding connection to Geant
|
|
and handling of all user input are "g4xvtwin.h" and "g4xvtwin.cxx"
|
|
- the 'window' files. These are both well commented.
|
|
|
|
Some of the other files have been added to (mainly for the floating
|
|
dockable palettes - see my Geant4 web page or palette documentation
|
|
in the 'palettes' directory).
|
|
|
|
I shall go through both files with a fine toothed comb and explain
|
|
as much as possible. (each method will be looked at carefully - if
|
|
need be).
|
|
|
|
==============================================================================
|
|
|
|
Abstract view of the prototype:
|
|
-------------------------------
|
|
|
|
OK, start the XVT GUI, GUI then spawns the Geant benchmark program. The user
|
|
interacts with the GUI via appropriate widgets selecting and executing
|
|
commands, these are sent to Geant which does the processing, Geant then
|
|
relays any information back to the user via the GUI.
|
|
|
|
==============================================================================
|
|
|
|
More Detailed view:
|
|
-------------------
|
|
|
|
My main idea(s) for this interface:
|
|
|
|
Basically, the application starts (by executing the XVT GUI
|
|
executable file).
|
|
|
|
This handles all the initialisation required for the IPC mechanism,
|
|
it is in charge of creating the named pipes and opens them at the
|
|
XVT end with the appropriate permissions on them.
|
|
|
|
Then it handles the startup of the Geant 'xvt.benchmark' file.
|
|
|
|
It basically forks off a process and execs the xvt.benchmark file.
|
|
|
|
See the xvt.benchmark documentation for the ideas behind that and a
|
|
detailed description of what happens when it is executed.
|
|
|
|
==============================================================================
|
|
|
|
I will now cover some of the major parts and ideas of the interface before
|
|
analysing the individual methods:
|
|
|
|
==============================================================================
|
|
|
|
The named pipes:
|
|
----------------
|
|
|
|
This was the chosen IPC method after reviewing several IPC mechanisms (See
|
|
the IPC section on my Geant4 web page). It works like the twoWay
|
|
program - incorporating a timer in the XVT end to read the pipe, a suitable
|
|
way of testing the pipe before reading it (blocking issues) etc - see the
|
|
early work in the IPC section or the program code for details.
|
|
|
|
The data Structures:
|
|
--------------------
|
|
|
|
Now, this was a new idea. I had to get all the command information from Geant
|
|
and transfer it via the pipes and then use it to build a suitable dynamic
|
|
widget at the XVT end. Therefore, the idea behind it all is simple, build a
|
|
data structure at the Geant end and fill it with command information, then when
|
|
requested by XVT, send all the information down the pipe. At the XVT end, parse
|
|
this information into a data structure at this end and then build the widget
|
|
etc using this data structures contained information.
|
|
|
|
The new data structures I defined were G4CommandData and G4ParameterData. (See
|
|
the header file "g4xvtwin.h" for implementation specifics.
|
|
|
|
Some important issues were encountered. It became clear that a certain
|
|
'protocol' had to be defined so that I could recognise command information etc
|
|
- this will be explained when documenting the individual method in detail.
|
|
|
|
The Palettes:
|
|
-------------
|
|
|
|
These were a new provided widget with XVT version 4.5 and were exactly what I
|
|
required. (I was working to emulate their behaviour before the release came
|
|
out). The best feature of them is that they are dynamic and can be created at
|
|
run time etc - thus giving the flexibility needed for Geant.
|
|
|
|
As they are like an artists palette the first point is that you make a
|
|
selection and it stays selected - this suited my idea well as I had the idea
|
|
to have all the command information in one palette - i.e. select a command from
|
|
this palette, then have a button which you press to 'Execute' the selected
|
|
command. I have since added a 'Help' button which you can also press - this
|
|
gives a small message about the selected command.
|
|
|
|
- This is my idea for command entry to date:
|
|
|
|
1.. Select command.
|
|
2.. If help is required click help button for information.
|
|
3.. If you are sure, press Execute which will dispatch the command to Geant.
|
|
|
|
Thus it gives a level of security so that selecting a command doesn't
|
|
necessarily mean it gets executed - until you EXPLICITLY say so.
|
|
|
|
Command Retrieval:
|
|
------------------
|
|
|
|
The idea behind this is quite clever. OK, firstly, on the geant side of
|
|
things. This reads all the commands from the Geant command tree using 'get'
|
|
methods from the Command tree class. All of the commands are read into a type
|
|
I have defined - called G4CommandData - this basically holds all the
|
|
information on a command and its parameters. (see data structures section
|
|
mentioned earlier)
|
|
|
|
Now back to the GUI end. After this has initialised itself and listed all the
|
|
available commands the user can click on a button to retrieve all the available
|
|
commands from Geant. When this happens a command is sent from the GUI down the
|
|
named pipes to Geant. When Geant receives this command it parses the command
|
|
array at that end and writes all the information down the named pipe to XVT.
|
|
|
|
XVT also has the same data structure declared and basically reads all the
|
|
information from the pipe into its own structure.
|
|
|
|
After this is done the floating command palette is constructed using the
|
|
information contained in the data structure at the XVT end.
|
|
|
|
I have defined a protocol so that XVT recognises when the commands are coming
|
|
down the pipe.
|
|
|
|
As the timer ticks and calls the DoTimer method this checks to see if there is
|
|
anything present in the pipe - if so reads it and decides what to do with it.
|
|
|
|
When it receives the string "comTree" it knows that the commands are coming.
|
|
|
|
I basically bypass the timer for a while and then call some methods to deal
|
|
with the incoming data. The first string that comes through is an integer
|
|
which tells me exactly how many command entries there are - then a loop can
|
|
be entered to fill the array at the XVT end with that number of entries.
|
|
|
|
All the appropriate casting and type changes are handled correctly. (i.e.
|
|
converting from string to integer).
|
|
|
|
You have to be careful when reading the pipe that you check there is something
|
|
present before actually reading it - especially in this case when order of
|
|
information is critical - thats why I defined a method (getString) to handle
|
|
correct reading of the named pipe. (it waits until thers is something present
|
|
before reading and returning the string).
|
|
|
|
==============================================================================
|
|
|
|
Now I shall look at the header file g4xvtwin.h and then I shall look at
|
|
the implementation file g4xvtwin.cxx in detail to explain what the methods
|
|
do etc.
|
|
|
|
==============================================================================
|
|
|
|
g4xvtwin.h:
|
|
-----------
|
|
|
|
First thing to note in this file is the #defines which define XvtToGeant and
|
|
GeantToXvt. These are names I will use in my code for the named pipes which
|
|
I set up for communication between the XVT executable and the Geant4 executable.
|
|
|
|
The next #define simply defines the file mode (i.e. appropriate UNIX
|
|
permissions) to open the named pipes with.
|
|
|
|
After this come several #includes which include various functions I will
|
|
use in the code.
|
|
|
|
After this I define 2 new types called 'G4parameterData' and 'G4commandData'.
|
|
These are structures to hold information about commands.
|
|
|
|
After this are the usual method declarations and data member definitions
|
|
etc. - These are commented.
|
|
|
|
******************************************************************************
|
|
*************************** IMPORTANT ***************************************
|
|
*** ***
|
|
*** The declaration of 'G4commandData commandArray[200];' in the header ***
|
|
*** file basically declares how many commands can be stored in the array ***
|
|
*** and then used to create the command palette. ***
|
|
*** IF during future use the GUI coredumps when creating the command ***
|
|
*** palette it is most likely that there are greater that 200 commands ***
|
|
*** - especially as commands are being added all the time. All you need ***
|
|
*** to do is increase this value and everything will work fine again. ***
|
|
*** ***
|
|
******************************************************************************
|
|
|
|
==============================================================================
|
|
|
|
g4xvtwin.cxx:
|
|
-------------
|
|
|
|
I shall cover the methods which I have written or added code to - the ones
|
|
automatically generated are self explanatory and have good commenting (see
|
|
file for more details).
|
|
|
|
The Constructor:
|
|
----------------
|
|
|
|
Initialisation occurs here by calling several initialiser functions - see their
|
|
own documentation later on (next).
|
|
|
|
initIndex:
|
|
----------
|
|
|
|
This initialises the command base array indexing variables - very simple.
|
|
|
|
initStatusBar:
|
|
--------------
|
|
|
|
This sets up the status bars fields with some initial values.
|
|
|
|
initTimer:
|
|
----------
|
|
|
|
Starts the XVT timer (on every time interval (which the coder can alter) it
|
|
activates the DoTimer method).
|
|
|
|
initIPC:
|
|
--------
|
|
|
|
This sets the value of the pipe reading variable (i.e. how many bytes are
|
|
read in a single read operation and then calls createNamedPipes and startSlave.
|
|
|
|
initFrame:
|
|
----------
|
|
|
|
Creates an attachment frame and allows attachment to all sides.
|
|
|
|
createNamedPipes:
|
|
-----------------
|
|
|
|
This method creates the named pipes required in the application.
|
|
|
|
It first creates the pipes and then opens them.
|
|
|
|
The XvtToGeant pipe with write permission only,
|
|
the GeantToXvt with read permission only.
|
|
|
|
The program uses the errorHandler method to report errors because the
|
|
program should terminate if IPC setup fails.
|
|
|
|
destroyNamedPipes:
|
|
------------------
|
|
|
|
This method closes and unlinks all the open named pipes.
|
|
|
|
startSlave:
|
|
-----------
|
|
|
|
This method forks and exec's the other process (xvt.benchmark - the Geant
|
|
executable).
|
|
|
|
This method also uses the errorHandler to report errors because if the
|
|
fork or Exec fail the program should terminate.
|
|
|
|
The fork and exec are UNIX specific - for more details on their use see a UNIX
|
|
manual or man pages.
|
|
|
|
DoTimer:
|
|
--------
|
|
|
|
Every time the timer ticks this method checks to see if the file descriptor
|
|
can be read without blocking (i.e. there is something in the pipe), if
|
|
there is it grabs the data from the pipe, if you are not in the process of
|
|
reading all the commands from Geant it then checks if the string is equal to
|
|
"comTree" which indicates all the commands are coming from Geant and
|
|
different action should be taken. If it isn't comTree then it simply
|
|
displays the string in the Main log area.
|
|
|
|
The different action to take is to call some other methods to do the reading of
|
|
commands and building of the command palette. (discussed later.)
|
|
|
|
Refer to code for the implementation specifics.
|
|
|
|
errorHandler:
|
|
-------------
|
|
|
|
A general purpose error handler. It can be called by any method. A string
|
|
is passed so that this method can post a dialog box to the user stating
|
|
where the program fault occurs then quit the GUI.
|
|
|
|
The key point is that this method should be called when processing should no
|
|
longer continue i.e. the GUI should be killed.
|
|
|
|
writeData:
|
|
----------
|
|
|
|
Writes the passed string to the Command log window and the XvtToGeant
|
|
pipe - i.e. will send the string to Geant (commands!) for processing.
|
|
|
|
initCommandPalette:
|
|
-------------------
|
|
|
|
Allocate storage space for a tool palette.
|
|
|
|
destroyCommandPalette:
|
|
----------------------
|
|
|
|
Free up storage space allocated for the command palette.
|
|
|
|
buildCommandPalettes:
|
|
---------------------
|
|
|
|
This method builds the palettes of commands available to the user.
|
|
|
|
This basically parses the commandArray that was received from Geant and
|
|
builds up the command palette 'on-the-fly' from this information.
|
|
|
|
It checks the flag of the command in the array to see whether it is
|
|
a 'directory', a command or a cascade. (this is denoted by the flag being a
|
|
0, 1 or 2 and this is set at the Geant end when it reads in the commands).
|
|
|
|
Once it has this information it can decide how to handle it.. If it is a
|
|
'directory' - i.e. a category of command it must have its own sub-palette
|
|
so this can be constructed. If it is a command it must be a button in the
|
|
current sub-palette and if it is a cascade it must be a sub-palette of the
|
|
current palette - see code for implementation specifics.
|
|
|
|
destroyDragSource:
|
|
------------------
|
|
|
|
This method destroys the space allocated for the drag source.
|
|
|
|
setStatus:
|
|
----------
|
|
|
|
This method places the passed string into the status field of the status
|
|
bar.
|
|
|
|
resetStatus:
|
|
------------
|
|
|
|
This method completely blanks the status field of the status bar.
|
|
|
|
retrieveCommand:
|
|
----------------
|
|
|
|
This method checks the command palette to see which button has been pressed
|
|
then it will scan the command array to find the command that corresponds to
|
|
the users selection and returns the command string to be sent to Geant.
|
|
|
|
It also tests to see if the command that is selected for execution requires a
|
|
parameter and if so calls 'getParameters' to obtain this from the user.
|
|
|
|
initTextWindows:
|
|
----------------
|
|
|
|
This method simply puts a title in the Text windows to start things off.
|
|
|
|
fillLocalArray:
|
|
---------------
|
|
|
|
This method fills the command data structure at the XVT end with data that is
|
|
being received from the Geant end. It uses the method 'getString' to grab the
|
|
strings from the pipe without error.
|
|
|
|
showHelp:
|
|
---------
|
|
|
|
This method is called when the user clicks on the 'help' button.
|
|
|
|
It looks which is the current selected tool and retrieves the guidance for
|
|
that tool - then puts this in the text widget and a pop up window.
|
|
|
|
getParameters:
|
|
--------------
|
|
|
|
This method retrieves parameters from the user via dialog boxes. - called by
|
|
retrieveCommand.
|
|
|
|
getTextCommand:
|
|
---------------
|
|
|
|
This method retrieves parameters from the user via dialog boxes. This method
|
|
is very similar to 'getParameters' however this one is called if the user
|
|
wishes to type a command in instead of using the command palette widget.
|
|
|
|
executeCommand:
|
|
---------------
|
|
|
|
When the user clicks on the execute button this method is called.
|
|
|
|
It retrieves the command (with parameters if necessary) and writes it
|
|
down the named pipe to Geant to deal with.
|
|
|
|
getString:
|
|
----------
|
|
|
|
This method grabs the string that is located in the pipe and returns it
|
|
to the caller - provided there is something present in the pipe.
|
|
|
|
activateButtons:
|
|
----------------
|
|
|
|
This method enables the 'exec' buttons on the toolbar. It is called just
|
|
after the user has retrieved the commands and built the widget.
|
|
|
|
It first enables the buttons and then refreshes the screen by redrawing
|
|
them.
|
|
|
|
I have tried to limit the mistakes a user could make and this is a very good
|
|
way of doing just that - by disabling buttons/widgets etc that could cause
|
|
problems if pressed/clicked on at the wrong time.
|
|
|
|
==============================================================================
|
|
|
|
NOTE: Any code not mentioned here is self explanatory and well commented.
|
|
|
|
==============================================================================
|
|
|
|
Now I a couple of XVT specific discoveries to mention:
|
|
|
|
DISCOVERY 1:
|
|
|
|
There is some sort of problem with Dialog boxes and floating dockable palettes.
|
|
|
|
I had a palette which contained a button, when this button was pressed it
|
|
called one of the pre-defined dialogs, this however caused a lock up concerning
|
|
the mouse - I couldn't get control back, the dialog seemed to keep it.
|
|
What happened exactly was when you clicked the button down it didn't pop up
|
|
again thus it wasn't receiving the mouse up event. When you did click the
|
|
mouse again however it spawned the dialog - again and again, it sort of
|
|
entered a loop repeatedly spawning the dialog. - Technical support said that
|
|
the dialog must have been inadvertently destroying the mouse handlers.
|
|
|
|
DISCOVERY 2:
|
|
|
|
You cannot have a toolbar with buttons in and a CAttachmentFrame which
|
|
encomapasses the whole window because if you do, the CAttachmentFrame
|
|
obscures all of the mouse events from reaching the toolbar - thus none
|
|
of the buttons react.
|
|
|
|
A solution to this problem is to have a CAttachmentFrame that doesn't
|
|
cover the entire window, just a part of it (this can be acheived with
|
|
a certain constructor - see code) - thus the events can then
|
|
get to the toolbar.
|
|
|
|
DISCOVERY 3:
|
|
|
|
For some reason you cannot pass a WINDOW variable between a view and a
|
|
document - when I tried it the program kept core dumping on this.
|
|
|
|
DISCOVERY 4:
|
|
|
|
The Select() system call has been dropped. The reason is that it was failing
|
|
for some reason which I couldn't work out. It kept returning TRUE all the
|
|
time when I used it to see if the named pipe was ready for reading and this
|
|
was not always the case.
|
|
|
|
The solution I came up with was to use a function from the ioctl library.
|
|
The function I used is the following:
|
|
|
|
int nbytes;
|
|
ioctl(fd_XvtToGeant, FIONREAD, &nbytes);
|
|
|
|
This is much better than select because I only have a single file descriptor
|
|
to test and using this is far shorter and easier to code/understand than the
|
|
select stuff.
|
|
|
|
==============================================================================
|
|
S.Prior - August '97
|