GadToolsBox's great Oberon Source Generator
===========================================

-v 38.02-

This is the third release of the external Oberon source generator for
GadToolsBox 2.x.  Please use it instead of the built in source generator
because some the internal version is buggy and will not be updated any more.

Let's explan the history of generating Oberon source with GadToolsBox:
I (Kai Bolay) thougt that it would be a good idea that GadToolsBox supports
Oberon so I changed Jan van den Baard's C generator "GenC.c" to
"GenOberon.c" and asked Jan to add it to GTB. With GTB 2.0 Jan came up with
the idea of external source generators. Jan helped me (in fact he did all
the work! Thanks, Jan!) to make "GenOberon.c" a standalone program. Now
Thomas Igracki did the great job of converting to C program "GenOberon.c"
to the Oberon program "OG.mod". I did some minor modifications to "OG.mod"
and released it.
In Version 38.xx several Bugs are fixed & finally the menus & ListView-Gadgets
are generated corectly ( Fixings & additions by Stefan Kurtz).


Please feel free to use "OG.mod" to make generators for other languages
similar to Oberon like Modula-2 or Pascal. But please inform me.

The usage of "OG" is very simple.  It has five parameters:
NAME/A       : name of the GUI file which should be converted
TO=AS/A      : name of the source which should be generated
RASTER/S     : generates a RasterPattern as WindowBackGround
UNDERMOUSE/S : windows are opened unter the mousePointer
FORCE/S      : the old source is overwriten without asking


To see how to use the generated source see the subdirectory "Demo".

Here's a little overview of the generated source:

If you use the getfile gadget the generated source will automatically
import the module "GetFile" which initializes the boopsi image. You can
find this module in the subdirectory "GetFile".

From here on when I refer to <Project-Name> I mean the name entered in the
Edit Data requester from the Window menu and when I refer to <Gadget-Label>
I mean the name you have typed in the "Label" gadget of one of the gadget
kind requesters.  When I refer to <Menu-Label> I mean the label you have
typed in the Label gadget of the Menu Editor.

The following exported routines are generated:

 PROCEDURE SetupScreen (): INTEGER

 This routine will open or lock the screen and get it's visual info.
 When requested this routine will also  open the font.
 This  routine  can  return  one of the following errors:

     0 = No error.
     1 = Could not open or lock the screen.
     2 = Could not get the screen it's visual info.
     5 = Could not open the font.

 PROCEDURE CloseDownScreen;

 This routine will free the resources taken by "SetupScreen()".  You
 must still call this routine when  "SetupScreen()"  failed to close
 and free the resources that didn't fail to open!!!

 PROCEDURE Create<Project-Name>Gadgets (createGads: BOOLAN): INTEGER;

 There are as much of these routines as there are Project Windows in
 the file you have generated. These routines will set-up the gadgets.
 These routines can return one of the following errors:

     0 = No error.
     1 = Could not create a gadget context.
     2 = Error during the gadget creation.

 PROCEDURE Open<Project-Name>Window (createGads: BOOLAN): INTEGER;

 There are as much of these routines as there are Project Windows in
 the file you have generated. These routines will set-up the gadgets
 (if you ask for it) and menus and open the window. These routines can
 return one of the following errors:

     0 = No error.
     1 = Could not create a gadget context.
     2 = Error during the gadget creation.
     3 = Could not create the menus.
     4 = Could not open the window.
     5 = Could not open the system font.

 PROCEDURE Close<Project-Name>Window;

 There are as much of these routines as there are Project Windows in
 the file you have generated. These routines will free all resources
 that the "Open<Project-Name>Window()" routine has taken.  You  must
 still call this routine if "Open<Project-Name>Window()" has failed!

 PROCEDURE <Project-Name>Render;

 Each Project Window which has texts and/or BevelBoxes  attached  to
 it will have a routine which renders these texts and/or  BevelBoxes
 in the window. This routine must also be called by the user program
 upon  receiving  a IDCMP-REFRESHWINDOW message at the  window port.
 When such a message  is received  this  routine   must  be   called
 between   the   gt.BeginRefresh()  and gt.EndRefresh() calls.  Here
 is a  small example of what I mean:

 IF (I.refreshWindow IN class) THEN
   gt.BeginRefresh (<Project-Name>Wnd);
   <Project-Name>Render;
   gt.EndRefresh (<Project-Name>Wnd, I.LTRUE);
 END;

The main file also has the following globals defined  which are shared by
all project windows:

  Scr: I.ScreenPtr;             A pointer to the opened/locked screen
  VisualInfo: e.APTR;           A pointer to the visual info

The following globals are only  generated when the file contains  gadgets
or menus and when the OpenFont routine is generated and  when  the window
must have a zoom gadget:

  <Project-Name>GList: I.GadgetPtr;         The created gadgets
  <Project-Name>Menus: I.MenuPtr;           The created menus
  <Project-Name>Zoom: ARRAY 4 OF INTEGER;   The window alternate positions
  Font: g.TextAttrPtr;                      The opened font

Also  generated  are  pointers for each project window that is in memory:

  <Project-Name>Wnd: I.WindowPtr;        A pointer to the window

Four constant are generated for each window.  These words contain the
window's left and topedge and it's width and height:

  <Project-Name>Left     Window left-edge
  <Project-Name>Top      Window top-edge
  <Project-Name>Width    Window width
  <Project-Name>Height   Window height

Also the main  file contains  the Gadget  Array's for each project window
which are define as follows:

  <Project-Name>Gadgets: ARRAY <Project-Name> OF I.GadgetPtr;

To access the pointers in this array the  program  generates  constants
which specify the position of  a certain  gadget in  the array:

  GD<Gadget-Label>

If you have questions, suggestions, bugs, donations, ... please contact:

Stefan Kurtz
Snail Mail:              EMail:
Auf dem Niederen Esch 10 InterNet -> stkurtz@post.uni-bielefeld.de
33607 Bielefeld          Z-Netz   -> St.Kurtz@Bionic.zer.de
Germany                  FIDO     -> Never !

and/or

Thomas Igracki
Snail Mail:              EMail:
Obstallee 45             UseNet -> lokai@cs.tu-berlin.de
13593 Berlin             Z-Netz -> T.Igracki@BAMP.ZER
Germany                  Fido   -> Thomas Igracki (2:2403/10.40)

and/or

Kai Bolay [kai]
Snail Mail:              EMail:
Hoffmannstrae 168       UUCP: kai@amokle.stgt.sub.org
D-71229 Leonberg         FIDO: 2:2407/106.3
Germany
