Using and configuring the PROGRES menus
=======================================

The tutorial of the GuidedTour has already told you how to use the
context sensitive menu on the left-hand side of the window. In this
document we will shortly describe how to use and configure the menubar 
and the buttons. Both have been added recently (Feb. 2000).


The Menubar
===========

The menubar is just a repetition of a menu group which is visible in
the menu window on the left-hand side of the PROGRES window. It is not 
possible (or has not been tested yet) to add a subgroup to the
menubar.

In order to add a menu group to the menubar you just have to edit your 
cmd.tab-file which is usually located in the $HOME/progresdata/tables
directory (unless you have set the environment variable DATAROOT
to a specific value - in this case you find that cmd.tab-file in
$DATAROOT/tables). In this file you can find the following entries:

  E;M_EDIT
  A;M_ANALYZE
  B;M_BROWSE
  C;CONSTRAINT
  D;M_DISPLAY
  I;INTERPRET
  L;M_LAYOUT
  M;M_MISC
  U;M_UN/REDO
  V;VERSION
  H;HELP
  Q;QUIT

As you can already guess, the 'M_'-prefix is indicating that this menu 
group will appear in the menubar. If you delete this prefix or add it
to other groups you are able to configure the menubar according to
your taste. Please bear in mind that the first letter (the one left of 
the semicolon) must be unique. We recommend not to change it.

The entries of the menubar are alphabetically sorted. Furthermore,
only those menus appear in the menubar which contain at least one
selectable command. In the example above you can see that the
UN/REDO-menu is added to the menubar. However, if there is nothing to
undo or redo this menu will not appear.


The Buttons
===========

Below the menubar you can find a list of buttons. You can freely
configure this list as well. The buttons are shortcuts to PROGRES menu 
entries. Clicking a button and clicking on a menu entry such as e.g.
"ShowErrors" is the same if you have defined a button to this
command. 

Defining a button is as easy as defining the menubar topics. Just pick 
out the command of the cmd.tab-file which you want to put onto a
button as shortcut, e.g. "CreateSession". Search for that keyword in
your cmd.tab-file. The line should look like this:

  450  :Ics  ;B_03_CreateSession;                 1;F;   ;w;   1; I
       :Ior  ;B_03_SessionRerun;                  0;F;   ;w;  29; I

In this case we have already defined a button which will appear at
position 3. Again, you can now already guess how to tell PROGRES to
have a button: Just add "B_xy_" as prefix to the command and you are
almost done. The 'xy' indicates the position of the button, starting
with 0. (In this case you would add "B_00_" as prefix, see
"ShowErrors"). The positions are fixed!

Every window has a Quit-Button as the left-most button. The position 0 
is located right next to this Quit-Button, position 1 is one further
etc. Please note that only those buttons are displayed which are
assigned to commands which are executable at that moment. In the
Project-View window it does not make any sense to analyse a
document. Therefore, you won't see any button assigned to an
analysation command (as e.g. "ShowErrors").

It is also possible to assign the same position to two different
buttons (see the example above: position 3 is assigned to
CreateSession and SessionRerun). These are closely connected commands
which either start a session or rerun it. So, it makes sense to put
the button at the same place. However, if you decide to do so please
make sure that these commands are mutually exclusive, i.e. if one
button appears it is impossible that the other assigned command can be 
executed as well. Another example for mutually exclusive commands is
"ShowErrors" and "HideErrors". You will find them to be assigned to
position 0 in the cmd.tab-file.

There is one more thing you have to do now before you can start
PROGRES and admire your new buttons: You have to paint an icon. This
icon may be of a maximum size of 30x30 pixels and may only be black
and white coloured. You must save it in xbm-format (XBitmap). The
directory to put the file in is
$HOME/progresdata/icons/ProgresIcons. The name of the file is the same 
as the command plus ".xbm". Example: CreateSession.xbm or
ShowErrors.xbm. Have a look at the existing ProgresIcons-directory and 
you will very soon get the idea of what to do.

If the icon is larger than 30x30 pixels then PROGRES will only
consider the top-left corner of appropriate size of your painting. If
it is smaller the icon will be put into the top left corner of the
button.


Switching the new features off:
===============================

However, if you do not like the new appearance of PROGRES you can
switch the menubar and the button list off. When you start PROGRES
you may give it a new flag: $PROGRESROOT/bin/Progres -b YES/NO
If you type "-b YES" it means that you want the buttons to be displayed
(which is the default case). If you type "-b NO" the buttons disappear.
Optionally, you can also make permanent changes by setting the
environment variable PROGWITHBUTTONS to YES or NO. In csh-syntax this
line should be added to your .cshrc:
  setenv PROGWITHBUTTONS NO
(or YES - however, you won't need that since it is the default anyway).
In case you are using a zsh please add to your .zshenv:
  export PROGWITHBUTTONS=NO
if you want to make the buttons disappear.


Known BUGS:
===========

- If you change the cmd.tab file via "MISC->ChangeMenu" then it seems
  to work for the moment. However, if you don't have write permit to
  the cmd.tab-file PROGRES won't be able to save the changes. If you
  open that window again for changing the menu you will find your
  previous changes discarded. This is not really a bug of our
  implementation but to inexperienced users it appears to be as one.
