| Next: Glib::Utils | Previous: Glib::Signal | [Gtk2-Perl - Table of Contents] | [Gtk2-Perl - Index] |
Glib::Type - Utilities for dealing with the GLib Type system
This package defines several utilities for dealing with the GLib type system
from Perl. Because of some fundamental differences in how the GLib and Perl
type systems work, a fair amount of the binding magic leaks out, and you can
find most of that in the Glib::Type::register* functions, which register
new types with the GLib type system.
Most of the rest of the functions provide introspection functionality, such as listing properties and values and other cool stuff that is used mainly by Glib's reference documentation generator (see Glib::GenPod).
List the ancestry of package, as seen by the GLib type system. The important difference is that GLib's type system implements only single inheritance, whereas Perl's @ISA allows multiple inheritance.
This returns the package names of the ancestral types in reverse order, with the root of the tree at the end of the list.
See also list_interfaces ().
List the GInterfaces implemented by the type associated with package. The interfaces are returned as package names.
List the signals associated with package. This lists only the signals for package, not any of its parents. The signals are returned as a list of anonymous hashes which mirror the GSignalQuery structure defined in the C API reference.
signal_connect.
signal_connect, which is always last (unless
the signal was connected with "swap", which swaps the instance and the data,
but you get the point).
List the legal values for the GEnum or GFlags type $package. If $package
is not a package name registered with the bindings, this name is passed on to
g_type_from_name() to see if it's a registered flags or enum type that just
hasn't been registered with the bindings by gperl_register_fundamental()
(see Glib::xsapi). If $package is not the name of an enum or flags type,
this function will croak.
Returns the values as a list of hashes, one hash for each value, containing the value, name and nickname, eg. for Glib::SignalFlags
{ value => 8,
name => 'G_SIGNAL_NO_RECURSE',
nick => 'no-recurse'
}
Convert a C type name to the corresponding Perl package name. If no package is registered to that type, returns $cname.
$parent_class (package) type from which to derive
$new_class (package) name of new type
... (list) arguments for creation
Register a new type with the GLib type system.
This is a traffic-cop function. If $parent_type derives from Glib::Object,
this passes the arguments through to register_object. If $parent_type
is Glib::Flags or Glib::Enum, this strips $parent_type and passes the
remaining args on to register_enum or register_flags. See those
functions' documentation for more information.
Register and initialize a new Glib::Enum type with the provided "values".
This creates a type properly registered GLib so that it can be used for
property and signal parameter or return types created with
Glib::Type->register or Glib::Object::Subclass.
The list of values is used to create the "nicknames" that are used in general Perl code; the actual numeric values used at the C level are automatically assigned, starting with 1. If you need to specify a particular numeric value for a nick, use an array reference containing the nickname and the numeric value, instead. You may mix and match the two styles.
Glib::Type->register_enum ('MyFoo::Bar',
'value-one', # assigned 1
'value-two', # assigned 2
['value-three' => 15 ], # explicit 15
['value-four' => 35 ], # explicit 35
'value-five', # assigned 5
);
If you use the array-ref form, beware: the code performs no validation for unique values.
Register and initialize a new Glib::Flags type with the provided "values".
This creates a type properly registered GLib so that it can be used for
property and signal parameter or return types created with
Glib::Type->register or Glib::Object::Subclass.
The list of values is used to create the "nicknames" that are used in general Perl code; the actual numeric values used at the C level are automatically assigned, of the form 1<<i, starting with i = 0. If you need to specify a particular numeric value for a nick, use an array reference containing the nickname and the numeric value, instead. You may mix and match the two styles.
Glib::Type->register_flags ('MyFoo::Baz',
'value-one', # assigned 1<<0
'value-two', # assigned 1<<1
['value-three' => 1<<10 ], # explicit 1<<10
['value-four' => 0x0f ], # explicit 0x0f
'value-five', # assigned 1<<4
);
If you use the array-ref form, beware: the code performs no validation for unique values.
$parent_package (string) name of the parent package, which must be a derivative of Glib::Object.
$new_package (string) usually __PACKAGE__.
... (list) key/value pairs controlling how the class is created.
Register new_package as an officially GLib-sanctioned derivative of the (GObject derivative) parent_package. This automatically sets up an @ISA entry for you, and creates a new GObjectClass under the hood.
The ... parameters are key/value pairs, currently supporting:
signals key contains a hash, keyed by signal names, which describes
how to set up the signals for new_package.
If the value is a code reference, the named signal must exist somewhere in parent_package or its ancestry; the code reference will be used to override the class closure for that signal. This is the officially sanctioned way to override virtual methods on Glib::Objects. The value may be a string rather than a code reference, in which case the sub with that name in new_package will be used. (The function should not be inherited.)
If the value is a hash reference, the key will be the name of a new signal created with the properties defined in the hash. All of the properties are optional, with defaults provided:
GET_PROPERTY and SET_PROPERTY in $new_package will be called to
get and set the values. Note that an object property is just a mechanism
for getting and setting a value -- it implies no storage. As a convenience,
however, Glib::Object provides fallbacks for GET_PROPERTY and SET_PROPERTY
which use the property nicknames as hash keys in the object variable for
storage.
Additionally, you may specify ParamSpecs as a describing hash instead of as an object; this form allows you to supply explicit getter and setter methods which override GET_PROPERY and SET_PROPERTY. The getter and setter are both optional in the hash form. For example:
Glib::Type->register_object ('Glib::Object', 'Foo',
properties => [
# specified normally
Glib::ParamSpec->string (...),
# specified explicitly
{
pspec => Glib::ParamSpec->int (...),
set => sub {
my ($object, $newval) = @_;
...
},
get => sub {
my ($object) = @_;
...
return $val;
},
},
]
);
You can mix the two declaration styles as you like.
Copyright (C) 2003-2009 by the gtk2-perl team.
This software is licensed under the LGPL. See Glib for a full notice.