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