General Information
===================

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

This is still a beta version, although it is already pretty usable.  Every
widget from gtk 1.0.6 as 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 version 2.0.35
   - SunOS 5.5.1
using the following compilers :
   - Gnat 3.10p
   - Gnat 3.11p
and the following version of gtk :
   - Gtk 1.0.4 (tested with GtkAda-0.1-alpha only)
   - Gtk 1.0.5
   - Gtk 1.0.6

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.

Ada Core Technologies Inc. (developpers of Gnat) is not responsible in
any way for this binding, and can not provide any support for it.

Content
=======

The full set of widget that comes with gtk 1.0.6 as been bound, and you should
be able to use all of them from your Ada program. The Gdk binding is not
complete yet, although most of it is done. It is important to know that only a
subset of this part of the binding has been actually 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
wants to free the memory.


Installing and compiling your programs
======================================

This is still beta software, so the installation is very basic : just use the
makefile, after making sure that the gtk-config program distributed with gtk
is located in your PATH.

   $ make

This will create two files, libgtkada.a and libgtkada.so and then compile the
testgtk example.

To install, copy these two library files, plus all the .ads, .adb and .ali
files into a directory.

   $ cp libgtkada.* *.ads *.adb *.ali <your_directory>
   $ cd <your_directory>
   $ chmod a-w *.ali

Then, when you want to compile your application, use the -I switch for
gnatmake (see the Makefile in testgtk/ for an example)

   $ gnatmake -I<your_directory> <your_application> -largs \
      -L<your_directory> -lgtk -lgdk -lglib -lXext -lX11 -lsocket \
      -lnsl -lm -lgtkada

Or even better use the gtk-config script :

   $ gnatmake `gtk-config --cflags` -largs `gtk-config --libs` -lgtkada


Creating and Binding new widgets
================================

There is at present no support in this binding for creating new widgets
directly from Ada. You will have to do it in C, and then create an Ada binding
for your new widget.

we provide a Perl script to help you create this binding (this is the script
we have used ourselves).  This will not fully automate the process, although
it should really speed things up. You will probably need less than 15 min to
create a new binding once you will get used to the way GtkAda works.

Here are the steps to create a new binding :

- Give the 'generate.pl' script the C header file

- The perl script should ask you for every field in the C structure if
you want to create a function to make it accessible from Ada. Answer
'y' or 'n' (the default value is 'n', just press ENTER).

   $ perl generate.pl ../include/gtk/gtkbutton.h > temporary
     Create a function for the field child (of type GtkWidget*) [n]?
     Create a function for the field in_button (of type guint) [n]?
     Create a function for the field button_down (of type guint) [n]?

- If you answered yes to at least one of the above questions, create a
new C file, and move the C part of the 'temporary' file created by
generate.pl to this C file.

- Do a gnatchop on the 'temporary' file created by generate.pl

   $ gnatchop temporary

  This should create two Ada files (specification and body)

- Edit these two files if needed (generally to change some parameters
  from Gint to Boolean for instance). It can be a little bit tricky
  when one of your functions returns a GList* of a GSList*. Please have
  a look at gtk-combo.ads for instance for how to do this.


Threads
=======

The current stable version of Gtk+ (1.0.6) is not thread-safe. Therefore, the
usage of tasks inside programs using this binding is not recommended. The
switch to the 1.1 series is currently under way, and will provide such
feature.


How to report bugs
==================

This library is still considered beta code, and it is thus likely that you
will find bugs.  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 binding.

For more general questions about gtk itself, please ask your questions to the
gtk mailing list. The authors of this binding are far from beeing specialists
of gtk, as it was 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 were the problem is, please recompile a static
version of your program, run gdb, and set a breakpoint on the function
'g_warning'.  Then run your program as usual, using the 'run' command. Then
send us the result of the 'bt' command. Here is a summary :

   $ make static
   $ gdb <your_program_name>
   gdb> break g_warning
   gdb> run
   ....
   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 binding. Please check your program carefully, and if you think this is a
problem in the binding, send us a mail.

To report errors, send a mail to both authors (see the email addresses at the
end of this document) explaining exactly what your 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 binding is
as useful as possible...

AUTHORS
=======

Emmanuel Briot <briot@gnat.com>
Joel Brobecker <jbrobecker@west.raytheon.com>
