1Glib::Type(3)         User Contributed Perl Documentation        Glib::Type(3)
2
3
4

NAME

6       Glib::Type -  Utilities for dealing with the GLib Type system
7

DESCRIPTION

9       This package defines several utilities for dealing with the GLib type
10       system from Perl.  Because of some fundamental differences in how the
11       GLib and Perl type systems work, a fair amount of the binding magic
12       leaks out, and you can find most of that in the "Glib::Type::register*"
13       functions, which register new types with the GLib type system.
14
15       Most of the rest of the functions provide introspection functionality,
16       such as listing properties and values and other cool stuff that is used
17       mainly by Glib's reference documentation generator (see Glib::GenPod).
18

METHODS

20   list = Glib::Type->list_ancestors ($package)
21       •   $package (string)
22
23       List the ancestry of package, as seen by the GLib type system.  The
24       important difference is that GLib's type system implements only single
25       inheritance, whereas Perl's @ISA allows multiple inheritance.
26
27       This returns the package names of the ancestral types in reverse order,
28       with the root of the tree at the end of the list.
29
30       See also list_interfaces ().
31
32   list = Glib::Type->list_interfaces ($package)
33       •   $package (string)
34
35       List the GInterfaces implemented by the type associated with package.
36       The interfaces are returned as package names.
37
38   list = Glib::Type->list_signals ($package)
39       •   $package (string)
40
41       List the signals associated with package.  This lists only the signals
42       for package, not any of its parents.  The signals are returned as a
43       list of anonymous hashes which mirror the GSignalQuery structure
44       defined in the C API reference.
45
46       - signal_id
47           Numeric id of a signal.  It's rare that you'll need this in
48           Gtk2-Perl.
49
50       - signal_name
51           Name of the signal, such as what you'd pass to "signal_connect".
52
53       - itype
54           The instance type for which this signal is defined.
55
56       - signal_flags
57           GSignalFlags describing this signal.
58
59       - return_type
60           The return type expected from handlers for this signal.  If undef
61           or not present, then no return is expected.  The type name is
62           mapped to the corresponding Perl package name if it is known,
63           otherwise you get the raw C name straight from GLib.
64
65       - param_types
66           The types of the parameters passed to any callbacks connected to
67           the emission of this signal.  The list does not include the
68           instance, which is always first, and the user data from
69           "signal_connect", which is always last (unless the signal was
70           connected with "swap", which swaps the instance and the data, but
71           you get the point).
72
73   list = Glib::Type->list_values ($package)
74       •   $package (string)
75
76       List the legal values for the GEnum or GFlags type $package.  If
77       $package is not a package name registered with the bindings, this name
78       is passed on to g_type_from_name() to see if it's a registered flags or
79       enum type that just hasn't been registered with the bindings by
80       gperl_register_fundamental() (see Glib::xsapi).  If $package is not the
81       name of an enum or flags type, this function will croak.
82
83       Returns the values as a list of hashes, one hash for each value,
84       containing the value, name and nickname, eg. for Glib::SignalFlags
85
86           { value => 8,
87             name  => 'G_SIGNAL_NO_RECURSE',
88             nick  => 'no-recurse'
89           }
90
91   string = Glib::Type->package_from_cname ($cname)
92       •   $cname (string)
93
94       Convert a C type name to the corresponding Perl package name.  If no
95       package is registered to that type, returns $cname.
96
97   Glib::Type->register ($parent_class, $new_class, ...)
98       •   $parent_class (package) type from which to derive
99
100       •   $new_class (package) name of new type
101
102       •   ... (list) arguments for creation
103
104       Register a new type with the GLib type system.
105
106       This is a traffic-cop function.  If $parent_type derives from
107       Glib::Object, this passes the arguments through to "register_object".
108       If $parent_type is Glib::Flags or Glib::Enum, this strips $parent_type
109       and passes the remaining args on to "register_enum" or
110       "register_flags".  See those functions' documentation for more
111       information.
112
113   Glib::Type->register_enum ($name, ...)
114       •   $name (string) package name for new enum type
115
116       •   ... (list) new enum's values; see description.
117
118       Register and initialize a new Glib::Enum type with the provided
119       "values".  This creates a type properly registered GLib so that it can
120       be used for property and signal parameter or return types created with
121       "Glib::Type->register" or "Glib::Object::Subclass".
122
123       The list of values is used to create the "nicknames" that are used in
124       general Perl code; the actual numeric values used at the C level are
125       automatically assigned, starting with 1.  If you need to specify a
126       particular numeric value for a nick, use an array reference containing
127       the nickname and the numeric value, instead.  You may mix and match the
128       two styles.
129
130         Glib::Type->register_enum ('MyFoo::Bar',
131                 'value-one',            # assigned 1
132                 'value-two',            # assigned 2
133                 ['value-three' => 15 ], # explicit 15
134                 ['value-four' => 35 ],  # explicit 35
135                 'value-five',           # assigned 5
136         );
137
138       If you use the array-ref form, beware: the code performs no validation
139       for unique values.
140
141   Glib::Type->register_flags ($name, ...)
142       •   $name (string) package name of new flags type
143
144       •   ... (list) flag values, see discussion.
145
146       Register and initialize a new Glib::Flags type with the provided
147       "values".  This creates a type properly registered GLib so that it can
148       be used for property and signal parameter or return types created with
149       "Glib::Type->register" or "Glib::Object::Subclass".
150
151       The list of values is used to create the "nicknames" that are used in
152       general Perl code; the actual numeric values used at the C level are
153       automatically assigned, of the form 1<<i, starting with i = 0.  If you
154       need to specify a particular numeric value for a nick, use an array
155       reference containing the nickname and the numeric value, instead.  You
156       may mix and match the two styles.
157
158         Glib::Type->register_flags ('MyFoo::Baz',
159                  'value-one',               # assigned 1<<0
160                  'value-two',               # assigned 1<<1
161                  ['value-three' => 1<<10 ], # explicit 1<<10
162                  ['value-four' => 0x0f ],   # explicit 0x0f
163                  'value-five',              # assigned 1<<4
164         );
165
166       If you use the array-ref form, beware: the code performs no validation
167       for unique values.
168
169   Glib::Type->register_object ($parent_package, $new_package, ...)
170       •   $parent_package (string) name of the parent package, which must be
171           a derivative of Glib::Object.
172
173       •   $new_package (string) usually __PACKAGE__.
174
175       •   ... (list) key/value pairs controlling how the class is created.
176
177       Register new_package as an officially GLib-sanctioned derivative of the
178       (GObject derivative) parent_package.  This automatically sets up an
179       @ISA entry for you, and creates a new GObjectClass under the hood.
180
181       The ... parameters are key/value pairs, currently supporting:
182
183       signals => HASHREF
184           The "signals" key contains a hash, keyed by signal names, which
185           describes how to set up the signals for new_package.
186
187           If the value is a code reference, the named signal must exist
188           somewhere in parent_package or its ancestry; the code reference
189           will be used to override the class closure for that signal.  This
190           is the officially sanctioned way to override virtual methods on
191           Glib::Objects.  The value may be a string rather than a code
192           reference, in which case the sub with that name in new_package will
193           be used.  (The function should not be inherited.)
194
195           If the value is a hash reference, the key will be the name of a new
196           signal created with the properties defined in the hash.  All of the
197           properties are optional, with defaults provided:
198
199           class_closure => subroutine or undef
200               Use this code reference (or sub name) as the class closure
201               (that is, the default handler for the signal).  If not
202               specified, "do_signal_name", in the current package, is used.
203
204           return_type => package name or undef
205               Return type for the signal.  If not specified, then the signal
206               has void return.
207
208           param_types => ARRAYREF
209               Reference to a list of parameter types (package names),
210               omitting the instance and user data.  Callbacks connected to
211               this signal will receive the instance object as the first
212               argument, followed by arguments with the types listed here, and
213               finally by any user data that was supplied when the callback
214               was connected.  Not specifying this key is equivalent to
215               supplying an empty list, which actually means instance and
216               maybe data.
217
218           flags => Glib::SignalFlags
219               Flags describing this signal's properties. See the GObject C
220               API reference' description of GSignalFlags for a complete
221               description.
222
223           accumulator => subroutine or undef
224               The signal accumulator is a special callback that can be used
225               to collect return values of the various callbacks that are
226               called during a signal emission.  Generally, you can omit this
227               parameter; custom accumulators are used to do things like
228               stopping signal propagation by return value or creating a list
229               of returns, etc.  See "SIGNALS" in Glib::Object::Subclass for
230               details.
231
232       properties => ARRAYREF
233           Array of Glib::ParamSpec objects, each describing an object
234           property to add to the new type.  These properties are available
235           for use by all code that can access the object, regardless of
236           implementation language.  See Glib::ParamSpec.  This list may be
237           empty; if it is not, the functions "GET_PROPERTY" and
238           "SET_PROPERTY" in $new_package will be called to get and set the
239           values.  Note that an object property is just a mechanism for
240           getting and setting a value -- it implies no storage.  As a
241           convenience, however, Glib::Object provides fallbacks for
242           GET_PROPERTY and SET_PROPERTY which use the property nicknames as
243           hash keys in the object variable for storage.
244
245           Additionally, you may specify ParamSpecs as a describing hash
246           instead of as an object; this form allows you to supply explicit
247           getter and setter methods which override GET_PROPERY and
248           SET_PROPERTY.  The getter and setter are both optional in the hash
249           form.  For example:
250
251              Glib::Type->register_object ('Glib::Object', 'Foo',
252                 properties => [
253                    # specified normally
254                    Glib::ParamSpec->string (...),
255                    # specified explicitly
256                    {
257                       pspec => Glib::ParamSpec->int (...),
258                       set => sub {
259                          my ($object, $newval) = @_;
260                          ...
261                       },
262                       get => sub {
263                          my ($object) = @_;
264                          ...
265                          return $val;
266                       },
267                    },
268                 ]
269              );
270
271           You can mix the two declaration styles as you like.  If you have
272           individual "get_foo" / "set_foo" methods with the operative code
273           for a property then the "get"/"set" form is a handy way to go
274           straight to that.
275
276       interfaces => ARRAYREF
277           Array of interface package names that the new object implements.
278           Interfaces are the GObject way of doing multiple inheritance, thus,
279           in Perl, the package names will be prepended to @ISA and certain
280           inheritable and overrideable ALLCAPS methods will automatically be
281           called whenever needed.  Which methods exactly depends on the
282           interface -- Gtk2::CellEditable for example uses START_EDITING,
283           EDITING_DONE, and REMOVE_WIDGET.
284

SEE ALSO

286       Glib
287
289       Copyright (C) 2003-2011 by the gtk2-perl team.
290
291       This software is licensed under the LGPL.  See Glib for a full notice.
292
293
294
295perl v5.36.0                      2023-01-20                     Glib::Type(3)
Impressum