changes to Glib::Object

["muppet" <scott asofyet org>]

i just committed to CVS the results of a week's work and a good while of
discussion with marc lehmann on Glib::Object.  huge thanks to marc for his
time and insight!

three sections:
  what was: how it used to be
  what is: what has changed
  what will be: how the changes will affect your code

please feel free to comment!
if you want to play with this and can't get it from sourceforge, i'll have a
tarball on http://gtk2-perl.sourceforge.net/ later today (stay tuned).

WHAT WAS:

up to and including gtk2-perl 0.24, Glib represented GObjects as opaque
objects, a blessed reference to a scalar containing the address of the
GObject.  the perl object was a throwaway wrapper; you could and usually did
have more than one perl wrapper to a single GObject at a time.  this made
subclassing a little cumbersome, as all member variables had to be kept in
GObject data (set_data and get_data).


WHAT IS:

as of today (somewhere in the 0.25 series for Glib), Glib represents objects
as a combined perl/C object, visible from perl as a blessed hash reference. 
the pointer to the GObject is attached via SV magic[1] and is invisible from
perl; the hash is persistent, and once created it lives as long as the GObject
does.  this means that you can now store member variables and anything else
you want directly in the hash, and they will always be visible until the
object is destroyed.  (this was how gtk-perl worked.)  the ability to store
anything in the hash is important, because set_data and get_data are untyped
and it is very dangerous to assume they contain SVs, as the previous code did.

along with this change, comes a huge improvement in GObject subclassing.  it
is now very easy and very useful to create your own widgets (or any object) in
perl, complete with signals and type-checked object properties.  See the pod
for the brand new Glib::Object::Subclass, which explains the process in full.

since object wrappers are persistent, you always get the same wrapper, which
means that the overloaded == operator is no longer necessary.  this removes
AMAGIC from Glib::Objects, making everything slightly faster.  ;)


WHAT WILL BE:

a little work up front paid off, and we've made this change almost entirely
transparent.  things will just be better when you upgrade Glib.

however, there are a few API breakages, mostly in esoteric things, so the next
release of Gtk2 will require you to upgrade to the newest Glib.

here's the rundown:
- IMPORTANT: $object->set_data and get_data now store ONLY integer or string
  data, not perl scalars!  in the next release these functions will emit
  warnings when you use them, to make sure you check your code.
  the replacement for this functionality is to store your data directly in
  the hash.  consider GObject data a way to communicate with C functions,
  not other perl functions.
- $object->eq method is gone.  you should've been using the overloaded
  == operator anyway.
- the call signature for Glib::Object::new has changed.  since subclassing
  was a bizarre and broken beast, i doubt anyone was using it, so we do not
  apologize.
- added bindings for most of the various GParamSpec constructors, in the
  Glib::ParamSpec module.  no docs yet, it's all XS, see the GLib C API
  reference.
- Glib::Type->register now accepts a list of Glib::ParamSpecs in the
  property key.
- the new module Glib::Object::Subclass takes away most of the pain of
  creating a new subclass by providing sensible defaults for the required
  functions, and documents how to do it.




[1] for the curious, i am not making this up.  MAGIC is the name of the
datatype representing various vtable-like operations you can do to scalars;
it's used for Ties, objects, and all sorts of other cool things.

-- 
muppet <scott at asofyet dot org>