NAME

Glib::Object::Subclass - register a perl class as a gobjectclass

SYNOPSIS

use Glib::Object::Subclass
   Glib::Object,        # parent class
   signals    =>
      {
          something_changed => {
             flags       => [qw(run-first)],
             return_type => undef,
             param_types => [],
          },

      },
   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/]
      ),
   ];

DESCRIPTION

This 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 GObjectClass.

There are three different issues that this module tries to solve:

• The gobject type and class system and the perl class system work slightly differently.

• Classes must be registered before they can be used.

• Some convenience methods to make GObjectClasses look more like normal perl objects.

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, and virtual functions are specific to its GObjectClass. If you want to create a new GObject which was a derivative of GtkDrawingArea, but added 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 Glib::Type. This module is a perl-developer-friendly interface to this bit of paradigm mismatch.

USAGE

This 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).

TODO: document it.

OBJECT METHODS AND FUNCTIONS

The 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.

$class->new (attr => value, ...)

The default constructor just calls Glib::Object::new, which allows you to set properties on the newly created object. This is done because many new methods inherited by Gtk2 or other libraries don't have new methods suitable for subclassing.

INIT_INSTANCE $self [not a method]

INIT_INSTANCE is called on each class in the hierarchy as the object is being created (i.e., from Glib::Object::new or our default new). Use this function to initialize any member data. The default implementation will leave the object untouched.

GET_PROPERTY $self, $pspec [not a method]

Get a property value, see SET_PROPERTY.

The default implementation looks like this:

my ($self, $pspec) = @_;
return $self->{$pspec->get_name};

SET_PROPERTY $self, $newval [not a method]

GET_PROPERTY and SET_PROPERTY are called whenever somebody does $object->get ($propname) or $object->set ($propname => $newval) (from other languages, too). This is your hook that allows you to store/fetch properties in any way you need to (maybe you have to calculate something or read a file).

GET_PROPERTY is different from a C get_property method in that the perl method returns the retrieved value. For symmetry, the $newval and $pspec args on SET_PROPERTY are swapped from the C usage. The default get and set methods store property data in the object as hash values named for the parameter name.

The default SET_PROPERTY looks like this:

my ($self, $pspec, $newval) = @_;
$self->{$pspec->get_name} = $newval;

FINALIZE_INSTANCE $self [not a method]

FINALIZE_INSTANCE is called as the GObject is being finalized, that is, as it's being really destroyed. This is independent of the more common DESTROY on the perl object; in fact, you must NOT override DESTROY (it's not useful to you, in any case, as it is being called multiple times!).

Use this hook to release anything you have to clean up manually. FINALIZE_INSTANCE will be called for each perl instance, in reverse order of construction.

The default finalizer does nothing.

$object->DESTROY [DO NOT OVERWRITE]

Don't ever overwrite DESTROY, use FINALIZE_INSTANCE instead.

The DESTROY method of all perl classes derived from GTypes is implemented in the Glib module and (ab-)used for it's own internal purposes. Overwriting it is not useful as it will be called multiple times, and often long before the object actually gets destroyed. Overwriting might be very harmful to your program, so never do that. Especially watch out for other classes in your ISA tree.

SEE ALSO

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

AUTHORS

Marc Lehmann <pcg@goof.com>, muppet <scott at asofyet dot org>

COPYRIGHT AND LICENSE

Copyright 2003 by muppet and the gtk2-perl team

This 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