This is gtkada_ug.info, produced by makeinfo version 4.0 from
gtkada_ug.texi.


File: gtkada_ug.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

GtkAda User's Guide
*******************

   GtkAda User's Guide

   GtkAda, the Ada 95 graphical toolkit

   Version 1.2.12

   Date: 2001/04/20 07:14:33

   Copyright (C) 1998-2000, Emmanuel Briot, Joel Brobecker, Arnaud
Charlet

   This document may be copied, in whole or in part, in any form or by
any means, as is or with alterations, provided that (1) alterations are
clearly marked as alterations and (2) this copyright notice is included
unmodified in any copy.

* Menu:

* Introduction::
* Getting started with GtkAda::
* Hierarchical composition of a window::
* Signal handling::
* Starting an application with GtkAda::
* Resource files::
* Memory management::
* Tasking with GtkAda::
* Object-oriented features::
* Support for Glade the Gtk GUI builder::
* Binding new widgets::
* How to report bugs::
* Bibliography::

 --- The Detailed Node Listing ---

Getting started with GtkAda

* How to build and install GtkAda::
* Organization of the GtkAda package::
* How to compile an application with GtkAda::
* Architecture of the toolkit::
* Widgets Hierarchy::

Object-oriented features
* Using tagged types to extend Gtk widgets::
* Creating new widgets in Ada::


File: gtkada_ug.info,  Node: Introduction,  Next: Getting started with GtkAda,  Prev: Top,  Up: Top

Introduction: What is GtkAda ?
******************************

GtkAda is a high-level portable graphical toolkit, based on the gtk+
toolkit, one of the official GNU toolkits. It makes it easy to create
portable user interfaces for multiple platforms, including most
platforms that have a X11 server and Win32 platforms.

   Although it is based on a C library, GtkAda uses some advanced Ada95
features like tagged types, generic packages, access to subprograms,
exceptions, etc... to make it easier to use and design interfaces.  For
efficiency reasons, it does not use controlled types, but takes care of
all the memory management for you in other ways.

   As a result, this library provides a secure, easy to use and
extensible toolkit.

   Compared to the C library, GtkAda provides type safety (especially
in the callbacks area), and object-oriented programming. As opposed to
common knowledge, it requires less type casting than with in C.  Its
efficiency is about the same as the C library through the use of inline
subprograms.

   GtkAda comes with a complete integration to the graphical interface
builder `Glade'(1). This makes it even easier to develop interfaces,
since you just have to click to create a window and all the dialogs.
Ada code can then be generated with a single click.

   GtkAda also has a full support for OpenGL, and comes with a very thin
binding to the OpenGL (`Mesa') libraries. You can thus create graphical
applications that display 3D graphics, and display them in a GtkAda
window, as with any other 2D graphics. This manual does not document
OpenGL at all, see any book on OpenGL, or the specification that came
with your OpenGL library, for more information.

   The following Internet sites will always contain the latest public
packages for `GtkAda', `gtk+' and `Glade'.

   `http://libre.act-europe.fr/GtkAda'

   `http://www.gtk.org'

   `http://glade.gnome.org'

   The scheme used for GtkAda's version numbers is the following: the
major version number is the same as for the underlying gtk+ library
(e.g 1.2 or 1.3). Thus, stable versions of GtkAda will have even major
numbers, and development versions (potentially less stable, although we
are trying to make sure that no big problem exists in those versions)
will have odd version numbers. The minor version numbers depends on
GtkAda's release number.

   This documentation is distributed with GtkAda version 1.2.12. At
this stage, every widget found in gtk+ 1.2 has been implemented, and
the test program found in the gtk release has been fully coded in Ada
(have a look at the `testgtk/' directory in the distribution).

   This toolkit was tested on the following systems:
   * Linux/x86

   * Linux/sparc

   * Linux/ppc

   * Solaris/sparc

   * Solaris/x86

   * Dec Unix

   * SGI IRIX 6.5

   * HP/UX

   * NT 4.0

   * Windows 2000

   * AiX 4.3.2

   * SCO UnixWare 7.1

   * FreeBSD 3.2

   with the latest version of the `GNAT' compiler, developed and
supported by Ada Core Technologies (see `http://www.gnat.com').

   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.

   This version of GtkAda is known to be compatible with `gtk+' 1.2.2 up
to version 1.2.8. This release is no longer compatible with older
versions of gtk+ (up to 1.0).

   This version of GtkAda is compatible with `Glade' version 0.5.9.
Due to some modification in the output format of Glade, this release
will not work with older versions. It is also not guaranteed to work
with more recent versions. Please update your version of Glade.

   This document does not describe all the widgets available in GtkAda,
