1Subclass(3)           User Contributed Perl Documentation          Subclass(3)
2
3
4

NAME

6       Glib::Object::Subclass - register a perl class as a GObject class
7

SYNOPSIS

9         use Glib::Object::Subclass
10            Some::Base::Class::,   # parent class, derived from Glib::Object
11            signals => {
12                   something_changed => {
13                      class_closure => sub { do_something_fun () },
14                      flags         => [qw(run-first)],
15                      return_type   => undef,
16                      param_types   => [],
17                   },
18                   some_existing_signal => \&class_closure_override,
19            },
20            properties => [
21               Glib::ParamSpec->string (
22                  'some_string',
23                  'Some String Property',
24                  'This property is a string that is used as an example',
25                  'default value',
26                  [qw/readable writable/]
27               ),
28            ];
29

DESCRIPTION

31       This module allows you to create your own GObject classes, which is
32       useful to e.g. implement your own Gtk2 widgets.
33
34       It doesn't "export" anything into your namespace, but acts more like a
35       pragmatic module that modifies your class to make it work as a GObject
36       class.
37
38       You may be wondering why you can't just bless a Glib::Object into a
39       different package and add some subs.  Well, if you aren't interested in
40       object parameters, signals, or having your new class interoperate
41       transparently with other GObject-based modules (e.g., Gtk2 and
42       friends), then you can just re-bless.
43
44       However, a GObject's signals, properties, virtual functions, and GIn‐
45       terface implementations are specific to its GObjectClass.  If you want
46       to create a new GObject which was a derivative of GtkDrawingArea, but
47       adds a new signal, you must create a new GObjectClass to which to add
48       the new signal.  If you don't, then all of the GtkDrawingAreas in your
49       application will get that new signal!
50
51       Thus, the only way to create a new signal or object property in the
52       Perl bindings for Glib is to register a new subclass with the GLib type
53       system via Glib::Type::register_object().  The Glib::Object::Subclass
54       module is a Perl-developer-friendly interface to this bit of paradigm
55       mismatch.
56
57       USAGE
58
59       This module works similar to the "use base" pragma in that it registers
60       the current package as a subclass of some other class (which must be a
61       GObjectClass implemented either in C or some other language).
62
63       The pragma requires at least one argument, the parent class name.  The
64       remaining arguments are key/value pairs, in any order, all optional:
65
66       - properties => []
67           Add object properties; see "PROPERTIES".
68
69       - signals => {}
70           Add or override signals; see "SIGNALS" and "OVERRIDING BASE METH‐
71           ODS".
72
73       - interfaces => []
74           Add GInterfaces to your class; see "INTERFACES".
75
76       (Actually, these parameters are all passed straight through to
77       Glib::Type::register_object(), adding __PACKAGE__ (the current package
78       name) as the name of the new child class.)
79
80       OBJECT METHODS AND FUNCTIONS
81
82       The following methods are either added to your class on request (not
83       yet implemented), or by default unless your own class implements them
84       itself. This means that all these methods and functions will get sensi‐
85       ble default implementations unless explicitly overwritten by you (by
86       defining your own version).
87
88       Except for "new", all of the following are functions and no methods.
89       That means that you should not call the superclass method. Instead, the
90       GObject system will call these functions per class as required, emulat‐
91       ing normal inheritance.
92
93       $class->new (attr => value, ...)
94           The default constructor just calls "Glib::Object::new", which
95           allows you to set properties on the newly created object. This is
96           done because many "new" methods inherited by Gtk2 or other
97           libraries don't have "new" methods suitable for subclassing.
98
99       INIT_INSTANCE $self                                 [not a method]
100           "INIT_INSTANCE" is called on each class in the hierarchy as the
101           object is being created (i.e., from "Glib::Object::new" or our
102           default "new"). Use this function to initialize any member data.
103           The default implementation will leave the object untouched.
104
105       GET_PROPERTY $self, $pspec                          [not a method]
106           Get a property value, see "SET_PROPERTY".
107
108           The default implementation looks like this:
109
110              my ($self, $pspec) = @_;
111              return ($self->{$pspec->get_name} ⎪⎪ $pspec->get_default_value);
112
113       SET_PROPERTY $self, $pspec, $newval                 [not a method]
114           "GET_PROPERTY" and "SET_PROPERTY" are called whenever somebody does
115           "$object->get ($propname)" or "$object->set ($propname => $newval)"
116           (from other languages, too). This is your hook that allows you to
117           store/fetch properties in any way you need to (maybe you have to
118           calculate something or read a file).
119
120           "GET_PROPERTY" is different from a C get_property method in that
121           the perl method returns the retrieved value. For symmetry, the
122           $newval and $pspec args on "SET_PROPERTY" are swapped from the C
123           usage. The default get and set methods store property data in the
124           object as hash values named for the parameter name.
125
126           The default "SET_PROPERTY" looks like this:
127
128              my ($self, $pspec, $newval) = @_;
129              $self->{$pspec->get_name} = $newval;
130
131       FINALIZE_INSTANCE $self                             [not a method]
132           "FINALIZE_INSTANCE" is called as the GObject is being finalized,
133           that is, as it is being really destroyed.  This is independent of
134           the more common DESTROY on the perl object; in fact, you must NOT
135           override "DESTROY" (it's not useful to you, in any case, as it is
136           being called multiple times!).
137
138           Use this hook to release anything you have to clean up manually.
139           FINALIZE_INSTANCE will be called for each perl instance, in reverse
140           order of construction.
141
142           The default finalizer does nothing.
143
144       $object->DESTROY           [DO NOT OVERWRITE]
145           Don't ever overwrite "DESTROY", use "FINALIZE_INSTANCE" instead.
146
147           The DESTROY method of all perl classes derived from GTypes is
148           implemented in the Glib module and (ab-)used for its own internal
149           purposes. Overwriting it is not useful as it will be called multi‐
150           ple times, and often long before the object actually gets
151           destroyed.  Overwriting might be very harmful to your program, so
152           never do that.  Especially watch out for other classes in your ISA
153           tree.
154

