1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gobject.Closure;
26 
27 private import glib.ConstructionException;
28 private import glib.MemorySlice;
29 private import glib.Source;
30 private import gobject.ObjectG;
31 private import gobject.Value;
32 private import gobject.c.functions;
33 public  import gobject.c.types;
34 public  import gtkc.gobjecttypes;
35 private import gtkd.Loader;
36 
37 
38 /**
39  * A #GClosure represents a callback supplied by the programmer. It
40  * will generally comprise a function of some kind and a marshaller
41  * used to call it. It is the responsibility of the marshaller to
42  * convert the arguments for the invocation from #GValues into
43  * a suitable form, perform the callback on the converted arguments,
44  * and transform the return value back into a #GValue.
45  * 
46  * In the case of C programs, a closure usually just holds a pointer
47  * to a function and maybe a data argument, and the marshaller
48  * converts between #GValue and native C types. The GObject
49  * library provides the #GCClosure type for this purpose. Bindings for
50  * other languages need marshallers which convert between #GValues
51  * and suitable representations in the runtime of the language in
52  * order to use functions written in that languages as callbacks.
53  * 
54  * Within GObject, closures play an important role in the
55  * implementation of signals. When a signal is registered, the
56  * @c_marshaller argument to g_signal_new() specifies the default C
57  * marshaller for any closure which is connected to this
58  * signal. GObject provides a number of C marshallers for this
59  * purpose, see the g_cclosure_marshal_*() functions. Additional C
60  * marshallers can be generated with the [glib-genmarshal][glib-genmarshal]
61  * utility.  Closures can be explicitly connected to signals with
62  * g_signal_connect_closure(), but it usually more convenient to let
63  * GObject create a closure automatically by using one of the
64  * g_signal_connect_*() functions which take a callback function/user
65  * data pair.
66  * 
67  * Using closures has a number of important advantages over a simple
68  * callback function/data pointer combination:
69  * 
70  * - Closures allow the callee to get the types of the callback parameters,
71  * which means that language bindings don't have to write individual glue
72  * for each callback type.
73  * 
74  * - The reference counting of #GClosure makes it easy to handle reentrancy
75  * right; if a callback is removed while it is being invoked, the closure
76  * and its parameters won't be freed until the invocation finishes.
77  * 
78  * - g_closure_invalidate() and invalidation notifiers allow callbacks to be
79  * automatically removed when the objects they point to go away.
80  */
81 public class Closure
82 {
83 	/** the main Gtk struct */
84 	protected GClosure* gClosure;
85 	protected bool ownedRef;
86 
87 	/** Get the main Gtk struct */
88 	public GClosure* getClosureStruct(bool transferOwnership = false)
89 	{
90 		if (transferOwnership)
91 			ownedRef = false;
92 		return gClosure;
93 	}
94 
95 	/** the main Gtk struct as a void* */
96 	protected void* getStruct()
97 	{
98 		return cast(void*)gClosure;
99 	}
100 
101 	/**
102 	 * Sets our main struct and passes it to the parent class.
103 	 */
104 	public this (GClosure* gClosure, bool ownedRef = false)
105 	{
106 		this.gClosure = gClosure;
107 		this.ownedRef = ownedRef;
108 	}
109 
110 	~this ()
111 	{
112 		if ( Linker.isLoaded(LIBRARY_GOBJECT) && ownedRef )
113 			g_closure_unref(gClosure);
114 	}
115 
116 
117 	/** */
118 	public static GType getType()
119 	{
120 		return g_closure_get_type();
121 	}
122 
123 	/**
124 	 * A variant of g_closure_new_simple() which stores @object in the
125 	 * @data field of the closure and calls g_object_watch_closure() on
126 	 * @object and the created closure. This function is mainly useful
127 	 * when implementing new types of closures.
128 	 *
129 	 * Params:
130 	 *     sizeofClosure = the size of the structure to allocate, must be at least
131 	 *         `sizeof (GClosure)`
132 	 *     object = a #GObject pointer to store in the @data field of the newly
133 	 *         allocated #GClosure
134 	 *
135 	 * Returns: a newly allocated #GClosure
136 	 *
137 	 * Throws: ConstructionException GTK+ fails to create the object.
138 	 */
139 	public this(uint sizeofClosure, ObjectG object)
140 	{
141 		auto p = g_closure_new_object(sizeofClosure, (object is null) ? null : object.getObjectGStruct());
142 
143 		if(p is null)
144 		{
145 			throw new ConstructionException("null returned by new_object");
146 		}
147 
148 		this(cast(GClosure*) p);
149 	}
150 
151 	/**
152 	 * Allocates a struct of the given size and initializes the initial
153 	 * part as a #GClosure. This function is mainly useful when
154 	 * implementing new types of closures.
155 	 *
156 	 * |[<!-- language="C" -->
157 	 * typedef struct _MyClosure MyClosure;
158 	 * struct _MyClosure
159 	 * {
160 	 * GClosure closure;
161 	 * // extra data goes here
162 	 * };
163 	 *
164 	 * static void
165 	 * my_closure_finalize (gpointer  notify_data,
166 	 * GClosure *closure)
167 	 * {
168 	 * MyClosure *my_closure = (MyClosure *)closure;
169 	 *
170 	 * // free extra data here
171 	 * }
172 	 *
173 	 * MyClosure *my_closure_new (gpointer data)
174 	 * {
175 	 * GClosure *closure;
176 	 * MyClosure *my_closure;
177 	 *
178 	 * closure = g_closure_new_simple (sizeof (MyClosure), data);
179 	 * my_closure = (MyClosure *) closure;
180 	 *
181 	 * // initialize extra data here
182 	 *
183 	 * g_closure_add_finalize_notifier (closure, notify_data,
184 	 * my_closure_finalize);
185 	 * return my_closure;
186 	 * }
187 	 * ]|
188 	 *
189 	 * Params:
190 	 *     sizeofClosure = the size of the structure to allocate, must be at least
191 	 *         `sizeof (GClosure)`
192 	 *     data = data to store in the @data field of the newly allocated #GClosure
193 	 *
194 	 * Returns: a floating reference to a new #GClosure
195 	 *
196 	 * Throws: ConstructionException GTK+ fails to create the object.
197 	 */
198 	public this(uint sizeofClosure, void* data)
199 	{
200 		auto p = g_closure_new_simple(sizeofClosure, data);
201 
202 		if(p is null)
203 		{
204 			throw new ConstructionException("null returned by new_simple");
205 		}
206 
207 		this(cast(GClosure*) p);
208 	}
209 
210 	/**
211 	 * Registers a finalization notifier which will be called when the
212 	 * reference count of @closure goes down to 0. Multiple finalization
213 	 * notifiers on a single closure are invoked in unspecified order. If
214 	 * a single call to g_closure_unref() results in the closure being
215 	 * both invalidated and finalized, then the invalidate notifiers will
216 	 * be run before the finalize notifiers.
217 	 *
218 	 * Params:
219 	 *     notifyData = data to pass to @notify_func
220 	 *     notifyFunc = the callback function to register
221 	 */
222 	public void addFinalizeNotifier(void* notifyData, GClosureNotify notifyFunc)
223 	{
224 		g_closure_add_finalize_notifier(gClosure, notifyData, notifyFunc);
225 	}
226 
227 	/**
228 	 * Registers an invalidation notifier which will be called when the
229 	 * @closure is invalidated with g_closure_invalidate(). Invalidation
230 	 * notifiers are invoked before finalization notifiers, in an
231 	 * unspecified order.
232 	 *
233 	 * Params:
234 	 *     notifyData = data to pass to @notify_func
235 	 *     notifyFunc = the callback function to register
236 	 */
237 	public void addInvalidateNotifier(void* notifyData, GClosureNotify notifyFunc)
238 	{
239 		g_closure_add_invalidate_notifier(gClosure, notifyData, notifyFunc);
240 	}
241 
242 	/**
243 	 * Adds a pair of notifiers which get invoked before and after the
244 	 * closure callback, respectively. This is typically used to protect
245 	 * the extra arguments for the duration of the callback. See
246 	 * g_object_watch_closure() for an example of marshal guards.
247 	 *
248 	 * Params:
249 	 *     preMarshalData = data to pass
250 	 *         to @pre_marshal_notify
251 	 *     preMarshalNotify = a function to call before the closure callback
252 	 *     postMarshalData = data to pass
253 	 *         to @post_marshal_notify
254 	 *     postMarshalNotify = a function to call after the closure callback
255 	 */
256 	public void addMarshalGuards(void* preMarshalData, GClosureNotify preMarshalNotify, void* postMarshalData, GClosureNotify postMarshalNotify)
257 	{
258 		g_closure_add_marshal_guards(gClosure, preMarshalData, preMarshalNotify, postMarshalData, postMarshalNotify);
259 	}
260 
261 	/**
262 	 * Sets a flag on the closure to indicate that its calling
263 	 * environment has become invalid, and thus causes any future
264 	 * invocations of g_closure_invoke() on this @closure to be
265 	 * ignored. Also, invalidation notifiers installed on the closure will
266 	 * be called at this point. Note that unless you are holding a
267 	 * reference to the closure yourself, the invalidation notifiers may
268 	 * unref the closure and cause it to be destroyed, so if you need to
269 	 * access the closure after calling g_closure_invalidate(), make sure
270 	 * that you've previously called g_closure_ref().
271 	 *
272 	 * Note that g_closure_invalidate() will also be called when the
273 	 * reference count of a closure drops to zero (unless it has already
274 	 * been invalidated before).
275 	 */
276 	public void invalidate()
277 	{
278 		g_closure_invalidate(gClosure);
279 	}
280 
281 	/**
282 	 * Invokes the closure, i.e. executes the callback represented by the @closure.
283 	 *
284 	 * Params:
285 	 *     returnValue = a #GValue to store the return
286 	 *         value. May be %NULL if the callback of @closure
287 	 *         doesn't return a value.
288 	 *     paramValues = an array of
289 	 *         #GValues holding the arguments on which to
290 	 *         invoke the callback of @closure
291 	 *     invocationHint = a context-dependent invocation hint
292 	 */
293 	public void invoke(out Value returnValue, Value[] paramValues, void* invocationHint)
294 	{
295 		GValue* outreturnValue = sliceNew!GValue();
296 
297 		GValue[] paramValuesArray = new GValue[paramValues.length];
298 		for ( int i = 0; i < paramValues.length; i++ )
299 		{
300 			paramValuesArray[i] = *(paramValues[i].getValueStruct());
301 		}
302 
303 		g_closure_invoke(gClosure, outreturnValue, cast(uint)paramValues.length, paramValuesArray.ptr, invocationHint);
304 
305 		returnValue = ObjectG.getDObject!(Value)(outreturnValue, true);
306 	}
307 
308 	/**
309 	 * Increments the reference count on a closure to force it staying
310 	 * alive while the caller holds a pointer to it.
311 	 *
312 	 * Returns: The @closure passed in, for convenience
313 	 */
314 	public Closure doref()
315 	{
316 		auto p = g_closure_ref(gClosure);
317 
318 		if(p is null)
319 		{
320 			return null;
321 		}
322 
323 		return ObjectG.getDObject!(Closure)(cast(GClosure*) p);
324 	}
325 
326 	/**
327 	 * Removes a finalization notifier.
328 	 *
329 	 * Notice that notifiers are automatically removed after they are run.
330 	 *
331 	 * Params:
332 	 *     notifyData = data which was passed to g_closure_add_finalize_notifier()
333 	 *         when registering @notify_func
334 	 *     notifyFunc = the callback function to remove
335 	 */
336 	public void removeFinalizeNotifier(void* notifyData, GClosureNotify notifyFunc)
337 	{
338 		g_closure_remove_finalize_notifier(gClosure, notifyData, notifyFunc);
339 	}
340 
341 	/**
342 	 * Removes an invalidation notifier.
343 	 *
344 	 * Notice that notifiers are automatically removed after they are run.
345 	 *
346 	 * Params:
347 	 *     notifyData = data which was passed to g_closure_add_invalidate_notifier()
348 	 *         when registering @notify_func
349 	 *     notifyFunc = the callback function to remove
350 	 */
351 	public void removeInvalidateNotifier(void* notifyData, GClosureNotify notifyFunc)
352 	{
353 		g_closure_remove_invalidate_notifier(gClosure, notifyData, notifyFunc);
354 	}
355 
356 	/**
357 	 * Sets the marshaller of @closure. The `marshal_data`
358 	 * of @marshal provides a way for a meta marshaller to provide additional
359 	 * information to the marshaller. (See g_closure_set_meta_marshal().) For
360 	 * GObject's C predefined marshallers (the g_cclosure_marshal_*()
361 	 * functions), what it provides is a callback function to use instead of
362 	 * @closure->callback.
363 	 *
364 	 * Params:
365 	 *     marshal = a #GClosureMarshal function
366 	 */
367 	public void setMarshal(GClosureMarshal marshal)
368 	{
369 		g_closure_set_marshal(gClosure, marshal);
370 	}
371 
372 	/**
373 	 * Sets the meta marshaller of @closure.  A meta marshaller wraps
374 	 * @closure->marshal and modifies the way it is called in some
375 	 * fashion. The most common use of this facility is for C callbacks.
376 	 * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
377 	 * are used everywhere, but the way that we get the callback function
378 	 * differs. In most cases we want to use @closure->callback, but in
379 	 * other cases we want to use some different technique to retrieve the
380 	 * callback function.
381 	 *
382 	 * For example, class closures for signals (see
383 	 * g_signal_type_cclosure_new()) retrieve the callback function from a
384 	 * fixed offset in the class structure.  The meta marshaller retrieves
385 	 * the right callback and passes it to the marshaller as the
386 	 * @marshal_data argument.
387 	 *
388 	 * Params:
389 	 *     marshalData = context-dependent data to pass
390 	 *         to @meta_marshal
391 	 *     metaMarshal = a #GClosureMarshal function
392 	 */
393 	public void setMetaMarshal(void* marshalData, GClosureMarshal metaMarshal)
394 	{
395 		g_closure_set_meta_marshal(gClosure, marshalData, metaMarshal);
396 	}
397 
398 	/**
399 	 * Takes over the initial ownership of a closure.  Each closure is
400 	 * initially created in a "floating" state, which means that the initial
401 	 * reference count is not owned by any caller. g_closure_sink() checks
402 	 * to see if the object is still floating, and if so, unsets the
403 	 * floating state and decreases the reference count. If the closure
404 	 * is not floating, g_closure_sink() does nothing. The reason for the
405 	 * existence of the floating state is to prevent cumbersome code
406 	 * sequences like:
407 	 * |[<!-- language="C" -->
408 	 * closure = g_cclosure_new (cb_func, cb_data);
409 	 * g_source_set_closure (source, closure);
410 	 * g_closure_unref (closure); // GObject doesn't really need this
411 	 * ]|
412 	 * Because g_source_set_closure() (and similar functions) take ownership of the
413 	 * initial reference count, if it is unowned, we instead can write:
414 	 * |[<!-- language="C" -->
415 	 * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
416 	 * ]|
417 	 *
418 	 * Generally, this function is used together with g_closure_ref(). Ane example
419 	 * of storing a closure for later notification looks like:
420 	 * |[<!-- language="C" -->
421 	 * static GClosure *notify_closure = NULL;
422 	 * void
423 	 * foo_notify_set_closure (GClosure *closure)
424 	 * {
425 	 * if (notify_closure)
426 	 * g_closure_unref (notify_closure);
427 	 * notify_closure = closure;
428 	 * if (notify_closure)
429 	 * {
430 	 * g_closure_ref (notify_closure);
431 	 * g_closure_sink (notify_closure);
432 	 * }
433 	 * }
434 	 * ]|
435 	 *
436 	 * Because g_closure_sink() may decrement the reference count of a closure
437 	 * (if it hasn't been called on @closure yet) just like g_closure_unref(),
438 	 * g_closure_ref() should be called prior to this function.
439 	 */
440 	public void sink()
441 	{
442 		g_closure_sink(gClosure);
443 	}
444 
445 	/**
446 	 * Decrements the reference count of a closure after it was previously
447 	 * incremented by the same caller. If no other callers are using the
448 	 * closure, then the closure will be destroyed and freed.
449 	 */
450 	public void unref()
451 	{
452 		g_closure_unref(gClosure);
453 	}
454 
455 	/**
456 	 * Set the callback for a source as a #GClosure.
457 	 *
458 	 * If the source is not one of the standard GLib types, the @closure_callback
459 	 * and @closure_marshal fields of the #GSourceFuncs structure must have been
460 	 * filled in with pointers to appropriate functions.
461 	 *
462 	 * Params:
463 	 *     source = the source
464 	 *     closure = a #GClosure
465 	 */
466 	public static void sourceSetClosure(Source source, Closure closure)
467 	{
468 		g_source_set_closure((source is null) ? null : source.getSourceStruct(), (closure is null) ? null : closure.getClosureStruct());
469 	}
470 
471 	/**
472 	 * Sets a dummy callback for @source. The callback will do nothing, and
473 	 * if the source expects a #gboolean return value, it will return %TRUE.
474 	 * (If the source expects any other type of return value, it will return
475 	 * a 0/%NULL value; whatever g_value_init() initializes a #GValue to for
476 	 * that type.)
477 	 *
478 	 * If the source is not one of the standard GLib types, the
479 	 * @closure_callback and @closure_marshal fields of the #GSourceFuncs
480 	 * structure must have been filled in with pointers to appropriate
481 	 * functions.
482 	 *
483 	 * Params:
484 	 *     source = the source
485 	 */
486 	public static void sourceSetDummyCallback(Source source)
487 	{
488 		g_source_set_dummy_callback((source is null) ? null : source.getSourceStruct());
489 	}
490 }