The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

GObject

To deal with the intricate interaction of the different reference-counting semantics of Perl objects versus GObjects, the bindings create a combined PerlObject+GObject, with the GObject's pointer in magic attached to the Perl object, and the Perl object's pointer in the GObject's user data. Thus it's not really a "wrapper", but we refer to it as one, because "combined Perl object + GObject" is a cumbersome and confusing mouthful.

GObjects are represented as blessed hash references. The GObject user data mechanism is not typesafe, and thus is used only for unsigned integer values; the Perl-level hash is available for any type of user data. The combined nature of the wrapper means that data stored in the hash will stick around as long as the object is alive.

Since the C pointer is stored in attached magic, the C pointer is not available to the Perl developer via the hash object, so there's no need to worry about breaking it from perl.

Propers go to Marc Lehmann for dreaming most of this up.

void gperl_register_object (GType gtype, const char * package)

tell the GPerl type subsystem what Perl package corresponds with a given GObject by GType. automagically sets up @package::ISA for you.

note that @ISA will not be created for gtype until gtype's parent has been registered. if you are experiencing strange problems with a class' @ISA not being set up, change the order in which you register them.

void gperl_register_sink_func (GType gtype, GPerlObjectSinkFunc func)

Tell gperl_new_object() to use func to claim ownership of objects derived from gtype.

gperl_new_object() always refs a GObject when wrapping it for the first time. To have the Perl wrapper claim ownership of a GObject as part of gperl_new_object(), you unref the object after ref'ing it. however, different GObject subclasses have different ways to claim ownership; for example, GtkObject simply requires you to call gtk_object_sink(). To make this concept generic, this function allows you to register a function to be called when then wrapper should claim ownership of the object. The func registered for a given type will be called on any object for which g_type_isa (G_TYPE_OBJECT (object), type) succeeds.

If no sinkfunc is found for an object, g_object_unref() will be used.

Even though GObjects don't need sink funcs, we need to have them in Glib as a hook for upstream objects. If we create a GtkObject (or any other type of object which uses a different way to claim ownership) via Glib::Object->new, any upstream wrappers, such as gtk2perl_new_object(), will not be called. Having a sink func facility down here enables us always to do the right thing.

void gperl_object_set_no_warn_unreg_subclass (GType gtype, gboolean nowarn)

In versions 1.00 through 1.10x of Glib, the bindings required all types to be registered ahead of time. Upon encountering an unknown type, the bindings would emit a warning to the effect of "unknown type 'Foo'; representing as first known parent type 'Bar'". However, for some types, such as GtkStyle or GdkGC, the actual object returned is an instance of a child type of a private implementation (e.g., a theme engine ("BlueCurveStyle") or gdk backend ("GdkGCX11")); we neither can nor should have registered names for these types. Therefore, it is possible to tell the bindings not to warn about these unregistered subclasses, and simply represent them as the parent type.

With 1.12x, the bindings will automatically register unknown classes into the namespace Glib::Object::_Unregistered to avoid possible breakage resulting from unknown ancestors of known children. To preserve the old registered-as-unregistered behavior, the value installed by this function is used to prevent the _Unregistered mapping for such private backend classes.

Note: this assumes gtype has already been registered with gperl_register_object().

const char * gperl_object_package_from_type (GType gtype)

Get the package corresponding to gtype. If gtype is not a GObject or GInterface, returns NULL. If gtype is not registered to a package name, a new name of the form Glib::Object::_Unregistered::$c_type_name will be created, used to register the class, and then returned.

HV * gperl_object_stash_from_type (GType gtype)

Get the stash corresponding to gtype; returns NULL if gtype is not registered. The stash is useful for blessing.

GType gperl_object_type_from_package (const char * package)

Inverse of gperl_object_package_from_type(), returns 0 if package is not registered.

SV * gperl_new_object (GObject * object, gboolean own)

Use this function to get the perl part of a GObject. If object has never been seen by perl before, a new, empty perl object will be created and added to a private key under object's qdata. If object already has a perl part, a new reference to it will be created. The gobject + perl object together form a combined object that is properly refcounted, i.e. both parts will stay alive as long as at least one of them is alive, and only when both perl object and gobject are no longer referenced will both be freed.

