1devel(3) User Contributed Perl Documentation devel(3)
2
6 Gtk2::devel - The internal workings of the gtk2-perl language bindings
7
9 This document is a supplement to Glib::devel, and assumes you have read
10 and understood all about how the base Glib bindings work. Most of this
11 will seem like nonsense, otherwise.
12 Here we focus on the ways in which Gtk2 extends Glib's concepts for
14 binding the Gtk+ C libraries to perl, a methodology and set of tools
15 you can use to wrap your own GObject-based libraries.
16
18 GtkObject adds the idea of a floating reference to GObject. A GObject
19 is created with one reference which must be explicitly removed by its
20 owner. GtkObject has a floating reference which is sunk by the code
21 which wants to own it. This makes it less painful to create lots of
22 objects in a row (you don't have to unref them).
23 To allow for this difference in procedure for taking ownership of an
25 object, Glib allows you to register a "sink" function for a particular
26 class. When asked to create a wrapper that owns the object,
27 gperl_new_object will compare the list of registered sink functions
28 with the type of the object; if the object is descended from a type,
29 that sink function will be run on the object. The default one is
30 g_object_unref(), of course. (this is inspired by pygtk.)
31 Thus, in Gtk2::Object's boot code, we register gtk_object_sink as the
33 sink func for types derived from GtkObject. Now all wrappers for
34 these types will be owned the proper way.
35 Of course, since gtk_object_sink() does nothing if the object isn't
37 floating, it doesn't hurt anything if you always call gperl_new_object
38 with "own" set to TRUE. So, to make life a little easier, Gtk2 defines
39 another function
40 SV * gtk2perl_new_gtkobject (GtkObject * o);
42 Which does nothing more than
44 {
46 return gperl_new_object (G_OBJECT (o), TRUE);
47 }
48 It's also important to know that this is largely done for you by the
50 typemap.
51
53 In the same way that the Glib module uses explicit one-to-one GType to
54 package registrations, it is most foolproof to use an explicit, even
55 exhaustive XS typemap. In this way we avoid problems such as finding
56 the proper set of regexes to map $var to the type macro and all sort of
57 other problems of extensibility. This of course means it must be auto‐
58 generated, but that's easy (and is described in the next section).
59 The other main feature of the typemap is that it masks in a very sensi‐
61 ble way the differences between GObject and GtkObject, and makes it
62 very easy to specify whether a wrapper owns the object it wraps. This
63 is handled through the idea of a "variant", which is a term I made up
64 just now because it sounds about right.
65 Basically, a variant is the name of the class with some suffix. For
67 example, for the a GBoxed subclass such as GdkEvent, a header would do
68 this:
69 typedef GdkEvent GdkEvent_ornull;
71 typedef GdkEvent GdkEvent_own;
72 #define SvGdkEvent(s) (gperl_get_boxed_check ((s), GDK_TYPE_EVENT))
74 #define SvGdkEvent_ornull(s) ((s)==&PL_sv_undef ? NULL : SvGdkEvent(s))
75 #define newSVGdkEvent(e) (gperl_new_boxed ((e), GDK_TYPE_EVENT, FALSE))
77 #define newSVGdkEvent_own(e) (gperl_new_boxed ((e), GDK_TYPE_EVENT, TRUE))
78 #define newSVGdkEvent_ornull(e) (e == NULL ? &PL_sv_undef ? newSVGdkEvent (e))
79 Then the typemap entries for its various variants would look like this:
81 TYPEMAP
83 GdkEvent * T_GDK_TYPE_EVENT
84 GdkEvent_ornull * T_GDK_TYPE_EVENT_ORNULL
85 GdkEvent_own * T_GDK_TYPE_EVENT_OWN
86 INPUT
88 T_GDK_TYPE_EVENT
89 $var = SvGdkEvent ($arg);
90 T_GDK_TYPE_EVENT_ORNULL
91 $var = SvGdkEvent_ornull ($arg);
92 OUTPUT
94 T_GDK_TYPE_EVENT
95 $arg = newSVGdkEvent ($var);
96 T_GDK_TYPE_EVENT_ORNULL
97 $arg = newSVGdkEvent_ornull ($var);
98 T_GDK_TYPE_EVENT_OWN
99 $arg = newSVGdkEvent_own ($var);
100 And with that, your XS wrapper code can look as simple as this:
102 GdkEvent_own *
104 gdk_get_event (class)
105 SV * class
106 C_ARGS:
107 /*void*/
108 guint
110 gdk_event_get_time (event)
111 GdkEvent * event
112 Isn't that nice and simple?
114 We have different variants for different types, and some are applicable
116 only to input or output. The ones used by gtk2-perl generally follow
117 the convention outlined in this table:
118 Variant I O Description
120 ------------ - - -------------------------------------------
121 GBoxed
122 /* no ext */ * * object will not be destroyed with wrapper
123 _own * object will be destroyed with wrapper
124 _copy * object will be copied (and copy will be owned)
125 _ornull * * undef/NULL is legal
126 _own_ornull * if object not NULL, wrapper will own object
127 GObject
129 /* no ext */ * * object's refcount will be increased (=>not owned)
130 _noinc * object's refcount will not be increased (=>owned)
131 _ornull * * undef/NULL is legal
132 GtkObject
134 /* no ext */ * * everything is peachy
135 _ornull * * undef/NULL is legal
136
138 The typemap scheme described above is great, but involves creating a
139 lot of typedefs and macros. For a large library like Gtk, with over
140 three hundred types to bind, you'd have to be crazy to write all of
141 those by hand.
142 Gtk2 handles this by using a code generation module to write the code
144 for us as part of the Makefile.PL configuration step. See Gtk2::Code‐
145 Gen for details on how to use the generators. Here I'll describe what
146 gets generated and why.
147 maps
149 This is the starting point for autogeneration, the input for the code
151 generator. This map lists the TYPE macro for each of the GObject types
152 in all of the gtk headers (including gdk, gdk-pixbuf, atk, and pango),
153 along with the actual name of the class, name of the package into which
154 it is to be blessed, and the base type (not exactly the fundamental
155 type). Most of those should be obvious except for the base type. The
156 base type is one of GEnum, GFlags, GBoxed, GObject, GInterface, or
157 GtkObject. This is the important flag which determines what kind of
158 code gets created for each record; GObjects must be handled by com‐
159 pletely different code than GBoxed objects, for instance. As noted
160 elsewhere, the distinction between GObject and GtkObject is not
161 strictly necessary, but is kept for historical and aesthetic reasons.
162 In this file, you can change the explicit name of an object. If you
164 don't like PangoFontDescription being Gtk2::Pango::FontDescription, you
165 can change it to Gtk2::Pango::Font::Desc::ription if you were so
166 inclined (but please don't).
167 If you wish to use Gtk2's autogeneration tools in your own project,
169 you'll need to create a maps file. This can be done by hand, but
170 that's tedious and error-prone; I used a script (called genmaps.pl in
171 CVS) that actually scans the gtk header files and creates and runs a
172 small program to generate the maps file. The advantage here is that
173 the type information comes directly from the code and I don't have to
174 worry about clerical errors making the software incorrect. In prac‐
175 tice, this should need to be run only when new classes are added to the
176 base libraries.
177 gtk2perl-autogen.h
179 This file contains the generated typedefs and cast macros. This
181 includes all the variant stuff described above.
182 gtk2perl.typemap
184 The exhaustive typemap uses the macros defined in gtk2perl-autogen.h so
186 that you are assured to get the same results from typemap generated
187 code as from hand-written perl stack manipulation.
188 register.xsh
190 Included from the BOOT section of the toplevel Gtk2 module
192 (xs/Gtk2.xs), this file lists all of the types in the maps file as a
193 series of calls to the appropriate package registration functions
194 (gperl_register_boxed, gperl_register_object, or gperl_register_funda‐
195 mental). This is done before the boot code below so that hand-written
196 code may override it. This code gets executed when your perl script
197 does a "use Gtk2".
198 boot.xsh
200 The Gtk2 module is made up of dozens of XS files but only one PM file.
202 Gtk2.pm calls bootstrap on Gtk2, but not on any of the others (because
203 it doesn't know about them). It is a module's boot code which binds
204 the xsubs into perl, so it's imperative that the modules get booted!
205 So, "Gtk2::CodeGen-"write_boot> (called from Makefile.PL) scans the xs/
207 subdirectory for all the "MODULE = ..." lines in the XS files. It maps
208 these to boot code symbols, and generates code to call these symbols in
209 boot.xsh, which is then included by the BOOT: section for the toplevel
210 module, right after register.xsh. (The generation code takes steps to
211 avoid spitting out the same symbol more than once, and will not emit
212 code to boot the toplevel module (or else you get an infinite loop).)
213 Just a point of style; you can change packages in an XS file by repeat‐
215 ing the MODULE = ... line with a different PACKAGE (and possibly PRE‐
216 FIX) value. It's a good idea, however, to keep the MODULE the same, so
217 that only one boot symbol gets generated per file.
218
220 perl(1), perlxs(1), Gtk2(3pm), Glib(3pm), Glib::devel(3pm),
221 Glib::xsapi(3pm), Gtk2::CodeGen(3pm)
222
224 muppet <scott at asofyet dot org>
225
227 Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
228 full list)
229 This library is free software; you can redistribute it and/or modify it
231 under the terms of the GNU Library General Public License as published
232 by the Free Software Foundation; either version 2.1 of the License, or
233 (at your option) any later version.
234 This library is distributed in the hope that it will be useful, but
236 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
237 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
238 General Public License for more details.
239 You should have received a copy of the GNU Library General Public
241 License along with this library; if not, write to the Free Software
242 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
243 USA.
244perl v5.8.8 2007-03-18 devel(3)