2 * This file is part of duit.
4 * duit is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation; either version 2.1 of the License, or
7 * (at your option) any later version.
9 * duit is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with duit; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 // generated automatically - do not change
20 // find conversion definition on APILookup.txt
21 // implement new conversion functionalities on the wrap.utils pakage
24 * Conversion parameters:
25 * inFile = gobject-Closures.html
50 * - GClosure* -> Closure
51 * - GObject* -> ObjectG
52 * - GSource* -> Source
57 module gobject
.Closure
;
59 private import gobject
.gobjecttypes
;
61 private import lib
.gobject
;
63 private import gobject
.ObjectG
;
64 private import gobject
.Closure
;
65 private import gobject
.Value
;
66 private import glib
.Source
;
70 * A GClosure represents a callback supplied by the programmer. It will generally
71 * comprise a function of some kind and a marshaller used to call it. It is the
72 * reponsibility of the marshaller to convert the arguments for the invocation
73 * from GValues into a suitable form, perform the callback on the
74 * converted arguments, and transform the return value back into a GValue.
75 * In the case of C programs, a closure usually just holds a pointer to a function
76 * and maybe a data argument, and the marshaller converts between GValue
77 * and native C types. The GObject library provides the GCClosure type for this
78 * purpose. Bindings for other languages need marshallers which
79 * convert between GValues and suitable representations in the runtime
80 * of the language in order to use functions written in that languages as
82 * Within GObject, closures play an important role in the implementation of
83 * signals. When a signal is registered, the c_marshaller argument to
84 * g_signal_new() specifies the default C marshaller for any closure which is
85 * connected to this signal. GObject provides a number of C marshallers
86 * for this purpose, see the g_cclosure_marshal_*() functions. Additional
87 * C marshallers can be generated with the glib-genmarshal utility.
88 * Closures can be explicitly connected to signals with
89 * g_signal_connect_closure(), but it usually more convenient to let GObject
90 * create a closure automatically by using one of the g_signal_connect_*()
91 * functions which take a callback function/user data pair.
92 * Using closures has a number of important advantages over a simple
93 * callback function/data pointer combination:
94 * Closures allow the callee to get the types of the callback parameters,
95 * which means that language bindings don't have to write individual glue
96 * for each callback type.
97 * The reference counting of GClosure makes it easy to handle reentrancy
98 * right; if a callback is removed while it is being invoked, the closure
99 * and it's parameters won't be freed until the invocation finishes.
100 * g_closure_invalidate() and invalidation notifiers allow callbacks to be
101 * automatically removed when the objects they point to go away.
106 /** the main Gtk struct */
107 protected GClosure
* gClosure
;
110 public GClosure
* getClosureStruct()
116 /** the main Gtk struct as a void* */
117 protected void* getStruct()
119 return cast(void*)gClosure
;
123 * Sets our main struct and passes it to the parent class
125 public this (GClosure
* gClosure
)
127 this.gClosure
= gClosure
;
148 * A variant of g_closure_new_simple() which stores object in the data
149 * field of the closure and calls g_object_watch_closure() on object and the
150 * created closure. This function is mainly useful when implementing new types
153 * the size of the structure to allocate, must be at least
156 * a GObject pointer to store in the data field of the newly
159 * a newly allocated GClosure
161 public this (uint sizeofClosure
, ObjectG object
)
163 // GClosure* g_closure_new_object (guint sizeof_closure, GObject *object);
164 this(cast(GClosure
*)g_closure_new_object(sizeofClosure
, (object
is null) ?
null : object
.getObjectGStruct()) );
168 * Increments the reference count on a closure to force it staying
169 * alive while the caller holds a pointer to it.
171 * GClosure to increment the reference count on
173 * The closure passed in, for convenience
177 // GClosure* g_closure_ref (GClosure *closure);
178 return new Closure( g_closure_ref(gClosure
) );
182 * Takes over the initial ownership of a closure.
183 * Each closure is initially created in afloating state,
184 * which means that the initial reference count is not owned by any caller.
185 * g_closure_sink() checks to see if the object is still floating, and if so,
186 * unsets the floating state and decreases the reference count. If the closure
187 * is not floating, g_closure_sink() does nothing. The reason for the existance
188 * of the floating state is to prevent cumbersome code sequences like:
189 * closure = g_cclosure_new (cb_func, cb_data);
190 * g_source_set_closure (source, closure);
191 * g_closure_unref (closure); /+* XXX GObject doesn't really need this +/
192 * Because g_source_set_closure() (and similar functions) take ownership of the
193 * initial reference count, if it is unowned, we instead can write:
194 * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
195 * Generally, this function is used together with g_closure_ref(). Ane example
196 * of storing a closure for later notification looks like:
197 * static GClosure *notify_closure = NULL;
199 * foo_notify_set_closure (GClosure *closure)
201 * if (notify_closure)
202 * g_closure_unref (notify_closure);
203 * notify_closure = closure;
204 * if (notify_closure)
206 * g_closure_ref (notify_closure);
207 * g_closure_sink (notify_closure);
210 * Because g_closure_sink() may decrement the reference count of a closure
211 * (if it hasn't been called on closure yet) just like g_closure_unref(),
212 * g_closure_ref() should be called prior to this function.
214 * GClosure to decrement the initial reference count on, if it's
219 // void g_closure_sink (GClosure *closure);
220 g_closure_sink(gClosure
);
224 * Decrements the reference count of a closure after it was previously
225 * incremented by the same caller. If no other callers are using the closure,
226 * then the closure will be destroyed and freed.
228 * GClosure to decrement the reference count on
232 // void g_closure_unref (GClosure *closure);
233 g_closure_unref(gClosure
);
237 * Invokes the closure, i.e. executes the callback represented by the closure.
241 * a GValue to store the return value. May be NULL if the
242 * callback of closure doesn't return a value.
244 * the length of the param_values array
246 * an array of GValues holding the arguments on
247 * which to invoke the callback of closure
249 * a context-dependent invocation hint
251 public void invoke(Value returnValue
, uint nParamValues
, Value paramValues
, void* invocationHint
)
253 // void g_closure_invoke (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint);
254 g_closure_invoke(gClosure
, (returnValue
is null) ?
null : returnValue
.getValueStruct(), nParamValues
, (paramValues
is null) ?
null : paramValues
.getValueStruct(), invocationHint
);
258 * Sets a flag on the closure to indicate that it's calling environment has
259 * become invalid, and thus causes any future invocations of g_closure_invoke()
260 * on this closure to be ignored. Also, invalidation notifiers installed on
261 * the closure will be called at this point. Note that unless you are holding
262 * a reference to the closure yourself, the invalidation notifiers may unref
263 * the closure and cause it to be destroyed, so if you need to access the
264 * closure after calling g_closure_invalidate(), make sure that you've
265 * previously called g_closure_ref().
266 * Note that g_closure_invalidate() will also be called when the reference count
267 * of a closure drops to zero (unless it has already been invalidated before).
269 * GClosure to invalidate
271 public void invalidate()
273 // void g_closure_invalidate (GClosure *closure);
274 g_closure_invalidate(gClosure
);
278 * Registers a finalization notifier which will be called when the reference
279 * count of closure goes down to 0. Multiple finalization notifiers on a
280 * single closure are invoked in unspecified order. If a single call to
281 * g_closure_unref() results in the closure being both invalidated and
282 * finalized, then the invalidate notifiers will be run before the finalize
287 * data to pass to notify_func
289 * the callback function to register
291 public void addFinalizeNotifier(void* notifyData
, GClosureNotify notifyFunc
)
293 // void g_closure_add_finalize_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func);
294 g_closure_add_finalize_notifier(gClosure
, notifyData
, notifyFunc
);
298 * Registers an invalidation notifier which will be called when the closure
299 * is invalidated with g_closure_invalidate(). Invalidation notifiers are
300 * invoked before finalization notifiers, in an unspecified order.
304 * data to pass to notify_func
306 * the callback function to register
308 public void addInvalidateNotifier(void* notifyData
, GClosureNotify notifyFunc
)
310 // void g_closure_add_invalidate_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func);
311 g_closure_add_invalidate_notifier(gClosure
, notifyData
, notifyFunc
);
315 * Removes a finalization notifier. Notifiers are automatically removed after
320 * data which was passed to g_closure_add_finalize_notifier()
321 * when registering notify_func
323 * the callback function to remove
325 public void removeFinalizeNotifier(void* notifyData
, GClosureNotify notifyFunc
)
327 // void g_closure_remove_finalize_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func);
328 g_closure_remove_finalize_notifier(gClosure
, notifyData
, notifyFunc
);
332 * Removes a invalidation notifier. Notifiers are automatically removed after
337 * data which was passed to g_closure_add_invalidate_notifier()
338 * when registering notify_func
340 * the callback function to remove
342 public void removeInvalidateNotifier(void* notifyData
, GClosureNotify notifyFunc
)
344 // void g_closure_remove_invalidate_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func);
345 g_closure_remove_invalidate_notifier(gClosure
, notifyData
, notifyFunc
);
349 * Allocates a struct of the given size and initializes the initial part
350 * as a GClosure. This function is mainly useful when implementing new types
352 * typedef struct _MyClosure MyClosure;
356 * /+* extra data goes here +/
359 * my_closure_finalize (gpointer notify_data,
362 * MyClosure *my_closure = (MyClosure *)closure;
363 * /+* free extra data here +/
365 * MyClosure *my_closure_new (gpointer data)
368 * MyClosure *my_closure;
369 * closure = g_closure_new_simple (sizeof (MyClosure), data);
370 * my_closure = (MyClosure *) closure;
371 * / initialize extra data here +/
372 * g_closure_add_finalize_notifier (closure, notify_data,
373 * my_closure_finalize);
377 * the size of the structure to allocate, must be at least
380 * data to store in the data field of the newly allocated GClosure
382 * a newly allocated GClosure
384 public this (uint sizeofClosure
, void* data
)
386 // GClosure* g_closure_new_simple (guint sizeof_closure, gpointer data);
387 this(cast(GClosure
*)g_closure_new_simple(sizeofClosure
, data
) );
391 * Sets the marshaller of closure. The marshal_data provides a way for a
392 * meta marshaller to provide additional information to the marshaller.
393 * (See g_closure_set_meta_marshal().) For GObject's C predefined marshallers
394 * (the g_cclosure_marshal_*() functions), what it provides is a callback
395 * function to use instead of closure->callback.
399 * a GClosureMarshal function
401 public void setMarshal(GClosureMarshal marshal
)
403 // void g_closure_set_marshal (GClosure *closure, GClosureMarshal marshal);
404 g_closure_set_marshal(gClosure
, marshal
);
408 * Adds a pair of notifiers which get invoked before and after the closure
409 * callback, respectively. This is typically used to protect the extra arguments
410 * for the duration of the callback. See g_object_watch_closure() for an
411 * example of marshal guards.
415 * data to pass to pre_marshal_notify
416 * pre_marshal_notify:
417 * a function to call before the closure callback
419 * data to pass to post_marshal_notify
420 * post_marshal_notify:
421 * a function to call after the closure callback
423 public void addMarshalGuards(void* preMarshalData
, GClosureNotify preMarshalNotify
, void* postMarshalData
, GClosureNotify postMarshalNotify
)
425 // void g_closure_add_marshal_guards (GClosure *closure, gpointer pre_marshal_data, GClosureNotify pre_marshal_notify, gpointer post_marshal_data, GClosureNotify post_marshal_notify);
426 g_closure_add_marshal_guards(gClosure
, preMarshalData
, preMarshalNotify
, postMarshalData
, postMarshalNotify
);
430 * Sets the meta marshaller of closure.
431 * A meta marshaller wraps closure->marshal and modifies the way it is called
432 * in some fashion. The most common use of this facility is for C callbacks.
433 * The same marshallers (generated by
434 * glib-genmarshal) are used everywhere,
435 * but the way that we get the callback function differs. In most cases we want
436 * to use closure->callback, but in other cases we want to use use some
437 * different technique to retrieve the callbakc function.
438 * For example, class closures for signals (see g_signal_type_cclosure_new())
439 * retrieve the callback function from a fixed offset in the class structure.
440 * The meta marshaller retrieves the right callback and passes it to the
441 * marshaller as the marshal_data argument.
445 * context-dependent data to pass to meta_marshal
447 * a GClosureMarshal function
449 public void setMetaMarshal(void* marshalData
, GClosureMarshal metaMarshal
)
451 // void g_closure_set_meta_marshal (GClosure *closure, gpointer marshal_data, GClosureMarshal meta_marshal);
452 g_closure_set_meta_marshal(gClosure
, marshalData
, metaMarshal
);
456 * Set the callback for a source as a GClosure.
457 * If the source is not one of the standard GLib types, the closure_callback
458 * and closure_marshal fields of the GSourceFuncs structure must have been
459 * filled in with pointers to appropriate functions.
465 public static void gSourceSetClosure(Source source
, Closure closure
)
467 // void g_source_set_closure (GSource *source, GClosure *closure);
468 g_source_set_closure((source
is null) ?
null : source
.getSourceStruct(), (closure
is null) ?
null : closure
.getClosureStruct());