The perl object will be blessed into the package corresponding to the GType returned by calling G_OBJECT_TYPE() on object; if that class has not been registered via gperl_register_object(), this function will emit a warning to that effect (with warn()), and attempt to bless it into the first known class in the object's ancestry. Since Glib::Object is already registered, you'll get a Glib::Object if you are lazy, and thus this function can fail only if object isn't descended from GObject, in which case it croaks. (In reality, if you pass a non-GObject to this function, you'll be lucky if you don't get a segfault, as there's not really a way to trap that.) In practice these warnings can be unavoidable, so you can use gperl_object_set_no_warn_unreg_subclass() to quell them on a class-by-class basis.

However, when perl code is calling a GObject constructor (any function which returns a new GObject), call gperl_new_object() with own set to %TRUE; this will cause the first matching sink function to be called on the GObject to claim ownership of that object, so that it will be destroyed when the perl object goes out of scope. The default sink func is g_object_unref(); other types should supply the proper function; e.g., GtkObject should use gtk_object_sink() here.

Returns the blessed perl object, or #&PL_sv_undef if object was #NULL.

GObject * gperl_get_object (SV * sv)

retrieve the GObject pointer from a Perl object. Returns NULL if sv is not linked to a GObject.

Note, this one is not safe -- in general you want to use gperl_get_object_check().

GObject * gperl_get_object_check (SV * sv, GType gtype);

croaks if sv is undef or is not blessed into the package corresponding to gtype. use this for bringing parameters into xsubs from perl. Returns the same as gperl_get_object() (provided it doesn't croak first).

SV * gperl_object_check_type (SV * sv, GType gtype)

Essentially the same as gperl_get_object_check().

FIXME this croaks if the types aren't compatible, but it would be useful if it just return FALSE instead.

typedef GObject GObject_noinc
typedef GObject GObject_ornull
newSVGObject(obj)
newSVGObject_noinc(obj)
SvGObject(sv)
SvGObject_ornull(sv)

Users shouldn't know this exists.

This is part of the machinery to support object tracking in a threaded environment. When perl spawns a new interpreter thread, it invokes CLONE on all packages -- NOT on objects. This is our only hook into that process.

DESCRIPTION

GObject is the base object class provided by the gobject library. It provides object properties with a notification system, and emittable signals.

Glib::Object is the corresponding Perl object class. Glib::Objects are represented by blessed hash references, with a magical connection to the underlying C object.

Instantiate a Glib::Object of type $class. Any key/value pairs in ... are used to set properties on the new object; see set. This is designed to be inherited by Perl-derived subclasses (see Glib::Object::Subclass), but you can actually use it to create any GObject-derived type.

Fetch and return the values for the object properties named in ....

Alias for get.

Set object properties.

Alias for set.

Emits a "notify" signal for the property $property on $object.

Stops emission of "notify" signals on $object. The signals are queued until thaw_notify is called on $object.

Reverts the effect of a previous call to freeze_notify. This causes all queued "notify" signals on $object to be emitted.

List all the object properties for $object_or_class_name; returns them as a list of hashes, containing these keys:

name
type
owner_type
descr

GObject provides an arbitrary data mechanism that assigns unsigned integers to key names. Functionality overlaps with the hash used as the Perl object instance, so we strongly recommend you use hash keys for your data storage. The GObject data values cannot store type information, so they are not safe to use for anything but integer values, and you really should use this method only if you know what you are doing.

Fetch the integer stored under the object data key $key. These values do not have types; type conversions must be done manually. See set_data.

Create a Perl Glib::Object reference for the C object pointed to by $pointer. You should need this very rarely; it's intended to support foreign objects.

NOTE: the cast from arbitrary integer to GObject may result in a core dump without warning, because the type-checking macro G_OBJECT() attempts to dereference the pointer to find a GTypeClass structure, and there is no portable way to validate the pointer.

Complement of new_from_pointer.

A special method avaiable to Glib::Object derivatives, it uses perl's tie facilities to associate hash keys with the properties of the object. For example:

  $button->tie_properties;
  # equivilent to $button->set (label => 'Hello World');
  $button->{label} = 'Hello World';
  print "the label is: ".$button->{label}."\n";

Attempts to write to read-only properties will croak, reading a write-only property will return '[write-only]'.

Care must be taken when using tie_properties with objects of types created with Glib::Object::Subclass as there may be clashes with existing hash keys that could cause infinite loops. The solution is to use custom property get/set functions to alter the storage locations of the properties.