view release on metacpan or  search on metacpan

devel.pod  view on Meta::CPAN

 /* collapse a list of strings to an integer with all the
  * correct bits set, croak if anything is invalid. */
 gint gperl_convert_flags (GType type, SV * val);

 /* convert a bitfield to a list of strings, or croak. */
 SV * gperl_convert_back_flags (GType type, gint val);

Other utility functions allow for finer-grained control, such as the ability to
pass unknown values, which can be necessary in special cases.  In general, each
of these functions raises an exception when something goes wrong.  To be
helpful, they croak with a message listing the valid values when they encounter
invalid input.

=head2 GBoxed 

GBoxed provides a way to register functions that create, copy, and destroy
opaque structures.  For our purposes, we'll allow any perl package to inherit
from Glib::Boxed and implement accessors for the struct members, but
Glib::Boxed will handle the object and wrapper lifetime issues.

There are two functions for creating boxed wrappers:

 SV * gperl_new_boxed (gpointer boxed, GType gtype, gboolean own);
 SV * gperl_new_boxed_copy (gpointer boxed, GType gtype);

If own is TRUE, the wrapper returned by gperl_new_boxed will take boxed with it
when it dies.  In the case of a copy, own is implied, so there's a separate
function which doesn't need the own option.

To get a boxed pointer out of a scalar wrapper, you just call
gperl_get_boxed_check --- this will croak if the sv is undef or not blessed
into the specified package.

When you register a boxed type you get the option of supplying a table of
function pointers describing how the boxed object should be wrapped, unwrapped,
and destroyed.  This allows you to decide in the wrapping function what
subclass of the boxed type's class the wrapper should actually take (a trick
used by Gtk2::Gdk::Event), or represent a boxed type as a native perl type
(such as using array references for Gnome2::Canvas::Point objects).  All of
this happens automagically, behind the scenes, and most types assume the
default wrapper class.

See the commentary in gperl.h for more information.

=head2 GObject 

The GObject knows its own type.  Thus, we need only one parameter to create a
GObject wrapper.  In reality, we ask for two:

 SV * gperl_new_object (GObject * object, gboolean own);

The wrapper SV will be blessed into the package corresponding to the gtype
returned by G_OBJECT_TYPE (object), that is, the bottommost type in the
inheritance chain.  If that bottommost type is not known, the function walks
back up the tree until it finds one that's known, blesses the reference into
that package, and spits out a warning on stderr.  To hush the warning, you need
merely call

In general, this process will claim a reference on the GObject (with
g_object_ref()), so that the C object stays alive so long as there is a perl
wrapper for it.  If <i>own</i> is set to TRUE, the perl wrapper will claim
ownership of the C object by removing that reference; in theory, for a new
GObject, fresh from a constructor, this leaves the object with a single
reference owned by the perl object.  The next question out of your mouth should
be, "But what about GObject derivatives that require sinking or other strange
methods to claim ownership?"  For the answer, see the GtkObject section's
description of sink functions.

 void gperl_register_object (GType gtype, const char * package);

This magical function also sets up the @ISA for the package to point to the
package corresponding to g_type_parent (gtype).  [Since this requires the
parent package to be registered, there is a simple deferral mechanism, which
means your @ISA might not be set until the next call to gperl_register_object.]


There are two ways to get an object out of an SV (though I think only one is
really needed):

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

The second one is like the first, but croaks if the object is not derived from
gtype.

You can get and set object data and object parameters just like you'd expect.

=head2 GSignal 

All of this GObject stuff wouldn't be very useful if you couldn't connect
signals and closures.  I got most of my handling code from gtk2-perl and pygtk,
and it's pretty straightforward.  The data member is optional, and must be a
scalar.

To connect perl subroutines to GSignals I use GClosures, which require the
handling of GValues.

=head2 GPerlClosure

Use a GPerlClosure wherever you could use a GClosure and things should work out
great.  I<FIXME say more here>

=head2 GPerlCallback

Function pointers are required in many places throughout gtk+, usually for a
callback to be used as a "foreach" function or for some other purpose.
Unfortunately, a majority of these spots aren't designed to work with GClosures
(usually by lacking a way to destroy data associated with the callback when it
is no longer needed).  For this purpose, the GPerlCallback wraps up the
gruntwork of using perl's call_sv to use a callback function directly.

=head1 SEE ALSO

perl(1), perlxs(1), perlguts(1), perlapi(1), perlxstut(1),
L<ExtUtils::Depends>(3pm), L<ExtUtils::PkgConfig>(3pm)
L<Glib>(3pm), L<Glib::Object::Subclass>(3pm), L<Glib::xsapi>(3pm)

=head1 AUTHOR

muppet E<lt>scott at asofyet.orgE<gt>