nor does it try to explain all the subprograms. The GtkAda Reference
Manual provides this documentation instead, as well as the GtkAda
sources spec files themselves, whose extension is `.ads'.

   No complete example is provided in this documentation. Instead,
please refer to the examples that you can find in the `testgtk/' and
`examples/' directory in the GtkAda distribution, since these are more
up-to-date (and more extensive).  They are heavily commented, and are
likely to contain a lot of information that you might find interesting.

   If you are interested in getting support for GtkAda (including
priority bug fixes, early releases, help in using the toolkit, help in
designing your interface, on site consulting...), please contact ACT
Europe (`mailto:sales@act-europe.fr') or Ada Core Technologies
(`mailto:sales@gnat.com').

   ---------- Footnotes ----------

   (1) Glade was written by Damon Chaplin


File: gtkada_ug.info,  Node: Getting started with GtkAda,  Next: Hierarchical composition of a window,  Prev: Introduction,  Up: Top

Getting started with GtkAda
***************************

This chapter describes how to start a new GtkAda application. It
explains the basic features of the toolkit, and shows how to compile
and run your application.

   It also gives a brief overview of the extensive widget hierarchy
available in GtkAda.

* Menu:

* How to build and install GtkAda::
* Organization of the GtkAda package::
* How to compile an application with GtkAda::
* Architecture of the toolkit::
* Widgets Hierarchy::


File: gtkada_ug.info,  Node: How to build and install GtkAda,  Next: Organization of the GtkAda package,  Up: Getting started with GtkAda

How to build and install GtkAda
===============================

This section explains how to build and install GtkAda on your machine.
It is Unix-oriented, since GtkAda is distributed in binary format on
Windows machines, and comes with all the dependent packages, including
the gtk+ libraries and `Glade'. If you are a Windows-user, you should
skip this section.

   On Unix systems, you first need to install the glib and gtk+
libraries. Download the compatible packages from the gtk+ web site
(<http://www.gtk.org>, compile and install it.  When compiling glib,
make sure that the support for multithreading is enabled (this is the
default, and can be enforced with the `--enable-threads' and
`--with-threads' command line switches.

   Change your PATH environment variable so that the script
`gtk-config', which indicates where gtk+ was installed and what
libraries it needs is automatically found by GtkAda. You will no longer
need this script once GtkAda is installed, unless you develop part of
your application in C.

   OpenGL support will not be activated in GtkAda unless you already
have the OpenGL libraries on your systems. You can for instance look at
Mesa, which is free implementation.

   Optionally, you can also install the `Glade' interface builder. Get
the compatible package from the Glade web site, compile and install it.
The official version already knows about Ada (at least enough to call
GtkAda's own programs), so no patch is needed.

   You can finally download the latest version of GtkAda from the web
site.  Untar and uncompress the package, then simply do the following
steps:
     > ./configure
     > make install

   As usual with the `configure' script, you can specify where you want
to install the GtkAda libraries by using the `--prefix' switch.

   If you have some OpenGL libraries installed on your system, you can
make sure that `configure' finds them by specifying the
`--with-GL-prefix' switch on the command line. `configure' should be
able to automatically detect the libraries however.

   You must then make sure that the system will be able to find the
dynamic libraries at run time if your application uses them. Typically,
you would do one of the following:
   * run `ldconfig' if you installed GtkAda in one of the standard
     location and you are super-user on your machine

   * edit `/etc/ld.conf' if you are super-user but did not install
     GtkAda in one of the standard location. Add the path that contains
      libgtkada.so (by default `/usr/local/lib' or `$prefix/lib'.

   * modify your `LD_LIBRARY_PATH' environment variable if you are
     not super-user. You should simply add the path to libgtkada.


File: gtkada_ug.info,  Node: Organization of the GtkAda package,  Next: How to compile an application with GtkAda,  Prev: How to build and install GtkAda,  Up: Getting started with GtkAda

Organization of the GtkAda package
==================================

   In addition to the full sources, the GtkAda package contains a lot of
heavily commented examples. If you haven't been through those examples,
we really recommend that you look at them and try to understand them,
since they contain some examples of code that you might find
interesting for your own application.

   * `testgtk/' directory:

     This directory contains an application that tests all the widgets
     in GtkAda.  It gives you a quick overview of what can be found in
     the toolkit, as well as some detailed information on the widgets
     and their parameters.

     Each demo is associated with contextual help pointing to aspects
     worth studying.

     It also contains an OpenGL demo, if GtkAda was compiled with
     support for OpenGL.

     This program is far more extensive that its C counterpart, and the
     GtkAda team has added a lot of new examples.

   * `examples/' directory:

     This directory contains some small examples, unrelated to testgtk.
     For instance, this is where you will find some sample XML files
     for `Gate' and `Dgate', as well as some new widgets created
     directly in Ada, as examples of how to create your own callback
     marshallers.

     On the whole these examples are a little more complex than testgtk
     but, since they focus on demonstrating a precise concept, they are
     still quite easy to understand.

   * `docs/' directory:

     It contains the html, info, text and TeX versions of the
     documentation you are currently reading. Note that the
     documentation is divided into two subdirectories, one containing
     the user guide, which you are currently reading, the other
     containing the reference manual, which gives detailed information
     on all the widgets found in GtkAda. The docs directory also
     contains a subdirectory with some slides that were used to present
     GtkAda at various shows.



File: gtkada_ug.info,  Node: How to compile an application with GtkAda,  Next: Architecture of the toolkit,  Prev: Organization of the GtkAda package,  Up: Getting started with GtkAda

How to compile an application with GtkAda
=========================================

   This section explains how you can compile your own applications.
The procedure is system-dependent, and thus is divided into two
subsections.

Unix systems
------------

On Unix systems, a script called `gtkada-config' is automatically
created when you build GtkAda. This script is copied in a subdirectory
`bin/' in the installation directory.

   The easiest and recommended way to build a GtkAda application is to
use the `gnatmake' program distributed with GNAT, that takes care of
all the dependencies for you. Use the `gtkada-config' to specify where
GtkAda and gtk+ libraries have been installed.

     > gnatmake <main-file> `gtkada-config`

   Note the use of back-ticks around gtkada-config, which force the
shell to evaluate the script and put the output on the command line.

   However, on complex systems, gnatmake might not be enough. Users
frequently like to create `Makefile's. The script `gtkada-config'
remains useful in that case, since you can call it from your Makefile
(same syntax as above with the back-ticks) to create variables like
FLAGS and LIBS. See the switches of `gtkada-config' below for more
information.

   The script `gtkada-config' understands the following command line
switches (chosen to be compatible with the ones set by `gtk-config'):

   * `--cflags': Output only the compiler flags, i.e the  include
     directories where the GtkAda spec files are found. This should be
     used   if you only want to compile your files, but do not want to
     bind or link   them.

   * `--libs': Output only the switches for the linker. This lists
     the directories where all the GtkAda, gtk+, and dependant
     libraries are   found. For instance, if GtkAda was compiled with
     support for OpenGL,   the OpenGL libraries will automatically be
     present.

   * `--static': Forces the libraries to be static libraries instead
     of dynamic ones.

Windows systems
---------------

   Things are somewhat easier on Windows systems. You don't have access
to the `gtkada-config' script. However, the good news is that you also
don't have to specify which libraries to use or where to find them.

   The only thing you should specify on the `gnatmake' command line is
where the GtkAda spec files are found, as in:

     > gnatmake <main-file> -Ic:\GtkAda\lib

   if GtkAda was installed in `c:\GtkAda'.

   No static libraries are provided currently, so you can't create a
static version of your application and you will have to use the dynamic
libraries.


File: gtkada_ug.info,  Node: Architecture of the toolkit,  Next: Widgets Hierarchy,  Prev: How to compile an application with GtkAda,  Up: Getting started with GtkAda

Architecture of the toolkit
===========================

The gtk+ toolkit has been designed from the beginning to be portable.
It is made of three libraries, `gtk', `gdk' and `glib'.

   `Glib' is a non-graphical library, that includes support for lists,
h-tables, threads, etc... It is a highly optimized,
platform-independent library. Since most of its contents are already
available in Ada (or in the `GNAT.*' hierarchy in the GNAT
distribution), GtkAda does not include a binding to it, except for a few
required packages. These are the `Glib.*' packages in the GtkAda
distribution.

   `Gdk' is the platform-dependent part of gtk+. Its implementation is
completely different on win32 systems and X11 systems, although the
interface is of course the same. It provides a set of functions to draw
lines, rectangles and pixmaps on the screen, manipulate colors, etc...
It has a complete equivalent in GtkAda, through the `Gdk.*' packages.

   `Gtk' is the top level library. It is platform independent, and does
all its drawing through calls to Gdk. This is where the high-level
widgets are defined. It also includes support for callbacks. Its
equivalent in the GtkAda libraries are the `Gtk.*' packages. It is made
of a fully object-oriented hierarchy of widgets (see *Note Widgets
Hierarchy::).

   Since your application only calls GtkAda, it is fully portable, and
can be recompiled as-is on other platforms.

     +---------------------------------------------+
     |             Your Application                |
     +---------------------------------------------+
     |                 GtkAda                      |
     |               +-----------------------------+
     |               |            GTK              |
     |       +-------+-----------------------------+
     |       |           GDK                       |
     +-------+--------------+--+-------------------+
     |          GLIB        |  | X-Window / Win32  |
     +----------------------+  +-------------------+

   Although the packages have been evolving a lot since the first
versions of GtkAda, the specs are stabilizing now. We will try as much
as possible to provide backward compatibility whenever possible.

   Since GtkAda is based on gtk+ we have tried to stay as close to it
as possible while using high-level features of the Ada95 language. It is
thus relatively easy to convert external examples from C to Ada.

   We have tried to adopt a consistent naming scheme for Ada
identifiers:
   * The widget names are the same as in C, except that an underscore
     sign (_) is used to separate words, e.g
          Gtk_Button   Gtk_Color_Selection_Dialog

   * Because of a clash between Ada keywords and widget names, there
     are two exceptions to the above general rule:
          Gtk.GEntry.Gtk_Entry   Gtk.GRange.Gtk_Range

   * The function names are the same as in  C, ignoring the leading
     `gtk_' and the widget name, e.g
          gtk_misc_set_padding        =>  Gtk.Misc.Set_Padding
          gtk_toggle_button_set_state =>  Gtk.Toggle_Button.Set_State

   * Most enum types have been grouped in the `gtk-enums.ads' file

   * Some features have been implemented as generic packages. These are
     the timeout functions (see Gtk.Main.Timeout), the idle functions
     (see Gtk.Main.Idle), and the data that can be attached to any
     object (see Gtk.Object.User_Data). Type safety is ensured through
     these generic packages.

   * Callbacks were the most difficult thing to interface with. These
     are extremely powerful and versatile, since the callbacks can have
     any number of arguments, can return values, or not,etc... These
     are once again implemented as generic packages, that require more
     explanation (*note Signal handling::).


   WARNING: all the generic packages allocate some memory for internal
structures, and call internal functions. This memory is freed by gtk
itself, by calling some Ada functions. Therefore 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.

   WARNING Before any other call to the GtkAda library is performed,
`Gtk.Main.Init' must be invoked first. Most of the time, this procedure
is invoked from the main procedure of the application, in which case no
use of GtkAda can be done during the application elaboration.


File: gtkada_ug.info,  Node: Widgets Hierarchy,  Prev: Architecture of the toolkit,  Up: Getting started with GtkAda

Widgets Hierarchy
=================

All widgets in `GtkAda' are implemented as tagged types. They all have
a common ancestor, called `Gtk.Object.Gtk_Object'. All visual objects
have a common ancestor called `Gtk.Widget.Gtk_Widget'.

   The following table describes the list of objects and their
inheritance tree. As usual with tagged types, all the primitive
subprograms defined for a type are also known for all of its children.
This is a very powerful way to create new widgets, as will be explained
in *Note Creating new widgets in Ada::.

   Although gtk+ was written in C its design is object-oriented, and
thus GtkAda has the same structure. The following rules have been
applied to convert from C names to Ada names: a widget `Gtk_XXX' is
defined in the Ada package `Gtk.XXX', in the file `gtk-xxx.ads'. This
follows the GNAT convention for file names.  For instance, the
`Gtk_Text' widget is defined in the package `Gtk.Text', in the file
`gtk-text.ads'.

   Note also that most of the documentation for GtkAda is found in the
spec files themselves.

   It is important to be familiar with this hierarchy. It is then
easier to know how to build and organize your windows. Most widgets are
demonstrated in the `testgtk/' directory in the GtkAda distribution.

Gtk_Object
  +-- Gtk_Data
  |     +-- Gtk_Tooltips
  |     \__ Gtk_Adjustment
  \__ Gtk_Widget  @i{(Visual widgets)}
        +-- Gtk_Calendar
        +-- Gtk_Container  @i{(Widgets that have children)}
        |     +-- Gtk_Bin  @i{(Widgets that have a single child)}
        |     |     +-- Gtk_Alignment
        |     |     +-- Gtk_Button @i{(Widgets that you can click)}
        |     |     |     +-- Gtk_Option_Menu
        |     |     |     +-- Gtk_Toggle_Button
        |     |     |     |     \__ Gtk_Check_Button
        |     |     |     |           \__ Gtk_Radio_Button
        |     |     +-- Gtk_Event_Box
        |     |     +-- Gtk_Frame
        |     |     |     \__ Gtk_Aspect_Frame
        |     |     +-- Gtk_Handle_Box
        |     |     +-- Gtk_Invisible
        |     |     +-- Gtk_Item
        |     |     |     +-- Gtk_List_Item
        |     |     |     +-- Gtk_Menu_Item
        |     |     |     |     +-- Gtk_Check_Menu_Item
        |     |     |     |     |     \__ Gtk_Radio_Menu_Item
        |     |     |     |     \__ Gtk_Tearoff_Menu_Item
        |     |     |     \__ Gtk_Tree_Item
        |     |     +-- Gtk_Viewport
        |     |     \__ Gtk_Window  @i{(Have an independent window)}
        |     |           +-- Gtk_Color_Selection_Dialog
        |     |           +-- Gtk_Dialog
        |     |           |     \__ Gtk_Input_Dialog
        |     |           +-- Gtk_File_Selection
        |     |           +-- Gtk_Font_Selection_Dialog
        |     |           \__ Gtk_Plug
        |     +-- Gtk_Box  @i{(Widgets that have one or more children)}
        |     |     +-- Gtk_Button_Box
        |     |     |     +-- Gtk_Vbutton_Box
        |     |     |     \__ Gtk_Hbutton_Box
        |     |     +-- Gtk_Color_Selection
        |     |     +-- Gtk_Combo
        |     |     +-- Gtk_Gamma_Curve
        |     |     \__ Gtk_Status_Bar
        |     +-- Gtk_Clist
        |     |     \__ Gtk_Ctree
        |     +-- Gtk_Fixed
        |     +-- Gtk_Layout
        |     +-- Gtk_List
        |     +-- Gtk_Menu_Shell
        |     |     +-- Gtk_Menu
        |     |     \__ Gtk_Menu_Bar
        |     +-- Gtk_Notebook
        |     |     \__ Gtk_Font_Selection
        |     +-- Gtk_Packer
        |     +-- Gtk_Paned
        |     +-- Gtk_Scrolled_Window
        |     +-- Gtk_Socket
        |     +-- Gtk_Toolbar
        |     +-- Gtk_Table
        |     \__ Gtk_Tree
        +-- Gtk_Drawing_Area
        |     \__ Gtk_Curve
        +-- Gtk_Editable
        |     +-- Gtk_Entry
        |     |     \__ Gtk_Spin_Button
        |     \__ Gtk_Text
        +-- Gtk_Misc
        |     +-- Gtk_Arrow
        |     +-- Gtk_Image
        |     +-- Gtk_Label
        |     |     +-- Gtk_Accel_Label
        |     |     \__ Gtk_Tips_Query
        |     \__ Gtk_Pixmap
        +-- Gtk_Preview
        +-- Gtk_Progress
        |     \__ Gtk_Progress_Bar
        +-- Gtk_Range
        |     +-- Gtk_Scale
        |     \__ Gtk_Scrollbar
        +-- Gtk_Ruler
        \__ Gtk_Separator
                 *Hierarchy of widgets in GtkAda*


File: gtkada_ug.info,  Node: Hierarchical composition of a window,  Next: Signal handling,  Prev: Getting started with GtkAda,  Up: Top

Hierarchical composition of a window
************************************

Interfaces in GtkAda are built in layers, as in Motif.  For instance, a
typical dialog is basically a Gtk_Window, that in turn contains a
Gtk_Box, itself divided into two boxes and a Gtk_Separator, and so on.

   Altough this may seem more complicated than setting absolute
positions for children, this is the simplest way to automatically
handle the resizing of windows. Each container that creates a layer
knows how it should behave when it is resized, and how it should move
its children.  Thus almost everything is handled automatically, and you
don't have to do anything to support resizing.

   If you really insist on moving the children to a specific position,
look at the `Gtk_Fixed' widget and its demo in `testgtk/'. But you
really should not use this container, since you will then have to do
everything by hand.

   All the containers are demonstrated in `testgtk/', in the GtkAda
distribution. This should help you understand all the parameters
associated with the containers. It is very important to master these
containers, since using the appropriate containers will make building
interfaces a lot easier.

   If you look at the widget hierarchy (*note Widgets Hierarchy::), you
can see that a Gtk_Window inherits from Gtk_Bin, and thus can have only
one child. In most cases, the child of a Gtk_Window will thus be a
Gtk_Box, which can have any number of children.

   Some widgets in GtkAda itself are built using this strategy, from the
very basic `Gtk_Button' to the more advanced `Gtk_File_Selection'.

   For example, by default a Gtk_Button contains a Gtk_Label, which
displays the text of the button (like "OK" or "Cancel").

   However, it is easy to put a pixmap in a button instead. When you
create the button, do not specify any label. Thus, no child will be
added, and you can give it your own. See `testgtk/create_pixmap.adb'
for an example on how to do that.


File: gtkada_ug.info,  Node: Signal handling,  Next: Starting an application with GtkAda,  Prev: Hierarchical composition of a window,  Up: Top

Signal handling
***************

In GtkAda, the interaction between the interface and the core
application is done via signals. Most user actions on the graphical
application trigger some signals to be `emitted'.

   A signal is a message that an object wants to broadcast. It is
identified by its name, and each one is associated with certain events
which happen during the widget's lifetime. For instance, when the user
clicks on a Gtk_Button, a "clicked" signal is emitted by that
button.More examples of signals can be found in the GtkAda reference
manual.

   It is possible to cause the application to react to such events by
`connecting' to a signal a special procedure called a `handler' or
`callback'.  This handler will be called every time that signal is
emitted, giving the application a chance to do any processing it needs.
More than one handler can be connected to the same signal on the same
object; the handlers are invoked in the order they were connected.

   Depending on their type, the widgets define zero (e.g `Gtk_Label'),
one or several different signals. Of course, the signals, as every
thing else, are inherited from the parents, thus every widget answers
to a lot of signals.

   The easiest way to find out what signals can be emitted by a widget
is to look at the GtkAda reference manual. Hopefully, every widget will
finally be documented there. That document explains when the signal is
emitted, and the general form that handlers should have (although you
can always add a User_Data is you wish).

   In the meantime, you can also look directly at the C header files,
distributed with the gtk+ library. Each widget is described in its own C
file and has two C structures associated with it. One of them is the
"class" structure, and contains a series of pointers to functions. Each
of these functions has the same name as the signal name.

   For instance, consider the following extract from gtkbutton.h:
     struct _GtkButtonClass
     {
       GtkBinClass        parent_class;
     
       void (* pressed)  (GtkButton *button);
       void (* released) (GtkButton *button);
       void (* clicked)  (GtkButton *button);
       void (* enter)    (GtkButton *button);
       void (* leave)    (GtkButton *button);
     };

   This means that the Gtk_Button widget redefines five new signals,
called respectively `"pressed"', `"release"', ...

   The profile of the handler can also be deduced from those pointers:
The handler has the same arguments, plus an optional User_Data parameter
that can be used to pass any kind of data to the handler.  When the
User_Data parameter is used, the value of this data is specified when
connecting the handler to the signal. It is then given back to the
handler when the signal is raised.

   Therefore, the profile of a handler should look like:
     procedure Pressed_Handler
       (Button    : access Gtk_Button_Record'Class;
        User_Data : ...);

   The callback does not need to use all the arguments. It is legal to
use a procedure that "drops" some of the last arguments.  The User_Data
is a special case, since you decide at connection time whether you want
it or not. If you decided to have it then you callback must accept it,
and this is checked by the compiler.

   Any number of arguments can be dropped as long as those arguments are
the last ones in the list and you keep the first one. For instance, the
signal "button_press_event" normally can be connected to a handler with
any of the following profiles:

     --  with a user_data
     procedure Handler
       (Widget    : access Gtk_Widget_Record'Class;
        Event     : Gdk.Event.Gdk_Event;
        User_Data : ...);
     procedure Handler
       (Widget    : access Gtk_Widget_Record'Class;
        User_Data : ...);
     
     --  without a user_data
     procedure Handler
       (Widget : access Gtk_Widget_Record'Class;
        Event  : Gdk.Event.Gdk_Event);
     procedure Handler (Widget : access Gtk_Widget_Record'Class);

   Beware that adding new arguments is not possible, since no value
would be provided for them. When connecting a handler GtkAda will not
always verify that your handler does not have more arguments than
expected, so caution is recommended (it only does so if you use the
`Gtk.Marshallers' package, see below).

   All the signal-handling work is performed by using the services
provided by the Gtk.Handlers package. This package is completely
self-documented, so please check the documentation for this package
either in the GtkAda Reference Manual or in the specifications
themselves.

   Here is a commented example of how to use it; the complete example
can be found in create_file_selection.adb (inside the testgtk/
directory). Let's imagine that an application opens a file selector to
allow the user to select a file.  GtkAda provides a high-level widget
called Gtk_File_Selection which can be used in this case:

     declare
        Window : Gtk_File_Selection;
     begin
        Gtk.File_Selection.Gtk_New (Window, Title => "Select a file");
     end;

   When the "OK" button is pressed, the application needs to retrieve
the file selected and then close the dialog. All we need to know in that
procedure is what widget to operate on. This can be achieved by the
following handler:

     procedure OK (Files : access Gtk_File_Selection_Record'Class) is
     begin
        Ada.Text_IO.Put_Line ("Selected " & Get_Filename (Files));
        --  Prints the name of the selected file.
        Destroy (Files);
        --  Destroys the file selector dialog
     end Ok;

   We now need to connect the object we created in the first part and
this new callback we just defined. As documented in the reference
manual, Gtk.Handlers defines four types of generic packages, depending
on the arguments one expects in the callback and whether the callback
returns a value or not. Note that you can not arbitrarily choose to
return a value, this depends on the signal, as explained above.

   In our case, since our callback does not return any value and does
not have any User_Data (ie we don't need to pass it extra values,
defined at connection time), the appropriate package is
Gtk.Handlers.Callback.

   We thus instantiate that package. Once again, remember that the
generic packages in GtkAda need to be present in memory at all time,
since they take care of freeing the memory they are using when
finished. They must be instantiated at library level and not inside a
subprogram.

     package Files_Cb is new
       Handlers.Callback (Gtk_File_Selection_Record);

   As you can see in `Gtk.Handlers', this package now provides a set of
Connect subprograms than can be used to establish a permanent tie
between a widget and a handler. It also provides a set of other
subprograms which one can use to emit the signals manually, although
most of the time the signals are simply emitted internally by GtkAda. We
will not discuss the Emit_By_Name subprograms here.

   The general form of handler, as used in `Gtk.Handlers', expects some
handlers that take two or three arguments: the widget on which the
signal was applied, an array of all the extra arguments sent internally
by GtkAda, and possibly some user data given when the connection was
made.

   This is the most general form of handler and it covers all the
possible cases. However, it also expects the user to manually extract
the needed values from the array of arguments. This is not always the
most convenient solution. This is why GtkAda provides a second package
related to signals, `Gtk.Marshallers'.

   This package provides a set of functions that can be used as
callbacks directly for GtkAda, and that will call your own handlers
after extracting the required values from the array of arguments.
Although this might sound a little bit complicated, this is in fact a
very powerful mechanism, in fact similar to what is done internally by
gtk+ in C. This does not add any overhead compared to C programs, since
we do basically the same thing but at the Ada level.

   A set of functions `To_Marshaller' is found in every generic package
in `Gtk.Handlers'. They take a single argument, the name of the function
you want to call, and return a handler that can be used directly in
`Connect'.

   The connection is then done with the following piece of code. Note
that this can be done just after creating the widget, in the same
block. As soon as it is created, a widget is ready to accept
connections (although no signals will be emitted before the widget is
shown on the screen).

   Note the two following things: we use `To_Marshaller' since our
handler does not accept the array of arguments as a parameter, and we
use the special `Object_Connect' procedure. This means that the
parameter to our callback (Files) will be the Slot_Object given in
Object_Connect, instead of being the button itself.

     Files_Cb.Object_Connect
       (Get_Ok_Button (Window),  --  The object to connect to the handler
        "clicked",               --  The name of the signal
        Files_Cb.To_Marshaller (Ok'Access),  --  The signal handler
        Slot_Object => Window);


File: gtkada_ug.info,  Node: Starting an application with GtkAda,  Next: Resource files,  Prev: Signal handling,  Up: Top

Starting an application with GtkAda
***********************************

   You need to perform some initializations to start a GtkAda
application:
     --  predefined units of the library
     with Gtk.Rc;
     with Gtk.Main;
     with Gtk.Enums;
     with Gtk.Window;
     ...
     --  My units
     with Callbacks;
     ...
     procedure Application is
        procedure Create_Window is ...
     
     begin
        --  Set the locale specific datas (e.g time and date format)
        Gtk.Main.Set_Locale;
     
        --  Initializes GtkAda
        Gtk.Main.Init;
     
        --  Load the resources. Note that this part is optional.
        Gtk.Rc.Parse ("application.rc");
     
        --  Create the main window
        Create_Window;
     
        --  Signal handling loop
        Gtk.Main.Main;
     end Application;

   the `Create_Window' procedure looks like

        procedure Create_Window is
           Main_Window : Gtk.Window.Gtk_Window;
           ...
        begin
           Gtk.Window.Gtk_New
             (Window   => Main_Window,
              The_Type => Gtk.Enums.Window_Toplevel);
     
           --  From Gtk.Widget:
           Gtk.Window.Set_Title (Window => Main_Window, Title  => "Editor");
     
           --  Construct the window and connect various callbacks
     
           ...
           Gtk.Window.Show_All (Main_Window);
        end Create_Window;


File: gtkada_ug.info,  Node: Resource files,  Next: Memory management,  Prev: Starting an application with GtkAda,  Up: Top

Resource files
**************

   Resource files let you parametize aspects of the widgets in a GtkAda
application without having to recompile it.

   A resource file needs to be loaded (`Gtk.Rc.Parse') BEFORE setting
the corresponding window.

   In this file, it is possible to specify the visual characteristics
of the widgets (colors, fonts, ...).  Under X, the `xfontsel' command
allows you to easily select a font.  The FontSelection widget is also a
simple way to select fonts.

   Here is an example of a resource file:
     # application.rc
     #
     # resource file for "Application"
     
     # Buttons style
     style "button"
     {
     # BackGround Colors
     #                  Red  Green  Blue
       bg[PRELIGHT] = { 0.0,  0.75, 0.0 } # Green when the mouse is on
                                          # the button
       bg[ACTIVE]   = { 0.75, 0.0,  0.0 } # Red on click
     # ForeGround Colors
     #                  Red  Green  Blue
       fg[PRELIGHT] = { 1.0,  1.0,  1.0 } # White when the mouse is on
                                          # the button
       fg[ACTIVE]   = { 1.0,  1.0,  1.0 } # White on click
     }
     
     # All the buttons will have the style "button"
     widget_class "*GtkButton*" style "button"
     
     # Text style
     style "text"
     {
       font = "-adobe-courier-medium-r-normal-*-15-*-*-*-*-*-*-*"
       text[NORMAL] = { 0.0, 0.0, 0.0 } # black
       fg[NORMAL]   = { 0.0, 0.0, 0.0 } # black
       base[NORMAL] = { 1.0, 1.0, 1.0 } # white : background color
     }
     
     # All Gtk_Text will have the "text" style
     widget_class "*GtkText" style "text"


File: gtkada_ug.info,  Node: Memory management,  Next: Tasking with GtkAda,  Prev: Resource files,  Up: Top

Memory management
*****************

   GtkAda takes care of almost all the memory management for you.  Here
is a brief overview of how this works, you'll have to check the sources
if you want more detailed information.  Gtk+ (the C library) does its
own memory management through reference counting, i.e. any widget is
destroyed when it is no longer referenced anywhere in the application.

   In GtkAda itself, a "user_data" is associated with each object
allocated by a `Gtk_New' procedure. A "destroy" callback is also
associated to be called when the object to which the user_data belongs
is destroyed (see Gtk.Initialize_User_Data).  Thus, every time a C
object is destroyed, the equivalent Ada structure is also destroyed
(see Gtk.Free_User_Data).

   Concerning widgets containing children, every container holds a
reference to its children, whose reference counting is thus different
from 0 (and generally 1). When the container is destroyed, the
reference of all its children and grand-children is decremented, and
they are destroyed in turn if needed. So the deallocation of a widget
hierarchy is also performed automatically.


File: gtkada_ug.info,  Node: Tasking with GtkAda,  Next: Object-oriented features,  Prev: Memory management,  Up: Top

Tasking with GtkAda
*******************

   The Glib library can be used in a task-safe mode by calling
Gdk.Thread.Init before making any other Glib calls. In this mode Glib
automatically locks all internal data structures as needed. This does
not mean that two tasks can simultaneously access, for example, a
single hash table, but they can access two different hash tables
simultaneously. If two different tasks need to access the same hash
table, the application is responsible for locking itself (e.g by using
protected objects).

   When Glib is initialized to be task-safe, GtkAda is task aware.
There is a single global lock that you must acquire with
Gdk.Threads.Enter before making any Gdk/Gtk call, and which you must
release with Gdk.Threads.Leave afterwards.

   Thus, Gtk.Main.Main should be called with the lock acquired (see
example below), ensuring that all the functions executed in the task
that started the main loop do not need to protect themselves again.

   Beware that the GtkAda main loop (Gtk.Main.Main) can only be be run
inside one specific task. In other words, you cannot call Gtk.Main.Main
from any task other than the one that started the outer level main loop.

   Note that Gdk.Threads assumes that you are using a tasking run time
that maps Ada tasks to native threads. For example under Linux with
GNAT, you need to change the default tasking run time for that purpose.

   A minimal main program for a tasking GtkAda application looks like:

     with Gdk.Threads;
     with Gtk.Main;
     with Gtk.Enums; use Gtk.Enums;
     with Gtk.Window; use Gtk.Window;
     
     procedure GtkAda_With_Tasks is
        Window : Gtk_Window;
     begin
        Gdk.Threads.Init;
        Gtk.Main.Init;
     
        Gtk_New (Window, Window_Toplevel);
        Show (Window);
     
        Gdk.Threads.Enter;
        Gtk.Main.Main;
        Gdk.Threads.Leave;
     end GtkAda_With_Tasks;

   Callbacks require a bit of attention. Callbacks from GtkAda
(signals) are made within the GtkAda lock. However, callbacks from Glib
(timeouts, IO callbacks, and idle functions) are made outside of the
GtkAda lock. So, within a signal handler you do not need to call
Gdk.Threads.Enter, but within the other types of callbacks, you do.


File: gtkada_ug.info,  Node: Object-oriented features,  Next: Support for Glade the Gtk GUI builder,  Prev: Tasking with GtkAda,  Up: Top

Object-oriented features
************************

   GtkAda has been designed from the beginning to provide a full Object
oriented layer over gtk+. This means that features such as type
extension, dynamic dispatching, ... are made available through the
standard Ada language.

   This section will describe both how things work and how you can
extend existing widgets or even create your own.

* Menu:

* General description of the tagged types::
* Using tagged types to extend Gtk widgets::
* Creating new widgets in Ada::


File: gtkada_ug.info,  Node: General description of the tagged types,  Next: Using tagged types to extend Gtk widgets,  Up: Object-oriented features

General description of the tagged types
=======================================

Why should I use object-oriented programing ?
---------------------------------------------

   Every widget in GtkAda is a tagged type and has a number of
primitive subprograms which are known to all its children.

   This means that, as opposed to what you see in C code, you don't have
(well most of the time you don't) to explictly cast types and, even
when you have to, Ada always makes sure that the conversion is valid.

   Thus your programs are much safer and most errors are found at
compile time, as is usually the case with Ada.

   For instance, if you create a table, put some widgets in it, and
then, later in your program, try to access those widgets, then you do
not need to know beforehand what their type is, when and by whom they
were created, ... You simply ask for the children of the table, and you
get in return a tagged type that contains all the information you need.
You can even use dynamic dispatching without ever having to cast to a
known type.

   This makes GtkAda a very powerful tool for designing graphical
interfaces.

   If you think one of the standard widgets is nice, but would be even
better if it was drawing itself in a slighlty different way, of if it
could contain some other data that you need in your application, there
is a very simple way to do it: just create a new type that extends the
current one (see the section *Note Using tagged types to extend Gtk
widgets:: below.

   Maybe you want to create your own brand new widget, that knows how
to draw itself, how to react to events, ... and you want to be able to
reuse it anytime you need ? Once again, using the standard Ada
features, you can simply create a new tagged type and teach it how to
interact with the user.  See the section *Note Creating new widgets in
Ada:: below.

Type conversions from C to Ada widgets
--------------------------------------

   There are basically three kinds of widgets that you can use with
GtkAda:
   * Ada widgets: These are widgets that are written directly in Ada,
     using the object oriented features of GtkAda

   * Standard widgets: These are the widgets that are part of the
     standard gtk+ and GtkAda distributions. This include all the basic
     widgets you need to build advanced interfaces.

   * imported C widgets These are widgets that were created in C, and
     for which you (or someone else) created an Ada binding. This is
     most probably the kind of widgets you will have if you want to use
     third party widgets.

   GtkAda will always be able to find and/or create a valid tagged type
in the first case, no matter if you explicitly created the widget or if
it was created automatically by gtk+. For instance, if you created a
widget in Ada, put it in a table, and later on extracted it from the
table, then you will still have the same widget.

   There are two issues: if the widget was explictly created by you, or
at least by GtkAda, then it will always be and remain associated with a
correct Ada type.

   If the widget was created implicitly (for instance every time you
create a Gtk_Button, a Gtk_Label is also created for the text
displayed), then GtkAda will only be able to create the corresponding
type by default for the following widgets: Gtk_Label, Gtk_Button,
Gtk_Item, Gtk_List_Item, Gtk_Menu_Item, Gtk_Check_Menu_Item,
Gtk_Radio_Menu_Item, Gtk_Tearoff_Menu_Item and Gtk_Tree_Item.  For
other widgets, it will instead create a Gtk_Widget, and you will have
to either call Gtk.Unchecked_Cast to convert it back to the type you
expect, or use Gtk.Type_Conversion as described below. Here is an
example of use of Gtk.Unchecked_Cast:

     declare
        Stub : Gtk_Window_Record;
     begin
        Window := Gtk.Unchecked_Cast (Widget, Stub);
     end;

   In the third case (imported C widgets), GtkAda is not, by default,
able to create the corresponding Ada type.

   The solution we suggest to solve these two issues is to 'with' the
Gtk.Type_Conversion unit. In that case, every standard widget, no
matter who created them, will always be correctly converted to an
appropriate Ada type.  So, basically, if you put the following in your
main unit:

     with Gtk.Type_Conversion;
     
     begin
        Gtk.Main.Init;
        Gtk.Type_Conversion.Init;
        ...
     end

   then you can safely get the children of any widget (table, boxes,
...) and be sure you have the right Ada type. You won't need to
explictly convert your widget to something else.

   However, 'with'ing this unit means that your application will depend
on every package of GtkAda, which is a little bit heavier, and explains
why this is not the default. We do recommend you use it if it is not
extremely important whether your application depends on all the
packages of GtkAda.

   The case of imported C widgets is a little bit trickier. Since
GtkAda does not know anything about them when it is built, it can't
magically convert the C widgets to Ada widgets. This is your job to
teach GtkAda how to do the conversion.

   We thus provide a 'hook' function which you need to modify. This
function is defined in the package Gtk.Type_Conversion. It is a
function that takes a string with the name of the C widget (ex/
"GtkButton"), and expects a newly allocated pointer in return. If you
don't know this type either, simply return null.


File: gtkada_ug.info,  Node: Using tagged types to extend Gtk widgets,  Next: Creating new widgets in Ada,  Prev: General description of the tagged types,  Up: Object-oriented features

Using tagged types to extend Gtk widgets
========================================

   Since version 0.6 of this toolkit, it is possible to associate your
own data with existing widgets simply by creating new types. This
section will show you a simple example, but you should rather read the
source code in testgtk/ where we used this feature instead of using
`user_data' as is used in the C version.

     type My_Button_Record is new Gtk_Button_Record with record
         --  whatever data you want to associate with your button
     end record;
     type My_Button is access all My_Button_Record'Class;

   With the above statements, your new type is defined. Every function
available for `Gtk_Button' is also available for `My_Button'.  Of
course, as with every tagged type in Ada, you can create your own
primitive functions with the following prototype:

     procedure My_Primitive_Func (Myb : access My_Button_Record);

   To instanciate an object of type `My_Button' in your application, do
the following:

     declare
        Myb : My_Button;
     begin
        Myb := new My_Button_Record;
        Initialize (Myb);   --  from Gtk.Button
     end;

   The first line creates the Ada type, whereas the `Initialize' call
actually creates the C widget and associates it with the Ada type.

