Object User Interface is copyright © 1998, Dominique Lorre

First, I would like to apologize for the lack of documentation.
The explanation for this is that :
- OUI has been designed to suit my needs
- The interface is changing so often that any documentation would have
become obsolete quickly.

The reasons why I am releasing OUI are :

- It may be of benefit to the Amiga community
- I am tired of coding examples programs in C, which produce very long code
  and make me reinvent the wheel at each time.

A note about GNU compiler

The GNU compiler is distributed with the GNU general public license.
Making a GNU OUI version is possible via a file named fstabs.h which is
distributed under this license. This should not mean that OUI is following
this license. If this is a problem to anyone, just tell me and I will simply
remove the GNU support since the additional file is not needed by OUI but by
the GNU compiler itself.

OUI is distrbuted under Copyrighted freeware. Feel free to use and modify this
files as long as you are developping for the Amiga OS. If you want to release
add-ons for OUI, feel free to do it but your files should not be mixed with
the OUI main archive (oui.lha).


A note about GUI systems

OUI is not a GUI system, it is a C++ encapsulation of some AmigaOS functions.
Making OUI work with any GUI system should not be a problem.


What is OUI ?

OUI provides the following services for the C++ developper :

locale support (independent, locale.cc, include/locale.h)
The locale support provides a lstring class which has the ability of creating
CatComp descriptors files automatically. You can use these features without
using any other feature of OUI.


memory support (independent, new.cc, include/new.h)
The memory support provides a pool based memory allocation. It does not
handles exceptions but rather provides an Oxygene feature which is a small
amount of memory released by the application when things are going wrong.
This can help the user quitting safely its applications when memory has
gone out. A side effect of this is that OUI programs cannot be tested with
memoration since memoration will eat the Oxygene pool as soon as OUI release it.
Of course, any data allocated with new will be released on program exit wether
or not you use delete on it.

list support (independent, slist.cc, include/slist.h)
These lists are much like the AmigaOS ones. Because of the virtual functions
I decided to not declare the nodes as AmigaOS MinNodes.

screens, windows and gadgets support (the big stuff).
The principle is the following :
Each OUI application which plans to use windows must declare a screen.
A screen can be a custom screen or a lock on a public screen.
The screen class contains useful informations such as the size, the ratio
and also tries to calculate extra pens (such as RED and GREEN).

A window is opened in two step :
first you use the new operator on it with the parameters you declared in
the class (for example the size).
second, you open it with others parameters (for example the screen pointer).

When you open a window you may add gadgets to it. For this you should allocate
a gadgetlist with the maximum number of gadgets you plan to use. This is quite
boring but I did not found a better way yet (Any idea ?). Then you add the gadgets
to the gadget list. The gadets can be of gadtools, Boopsi or anywhere else.

The window class also provides support for special rendering such as background
Bitmaps, areadraw and clipping.
Many other system functions have also been encapsulated. Menu functions were
added and also the cleanup code has been carefully designed. When processing
events, you will have control on the way you want to handle these. Keyboard
support has been added.

In conclusion, the first window application I have ported from C to C++
has been reduced from 1400 lines to 700 for the same functionnalities.


Evolution of OUI.

I do not guarantee anything except this : the set() gadgets functions are planned to
move to a TagItem version and are guaranteed to change. The locale, new and slist
support should not change much. When upgrading oui, the best thing will be
to recompile every module, and sometime you will have to modify some of your code.
Of course, this warning is excessive but it happened in the past that I had to
make big modifications in the interface.

Installing OUI

The best is to create a drawer named OUI and another named Ulib and to assign
Ulib: to this drawer. Then you place the OUI code in the OUI drawer and the
library itself in Ulib:. The Oui_localise version is for making .ct and .cd
files automatically and is generally not much used.

Compiling OUI

If you use SAS/C the call is :

SMake -b smakeXXX.def where XXX is your compiler flavor.

For GNU you will find the appropriate GNUMakefile.


Compiling with OUI

Do not forget to add XXX/OUI/include and XXX/OUI/include/gadgets to your
INCLUDE path (XXX is the Path where you created the OUI drawer).

Programming example :

You should look to the envman.lha archive for a complete example of programming
with oui.

HWGRCS support
You can use the ciall file for automatical RCS support if you plan to use your custom
OUI. The ciall.lha archive will be uploaded separately.

The Author:
You can reach me at :
Dominique Lorre
le Fabary, BAT C
4, Allée des Peupliers
13100 Aix-en-Provence, FRANCE
EMAIL: dlorre@caramail.com