1Glib::Object::Subclass(U3s)er Contributed Perl DocumentatGiloinb::Object::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 Care must be taken with boxed non-reference-counted types such as
143 "Gtk2::Gdk::Color". In "SET_PROPERTY" the $newval is generally
144 good only for the duration of the call. Use "copy" or similar if
145 keeping it longer (see Glib::Boxed). In "GET_PROPERTY" the
146 returned memory must last long enough to reach the caller, which
147 generally means returning a field, not a newly created object
148 (which is destroyed with the scalar holding it).
149 "GET_PROPERTY" is different from a C get_property method in that
151 the perl method returns the retrieved value. For symmetry, the
152 $newval and $pspec args on "SET_PROPERTY" are swapped from the C
153 usage.
154 FINALIZE_INSTANCE $self [not a method]
156 "FINALIZE_INSTANCE" is called as the GObject is being finalized,
157 that is, as it is being really destroyed. This is independent of
158 the more common DESTROY on the perl object; in fact, you must NOT
159 override "DESTROY" (it's not useful to you, in any case, as it is
160 being called multiple times!).
161 Use this hook to release anything you have to clean up manually.
163 FINALIZE_INSTANCE will be called for each perl instance, in reverse
164 order of construction.
165 The default finalizer does nothing.
167 $object->DESTROY [DO NOT OVERWRITE]
169 Don't ever overwrite "DESTROY", use "FINALIZE_INSTANCE" instead.
170 The DESTROY method of all perl classes derived from GTypes is
172 implemented in the Glib module and (ab-)used for its own internal
173 purposes. Overwriting it is not useful as it will be called
174 multiple times, and often long before the object actually gets
175 destroyed. Overwriting might be very harmful to your program, so
176 never do that. Especially watch out for other classes in your ISA
177 tree.
178
180 To create gobject properties, supply a list of Glib::ParamSpec objects
181 as the value for the key 'properties'. There are lots of different
182 paramspec constructors, documented in the C API reference's Parameters
183 and Values page, as well as Glib::ParamSpec.
184 As of Glib 1.060, you can also specify explicit getters and setters for
186 your properties at creation time. The default values in your
187 properties are also honored if you don't set anything else. See
188 Glib::Type::register_object in Glib::Type for an example.
189
191 Creating new signals for your new object is easy. Just provide a hash
192 of signal names and signal descriptions under the key 'signals'. Each
193 signal description is also a hash, with a few expected keys. All the
194 keys are allowed to default.
195 flags => GSignalFlags
197 If not present, assumed to be 'run-first'.
198 param_types => reference to a list of package names
200 If not present, assumed to be empty (no parameters).
201 class_closure => reference to a subroutine to call as the class
203 closure.
204 may also be a string interpreted as the name of a subroutine to
205 call, but you should be very very very careful about that.
206 If not present, the library will attempt to call the method named
208 "do_signal_name" for the signal "signal_name" (uses underscores).
209 You'll want to be careful not to let this handler method be a
211 publically callable method, or one that has the name name as
212 something that emits the signal. Due to the funky ways in which
213 Glib is different from Perl, the class closures should not inherit
214 through normal perl inheritance.
215 return_type => package name for return value.
217 If undefined or not present, the signal expects no return value.
218 if defined, the signal is expected to return a value; flags must be
219 set such that the signal does not run only first (at least use
220 'run-last').
221 accumulator => signal return value accumulator
223 quoting the Glib manual: "The signal accumulator is a special
224 callback function that can be used to collect return values of the
225 various callbacks that are called during a signal emission."
226 If not specified, the default accumulator is used, and you just get
228 the return value of the last handler to run.
229 Accumulators are not really documented very much in the C
231 reference, and the perl interface here is slightly different, so
232 here's an inordinate amount of detail for this arcane feature:
233 The accumulator function is called for every handler as
235 ($cont, $acc) = &$func ($invocation_hint, $acc, $ret)
237 $invocation_hint is an anonymous hash (including the signal name);
239 $acc is the current accumulated return value; $ret is the value
240 from the most recent handler.
241 The two return values are a boolean $cont for whether signal
243 emission should continue (false to stop); and a new $acc
244 accumulated return value. (This is different from the C version,
245 which writes through a return_accu.)
246
248 GLib pulls some fancy tricks with function pointers to implement
249 methods in C. This is not very language-binding-friendly, as you might
250 guess.
251 However, as described above, every signal allows a "class closure"; you
253 may override the class closure with your own function, and you can
254 chain from the overridden method to the original. This serves to
255 implement virtual overrides for language bindings.
256 So, to override a method, you supply a subroutine reference instead of
258 a signal description hash as the value for the name of the existing
259 signal in the "signals" hash described in "SIGNALS".
260 # override some important widget methods:
262 use Glib::Object::Subclass
263 Gtk2::Widget::,
264 signals => {
265 expose_event => \&expose_event,
266 configure_event => \&configure_event,
267 button_press_event => \&button_press_event,
268 button_release_event => \&button_release_event,
269 motion_notify_event => \&motion_notify_event,
270 # note the choice of names here... see the discussion.
271 size_request => \&do_size_request,
272 }
273 It's important to note that the handlers you supply for these are
275 class-specific, and that normal perl method inheritance rules are not
276 followed to invoke them from within the library. However, perl code
277 can still find them! Therefore it's rather important that you choose
278 your handlers' names carefully, avoiding any public interfaces that you
279 might call from perl. Case in point, since size_request is a widget
280 method, i chose do_size_request as the override handler.
281
283 GObject supports only single inheritance; in place of multiple
284 inheritance, GObject uses GInterfaces. In the Perl bindings we have
285 mostly masqueraded this with multiple inheritance (that is, simply
286 adding the GInterface class to the @ISA of the implementing class), but
287 in deriving new objects the facade breaks and the magic leaks out.
288 In order to derive an object that implements a GInterface, you have to
290 tell the GLib type system you want your class to include a GInterface.
291 To do this, simply pass a list of package names through the
292 "interfaces" key; this will add these packages to your @ISA, and cause
293 perl to invoke methods that you must provide.
294 package Mup::MultilineEntry;
296 use Glib::Object::Subclass
297 'Gtk2::TextView',
298 interfaces => [ 'Gtk2::CellEditable' ],
299 ;
300 # perl will now invoke these methods, which are part of the
302 # GtkCellEditable GInterface, when somebody invokes the
303 # corresponding lower-case methods on your objects.
304 sub START_EDITING { warn "start editing\n"; }
305 sub EDITING_DONE { warn "editing done\n"; }
306 sub REMOVE_WIDGET { warn "remove widget\n"; }
307
309 GObject - http://developer.gnome.org/doc/API/2.0/gobject/
310
312 Marc Lehmann <schmorp@schmorp.de>, muppet <scott at asofyet dot org>
313
315 Copyright 2003-2004, 2010 by muppet and the gtk2-perl team
316 This library is free software; you can redistribute it and/or modify it
318 under the terms of the Lesser General Public License (LGPL). For more
319 information, see http://www.fsf.org/licenses/lgpl.txt
320perl v5.38.0 2023-08-01 Glib::Object::Subclass(3)