1Gtk2::devel(3) User Contributed Perl Documentation Gtk2::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
58 autogenerated, 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
61 sensible way the differences between GObject and GtkObject, and makes
62 it very easy to specify whether a wrapper owns the object it wraps.
63 This is handled through the idea of a "variant", which is a term I made
64 up 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
145 Gtk2::CodeGen for details on how to use the generators. Here I'll
146 describe what gets generated and why.
147 maps
149 This is the starting point for autogeneration, the input for the code
150 generator. This map lists the TYPE macro for each of the GObject types
151 in all of the gtk headers (including gdk, gdk-pixbuf, atk, and pango),
152 along with the actual name of the class, name of the package into which
153 it is to be blessed, and the base type (not exactly the fundamental
154 type). Most of those should be obvious except for the base type. The
155 base type is one of GEnum, GFlags, GBoxed, GObject, GInterface, or
156 GtkObject. This is the important flag which determines what kind of
157 code gets created for each record; GObjects must be handled by
158 completely different code than GBoxed objects, for instance. As noted
159 elsewhere, the distinction between GObject and GtkObject is not
160 strictly necessary, but is kept for historical and aesthetic reasons.
161 In this file, you can change the explicit name of an object. If you
163 don't like PangoFontDescription being Gtk2::Pango::FontDescription, you
164 can change it to Gtk2::Pango::Font::Desc::ription if you were so
165 inclined (but please don't).
166 If you wish to use Gtk2's autogeneration tools in your own project,
168 you'll need to create a maps file. This can be done by hand, but
169 that's tedious and error-prone; I used a script (called genmaps.pl in
170 CVS) that actually scans the gtk header files and creates and runs a
171 small program to generate the maps file. The advantage here is that
172 the type information comes directly from the code and I don't have to
173 worry about clerical errors making the software incorrect. In
174 practice, this should need to be run only when new classes are added to
175 the base libraries.
176 gtk2perl-autogen.h
178 This file contains the generated typedefs and cast macros. This
179 includes all the variant stuff described above.
180 gtk2perl.typemap
182 The exhaustive typemap uses the macros defined in gtk2perl-autogen.h so
183 that you are assured to get the same results from typemap generated
184 code as from hand-written perl stack manipulation.
185 register.xsh
187 Included from the BOOT section of the toplevel Gtk2 module
188 (xs/Gtk2.xs), this file lists all of the types in the maps file as a
189 series of calls to the appropriate package registration functions
190 (gperl_register_boxed, gperl_register_object, or
191 gperl_register_fundamental). This is done before the boot code below
192 so that hand-written code may override it. This code gets executed
193 when your perl script does a "use Gtk2".
194 boot.xsh
196 The Gtk2 module is made up of dozens of XS files but only one PM file.
197 Gtk2.pm calls bootstrap on Gtk2, but not on any of the others (because
198 it doesn't know about them). It is a module's boot code which binds
199 the xsubs into perl, so it's imperative that the modules get booted!
200 So, "Gtk2::CodeGen->write_boot" (called from Makefile.PL) scans the xs/
202 subdirectory for all the "MODULE = ..." lines in the XS files. It maps
203 these to boot code symbols, and generates code to call these symbols in
204 boot.xsh, which is then included by the BOOT: section for the toplevel
205 module, right after register.xsh. (The generation code takes steps to
206 avoid spitting out the same symbol more than once, and will not emit
207 code to boot the toplevel module (or else you get an infinite loop).)
208 Just a point of style; you can change packages in an XS file by
210 repeating the MODULE = ... line with a different PACKAGE (and possibly
211 PREFIX) value. It's a good idea, however, to keep the MODULE the same,
212 so that only one boot symbol gets generated per file.
213
215 perl(1), perlxs(1), Gtk2(3pm), Glib(3pm), Glib::devel(3pm),
216 Glib::xsapi(3pm), Gtk2::CodeGen(3pm)
217
219 muppet <scott at asofyet dot org>
220
222 Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
223 full list)
224 This library is free software; you can redistribute it and/or modify it
226 under the terms of the GNU Library General Public License as published
227 by the Free Software Foundation; either version 2.1 of the License, or
228 (at your option) any later version.
229 This library is distributed in the hope that it will be useful, but
231 WITHOUT ANY WARRANTY; without even the implied warranty of
232 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
233 Library General Public License for more details.
234 You should have received a copy of the GNU Library General Public
236 License along with this library; if not, write to the Free Software
237 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
238 02110-1301 USA.
239perl v5.34.0 2021-07-22 Gtk2::devel(3)