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 alias doref = ref_; 309 /** 310 * Increments the reference count on a closure to force it staying 311 * alive while the caller holds a pointer to it. 312 * 313 * Returns: The @closure passed in, for convenience 314 */ 315 public Closure ref_() 316 { 317 auto p = g_closure_ref(gClosure); 318 319 if(p is null) 320 { 321 return null; 322 } 323 324 return ObjectG.getDObject!(Closure)(cast(GClosure*) p); 325 } 326 327 /** 328 * Removes a finalization notifier. 329 * 330 * Notice that notifiers are automatically removed after they are run. 331 * 332 * Params: 333 * notifyData = data which was passed to g_closure_add_finalize_notifier() 334 * when registering @notify_func 335 * notifyFunc = the callback function to remove 336 */ 337 public void removeFinalizeNotifier(void* notifyData, GClosureNotify notifyFunc) 338 { 339 g_closure_remove_finalize_notifier(gClosure, notifyData, notifyFunc); 340 } 341 342 /** 343 * Removes an invalidation notifier. 344 * 345 * Notice that notifiers are automatically removed after they are run. 346 * 347 * Params: 348 * notifyData = data which was passed to g_closure_add_invalidate_notifier() 349 * when registering @notify_func 350 * notifyFunc = the callback function to remove 351 */ 352 public void removeInvalidateNotifier(void* notifyData, GClosureNotify notifyFunc) 353 { 354 g_closure_remove_invalidate_notifier(gClosure, notifyData, notifyFunc); 355 } 356 357 /** 358 * Sets the marshaller of @closure. The `marshal_data` 359 * of @marshal provides a way for a meta marshaller to provide additional 360 * information to the marshaller. (See g_closure_set_meta_marshal().) For 361 * GObject's C predefined marshallers (the g_cclosure_marshal_*() 362 * functions), what it provides is a callback function to use instead of 363 * @closure->callback. 364 * 365 * Params: 366 * marshal = a #GClosureMarshal function 367 */ 368 public void setMarshal(GClosureMarshal marshal) 369 { 370 g_closure_set_marshal(gClosure, marshal); 371 } 372 373 /** 374 * Sets the meta marshaller of @closure. A meta marshaller wraps 375 * @closure->marshal and modifies the way it is called in some 376 * fashion. The most common use of this facility is for C callbacks. 377 * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), 378 * are used everywhere, but the way that we get the callback function 379 * differs. In most cases we want to use @closure->callback, but in 380 * other cases we want to use some different technique to retrieve the 381 * callback function. 382 * 383 * For example, class closures for signals (see 384 * g_signal_type_cclosure_new()) retrieve the callback function from a 385 * fixed offset in the class structure. The meta marshaller retrieves 386 * the right callback and passes it to the marshaller as the 387 * @marshal_data argument. 388 * 389 * Params: 390 * marshalData = context-dependent data to pass 391 * to @meta_marshal 392 * metaMarshal = a #GClosureMarshal function 393 */ 394 public void setMetaMarshal(void* marshalData, GClosureMarshal metaMarshal) 395 { 396 g_closure_set_meta_marshal(gClosure, marshalData, metaMarshal); 397 } 398 399 /** 400 * Takes over the initial ownership of a closure. Each closure is 401 * initially created in a "floating" state, which means that the initial 402 * reference count is not owned by any caller. g_closure_sink() checks 403 * to see if the object is still floating, and if so, unsets the 404 * floating state and decreases the reference count. If the closure 405 * is not floating, g_closure_sink() does nothing. The reason for the 406 * existence of the floating state is to prevent cumbersome code 407 * sequences like: 408 * |[<!-- language="C" --> 409 * closure = g_cclosure_new (cb_func, cb_data); 410 * g_source_set_closure (source, closure); 411 * g_closure_unref (closure); // GObject doesn't really need this 412 * ]| 413 * Because g_source_set_closure() (and similar functions) take ownership of the 414 * initial reference count, if it is unowned, we instead can write: 415 * |[<!-- language="C" --> 416 * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); 417 * ]| 418 * 419 * Generally, this function is used together with g_closure_ref(). Ane example 420 * of storing a closure for later notification looks like: 421 * |[<!-- language="C" --> 422 * static GClosure *notify_closure = NULL; 423 * void 424 * foo_notify_set_closure (GClosure *closure) 425 * { 426 * if (notify_closure) 427 * g_closure_unref (notify_closure); 428 * notify_closure = closure; 429 * if (notify_closure) 430 * { 431 * g_closure_ref (notify_closure); 432 * g_closure_sink (notify_closure); 433 * } 434 * } 435 * ]| 436 * 437 * Because g_closure_sink() may decrement the reference count of a closure 438 * (if it hasn't been called on @closure yet) just like g_closure_unref(), 439 * g_closure_ref() should be called prior to this function. 440 */ 441 public void sink() 442 { 443 g_closure_sink(gClosure); 444 } 445 446 /** 447 * Decrements the reference count of a closure after it was previously 448 * incremented by the same caller. If no other callers are using the 449 * closure, then the closure will be destroyed and freed. 450 */ 451 public void unref() 452 { 453 g_closure_unref(gClosure); 454 } 455 456 /** 457 * Set the callback for a source as a #GClosure. 458 * 459 * If the source is not one of the standard GLib types, the @closure_callback 460 * and @closure_marshal fields of the #GSourceFuncs structure must have been 461 * filled in with pointers to appropriate functions. 462 * 463 * Params: 464 * source = the source 465 * closure = a #GClosure 466 */ 467 public static void sourceSetClosure(Source source, Closure closure) 468 { 469 g_source_set_closure((source is null) ? null : source.getSourceStruct(), (closure is null) ? null : closure.getClosureStruct()); 470 } 471 472 /** 473 * Sets a dummy callback for @source. The callback will do nothing, and 474 * if the source expects a #gboolean return value, it will return %TRUE. 475 * (If the source expects any other type of return value, it will return 476 * a 0/%NULL value; whatever g_value_init() initializes a #GValue to for 477 * that type.) 478 * 479 * If the source is not one of the standard GLib types, the 480 * @closure_callback and @closure_marshal fields of the #GSourceFuncs 481 * structure must have been filled in with pointers to appropriate 482 * functions. 483 * 484 * Params: 485 * source = the source 486 */ 487 public static void sourceSetDummyCallback(Source source) 488 { 489 g_source_set_dummy_callback((source is null) ? null : source.getSourceStruct()); 490 } 491 }