1Glib::Object::Subclass(U3s)er Contributed Perl DocumentatGiloinb::Object::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
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
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       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
62       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
65       - properties => []
66           Add object properties; see "PROPERTIES".
67
68       - signals => {}
69           Add or override signals; see "SIGNALS" and "OVERRIDING BASE
70           METHODS".
71
72       - interfaces => []
73           Add GInterfaces to your class; see "INTERFACES".
74
75       (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
79   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
86       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
91       $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
97       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
103       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
110              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
121           Because "$pspec->get_name" converts hyphens to underscores, a
122           property "line-style" is in the hash as "line_style".
123
124           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
128           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
132              sub SET_PROPERTY {
133                my ($self, $pspec, $newval) = @_;
134                my $pname = $pspec->get_name
135                $self->{$pname} = $newval; # ready for default GET_PROPERTY
136
137                if ($pname eq 'line_style') {
138                  $self->queue_draw;  # redraw with new lines
139                }
140              }
141
142           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
150           "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
155       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
162           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
166           The default finalizer does nothing.
167
168       $object->DESTROY           [DO NOT OVERWRITE]
169           Don't ever overwrite "DESTROY", use "FINALIZE_INSTANCE" instead.
170
171           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

PROPERTIES

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

SIGNALS

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
196       flags => GSignalFlags
197           If not present, assumed to be 'run-first'.
198
199       param_types => reference to a list of package names
200           If not present, assumed to be empty (no parameters).
201
202       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
207           If not present, the library will attempt to call the method named
208           "do_signal_name" for the signal "signal_name" (uses underscores).
209
210           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
216       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
222       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
227           If not specified, the default accumulator is used, and you just get
228           the return value of the last handler to run.
229
230           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
234           The accumulator function is called for every handler as
235
236               ($cont, $acc) = &$func ($invocation_hint, $acc, $ret)
237
238           $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
242           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

OVERRIDING BASE METHODS

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
252       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
257       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
261         # 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
274       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

INTERFACES

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
289       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
295         package Mup::MultilineEntry;
296         use Glib::Object::Subclass
297             'Gtk2::TextView',
298             interfaces => [ 'Gtk2::CellEditable' ],
299             ;
300
301         # 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

SEE ALSO

309         GObject - http://developer.gnome.org/doc/API/2.0/gobject/
310

AUTHORS

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
317       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
320
321
322
323perl v5.32.1                      2021-01-27         Glib::Object::Subclass(3)
Impressum