----------------------------------------------------------------------
--                                                                  --
--        GtkAda . An Ada95 graphical toolkit based on Gtk+         --
--                                                                  --
----------------------------------------------------------------------

Installation
============
 
See the file 'INSTALL'

General Information
===================
     
The home page for GtkAda is
     
     http://gtkada.eu.org

The home page for gtk is
    
     http://www.gtk.org
     
This home page will always contain the latest news for this toolkit.

This is GtkAda version 1.2.4. This package is an Ada95 graphical library
for the Gimp Toolkit, which means this is a set of packages to allow you
to easily create some graphical interfaces under X11 and Win32, using Ada95
as a programming language.

From now on, major version numbers will follow Gtk+ (e.g 1.2, 1.3),
meaning that stable versions of GtkAda will have major number 1.2 and
development versions will have number 1.3.

Every widget from gtk 1.2 has been implemented, and the test
program found in the gtk release has been reimplemented in Ada (have a
look at the testgtk/ directory).
     
These functions were tested on the following systems :
   - Linux/x86
   - Solaris/sparc
   - Solaris/x86
   - Dec Unix 4.0b
   - SGI IRIX 6.5
   - HP/UX 10.20
   - NT 4.0
   - AiX 4.3.2
using the following compilers:
   - Gnat 3.12
   - Gnat 3.11b2
   - Gnat 3.11p

the following versions of gtk:
   - Gtk 1.2.2
   - Gtk 1.2.1
   - Gtk 1.2.0

and the following versions of glade:
   - Glade 0.4.1
   - Glade 0.4.0

Although versions up to 0.2.1 were compatible with Gtk1.0, this one is
Gtk-1.2 specific. If you are looking for a binding to Gtk1.0, please consider
downloading GtkAda 0.2.1.

If you manage to use it on other systems (which should probably be
straightforward - just recompile GtkAda), please let us know so that
we can add to the above list.

Disclaimer
==========

GtkAda  is free software;  you  can redistribute  it and/or  modify it
under terms of the GNU General Public License as published by the Free
Software Foundation; either  version 2, or  (at your option) any later
version.  GtkAda is  distributed in the  hope that it  will be useful,
but WITHOUT ANY   WARRANTY;   without even  the implied  warranty   of
MERCHANTABILITY -- or  FITNESS FOR A PARTICULAR  PURPOSE.  See the GNU
General Public  License for more details.  You  should have received a
copy of the GNU General -- Public License distributed with GtkAda; see
file  COPYING.  If  not,  write to  the  Free  Software Foundation, 59
Temple Place - Suite 330, Boston, -- MA 02111-1307, USA.

Content
=======

The full set of widget that comes with Gtk+ 1.2 have been bound,
and you should be able to use all of them from your Ada program.

Although it is not quite complete yet, the Gdk binding (the low level
layer) will probably not evolve soon, unless some people (why not
you?) send us patches, or at least ask for specific functions.

It is important to know that only a subset of the gdk binding has
actually been tested, and therefore errors are still likely to appear.

We have tried to adopt a consistent naming scheme for Ada identifiers :

- The widget names are  the same as in  C, excepted that an underscore
sign (_) is used to separate words
     
    ex/   Gtk_Button   Gtk_Color_Selection_Dialog
     
- The function names are the  same as in  C, ignoring the leading gtk_
and the widget name
     
    ex/   gtk_misc_set_padding        ->  Set_Padding
          gtk_toggle_button_set_state ->  Set_State
     
- All the enum types have been grouped in the gtk-enums.ads file
     
- The only tricky part is for the callbacks, the timeout functions,
the idle functions, and the data that can be attached to every
Object. In these cases, we have used generic package to provide type
safety. Please have a look at the files in testgtk to see how these
functions are implemented.
     
!!WARNING!!  All  the  generic   functions allocate   some  memory for
internal structures. This  memory is freed  by gtk itself,  by calling
some Ada functions. Thus the generic packages  have to be instanciated
at library level, not  inside a subprogram,  so that the functions are
still defined when gtk needs to free the memory.


Documentation
=============

Although not complete, a first set of documentation is provided in the
docs/ subdirectory in various formats (texinfo, ps, txt, info, html)


How to report bugs
==================
     
While this library is now considered stable, you still might find some
bugs in it. We have tried to test it as much  as possible, essentially
by converting the testgtk.c file found in the gtk distribution.
We have been able to rewrite nearly all the tests.  Please have a look
at the  testgtk,  which can  give you a lot  of examples of how to use
this toolkit.

For more general questions about gtk itself, please ask your questions
to the  gtk  mailing list. The  authors of  this toolkit  are far from
beeing specialists of gtk, as it was one of our first project with gtk.
     
There are two kinds of problems you can encounter :
     
- If the gtk library itself  was compiled with warnings turned on, you
may  get some  warnings messages,  mainly because  of  types problems.
These warnings should not appear, as  we have tried to be as type safe
as possible  in this package.  To  know exactly where  the problem is,
we recommand using gdb. You will have to load the dynamic libraries
first. Then  send  us the  result  of  the  'bt' command.
Here is a summary :
     
   $ gnatmake -g <your_program> `gtkada-config`
   $ gdb <your_program_name>
   (gdb) break main
   (gdb) run
   (gdb) break g_log
   (gdb) cont
   ....
   (gdb) bt
     
- In  some  (hopefully) rare cases,   you can even get a  segmentation
fault  within gtk.  That  means there is  definitevly  something wrong
either  your program  or   the  toolkit.  Please  check   your program
carefully, and if you think this is a problem in GtkAda itself, send us
an email.
     
To report  errors, if you are a supported user of GNAT, send a mail to
report@gnat.com following  the usual procedure. Otherwise, send a mail
to gtkada@ada.eu.org to reach all the authors, explaining exactly what
you are doing, what it the  expected  result  and  what  you  actually
get. Please include the required sources to reproduced the problem, in
a  format usable  by 'gnatchop'  (basically, insert  all  the required
sources at  the end of  the mail). Please  try to provide a  subset of
your sources as small as possible.
     
Of course, we will  welcome any patch   you can provide, so  that this
toolkit is as useful as possible...

