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