PROPERTIES

156       To create gobject properties, supply a list of Glib::ParamSpec objects
157       as the value for the key 'properties'.  There are lots of different
158       paramspec constructors, documented in the C API reference's Parameters
159       and Values page, as well as Glib::ParamSpec.
160
161       As of Glib 1.060, you can also specify explicit getters and setters for
162       your properties at creation time.  The default values in your proper‐
163       ties are also honored if you don't set anything else.  See
164       Glib::Type::register_object in Glib::Type for an example.
165

SIGNALS

167       Creating new signals for your new object is easy.  Just provide a hash
168       of signal names and signal descriptions under the key 'signals'.  Each
169       signal description is also a hash, with a few expected keys.  All the
170       keys are allowed to default.
171
172       flags => GSignalFlags
173           If not present, assumed to be 'run-first'.
174
175       param_types => reference to a list of package names
176           If not present, assumed to be empty (no parameters).
177
178       class_closure => reference to a subroutine to call as the class clo‐
179       sure.
180           may also be a string interpreted as the name of a subroutine to
181           call, but you should be very very very careful about that.
182
183           If not present, the library will attempt to call the method named
184           "do_signal_name" for the signal "signal_name" (uses underscores).
185
186           You'll want to be careful not to let this handler method be a pub‐
187           lically callable method, or one that has the name name as something
188           that emits the signal.  Due to the funky ways in which Glib is dif‐
189           ferent from Perl, the class closures should not inherit through
190           normal perl inheritance.
191
192       return_type => package name for return value.
193           If undefined or not present, the signal expects no return value.
194           if defined, the signal is expected to return a value; flags must be
195           set such that the signal does not run only first (at least use
196           'run-last').
197
198       accumulator => signal return value accumulator
199           quoting the Glib manual: "The signal accumulator is a special call‐
200           back function that can be used to collect return values of the var‐
201           ious callbacks that are called during a signal emission."
202
203           If not specified, the default accumulator is used, and you just get
204           the return value of the last handler to run.
205
206           Accumulators are not really documented very much in the C refer‐
207           ence, and the perl interface here is slightly different, so here's
208           an inordinate amount of detail for this arcane feature:
209
210           The accumulator function is called for every handler.  It is given
211           three arguments: the signal invocation hint as an anonymous hash
212           (containing the signal name, notably); the current accumulated
213           return value; and the value returned by the most recent handler.
214           The accumulator must return two values: a boolean value determining
215           whether signal emission should continue (false stops the emission),
216           and the new value for the accumulated return value.  (This is dif‐
217           ferent from the C version, which writes through the return_accu.)
218

