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
45 GInterface implementations are specific to its GObjectClass. If you
46 want to create a new GObject which was a derivative of GtkDrawingArea,
47 but adds a new signal, you must create a new GObjectClass to which to
48 add the new signal. If you don't, then all of the GtkDrawingAreas in
49 your 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
59 the current package as a subclass of some other class (which must be a
60 GObjectClass implemented either in C or some other language).
61 The pragma requires at least one argument, the parent class name. The
63 remaining arguments are key/value pairs, in any order, all optional:
64 - properties => []
66 Add object properties; see "PROPERTIES".
67 - signals => {}
69 Add or override signals; see "SIGNALS" and "OVERRIDING BASE
70 METHODS".
71 - interfaces => []
73 Add GInterfaces to your class; see "INTERFACES".
74 (Actually, these parameters are all passed straight through to
76 Glib::Type::register_object(), adding __PACKAGE__ (the current package
77 name) as the name of the new child class.)
78 OBJECT METHODS AND FUNCTIONS
80 The following methods are either added to your class on request (not
81 yet implemented), or by default unless your own class implements them
82 itself. This means that all these methods and functions will get
83 sensible default implementations unless explicitly overwritten by you
84 (by defining your own version).
85 Except for "new", all of the following are functions and no methods.
87 That means that you should not call the superclass method. Instead, the
88 GObject system will call these functions per class as required,
89 emulating normal inheritance.
90 $class->new (attr => value, ...)
92 The default constructor just calls "Glib::Object::new", which
93 allows you to set properties on the newly created object. This is
94 done because many "new" methods inherited by Gtk2 or other
95 libraries don't have "new" methods suitable for subclassing.
96 INIT_INSTANCE $self [not a method]
98 "INIT_INSTANCE" is called on each class in the hierarchy as the
99 object is being created (i.e., from "Glib::Object::new" or our
100 default "new"). Use this function to initialize any member data.
101 The default implementation will leave the object untouched.
102 GET_PROPERTY $self, $pspec [not a method]
104 SET_PROPERTY $self, $pspec, $newval [not a method]
105 "GET_PROPERTY" and "SET_PROPERTY" are called whenever somebody does
106 "$object->get ($propname)" or "$object->set ($propname => $newval)"
107 (from other languages, too). The default implementations hold
108 property values in the object hash, equivalent to
109 sub GET_PROPERTY {
111 my ($self, $pspec) = @_;
112 my $pname = $pspec->get_name;
113 return (exists $self->{$pname} ? $self->{$pname}
114 : $pspec->get_default_value); # until set
115 }
116 sub SET_PROPERTY {
117 my ($self, $pspec, $newval) = @_;
118 $self->{$pspec->get_name} = $newval;
119 }
120 Because "$pspec->get_name" converts hyphens to underscores, a
122 property "line-style" is in the hash as "line_style".
123 These methods let you store/fetch properties in any way you need
125 to. They don't have to be in the hash, you can calculate
126 something, read a file, whatever.
127 Most often you'll write your own "SET_PROPERTY" so you can take
129 action when a property changes, like redraw or resize a widget.
130 Eg.
131 sub SET_PROPERTY {
133 my ($self, $pspec, $newval) = @_;
134 my $pname = $pspec->get_name
135 $self->{$pname} = $newval; # ready for default GET_PROPERTY
136 if ($pname eq 'line_style') {
138 $self->queue_draw; # redraw with new lines
139 }
140 }
141 "GET_PROPERTY" is different from a C get_property method in that
143 the perl method returns the retrieved value. For symmetry, the
144 $newval and $pspec args on "SET_PROPERTY" are swapped from the C
145 usage.
146 FINALIZE_INSTANCE $self [not a method]
148 "FINALIZE_INSTANCE" is called as the GObject is being finalized,
149 that is, as it is being really destroyed. This is independent of
150 the more common DESTROY on the perl object; in fact, you must NOT
151 override "DESTROY" (it's not useful to you, in any case, as it is
152 being called multiple times!).
153 Use this hook to release anything you have to clean up manually.
155 FINALIZE_INSTANCE will be called for each perl instance, in reverse
156 order of construction.
157 The default finalizer does nothing.
159 $object->DESTROY [DO NOT OVERWRITE]
161 Don't ever overwrite "DESTROY", use "FINALIZE_INSTANCE" instead.
162 The DESTROY method of all perl classes derived from GTypes is
164 implemented in the Glib module and (ab-)used for its own internal
165 purposes. Overwriting it is not useful as it will be called
166 multiple times, and often long before the object actually gets
167 destroyed. Overwriting might be very harmful to your program, so
168 never do that. Especially watch out for other classes in your ISA
169 tree.
170
172 To create gobject properties, supply a list of Glib::ParamSpec objects
173 as the value for the key 'properties'. There are lots of different
174 paramspec constructors, documented in the C API reference's Parameters
175 and Values page, as well as Glib::ParamSpec.
176 As of Glib 1.060, you can also specify explicit getters and setters for
178 your properties at creation time. The default values in your
179 properties are also honored if you don't set anything else. See
180 Glib::Type::register_object in Glib::Type for an example.
181
183 Creating new signals for your new object is easy. Just provide a hash
184 of signal names and signal descriptions under the key 'signals'. Each
185 signal description is also a hash, with a few expected keys. All the
186 keys are allowed to default.
187 flags => GSignalFlags
189 If not present, assumed to be 'run-first'.
190 param_types => reference to a list of package names
192 If not present, assumed to be empty (no parameters).
193 class_closure => reference to a subroutine to call as the class
195 closure.
196 may also be a string interpreted as the name of a subroutine to
197 call, but you should be very very very careful about that.
198 If not present, the library will attempt to call the method named
200 "do_signal_name" for the signal "signal_name" (uses underscores).
201 You'll want to be careful not to let this handler method be a
203 publically callable method, or one that has the name name as
204 something that emits the signal. Due to the funky ways in which
205 Glib is different from Perl, the class closures should not inherit
206 through normal perl inheritance.
207 return_type => package name for return value.
209 If undefined or not present, the signal expects no return value.
210 if defined, the signal is expected to return a value; flags must be
211 set such that the signal does not run only first (at least use
212 'run-last').
213 accumulator => signal return value accumulator
215 quoting the Glib manual: "The signal accumulator is a special
216 callback function that can be used to collect return values of the
217 various callbacks that are called during a signal emission."
218 If not specified, the default accumulator is used, and you just get
220 the return value of the last handler to run.
221 Accumulators are not really documented very much in the C
223 reference, and the perl interface here is slightly different, so
224 here's an inordinate amount of detail for this arcane feature:
225 The accumulator function is called for every handler. It is given
227 three arguments: the signal invocation hint as an anonymous hash
228 (containing the signal name, notably); the current accumulated
229 return value; and the value returned by the most recent handler.
230 The accumulator must return two values: a boolean value determining
231 whether signal emission should continue (false stops the emission),
232 and the new value for the accumulated return value. (This is
233 different from the C version, which writes through the
234 return_accu.)
235
237 GLib pulls some fancy tricks with function pointers to implement
238 methods in C. This is not very language-binding-friendly, as you might
239 guess.
240 However, as described above, every signal allows a "class closure"; you
242 may override thie class closure with your own function, and you can
243 chain from the overridden method to the original. This serves to
244 implement virtual overrides for language bindings.
245 So, to override a method, you supply a subroutine reference instead of
247 a signal description hash as the value for the name of the existing
248 signal in the "signals" hash described in "SIGNALS".
249 # override some important widget methods:
251 use Glib::Object::Subclass
252 Gtk2::Widget::,
253 signals => {
254 expose_event => \&expose_event,
255 configure_event => \&configure_event,
256 button_press_event => \&button_press_event,
257 button_release_event => \&button_release_event,
258 motion_notify_event => \&motion_notify_event,
259 # note the choice of names here... see the discussion.
260 size_request => \&do_size_request,
261 }
262 It's important to note that the handlers you supply for these are
264 class-specific, and that normal perl method inheritance rules are not
265 followed to invoke them from within the library. However, perl code
266 can still find them! Therefore it's rather important that you choose
267 your handlers' names carefully, avoiding any public interfaces that you
268 might call from perl. Case in point, since size_request is a widget
269 method, i chose do_size_request as the override handler.
270
272 GObject supports only single inheritance; in place of multiple
273 inheritance, GObject uses GInterfaces. In the Perl bindings we have
274 mostly masqueraded this with multiple inheritance (that is, simply
275 adding the GInterface class to the @ISA of the implementing class), but
276 in deriving new objects the facade breaks and the magic leaks out.
277 In order to derive an object that implements a GInterface, you have to
279 tell the GLib type system you want your class to include a GInterface.
280 To do this, simply pass a list of package names through the
281 "interfaces" key; this will add these packages to your @ISA, and cause
282 perl to invoke methods that you must provide.
283 package Mup::MultilineEntry;
285 use Glib::Object::Subclass
286 'Gtk2::TextView',
287 interfaces => [ 'Gtk2::CellEditable' ],
288 ;
289 # perl will now invoke these methods, which are part of the
291 # GtkCellEditable GInterface, when somebody invokes the
292 # corresponding lower-case methods on your objects.
293 sub START_EDITING { warn "start editing\n"; }
294 sub EDITING_DONE { warn "editing done\n"; }
295 sub REMOVE_WIDGET { warn "remove widget\n"; }
296
298 GObject - http://developer.gnome.org/doc/API/2.0/gobject/
299
301 Marc Lehmann <schmorp@schmorp.de>, muppet <scott at asofyet dot org>
302
304 Copyright 2003-2004 by muppet and the gtk2-perl team
305 This library is free software; you can redistribute it and/or modify it
307 under the terms of the Lesser General Public License (LGPL). For more
308 information, see http://www.fsf.org/licenses/lgpl.txt
309perl v5.12.1 2010-05-30 Subclass(3)