|
NAMEGlib::Object::Subclass - register a perl class as a GObject classSYNOPSISuse Glib::Object::Subclass Some::Base::Class::, # parent class, derived from Glib::Object signals => { something_changed => { class_closure => sub { do_something_fun () }, flags => [qw(run-first)], return_type => undef, param_types => [], }, some_existing_signal => \&class_closure_override, }, properties => [ Glib::ParamSpec->string ( 'some_string', 'Some String Property', 'This property is a string that is used as an example', 'default value', [qw/readable writable/] ), ]; DESCRIPTIONThis module allows you to create your own GObject classes, which is useful to e.g. implement your own Gtk2 widgets.It doesn't "export" anything into your namespace, but acts more like a pragmatic module that modifies your class to make it work as a GObject class. You may be wondering why you can't just bless a Glib::Object into a different package and add some subs. Well, if you aren't interested in object parameters, signals, or having your new class interoperate transparently with other GObject-based modules (e.g., Gtk2 and friends), then you can just re-bless. However, a GObject's signals, properties, virtual functions, and GInterface implementations are specific to its GObjectClass. If you want to create a new GObject which was a derivative of GtkDrawingArea, but adds a new signal, you must create a new GObjectClass to which to add the new signal. If you don't, then all of the GtkDrawingAreas in your application will get that new signal! Thus, the only way to create a new signal or object property in the Perl bindings for Glib is to register a new subclass with the GLib type system via Glib::Type::register_object(). The Glib::Object::Subclass module is a Perl-developer-friendly interface to this bit of paradigm mismatch. USAGEThis module works similar to the "use base" pragma in that it registers the current package as a subclass of some other class (which must be a GObjectClass implemented either in C or some other language).The pragma requires at least one argument, the parent class name. The remaining arguments are key/value pairs, in any order, all optional:
(Actually, these parameters are all passed straight through to Glib::Type::register_object(), adding __PACKAGE__ (the current package name) as the name of the new child class.) OBJECT METHODS AND FUNCTIONSThe following methods are either added to your class on request (not yet implemented), or by default unless your own class implements them itself. This means that all these methods and functions will get sensible default implementations unless explicitly overwritten by you (by defining your own version).Except for "new", all of the following are functions and no methods. That means that you should not call the superclass method. Instead, the GObject system will call these functions per class as required, emulating normal inheritance.
PROPERTIESTo create gobject properties, supply a list of Glib::ParamSpec objects as the value for the key 'properties'. There are lots of different paramspec constructors, documented in the C API reference's Parameters and Values page, as well as Glib::ParamSpec.As of Glib 1.060, you can also specify explicit getters and setters for your properties at creation time. The default values in your properties are also honored if you don't set anything else. See Glib::Type::register_object in Glib::Type for an example. SIGNALSCreating new signals for your new object is easy. Just provide a hash of signal names and signal descriptions under the key 'signals'. Each signal description is also a hash, with a few expected keys. All the keys are allowed to default.
OVERRIDING BASE METHODSGLib pulls some fancy tricks with function pointers to implement methods in C. This is not very language-binding-friendly, as you might guess.However, as described above, every signal allows a "class closure"; you may override the class closure with your own function, and you can chain from the overridden method to the original. This serves to implement virtual overrides for language bindings. So, to override a method, you supply a subroutine reference instead of a signal description hash as the value for the name of the existing signal in the "signals" hash described in "SIGNALS". # override some important widget methods: use Glib::Object::Subclass Gtk2::Widget::, signals => { expose_event => \&expose_event, configure_event => \&configure_event, button_press_event => \&button_press_event, button_release_event => \&button_release_event, motion_notify_event => \&motion_notify_event, # note the choice of names here... see the discussion. size_request => \&do_size_request, } It's important to note that the handlers you supply for these are class-specific, and that normal perl method inheritance rules are not followed to invoke them from within the library. However, perl code can still find them! Therefore it's rather important that you choose your handlers' names carefully, avoiding any public interfaces that you might call from perl. Case in point, since size_request is a widget method, i chose do_size_request as the override handler. INTERFACESGObject supports only single inheritance; in place of multiple inheritance, GObject uses GInterfaces. In the Perl bindings we have mostly masqueraded this with multiple inheritance (that is, simply adding the GInterface class to the @ISA of the implementing class), but in deriving new objects the facade breaks and the magic leaks out.In order to derive an object that implements a GInterface, you have to tell the GLib type system you want your class to include a GInterface. To do this, simply pass a list of package names through the "interfaces" key; this will add these packages to your @ISA, and cause perl to invoke methods that you must provide. package Mup::MultilineEntry; use Glib::Object::Subclass 'Gtk2::TextView', interfaces => [ 'Gtk2::CellEditable' ], ; # perl will now invoke these methods, which are part of the # GtkCellEditable GInterface, when somebody invokes the # corresponding lower-case methods on your objects. sub START_EDITING { warn "start editing\n"; } sub EDITING_DONE { warn "editing done\n"; } sub REMOVE_WIDGET { warn "remove widget\n"; } SEE ALSOGObject - http://developer.gnome.org/doc/API/2.0/gobject/ AUTHORSMarc Lehmann <schmorp@schmorp.de>, muppet <scott at asofyet dot org>COPYRIGHT AND LICENSECopyright 2003-2004, 2010 by muppet and the gtk2-perl teamThis library is free software; you can redistribute it and/or modify it under the terms of the Lesser General Public License (LGPL). For more information, see http://www.fsf.org/licenses/lgpl.txt
Visit the GSP FreeBSD Man Page Interface. |