OVERRIDING BASE METHODS

220       GLib pulls some fancy tricks with function pointers to implement meth‐
221       ods in C.  This is not very language-binding-friendly, as you might
222       guess.
223
224       However, as described above, every signal allows a "class closure"; you
225       may override thie class closure with your own function, and you can
226       chain from the overridden method to the original.  This serves to
227       implement virtual overrides for language bindings.
228
229       So, to override a method, you supply a subroutine reference instead of
230       a signal description hash as the value for the name of the existing
231       signal in the "signals" hash described in "SIGNALS".
232
233         # override some important widget methods:
234         use Glib::Object::Subclass
235               Gtk2::Widget::,
236               signals => {
237                       expose_event => \&expose_event,
238                       configure_event => \&configure_event,
239                       button_press_event => \&button_press_event,
240                       button_release_event => \&button_release_event,
241                       motion_notify_event => \&motion_notify_event,
242                       # note the choice of names here... see the discussion.
243                       size_request => \&do_size_request,
244               }
245
246       It's important to note that the handlers you supply for these are
247       class-specific, and that normal perl method inheritance rules are not
248       followed to invoke them from within the library.  However, perl code
249       can still find them!  Therefore it's rather important that you choose
250       your handlers' names carefully, avoiding any public interfaces that you
251       might call from perl.  Case in point, since size_request is a widget
252       method, i chose do_size_request as the override handler.
253

INTERFACES

255       GObject supports only single inheritance; in place of multiple inheri‐
256       tance, GObject uses GInterfaces.  In the Perl bindings we have mostly
257       masqueraded this with multiple inheritance (that is, simply adding the
258       GInterface class to the @ISA of the implementing class), but in deriv‐
259       ing new objects the facade breaks and the magic leaks out.
260
261       In order to derive an object that implements a GInterface, you have to
262       tell the GLib type system you want your class to include a GInterface.
263       To do this, simply pass a list of package names through the "inter‐
264       faces" key; this will add these packages to your @ISA, and cause perl
265       to invoke methods that you must provide.
266
267         package Mup::MultilineEntry;
268         use Glib::Object::Subclass
269             'Gtk2::TextView',
270             interfaces => [ 'Gtk2::CellEditable' ],
271             ;
272
273         # perl will now invoke these methods, which are part of the
274         # GtkCellEditable GInterface, when somebody invokes the
275         # corresponding lower-case methods on your objects.
276         sub START_EDITING { warn "start editing\n"; }
277         sub EDITING_DONE { warn "editing done\n"; }
278         sub REMOVE_WIDGET { warn "remove widget\n"; }
279

SEE ALSO

281         GObject - http://developer.gnome.org/doc/API/2.0/gobject/
282

AUTHORS

284       Marc Lehmann <schmorp@schmorp.de>, muppet <scott at asofyet dot org>
285
287       Copyright 2003-2004 by muppet and the gtk2-perl team
288
289       This library is free software; you can redistribute it and/or modify it
290       under the terms of the Lesser General Public License (LGPL).  For more
291       information, see http://www.fsf.org/licenses/lgpl.txt
292
293
294
295perl v5.8.8                       2007-02-26                       Subclass(3)
Impressum