40
40
GtkAda User's Guide
42
GtkAda, the Ada 95 graphical toolkit
42
GtkAda, the Ada graphical toolkit
44
44
Version @value{GtkAdaVersion}
46
Date: $Date: 2006/06/20 07:37:33 $
46
Date: $Date: 2008-06-03 14:24:10 +0200 (Tue, 03 Jun 2008) $
48
48
Copyright @copyright{} 1998-2000, Emmanuel Briot, Joel Brobecker, Arnaud Charlet
50
Copyright @copyright{} 2000-2005, AdaCore
50
Copyright @copyright{} 2000-2008, AdaCore
52
52
This document may be copied, in whole or in part, in any form or by any
53
53
means, as is or with alterations, provided that (1) alterations are clearly
136
137
The following Internet sites will always contain the latest public
137
138
packages for @code{GtkAda}, @code{gtk+} and @code{Glade}.
139
@uref{http://libre.act-europe.fr/GtkAda}
141
@uref{http://www.gtk.org}
143
@uref{http://glade.gnome.org}
140
@uref{http://libre.act-europe.fr/GtkAda/}
142
@uref{http://www.gtk.org/}
144
@uref{http://glade.gnome.org/}
146
147
The scheme used for GtkAda's version numbers is the following: the major
147
148
and minor version number is the same as for the underlying gtk+ library
149
150
The micro version number depends on GtkAda's release number.
151
152
This toolkit was tested on the following systems:
153
154
@item GNU Linux/x86
154
155
@item GNU Linux/x86-64
155
157
@item Solaris/sparc
158
@item Windows XP/Vista/2003
161
161
with the latest version of the @code{GNAT} compiler, developed and supported by
162
162
Ada Core Technologies (see @uref{http://www.adacore.com}).
164
This version of GtkAda is known to be compatible with @code{gtk+} @b{2.8.x}.
164
This version of GtkAda is known to be compatible with @code{gtk+} @b{2.12.x}.
165
165
This release may or may not be compatible with older versions of gtk+.
167
167
This version of GtkAda is compatible with @code{Glade} @b{version
241
242
Untar and uncompress the package, then simply do the following
247
$ make tests (this step is optional)
246
249
@end smallexample
248
251
As usual with the @code{configure} script, you can specify where you want
249
252
to install the GtkAda libraries by using the @code{--prefix} switch.
254
You can specify the switch @code{--disable-shared} to prevent building
255
shared libraries, even if your system supports them (by default, both
256
shared and static libraries are installed). By default, your application
257
will be linked statically with the GtkAda libraries. You can override this
258
default by specifying @code{--enable-shared} as a switch to @code{configure},
259
although you can override it later through the LIBRARY_TYPE scenario
251
262
If you have some OpenGL libraries installed on your system, you can make
252
263
sure that @code{configure} finds them by specifying the
253
264
@code{--with-GL-prefix} switch on the command line. @code{configure}
277
288
$ export FONTCONFIG_FILE=/opt/gtk/etc/fonts/fonts.conf
278
289
@end smallexample
291
@c ---------------------------------------------------------------------
292
@node How to distribute a GtkAda application
293
@section How to distribute a GtkAda application
294
@c ---------------------------------------------------------------------
297
Since GtkAda depends on Gtk+, you usually need to distribute some Gtk+
298
libraries along with your application.
300
Under some OSes such as Linux, Gtk+ comes preinstalled, so in this case,
301
a simple solution is to rely on the preinstalled Gtk+ libraries. See
302
below for more information on the gtkada library itself.
304
Under other unix systems, GtkAda usually comes with a precompiled set of Gtk+
305
libraries that have been specifically designed to be easily redistributed.
307
In order to use the precompiled Gtk+ binaries that we distribute
308
with GtkAda, you need to do distribute all the Gtk+ .so libraries along
309
with your application, and use the LD_LIBRARY_PATH environment variable to
310
point to these libraries.
312
The list of libraries needed is @file{<gtkada-prefix>/lib/lib*.so.?}
313
along with your executable, and set LD_LIBRARY_PATH.
315
By default you will also need the @file{libgtkada-xxx.so} file. This dependency
316
is optional since gtkada supports both static and dynamic linking, so
317
by e.g. using @code{gtkada-config --static} or by using
318
@file{gtkada_static.gpr}, you will end up linking with @file{libgtkada.a}.
320
Under Windows, you need to distribute the following files and directories
321
along with your application, and respect the original directory set up:
324
@item @file{bin/*.dll}
326
@item @file{lib/gtk-2.0}
280
329
@c ----------------------------------------------------------------------
281
330
@node Organization of the GtkAda package
282
331
@section Organization of the GtkAda package
283
332
@c ----------------------------------------------------------------------
285
335
In addition to the full sources, the GtkAda package contains a lot of
286
336
heavily commented examples. If you haven't been through those examples, we
287
337
really recommend that you look at them and try to understand them, since
1304
1362
GtkAda will always be able to find and/or create a valid tagged type in
1305
the first case, no matter if you explicitly created the widget or if it
1363
the first two cases, no matter if you explicitly created the widget or if it
1306
1364
was created automatically by gtk+. For instance, if you created a widget
1307
1365
in Ada, put it in a table, and later on extracted it from the table, then you
1308
1366
will still have the same widget.
1310
There are two issues: if the widget was explictly created by you,
1311
or at least by GtkAda, then it will always be and remain associated with a
1314
If the widget was created implicitly (for instance every time you
1315
create a Gtk_Button, a Gtk_Label is also created for the text displayed), then
1316
GtkAda will only be able to create the corresponding type by default for the
1317
following widgets: Gtk_Label, Gtk_Button, Gtk_Item, Gtk_List_Item,
1318
Gtk_Menu_Item, Gtk_Check_Menu_Item, Gtk_Radio_Menu_Item, Gtk_Tearoff_Menu_Item,
1319
Gtk_Tree_Item and Gtk_Entry.
1320
For other widgets, it will instead create a Gtk_Widget, and you will have
1321
to either call Gtk.Unchecked_Cast to convert it back to the type you expect,
1322
or use @b{Gtk.Type_Conversion} as described below. Here is an example of
1323
use of Gtk.Unchecked_Cast:
1327
Stub : Gtk_Window_Record;
1329
Window := Gtk.Unchecked_Cast (Widget, Stub);
1333
1368
In the third case (third party C widgets), GtkAda is not, by default, able to
1334
1369
create the corresponding Ada type.
1336
The solution we suggest to solve the first issue is to 'with' the
1337
@b{Gtk.Type_Conversion} unit. In that case, every standard widget, no matter who
1338
created them, will always be correctly converted to an appropriate Ada type.
1339
So, basically, if you put the following in your main unit:
1342
@b{with} Gtk.Type_Conversion;
1350
then you can safely get the children of any widget (table, boxes, ...) and be
1351
sure you have the right Ada type. You won't need to explictly convert your
1352
widget to something else.
1354
However, 'with'ing this unit means that your application will depend on every
1355
package of GtkAda, which is a little bit heavier, and explains why this is not
1356
the default. We do recommend you use it if it is not extremely important
1357
whether your application depends on all the packages of GtkAda.
1359
The case of third party C widgets is a little bit trickier. Since GtkAda does not
1360
know anything about them when it is built, it can't magically convert the C
1371
The case of third party C widgets is a little bit trickier. Since GtkAda does
1372
not know anything about them when it is built, it can't magically convert the C
1361
1373
widgets to Ada widgets. This is your job to teach GtkAda how to do the
1364
1376
We thus provide a 'hook' function which you need to modify. This function is
1365
defined in the package @b{Gtk.Type_Conversion}. This function takes
1366
a string with the name of the C widget (ex/ "GtkButton"), and should return a newly
1367
allocated pointer. If you don't know this type either, simply
1377
defined in the package @b{Glib.Type_Conversion}. This function takes
1378
a string with the name of the C widget (ex/ "GtkButton"), and should return a
1379
newly allocated pointer. If you don't know this type either, simply
1368
1380
return @b{null}.
1370
1382
@node Using tagged types to extend Gtk widgets
1371
1383
@section Using tagged types to extend Gtk widgets
1373
Since version 0.6 of this toolkit, it is possible to associate your
1385
With this toolkit, it's possible to associate your
1374
1386
own data with existing widgets simply by creating new types. This
1375
1387
section will show you a simple example, but you should rather read the
1376
1388
source code in testgtk/ where we used this feature instead of using
1822
1834
will get used to the way GtkAda works. Note that your C file should
1823
1835
have the same format as is used by Gtk+ itself.
1825
Here are the steps to create a new binding :
1828
@item Give the 'generate.pl' script the C header file
1830
@item The perl script should ask you for every field in the C structure if
1831
you want to create a function to make it accessible from Ada. Answer
1832
@i{y} or @i{n} (the default value is @i{n}, just press ENTER).
1835
$ generate.pl ../include/gtk/gtkbutton.h > temporary
1836
Create a function for the field child (of type GtkWidget*) [n]?
1837
Create a function for the field in_button (of type guint) [n]?
1838
Create a function for the field button_down (of type guint) [n]?
1841
@item If you answered yes to at least one of the above questions, create a
1842
new C file, and move the C part of the @i{temporary} file created by
1843
generate.pl to this C file.
1845
@item Do a gnatchop on the @i{temporary} file created by generate.pl
1848
$ gnatchop temporary
1851
This should create two Ada files (spec and body)
1853
@item Edit these two files if needed (generally to change some parameters
1854
from Gint to Boolean for instance). It can be a little bit tricky
1855
when one of your functions returns a GList* or a GSList*. Please have
1856
a look at @code{gtk-combo.ads} for examples how to do this.
1837
To get started on a new binding, launch the script @file{contrib/binding.pl}
1841
$ touch gtk-button.ads
1842
$ binding.pl ../include/gtk/gtkbutton.h > temporary
1845
This dumps several kind of information on the standard output:
1848
@item List of subprograms defined in the @file{.h} file. Their
1849
documentation is also added, since binding.pl will parse the @file{.c} file
1851
@item List of properties and signals for the widget
1852
@item Tentative bodies for the subprograms
1853
These will often need adjustements, but provide a good start
1856
You can also use this script to update existing bindings:
1859
$ binding.pl ../include/gtk/*.h
1859
1862
@c -------------------------------------------------------------------
1860
1863
@node Debugging GtkAda applications
1861
1864
@chapter Debugging GtkAda applications
added
removed
docs/gtkada_ug/gtkada_ug.texi
