1Gtk2::devel(3)        User Contributed Perl Documentation       Gtk2::devel(3)
2
3
4

NAME

6       Gtk2::devel - The internal workings of the gtk2-perl language bindings
7

DESCRIPTION

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
13       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

GtkObject

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
24       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
32       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
36       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
41        SV * gtk2perl_new_gtkobject (GtkObject * o);
42
43       Which does nothing more than
44
45        {
46            return gperl_new_object (G_OBJECT (o), TRUE);
47        }
48
49       It's also important to know that this is largely done for you by the
50       typemap.
51

Typemap scheme

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
60       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
66       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
70        typedef GdkEvent GdkEvent_ornull;
71        typedef GdkEvent GdkEvent_own;
72
73        #define SvGdkEvent(s)           (gperl_get_boxed_check ((s), GDK_TYPE_EVENT))
74        #define SvGdkEvent_ornull(s)    ((s)==&PL_sv_undef ? NULL : SvGdkEvent(s))
75
76        #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
80       Then the typemap entries for its various variants would look like this:
81
82        TYPEMAP
83        GdkEvent *     T_GDK_TYPE_EVENT
84        GdkEvent_ornull *      T_GDK_TYPE_EVENT_ORNULL
85        GdkEvent_own * T_GDK_TYPE_EVENT_OWN
86
87        INPUT
88        T_GDK_TYPE_EVENT
89               $var = SvGdkEvent ($arg);
90        T_GDK_TYPE_EVENT_ORNULL
91               $var = SvGdkEvent_ornull ($arg);
92
93        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
101       And with that, your XS wrapper code can look as simple as this:
102
103        GdkEvent_own *
104        gdk_get_event (class)
105                SV * class
106            C_ARGS:
107                /*void*/
108
109        guint
110        gdk_event_get_time (event)
111                GdkEvent * event
112
113       Isn't that nice and simple?
114
115       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
119         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
128         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
133         GtkObject
134         /* no ext */ * *  everything is peachy
135         _ornull      * *  undef/NULL is legal
136

Autogeneration

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
143       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
148   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
162       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
167       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
177   gtk2perl-autogen.h
178       This file contains the generated typedefs and cast macros.  This
179       includes all the variant stuff described above.
180
181   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
186   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
195   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
201       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
209       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

SEE ALSO

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

AUTHOR

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
225       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
230       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
235       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.
239
240
241
242perl v5.34.0                      2022-01-21                    Gtk2::devel(3)
Impressum