.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Glib::Type 3pm"
.TH Glib::Type 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Glib::Type \-  Utilities for dealing with the GLib Type system
.SH DESCRIPTION
.IX Header "DESCRIPTION"
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 \f(CW\*(C`Glib::Type::register*\*(C'\fR functions, which register
new types with the GLib type system.
.PP
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).
.SH METHODS
.IX Header "METHODS"
.SS "list = Glib::Type\->\fBlist_ancestors\fP ($package)"
.IX Subsection "list = Glib::Type->list_ancestors ($package)"
.IP \(bu 4
\&\f(CW$package\fR (string)
.PP
List the ancestry of \fIpackage\fR, as seen by the GLib type system.  The
important difference is that GLib's type system implements only single
inheritance, whereas Perl's \f(CW@ISA\fR allows multiple inheritance.
.PP
This returns the package names of the ancestral types in reverse order, with
the root of the tree at the end of the list.
.PP
See also list_interfaces ().
.SS "list = Glib::Type\->\fBlist_interfaces\fP ($package)"
.IX Subsection "list = Glib::Type->list_interfaces ($package)"
.IP \(bu 4
\&\f(CW$package\fR (string)
.PP
List the GInterfaces implemented by the type associated with \fIpackage\fR.
The interfaces are returned as package names.
.SS "list = Glib::Type\->\fBlist_signals\fP ($package)"
.IX Subsection "list = Glib::Type->list_signals ($package)"
.IP \(bu 4
\&\f(CW$package\fR (string)
.PP
List the signals associated with \fIpackage\fR.  This lists only the signals
for \fIpackage\fR, 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.
.IP "\- signal_id" 4
.IX Item "- signal_id"
Numeric id of a signal.  It's rare that you'll need this in Gtk2\-Perl.
.IP "\- signal_name" 4
.IX Item "- signal_name"
Name of the signal, such as what you'd pass to \f(CW\*(C`signal_connect\*(C'\fR.
.IP "\- itype" 4
.IX Item "- itype"
The \fIi\fRnstance \fItype\fR for which this signal is defined.
.IP "\- signal_flags" 4
.IX Item "- signal_flags"
GSignalFlags describing this signal.
.IP "\- return_type" 4
.IX Item "- return_type"
The return type expected from handlers for this signal.  If undef or not
present, then no return is expected.  The type name is mapped to the 
corresponding Perl package name if it is known, otherwise you get the
raw C name straight from GLib.
.IP "\- param_types" 4
.IX Item "- param_types"
The types of the parameters passed to any callbacks connected to the emission
of this signal.  The list does not include the instance, which is always
first, and the user data from \f(CW\*(C`signal_connect\*(C'\fR, which is always last (unless
the signal was connected with "swap", which swaps the instance and the data,
but you get the point).
.SS "list = Glib::Type\->\fBlist_values\fP ($package)"
.IX Subsection "list = Glib::Type->list_values ($package)"
.IP \(bu 4
\&\f(CW$package\fR (string)
.PP
List the legal values for the GEnum or GFlags type \fR\f(CI$package\fR\fI\fR.  If \fI\fR\f(CI$package\fR\fI\fR
is not a package name registered with the bindings, this name is passed on to
\&\fBg_type_from_name()\fR to see if it's a registered flags or enum type that just
hasn't been registered with the bindings by \f(CWgperl_register_fundamental()\fR
(see Glib::xsapi).  If \fI\fR\f(CI$package\fR\fI\fR is not the name of an enum or flags type,
this function will croak.
.PP
Returns the values as a list of hashes, one hash for each value, containing
the value, name and nickname, eg. for Glib::SignalFlags
.PP
.Vb 4
\&    { value => 8,
\&      name  => \*(AqG_SIGNAL_NO_RECURSE\*(Aq,
\&      nick  => \*(Aqno\-recurse\*(Aq
\&    }
.Ve
.SS "string = Glib::Type\->\fBpackage_from_cname\fP ($cname)"
.IX Subsection "string = Glib::Type->package_from_cname ($cname)"
.IP \(bu 4
\&\f(CW$cname\fR (string)
.PP
Convert a C type name to the corresponding Perl package name.  If no package
is registered to that type, returns \fR\f(CI$cname\fR\fI\fR.
.ie n .SS "Glib::Type\->\fBregister\fP ($parent_class, $new_class, ...)"
.el .SS "Glib::Type\->\fBregister\fP ($parent_class, \f(CW$new_class\fP, ...)"
.IX Subsection "Glib::Type->register ($parent_class, $new_class, ...)"
.IP \(bu 4
\&\f(CW$parent_class\fR (package) type from which to derive
.IP \(bu 4
\&\f(CW$new_class\fR (package) name of new type
.IP \(bu 4
\&... (list) arguments for creation
.PP
Register a new type with the GLib type system.
.PP
This is a traffic-cop function.  If \fR\f(CI$parent_type\fR\fI\fR derives from Glib::Object,
this passes the arguments through to \f(CW\*(C`register_object\*(C'\fR.  If \fI\fR\f(CI$parent_type\fR\fI\fR
is Glib::Flags or Glib::Enum, this strips \fI\fR\f(CI$parent_type\fR\fI\fR and passes the
remaining args on to \f(CW\*(C`register_enum\*(C'\fR or \f(CW\*(C`register_flags\*(C'\fR.  See those
functions' documentation for more information.
.SS "Glib::Type\->\fBregister_enum\fP ($name, ...)"
.IX Subsection "Glib::Type->register_enum ($name, ...)"
.IP \(bu 4
\&\f(CW$name\fR (string) package name for new enum type
.IP \(bu 4
\&... (list) new enum's values; see description.
.PP
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
\&\f(CW\*(C`Glib::Type\->register\*(C'\fR or \f(CW\*(C`Glib::Object::Subclass\*(C'\fR.
.PP
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.
.PP
.Vb 7
\&  Glib::Type\->register_enum (\*(AqMyFoo::Bar\*(Aq,
\&          \*(Aqvalue\-one\*(Aq,            # assigned 1
\&          \*(Aqvalue\-two\*(Aq,            # assigned 2
\&          [\*(Aqvalue\-three\*(Aq => 15 ], # explicit 15
\&          [\*(Aqvalue\-four\*(Aq => 35 ],  # explicit 35
\&          \*(Aqvalue\-five\*(Aq,           # assigned 5
\&  );
.Ve
.PP
If you use the array-ref form, beware: the code performs no validation
for unique values.
.SS "Glib::Type\->\fBregister_flags\fP ($name, ...)"
.IX Subsection "Glib::Type->register_flags ($name, ...)"
.IP \(bu 4
\&\f(CW$name\fR (string) package name of new flags type
.IP \(bu 4
\&... (list) flag values, see discussion.
.PP
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
\&\f(CW\*(C`Glib::Type\->register\*(C'\fR or \f(CW\*(C`Glib::Object::Subclass\*(C'\fR.
.PP
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.
.PP
.Vb 7
\&  Glib::Type\->register_flags (\*(AqMyFoo::Baz\*(Aq,
\&           \*(Aqvalue\-one\*(Aq,               # assigned 1<<0
\&           \*(Aqvalue\-two\*(Aq,               # assigned 1<<1
\&           [\*(Aqvalue\-three\*(Aq => 1<<10 ], # explicit 1<<10
\&           [\*(Aqvalue\-four\*(Aq => 0x0f ],   # explicit 0x0f
\&           \*(Aqvalue\-five\*(Aq,              # assigned 1<<4
\&  );
.Ve
.PP
If you use the array-ref form, beware: the code performs no validation
for unique values.
.ie n .SS "Glib::Type\->\fBregister_object\fP ($parent_package, $new_package, ...)"
.el .SS "Glib::Type\->\fBregister_object\fP ($parent_package, \f(CW$new_package\fP, ...)"
.IX Subsection "Glib::Type->register_object ($parent_package, $new_package, ...)"
.IP \(bu 4
\&\f(CW$parent_package\fR (string) name of the parent package, which must be a derivative of Glib::Object.
.IP \(bu 4
\&\f(CW$new_package\fR (string) usually _\|_PACKAGE_\|_.
.IP \(bu 4
\&... (list) key/value pairs controlling how the class is created.
.PP
Register \fInew_package\fR as an officially GLib-sanctioned derivative of
the (GObject derivative) \fIparent_package\fR.  This automatically sets up
an \f(CW@ISA\fR entry for you, and creates a new GObjectClass under the hood.
.PP
The \fI...\fR parameters are key/value pairs, currently supporting:
.IP "signals => HASHREF" 4
.IX Item "signals => HASHREF"
The \f(CW\*(C`signals\*(C'\fR key contains a hash, keyed by signal names, which describes
how to set up the signals for \fInew_package\fR.
.Sp
If the value is a code reference, the named signal must exist somewhere in
\&\fIparent_package\fR 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 
\&\fInew_package\fR will be used.  (The function should not be inherited.)
.Sp
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:
.RS 4
.IP "class_closure => subroutine or undef" 4
.IX Item "class_closure => subroutine or undef"
Use this code reference (or sub name) as the class closure (that is, the 
default handler for the signal).  If not specified, "do_\fIsignal_name\fR",
in the current package, is used.
.IP "return_type => package name or undef" 4
.IX Item "return_type => package name or undef"
Return type for the signal.  If not specified, then the signal has void return.
.IP "param_types => ARRAYREF" 4
.IX Item "param_types => ARRAYREF"
Reference to a list of parameter types (package names), \fIomitting the instance
and user data\fR.  Callbacks connected to this signal will receive the instance
object as the first argument, followed by arguments with the types listed here,
and finally by any user data that was supplied when the callback was connected.
Not specifying this key is equivalent to supplying an empty list, which
actually means instance and maybe data.
.IP "flags => Glib::SignalFlags" 4
.IX Item "flags => Glib::SignalFlags"
Flags describing this signal's properties. See the GObject C API reference'
description of GSignalFlags for a complete description.
.IP "accumulator => subroutine or undef" 4
.IX Item "accumulator => subroutine or undef"
The signal accumulator is a special callback that can be used to collect return
values of the various callbacks that are called during a signal emission.
Generally, you can omit this parameter; custom accumulators are used to do
things like stopping signal propagation by return value or creating a list of
returns, etc.  See "SIGNALS" in Glib::Object::Subclass for details.
.RE
.RS 4
.RE
.IP "properties => ARRAYREF" 4
.IX Item "properties => ARRAYREF"
Array of Glib::ParamSpec objects, each describing an object property to add
to the new type.  These properties are available for use by all code that
can access the object, regardless of implementation language.  See
Glib::ParamSpec.  This list may be empty; if it is not, the functions
\&\f(CW\*(C`GET_PROPERTY\*(C'\fR and \f(CW\*(C`SET_PROPERTY\*(C'\fR in \fR\f(CI$new_package\fR\fI\fR 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.
.Sp
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:
.Sp
.Vb 10
\&   Glib::Type\->register_object (\*(AqGlib::Object\*(Aq, \*(AqFoo\*(Aq,
\&      properties => [
\&         # specified normally
\&         Glib::ParamSpec\->string (...),
\&         # specified explicitly
\&         {
\&            pspec => Glib::ParamSpec\->int (...),
\&            set => sub {
\&               my ($object, $newval) = @_;
\&               ...
\&            },
\&            get => sub {
\&               my ($object) = @_;
\&               ...
\&               return $val;
\&            },
\&         },
\&      ]
\&   );
.Ve
.Sp
You can mix the two declaration styles as you like.  If you have
individual \f(CW\*(C`get_foo\*(C'\fR / \f(CW\*(C`set_foo\*(C'\fR methods with the operative code for
a property then the \f(CW\*(C`get\*(C'\fR/\f(CW\*(C`set\*(C'\fR form is a handy way to go straight
to that.
.IP "interfaces => ARRAYREF" 4
.IX Item "interfaces => ARRAYREF"
Array of interface package names that the new object implements.  Interfaces
are the GObject way of doing multiple inheritance, thus, in Perl, the package
names will be prepended to \f(CW@ISA\fR and certain inheritable and overrideable
ALLCAPS methods will automatically be called whenever needed.  Which methods
exactly depends on the interface \-\- Gtk2::CellEditable for example uses
START_EDITING, EDITING_DONE, and REMOVE_WIDGET.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Glib
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2003\-2011 by the gtk2\-perl team.
.PP
This software is licensed under the LGPL.  See Glib for a full notice.