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 gtkc.gobject; 32 public import gtkc.gobjecttypes; 33 private import gtkd.Loader; 34 35 36 /** 37 * A #GClosure represents a callback supplied by the programmer. It 38 * will generally comprise a function of some kind and a marshaller 39 * used to call it. It is the responsibility of the marshaller to 40 * convert the arguments for the invocation from #GValues into 41 * a suitable form, perform the callback on the converted arguments, 42 * and transform the return value back into a #GValue. 43 * 44 * In the case of C programs, a closure usually just holds a pointer 45 * to a function and maybe a data argument, and the marshaller 46 * converts between #GValue and native C types. The GObject 47 * library provides the #GCClosure type for this purpose. Bindings for 48 * other languages need marshallers which convert between #GValue<!-- 49 * -->s and suitable representations in the runtime of the language in 50 * order to use functions written in that languages as callbacks. 51 * 52 * Within GObject, closures play an important role in the 53 * implementation of signals. When a signal is registered, the 54 * @c_marshaller argument to g_signal_new() specifies the default C 55 * marshaller for any closure which is connected to this 56 * signal. GObject provides a number of C marshallers for this 57 * purpose, see the g_cclosure_marshal_*() functions. Additional C 58 * marshallers can be generated with the [glib-genmarshal][glib-genmarshal] 59 * utility. Closures can be explicitly connected to signals with 60 * g_signal_connect_closure(), but it usually more convenient to let 61 * GObject create a closure automatically by using one of the 62 * g_signal_connect_*() functions which take a callback function/user 63 * data pair. 64 * 65 * Using closures has a number of important advantages over a simple 66 * callback function/data pointer combination: 67 * 68 * - Closures allow the callee to get the types of the callback parameters, 69 * which means that language bindings don't have to write individual glue 70 * for each callback type. 71 * 72 * - The reference counting of #GClosure makes it easy to handle reentrancy 73 * right; if a callback is removed while it is being invoked, the closure 74 * and its parameters won't be freed until the invocation finishes. 75 * 76 * - g_closure_invalidate() and invalidation notifiers allow callbacks to be 77 * automatically removed when the objects they point to go away. 78 */ 79 public class Closure 80 { 81 /** the main Gtk struct */ 82 protected GClosure* gClosure; 83 protected bool ownedRef; 84 85 /** Get the main Gtk struct */ 86 public GClosure* getClosureStruct(bool transferOwnership = false) 87 { 88 if (transferOwnership) 89 ownedRef = false; 90 return gClosure; 91 } 92 93 /** the main Gtk struct as a void* */ 94 protected void* getStruct() 95 { 96 return cast(void*)gClosure; 97 } 98 99 /** 100 * Sets our main struct and passes it to the parent class. 101 */ 102 public this (GClosure* gClosure, bool ownedRef = false) 103 { 104 this.gClosure = gClosure; 105 this.ownedRef = ownedRef; 106 } 107 108 ~this () 109 { 110 if ( Linker.isLoaded(LIBRARY_GOBJECT) && ownedRef ) 111 g_closure_unref(gClosure); 112 } 113 114 115 /** */ 116 public static GType getType() 117 { 118 return g_closure_get_type(); 119 } 120 121 /** 122 * A variant of g_closure_new_simple() which stores @object in the 123 * @data field of the closure and calls g_object_watch_closure() on 124 * @object and the created closure. This function is mainly useful 125 * when implementing new types of closures. 126 * 127 * Params: 128 * sizeofClosure = the size of the structure to allocate, must be at least 129 * `sizeof (GClosure)` 130 * object = a #GObject pointer to store in the @data field of the newly 131 * allocated #GClosure 132 * 133 * Returns: a newly allocated #GClosure 134 * 135 * Throws: ConstructionException GTK+ fails to create the object. 136 */ 137 public this(uint sizeofClosure, ObjectG object) 138 { 139 auto p = g_closure_new_object(sizeofClosure, (object is null) ? null : object.getObjectGStruct()); 140 141 if(p is null) 142 { 143 throw new ConstructionException("null returned by new_object"); 144 } 145 146 this(cast(GClosure*) p); 147 } 148 149 /** 150 * Allocates a struct of the given size and initializes the initial 151 * part as a #GClosure. This function is mainly useful when 152 * implementing new types of closures. 153 * 154 * |[<!-- language="C" --> 155 * typedef struct _MyClosure MyClosure; 156 * struct _MyClosure 157 * { 158 * GClosure closure; 159 * // extra data goes here 160 * }; 161 * 162 * static void 163 * my_closure_finalize (gpointer notify_data, 164 * GClosure *closure) 165 * { 166 * MyClosure *my_closure = (MyClosure *)closure; 167 * 168 * // free extra data here 169 * } 170 * 171 * MyClosure *my_closure_new (gpointer data) 172 * { 173 * GClosure *closure; 174 * MyClosure *my_closure; 175 * 176 * closure = g_closure_new_simple (sizeof (MyClosure), data); 177 * my_closure = (MyClosure *) closure; 178 * 179 * // initialize extra data here 180 * 181 * g_closure_add_finalize_notifier (closure, notify_data, 182 * my_closure_finalize); 183 * return my_closure; 184 * } 185 * ]| 186 * 187 * Params: 188 * sizeofClosure = the size of the structure to allocate, must be at least 189 * `sizeof (GClosure)` 190 * data = data to store in the @data field of the newly allocated #GClosure 191 * 192 * Returns: a newly allocated #GClosure 193 * 194 * Throws: ConstructionException GTK+ fails to create the object. 195 */ 196 public this(uint sizeofClosure, void* data) 197 { 198 auto p = g_closure_new_simple(sizeofClosure, data); 199 200 if(p is null) 201 { 202 throw new ConstructionException("null returned by new_simple"); 203 } 204 205 this(cast(GClosure*) p); 206 } 207 208 /** 209 * Registers a finalization notifier which will be called when the 210 * reference count of @closure goes down to 0. Multiple finalization 211 * notifiers on a single closure are invoked in unspecified order. If 212 * a single call to g_closure_unref() results in the closure being 213 * both invalidated and finalized, then the invalidate notifiers will 214 * be run before the finalize notifiers. 215 * 216 * Params: 217 * notifyData = data to pass to @notify_func 218 * notifyFunc = the callback function to register 219 */ 220 public void addFinalizeNotifier(void* notifyData, GClosureNotify notifyFunc) 221 { 222 g_closure_add_finalize_notifier(gClosure, notifyData, notifyFunc); 223 } 224 225 /** 226 * Registers an invalidation notifier which will be called when the 227 * @closure is invalidated with g_closure_invalidate(). Invalidation 228 * notifiers are invoked before finalization notifiers, in an 229 * unspecified order. 230 * 231 * Params: 232 * notifyData = data to pass to @notify_func 233 * notifyFunc = the callback function to register 234 */ 235 public void addInvalidateNotifier(void* notifyData, GClosureNotify notifyFunc) 236 { 237 g_closure_add_invalidate_notifier(gClosure, notifyData, notifyFunc); 238 } 239 240 /** 241 * Adds a pair of notifiers which get invoked before and after the 242 * closure callback, respectively. This is typically used to protect 243 * the extra arguments for the duration of the callback. See 244 * g_object_watch_closure() for an example of marshal guards. 245 * 246 * Params: 247 * preMarshalData = data to pass 248 * to @pre_marshal_notify 249 * preMarshalNotify = a function to call before the closure callback 250 * postMarshalData = data to pass 251 * to @post_marshal_notify 252 * postMarshalNotify = a function to call after the closure callback 253 */ 254 public void addMarshalGuards(void* preMarshalData, GClosureNotify preMarshalNotify, void* postMarshalData, GClosureNotify postMarshalNotify) 255 { 256 g_closure_add_marshal_guards(gClosure, preMarshalData, preMarshalNotify, postMarshalData, postMarshalNotify); 257 } 258 259 /** 260 * Sets a flag on the closure to indicate that its calling 261 * environment has become invalid, and thus causes any future 262 * invocations of g_closure_invoke() on this @closure to be 263 * ignored. Also, invalidation notifiers installed on the closure will 264 * be called at this point. Note that unless you are holding a 265 * reference to the closure yourself, the invalidation notifiers may 266 * unref the closure and cause it to be destroyed, so if you need to 267 * access the closure after calling g_closure_invalidate(), make sure 268 * that you've previously called g_closure_ref(). 269 * 270 * Note that g_closure_invalidate() will also be called when the 271 * reference count of a closure drops to zero (unless it has already 272 * been invalidated before). 273 */ 274 public void invalidate() 275 { 276 g_closure_invalidate(gClosure); 277 } 278 279 /** 280 * Invokes the closure, i.e. executes the callback represented by the @closure. 281 * 282 * Params: 283 * returnValue = a #GValue to store the return 284 * value. May be %NULL if the callback of @closure 285 * doesn't return a value. 286 * nParamValues = the length of the @param_values array 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 }