1Glib::Object(3) User Contributed Perl Documentation Glib::Object(3)
2
3
4
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
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
31 Glib::Object
32
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
324 notify (Glib::Object, Glib::ParamSpec)
325
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.28.0 2018-10-04 Glib::Object(3)