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

NAME

6       Glib::Object -  Bindings for GObject
7

DESCRIPTION

9       GObject is the base object class provided by the gobject library.  It
10       provides object properties with a notification system, and emittable
11       signals.
12
13       Glib::Object is the corresponding Perl object class.  Glib::Objects are
14       represented by blessed hash references, with a magical connection to
15       the underlying C object.
16
17   get and set
18       Some subclasses of "Glib::Object" override "get" and "set" with methods
19       more useful to the subclass, for example "Gtk2::TreeModel" getting and
20       setting row contents.
21
22       This is usually done when the subclass has no object properties.  Any
23       object properties it or a further subclass does have can always be
24       accessed with "get_property" and "set_property" (together with
25       "find_property" and "list_properties" to enquire about them).
26
27       Generic code for any object subclass can use the names "get_property"
28       and "set_property" to be sure of getting the object properties as such.
29

HIERARCHY

31         Glib::Object
32

METHODS

34   object = $class->new (...)
35       •   ... (list) key/value pairs, property values to set on creation
36
37       Instantiate a Glib::Object of type $class.  Any key/value pairs in ...
38       are used to set properties on the new object; see "set".  This is
39       designed to be inherited by Perl-derived subclasses (see
40       Glib::Object::Subclass), but you can actually use it to create any
41       GObject-derived type.
42
43   scalar = Glib::Object->new_from_pointer ($pointer, $noinc=FALSE)
44       •   $pointer (unsigned) a C pointer value as an integer.
45
46       •   $noinc (boolean) if true, do not increase the GObject's reference
47           count when creating the Perl wrapper.  this typically means that
48           when the Perl wrapper will own the object.  in general you don't
49           want to do that, so the default is false.
50
51       Create a Perl Glib::Object reference for the C object pointed to by
52       $pointer.  You should need this very rarely; it's intended to support
53       foreign objects.
54
55       NOTE: the cast from arbitrary integer to GObject may result in a core
56       dump without warning, because the type-checking macro G_OBJECT()
57       attempts to dereference the pointer to find a GTypeClass structure, and
58       there is no portable way to validate the pointer.
59
60   unsigned = $object->get_data ($key)
61       •   $key (string)
62
63       Fetch the integer stored under the object data key $key.  These values
64       do not have types; type conversions must be done manually.  See
65       "set_data".
66
67   $object->set_data ($key, $data)
68       •   $key (string)
69
70       •   $data (scalar)
71
72       GObject provides an arbitrary data mechanism that assigns unsigned
73       integers to key names.  Functionality overlaps with the hash used as
74       the Perl object instance, so we strongly recommend you use hash keys
75       for your data storage.  The GObject data values cannot store type
76       information, so they are not safe to use for anything but integer
77       values, and you really should use this method only if you know what you
78       are doing.
79
80   pspec or undef = $object_or_class_name->find_property ($name)
81       •   $name (string)
82
83       Find the definition of object property $name for $object_or_class_name.
84       Return "undef" if no such property.  For the returned data see
85       Glib::Object::list_properties.
86
87   $object->freeze_notify
88       Stops emission of "notify" signals on $object. The signals are queued
89       until "thaw_notify" is called on $object.
90
91   $object->get (...)
92       •   ... (list) list of property names
93
94       Alias for "get_property" (see "get and set" above).
95
96   $object->set (key => $value, ...)
97       •   ... (list) key/value pairs
98
99       Alias for "set_property" (see "get and set" above).
100
101   list = $object_or_class_name->list_properties
102       List all the object properties for $object_or_class_name; returns them
103       as a list of hashes, containing these keys:
104
105       name
106           The name of the property
107
108       type
109           The type of the property
110
111       owner_type
112           The type that owns the property
113
114       descr
115           The description of the property
116
117       flags
118           The Glib::ParamFlags of the property
119
120   $object->notify ($property_name)
121       •   $property_name (string)
122
123       Emits a "notify" signal for the property $property on $object.
124
125   gpointer = $object->get_pointer
126       Complement of "new_from_pointer".
127
128   $object->get_property (...)
129       Fetch and return the values for the object properties named in ....
130
131   $object->set_property (key => $value, ...)
132       Set object properties.
133
134   unsigned = $object_or_class_name->signal_add_emission_hook
135       ($detailed_signal, $hook_func, $hook_data=undef)
136       •   $detailed_signal (string) of the form "signal-name::detail"
137
138       •   $hook_func (subroutine)
139
140       •   $hook_data (scalar)
141
142       Add an emission hook for a signal.  The hook will be called for any
143       emission of that signal, independent of the instance.  This is possible
144       only for signals which don't have the "G_SIGNAL_NO_HOOKS" flag set.
145
146       The $hook_func should be reference to a subroutine that looks something
147       like this:
148
149         sub emission_hook {
150             my ($invocation_hint, $parameters, $hook_data) = @_;
151             # $parameters is a reference to the @_ to be passed to
152             # signal handlers, including the instance as $parameters->[0].
153             return $stay_connected;  # boolean
154         }
155
156       This function returns an id that can be used with
157       "remove_emission_hook".
158
159       Since 1.100.
160
161   list = $instance->signal_chain_from_overridden (...)
162       •   ... (list)
163
164       Chain up to an overridden class closure; it is only valid to call this
165       from a class closure override.
166
167       Translation: because of various details in how GObjects are
168       implemented, the way to override a virtual method on a GObject is to
169       provide a new "class closure", or default handler for a signal.  This
170       happens when a class is registered with the type system (see
171       Glib::Type::register and Glib::Object::Subclass).  When called from
172       inside such an override, this method runs the overridden class closure.
173       This is equivalent to calling $self->SUPER::$method (@_) in normal Perl
174       objects.
175
176   unsigned = $instance->signal_connect ($detailed_signal, $callback,
177       $data=undef)
178       •   $detailed_signal (string)
179
180       •   $callback (subroutine)
181
182       •   $data (scalar) arbitrary data to be passed to each invocation of
183           callback
184
185       Register callback to be called on each emission of $detailed_signal.
186       Returns an identifier that may be used to remove this handler with
187       "$object->signal_handler_disconnect".
188
189   unsigned = $instance->signal_connect_after ($detailed_signal, $callback,
190       $data=undef)
191       •   $detailed_signal (string)
192
193       •   $callback (scalar)
194
195       •   $data (scalar)
196
197       Like "signal_connect", except that $callback will be run after the
198       default handler.
199
200   unsigned = $instance->signal_connect_swapped ($detailed_signal, $callback,
201       $data=undef)
202       •   $detailed_signal (string)
203
204       •   $callback (scalar)
205
206       •   $data (scalar)
207
208       Like "signal_connect", except that $data and $object will be swapped on
209       invocation of $callback.
210
211   retval = $object->signal_emit ($name, ...)
212       •   $name (string) the name of the signal
213
214       •   ... (list) any arguments to pass to handlers.
215
216       Emit the signal name on $object.  The number and types of additional
217       arguments in ... are determined by the signal; similarly, the presence
218       and type of return value depends on the signal being emitted.
219
220   $ihint = $instance->signal_get_invocation_hint
221       Get a reference to a hash describing the innermost signal currently
222       active on $instance.  Returns undef if no signal emission is active.
223       This invocation hint is the same object passed to signal emission
224       hooks, and contains these keys:
225
226       signal_name
227           The name of the signal being emitted.
228
229       detail
230           The detail passed on for this emission.  For example, a "notify"
231           signal will have the property name as the detail.
232
233       run_type
234           The current stage of signal emission, one of "run-first", "run-
235           last", or "run-cleanup".
236
237   $object->signal_handler_block ($handler_id)
238       •   $handler_id (unsigned)
239
240   $object->signal_handler_disconnect ($handler_id)
241       •   $handler_id (unsigned)
242
243   boolean = $object->signal_handler_is_connected ($handler_id)
244       •   $handler_id (unsigned)
245
246   $object->signal_handler_unblock ($handler_id)
247       •   $handler_id (unsigned)
248
249   integer = $instance->signal_handlers_block_by_func ($func, $data=undef)
250       •   $func (subroutine) function to block
251
252       •   $data (scalar) data to match, ignored if undef
253
254   integer = $instance->signal_handlers_disconnect_by_func ($func,
255       $data=undef)
256       •   $func (subroutine) function to block
257
258       •   $data (scalar) data to match, ignored if undef
259
260   integer = $instance->signal_handlers_unblock_by_func ($func, $data=undef)
261       •   $func (subroutine) function to block
262
263       •   $data (scalar) data to match, ignored if undef
264
265   scalar = $object_or_class_name->signal_query ($name)
266       •   $name (string)
267
268       Look up information about the signal $name on the instance type
269       $object_or_class_name, which may be either a Glib::Object or a package
270       name.
271
272       See also "Glib::Type::list_signals", which returns the same kind of
273       hash refs as this does.
274
275       Since 1.080.
276
277   $object_or_class_name->signal_remove_emission_hook ($signal_name, $hook_id)
278       •   $signal_name (string)
279
280       •   $hook_id (unsigned)
281
282       Remove a hook that was installed by "add_emission_hook".
283
284       Since 1.100.
285
286   $instance->signal_stop_emission_by_name ($detailed_signal)
287       •   $detailed_signal (string)
288
289   $object->thaw_notify
290       Reverts the effect of a previous call to "freeze_notify". This causes
291       all queued "notify" signals on $object to be emitted.
292
293   boolean = Glib::Object->set_threadsafe ($threadsafe)
294       •   $threadsafe (boolean)
295
296       Enables/disables threadsafe gobject tracking. Returns whether or not
297       tracking will be successful and thus whether using perl ithreads will
298       be possible.
299
300   $object->tie_properties ($all=FALSE)
301       •   $all (boolean) if FALSE (or omitted) tie only properties for this
302           object's class, if TRUE tie the properties of this and all parent
303           classes.
304
305       A special method available to Glib::Object derivatives, it uses perl's
306       tie facilities to associate hash keys with the properties of the
307       object. For example:
308
309         $button->tie_properties;
310         # equivilent to $button->set (label => 'Hello World');
311         $button->{label} = 'Hello World';
312         print "the label is: ".$button->{label}."\n";
313
314       Attempts to write to read-only properties will croak, reading a write-
315       only property will return '[write-only]'.
316
317       Care must be taken when using tie_properties with objects of types
318       created with Glib::Object::Subclass as there may be clashes with
319       existing hash keys that could cause infinite loops. The solution is to
320       use custom property get/set functions to alter the storage locations of
321       the properties.
322

SIGNALS

324       notify (Glib::Object, Glib::ParamSpec)
325

SEE ALSO

327       Glib
328
330       Copyright (C) 2003-2011 by the gtk2-perl team.
331
332       This software is licensed under the LGPL.  See Glib for a full notice.
333
334
335
336perl v5.32.1                      2021-01-27                   Glib::Object(3)
Impressum