Brian Manning > Gtk2-1.249 > Gtk2::devel


Annotate this POD



New  1
Open  6
View/Report Bugs




This document is a supplement to Glib::devel, and assumes you have read and understood all about how the base Glib bindings work. Most of this will seem like nonsense, otherwise.

Here we focus on the ways in which Gtk2 extends Glib's concepts for binding the Gtk+ C libraries to perl, a methodology and set of tools you can use to wrap your own GObject-based libraries.

GtkObject ^





 SV * gtk2perl_new_gtkobject (GtkObject * o);

Which does nothing more than

     return gperl_new_object (G_OBJECT (o), TRUE);


Typemap scheme ^

In the same way that the Glib module uses explicit one-to-one GType to package registrations, it is most foolproof to use an explicit, even exhaustive XS typemap. In this way we avoid problems such as finding the proper set of regexes to map $var to the type macro and all sort of other problems of extensibility. This of course means it must be autogenerated, but that's easy (and is described in the next section).



 typedef GdkEvent GdkEvent_ornull;
 typedef GdkEvent GdkEvent_own;




 GdkEvent *     T_GDK_TYPE_EVENT 
 GdkEvent_ornull *      T_GDK_TYPE_EVENT_ORNULL
 GdkEvent_own * T_GDK_TYPE_EVENT_OWN

        $var = SvGdkEvent ($arg);
        $var = SvGdkEvent_ornull ($arg); 

        $arg = newSVGdkEvent ($var); 
        $arg = newSVGdkEvent_ornull ($var); 
        $arg = newSVGdkEvent_own ($var); 


 GdkEvent_own *
 gdk_get_event (class)
         SV * class

 gdk_event_get_time (event)
         GdkEvent * event

Isn't that nice and simple?

We have different variants for different types, and some are applicable only to input or output. The ones used by gtk2-perl generally follow the convention outlined in this table:

  Variant      I O  Description
  _own           *  object will be destroyed with wrapper
  _ornull      * *  undef/NULL is legal
  _own_ornull    *  if object not NULL, wrapper will own object

  _ornull      * *  undef/NULL is legal

  /* no ext */ * *  everything is peachy
  _ornull      * *  undef/NULL is legal

Autogeneration ^

The typemap scheme described above is great, but involves creating a lot of typedefs and macros. For a large library like Gtk, with over three hundred types to bind, you'd have to be crazy to write all of those by hand.

Gtk2 handles this by using a code generation module to write the code for us as part of the Makefile.PL configuration step. See Gtk2::CodeGen for details on how to use the generators. Here I'll describe what gets generated and why.


This is the starting point for autogeneration, the input for the code generator. This map lists the TYPE macro for each of the GObject types in all of the gtk headers (including gdk, gdk-pixbuf, atk, and pango), along with the actual name of the class, name of the package into which it is to be blessed, and the base type (not exactly the fundamental type). Most of those should be obvious except for the base type. The base type is one of GEnum, GFlags, GBoxed, GObject, GInterface, or GtkObject. This is the important flag which determines what kind of code gets created for each record; GObjects must be handled by completely different code than GBoxed objects, for instance. As noted elsewhere, the distinction between GObject and GtkObject is not strictly necessary, but is kept for historical and aesthetic reasons.


If you wish to use Gtk2's autogeneration tools in your own project, you'll need to create a maps file. This can be done by hand, but that's tedious and error-prone; I used a script (called in CVS) that actually scans the gtk header files and creates and runs a small program to generate the maps file. The advantage here is that the type information comes directly from the code and I don't have to worry about clerical errors making the software incorrect. In practice, this should need to be run only when new classes are added to the base libraries.


This file contains the generated typedefs and cast macros. This includes all the variant stuff described above.




Included from the BOOT section of the toplevel Gtk2 module (xs/Gtk2.xs), this file lists all of the types in the maps file as a series of calls to the appropriate package registration functions (gperl_register_boxed, gperl_register_object, or gperl_register_fundamental). This is done before the boot code below so that hand-written code may override it. This code gets executed when your perl script does a "use Gtk2".



So, Gtk2::CodeGen->write_boot (called from Makefile.PL) scans the xs/ subdirectory for all the "MODULE = ..." lines in the XS files. It maps these to boot code symbols, and generates code to call these symbols in boot.xsh, which is then included by the BOOT: section for the toplevel module, right after register.xsh. (The generation code takes steps to avoid spitting out the same symbol more than once, and will not emit code to boot the toplevel module (or else you get an infinite loop).)



perl(1), perlxs(1), Gtk2(3pm), Glib(3pm), Glib::devel(3pm), Glib::xsapi(3pm), Gtk2::CodeGen(3pm)


muppet <scott at asofyet dot org>






syntax highlighting: