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