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 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 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 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
31 Glib::Object
32
34 object = $class->new (...)
35 • ... (list) key/value pairs, property values to set on creation
36 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 scalar = Glib::Object->new_from_pointer ($pointer, $noinc=FALSE)
44 • $pointer (unsigned) a C pointer value as an integer.
45 • $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 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 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 unsigned = $object->get_data ($key)
61 • $key (string)
62 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 $object->set_data ($key, $data)
68 • $key (string)
69 • $data (scalar)
71 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 pspec or undef = $object_or_class_name->find_property ($name)
81 • $name (string)
82 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 $object->freeze_notify
88 Stops emission of "notify" signals on $object. The signals are queued
89 until "thaw_notify" is called on $object.
90 $object->get (...)
92 • ... (list) list of property names
93 Alias for "get_property" (see "get and set" above).
95 $object->set (key => $value, ...)
97 • ... (list) key/value pairs
98 Alias for "set_property" (see "get and set" above).
100 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 name
106 The name of the property
107 type
109 The type of the property
110 owner_type
112 The type that owns the property
113 descr
115 The description of the property
116 flags
118 The Glib::ParamFlags of the property
119 $object->notify ($property_name)
121 • $property_name (string)
122 Emits a "notify" signal for the property $property on $object.
124 gpointer = $object->get_pointer
126 Complement of "new_from_pointer".
127 $object->get_property (...)
129 Fetch and return the values for the object properties named in ....
130 $object->set_property (key => $value, ...)
132 Set object properties.
133 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 • $hook_func (subroutine)
139 • $hook_data (scalar)
141 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 The $hook_func should be reference to a subroutine that looks something
147 like this:
148 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 This function returns an id that can be used with
157 "remove_emission_hook".
158 Since 1.100.
160 list = $instance->signal_chain_from_overridden (...)
162 • ... (list)
163 Chain up to an overridden class closure; it is only valid to call this
165 from a class closure override.
166 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 unsigned = $instance->signal_connect ($detailed_signal, $callback,
177 $data=undef)
178 • $detailed_signal (string)
179 • $callback (subroutine)
181 • $data (scalar) arbitrary data to be passed to each invocation of
183 callback
184 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 unsigned = $instance->signal_connect_after ($detailed_signal, $callback,
190 $data=undef)
191 • $detailed_signal (string)
192 • $callback (scalar)
194 • $data (scalar)
196 Like "signal_connect", except that $callback will be run after the
198 default handler.
199 unsigned = $instance->signal_connect_swapped ($detailed_signal, $callback,
201 $data=undef)
202 • $detailed_signal (string)
203 • $callback (scalar)
205 • $data (scalar)
207 Like "signal_connect", except that $data and $object will be swapped on
209 invocation of $callback.
210 retval = $object->signal_emit ($name, ...)
212 • $name (string) the name of the signal
213 • ... (list) any arguments to pass to handlers.
215 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 $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 signal_name
227 The name of the signal being emitted.
228 detail
230 The detail passed on for this emission. For example, a "notify"
231 signal will have the property name as the detail.
232 run_type
234 The current stage of signal emission, one of "run-first", "run-
235 last", or "run-cleanup".
236 $object->signal_handler_block ($handler_id)
238 • $handler_id (unsigned)
239 $object->signal_handler_disconnect ($handler_id)
241 • $handler_id (unsigned)
242 boolean = $object->signal_handler_is_connected ($handler_id)
244 • $handler_id (unsigned)
245 $object->signal_handler_unblock ($handler_id)
247 • $handler_id (unsigned)
248 integer = $instance->signal_handlers_block_by_func ($func, $data=undef)
250 • $func (subroutine) function to block
251 • $data (scalar) data to match, ignored if undef
253 integer = $instance->signal_handlers_disconnect_by_func ($func,
255 $data=undef)
256 • $func (subroutine) function to block
257 • $data (scalar) data to match, ignored if undef
259 integer = $instance->signal_handlers_unblock_by_func ($func, $data=undef)
261 • $func (subroutine) function to block
262 • $data (scalar) data to match, ignored if undef
264 scalar = $object_or_class_name->signal_query ($name)
266 • $name (string)
267 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 See also "Glib::Type::list_signals", which returns the same kind of
273 hash refs as this does.
274 Since 1.080.
276 $object_or_class_name->signal_remove_emission_hook ($signal_name, $hook_id)
278 • $signal_name (string)
279 • $hook_id (unsigned)
281 Remove a hook that was installed by "add_emission_hook".
283 Since 1.100.
285 $instance->signal_stop_emission_by_name ($detailed_signal)
287 • $detailed_signal (string)
288 $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 boolean = Glib::Object->set_threadsafe ($threadsafe)
294 • $threadsafe (boolean)
295 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 $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 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 $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 Attempts to write to read-only properties will croak, reading a write-
315 only property will return '[write-only]'.
316 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
324 notify (Glib::Object, Glib::ParamSpec)
325
327 Glib
328
330 Copyright (C) 2003-2011 by the gtk2-perl team.
331 This software is licensed under the LGPL. See Glib for a full notice.
333perl v5.36.0 2023-01-20 Glib::Object(3)