1Subclass(3) User Contributed Perl Documentation Subclass(3)
2
6 Glib::Object::Subclass - register a perl class as a GObject class
7
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
31 This module allows you to create your own GObject classes, which is
32 useful to e.g. implement your own Gtk2 widgets.
33 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 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 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 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 USAGE
58 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 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 - properties => []
67 Add object properties; see "PROPERTIES".
68 - signals => {}
70 Add or override signals; see "SIGNALS" and "OVERRIDING BASE METH‐
71 ODS".
72 - interfaces => []
74 Add GInterfaces to your class; see "INTERFACES".
75 (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 OBJECT METHODS AND FUNCTIONS
81 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 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 $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 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 GET_PROPERTY $self, $pspec [not a method]
106 Get a property value, see "SET_PROPERTY".
107 The default implementation looks like this:
109 my ($self, $pspec) = @_;
111 return ($self->{$pspec->get_name} ⎪⎪ $pspec->get_default_value);
112 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 "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 The default "SET_PROPERTY" looks like this:
127 my ($self, $pspec, $newval) = @_;
129 $self->{$pspec->get_name} = $newval;
130 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 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 The default finalizer does nothing.
143 $object->DESTROY [DO NOT OVERWRITE]
145 Don't ever overwrite "DESTROY", use "FINALIZE_INSTANCE" instead.
146 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
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 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
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 flags => GSignalFlags
173 If not present, assumed to be 'run-first'.
174 param_types => reference to a list of package names
176 If not present, assumed to be empty (no parameters).
177 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 If not present, the library will attempt to call the method named
184 "do_signal_name" for the signal "signal_name" (uses underscores).
185 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 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 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 If not specified, the default accumulator is used, and you just get
204 the return value of the last handler to run.
205 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 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
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 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 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 # 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 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
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 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 package Mup::MultilineEntry;
268 use Glib::Object::Subclass
269 'Gtk2::TextView',
270 interfaces => [ 'Gtk2::CellEditable' ],
271 ;
272 # 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
281 GObject - http://developer.gnome.org/doc/API/2.0/gobject/
282
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 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
292perl v5.8.8 2007-02-26 Subclass(3)