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