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) of key/value pairs, property values to set on creation
24 Instantiate a Glib::Object of type $class. Any key/value pairs in
26 ... are used to set properties on the new object; see "set". This
27 is designed to be inherited by Perl-derived subclasses (see
28 Glib::Object::Subclass), but you can actually use it to create any
29 GObject-derived type.
30 scalar = Glib::Object->new_from_pointer ($pointer, $noinc=FALSE)
32 * $pointer (unsigned) a C pointer value as an integer.
34 * $noinc (boolean) if true, do not increase the GObject's reference
35 count when creating the Perl wrapper. this typically means that
36 when the Perl wrapper will own the object. in general you don't
37 want to do that, so the default is false.
38 Create a Perl Glib::Object reference for the C object pointed to by
40 $pointer. You should need this very rarely; it's intended to sup‐
41 port foreign objects.
42 NOTE: the cast from arbitrary integer to GObject may result in a
44 core dump without warning, because the type-checking macro
45 G_OBJECT() attempts to dereference the pointer to find a GTypeClass
46 structure, and there is no portable way to validate the pointer.
47 unsigned = $object->get_data ($key)
49 * $key (string)
51 Fetch the integer stored under the object data key $key. These
53 values do not have types; type conversions must be done manually.
54 See "set_data".
55 $object->set_data ($key, $data)
57 * $key (string)
59 * $data (scalar)
60 GObject provides an arbitrary data mechanism that assigns unsigned
62 integers to key names. Functionality overlaps with the hash used
63 as the Perl object instance, so we strongly recommend you use hash
64 keys for your data storage. The GObject data values cannot store
65 type information, so they are not safe to use for anything but
66 integer values, and you really should use this method only if you
67 know what you are doing.
68 pspec = $object_or_class_name->find_property ($name)
70 * $name (string)
72 Find the definition of object property $name for
74 $object_or_class_name; for the returned data see
75 Glib::Object::list_properties.
76 $object->freeze_notify
78 Stops emission of "notify" signals on $object. The signals are
80 queued until "thaw_notify" is called on $object.
81 list = $object->get (...)
83 * ... (list) list of property names
85 Fetch and return the values for the object properties named in ....
87 $object->set (key => $value, ...)
89 * ... (list)
91 Set object properties.
93 list = $object_or_class_name->list_properties
95 List all the object properties for $object_or_class_name; returns
97 them as a list of hashes, containing these keys:
98 name
100 The name of the property
101 type
103 The type of the property
104 owner_type
106 The type that owns the property
107 descr
109 The description of the property
110 flags
112 The Glib::ParamFlags of the property
113 $object->notify ($property_name)
115 * $property_name (string)
117 Emits a "notify" signal for the property $property on $object.
119 gpointer = $object->get_pointer
121 Complement of "new_from_pointer".
123 list = $object->get_property (...)
125 Alias for "get".
127 $object->set_property (key => $value, ...)
129 Alias for "set".
131 unsigned = $object_or_class_name->signal_add_emission_hook
133 ($detailed_signal, $hook_func, $hook_data=undef)
134 * $detailed_signal (string) of the form "signal-name::detail"
136 * $hook_func (subroutine)
137 * $hook_data (scalar)
138 Add an emission hook for a signal. The hook will be called for any
140 emission of that signal, independent of the instance. This is pos‐
141 sible only for signals which don't have the "G_SIGNAL_NO_HOOKS"
142 flag set.
143 The $hook_func should be reference to a subroutine that looks some‐
145 thing like this:
146 sub emission_hook {
148 my ($invocation_hint, $parameters, $hook_data) = @_;
149 # $parameters is a reference to the @_ to be passed to
150 # signal handlers, including the instance as $parameters->[0].
151 return $stay_connected; # boolean
152 }
153 This function returns an id that can be used with "remove_emis‐
155 sion_hook".
156 Since 1.100.
158 list = $instance->signal_chain_from_overridden (...)
160 * ... (list)
162 Chain up to an overridden class closure; it is only valid to call
164 this from a class closure override.
165 Translation: because of various details in how GObjects are imple‐
167 mented, the way to override a virtual method on a GObject is to
168 provide a new "class closure", or default handler for a signal.
169 This happens when a class is registered with the type system (see
170 Glib::Type::register and Glib::Object::Subclass). When called from
171 inside such an override, this method runs the overridden class clo‐
172 sure. This is equivalent to calling $self->SUPER::$method (@_) in
173 normal Perl objects.
174 unsigned = $instance->signal_connect ($detailed_signal, $callback,
176 $data=undef)
177 * $detailed_signal (string)
179 * $callback (subroutine)
180 * $data (scalar) arbitrary data to be passed to each invocation of
181 callback
182 Register callback to be called on each emission of $detailed_sig‐
184 nal. Returns an identifier that may be used to remove this handler
185 with "$object->signal_handler_disconnect".
186 unsigned = $instance->signal_connect_after ($detailed_signal, $call‐
188 back, $data=undef)
189 * $detailed_signal (string)
191 * $callback (scalar)
192 * $data (scalar)
193 Like "signal_connect", except that $callback will be run after the
195 default handler.
196 unsigned = $instance->signal_connect_swapped ($detailed_signal, $call‐
198 back, $data=undef)
199 * $detailed_signal (string)
201 * $callback (scalar)
202 * $data (scalar)
203 Like "signal_connect", except that $data and $object will be
205 swapped on invocation of $callback.
206 retval = $object->signal_emit ($name, ...)
208 * $name (string) the name of the signal
210 * ... (list) any arguments to pass to handlers.
211 Emit the signal name on $object. The number and types of addi‐
213 tional arguments in ... are determined by the signal; similarly,
214 the presence and type of return value depends on the signal being
215 emitted.
216 $object->signal_handler_block ($handler_id)
218 * $handler_id (unsigned)
220 $object->signal_handler_disconnect ($handler_id)
222 * $handler_id (unsigned)
224 boolean = $object->signal_handler_is_connected ($handler_id)
226 * $handler_id (unsigned)
228 $object->signal_handler_unblock ($handler_id)
230 * $handler_id (unsigned)
232 integer = $instance->signal_handlers_block_by_func ($func, $data=undef)
234 * $func (subroutine) function to block
236 * $data (scalar) data to match, ignored if undef
237 integer = $instance->signal_handlers_disconnect_by_func ($func,
239 $data=undef)
240 * $func (subroutine) function to block
242 * $data (scalar) data to match, ignored if undef
243 integer = $instance->signal_handlers_unblock_by_func ($func,
245 $data=undef)
246 * $func (subroutine) function to block
248 * $data (scalar) data to match, ignored if undef
249 scalar = $object_or_class_name->signal_query ($name)
251 * $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
256 package 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,
264 $hook_id)
265 * $signal_name (string)
267 * $hook_id (unsigned)
268 Remove a hook that was installed by "add_emission_hook".
270 Since 1.100.
272 $instance->signal_stop_emission_by_name ($detailed_signal)
274 * $detailed_signal (string)
276 $object->thaw_notify
278 Reverts the effect of a previous call to "freeze_notify". This
280 causes all queued "notify" signals on $object to be emitted.
281 boolean = Glib::Object->set_threadsafe ($threadsafe)
283 * $threadsafe (boolean)
285 Enables/disables threadsafe gobject tracking. Returns whether or
287 not tracking will be successful and thus whether using perl
288 ithreads will be possible.
289 $object->tie_properties ($all=FALSE)
291 * $all (boolean) if FALSE (or omitted) tie only properties for this
293 object's class, if TRUE tie the properties of this and all parent
294 classes.
295 A special method avaiable to Glib::Object derivatives, it uses
297 perl's tie facilities to associate hash keys with the properties of
298 the object. For example:
299 $button->tie_properties;
301 # equivilent to $button->set (label => 'Hello World');
302 $button->{label} = 'Hello World';
303 print "the label is: ".$button->{label}."\n";
304 Attempts to write to read-only properties will croak, reading a
306 write-only property will return '[write-only]'.
307 Care must be taken when using tie_properties with objects of types
309 created with Glib::Object::Subclass as there may be clashes with
310 existing hash keys that could cause infinite loops. The solution is
311 to use custom property get/set functions to alter the storage loca‐
312 tions of the properties.
313
315 notify (Glib::Object, Glib::ParamSpec)
316
318 flags Glib::SignalFlags
319 * 'run-first' / 'G_SIGNAL_RUN_FIRST'
321 * 'run-last' / 'G_SIGNAL_RUN_LAST'
322 * 'run-cleanup' / 'G_SIGNAL_RUN_CLEANUP'
323 * 'no-recurse' / 'G_SIGNAL_NO_RECURSE'
324 * 'detailed' / 'G_SIGNAL_DETAILED'
325 * 'action' / 'G_SIGNAL_ACTION'
326 * 'no-hooks' / 'G_SIGNAL_NO_HOOKS'
327
329 Glib
330
332 Copyright (C) 2003-2007 by the gtk2-perl team.
333 This software is licensed under the LGPL. See Glib for a full notice.
335perl v5.8.8 2007-02-26 Glib::Object(3)