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.ObjectG; 26 27 private import core.memory; 28 private import glib.ConstructionException; 29 private import glib.Str; 30 private import gobject.Binding; 31 private import gobject.Closure; 32 private import gobject.ObjectG; 33 private import gobject.ParamSpec; 34 private import gobject.Signals; 35 private import gobject.TypeInterface; 36 private import gobject.Value; 37 private import gobject.c.functions; 38 public import gobject.c.types; 39 public import gtkc.gobjecttypes; 40 private import gtkd.Loader; 41 private import std.algorithm; 42 private import std.traits; 43 44 45 /** 46 * All the fields in the GObject structure are private 47 * to the #GObject implementation and should never be accessed directly. 48 */ 49 public class ObjectG 50 { 51 /** the main Gtk struct */ 52 protected GObject* gObject; 53 protected bool ownedRef; 54 55 /** Get the main Gtk struct */ 56 public GObject* getObjectGStruct(bool transferOwnership = false) 57 { 58 if (transferOwnership) 59 ownedRef = false; 60 return gObject; 61 } 62 63 /** the main Gtk struct as a void* */ 64 protected void* getStruct() 65 { 66 return cast(void*)gObject; 67 } 68 69 protected bool isGcRoot; 70 71 /** 72 * Sets our main struct and passes store it on the gobject. 73 * Add a gabage collector root to the gtk+ struct so it doesn't get collect 74 */ 75 public this (GObject* gObject, bool ownedRef = false) 76 { 77 this.gObject = gObject; 78 if ( gObject !is null ) 79 { 80 setDataFull("GObject", cast(void*)this, cast(GDestroyNotify)&destroyNotify); 81 addToggleRef(cast(GToggleNotify)&toggleNotify, cast(void*)this); 82 83 //If the refCount is larger then 1 toggleNotify isn't called 84 if (gObject.refCount > 1 && !isGcRoot) 85 { 86 GC.addRoot(cast(void*)this); 87 isGcRoot = true; 88 } 89 90 //Remove the floating reference if there is one. 91 if ( isFloating() ) 92 { 93 refSink(); 94 unref(); 95 } 96 //If we already owned this reference remove the one added by addToggleRef. 97 else if ( ownedRef ) 98 { 99 unref(); 100 } 101 } 102 } 103 104 extern(C) 105 { 106 static void destroyNotify(ObjectG obj) 107 { 108 if ( obj.isGcRoot ) 109 { 110 GC.removeRoot(cast(void*)obj); 111 obj.isGcRoot = false; 112 } 113 114 if ( obj.gObject.refCount > 0 ) 115 obj.removeToggleRef(cast(GToggleNotify)&toggleNotify, cast(void*)obj); 116 117 obj.gObject = null; 118 } 119 120 static void toggleNotify(ObjectG obj, GObject* object, int isLastRef) 121 { 122 if ( isLastRef && obj.isGcRoot ) 123 { 124 GC.removeRoot(cast(void*)obj); 125 obj.isGcRoot = false; 126 } 127 else if ( !obj.isGcRoot ) 128 { 129 GC.addRoot(cast(void*)obj); 130 obj.isGcRoot = true; 131 } 132 } 133 } 134 135 ~this() 136 { 137 static if ( isPointer!(typeof(g_object_steal_data)) ) 138 bool libLoaded = Linker.isLoaded(LIBRARY_GOBJECT); 139 else 140 enum libLoaded = true; 141 142 if ( libLoaded && gObject !is null ) 143 { 144 // Remove the GDestroyNotify callback, 145 // for when the D object is destroyed before the C one. 146 g_object_steal_data(gObject, cast(char*)"GObject"); 147 148 if ( isGcRoot ) 149 { 150 GC.removeRoot(cast(void*)this); 151 isGcRoot = false; 152 } 153 154 g_object_remove_toggle_ref(gObject, cast(GToggleNotify)&toggleNotify, cast(void*)this); 155 } 156 } 157 158 /** */ 159 T opCast(T)() 160 { 161 if ( !this ) 162 return null; 163 164 static if ( is(T : ObjectG) 165 && !is(T == interface) 166 && is(typeof(new T(cast(typeof(T.tupleof[0]))gObject, false))) ) 167 { 168 //If a regular cast works, return the result. 169 if ( auto r = cast(T)super ) 170 return r; 171 172 //Prints a warning if the cast is invalid. 173 //g_type_check_instance_cast(cast(GTypeInstance*)gObject, T.getType()); 174 175 //Can we cast this type to T. 176 if ( !g_type_is_a(gObject.gTypeInstance.gClass.gType, T.getType()) ) 177 return null; 178 179 //Remove the GDestroyNotify callback for the original d object. 180 g_object_steal_data(gObject, "GObject"); 181 //Remove the original object as a GC root if needed. 182 if ( isGcRoot ) 183 { 184 GC.removeRoot(cast(void*)this); 185 isGcRoot = false; 186 } 187 //Add a reference for the original D object before we remove the toggle reference. 188 g_object_ref(gObject); 189 g_object_remove_toggle_ref(gObject, cast(GToggleNotify)&toggleNotify, cast(void*)this); 190 191 //The new object handles the memory management. 192 return new T(cast(typeof(T.tupleof[0]))gObject, false); 193 } 194 else static if ( is(T == interface) 195 && hasStaticMember!(T, "getType") 196 && is(ReturnType!(T.getType) == GType) ) 197 { 198 //If a regular cast works, return the result. 199 if ( auto r = cast(T)super ) 200 return r; 201 202 //Do we implement interface T. 203 if ( !g_type_is_a(gObject.gTypeInstance.gClass.gType, T.getType()) ) 204 return null; 205 206 return getInterfaceInstance!T(gObject); 207 } 208 else 209 return cast(T)super; 210 } 211 212 unittest 213 { 214 ObjectG obj = null; 215 216 assert( (cast(Binding)obj) is null ); 217 } 218 219 /** 220 * Gets a D Object from the objects table of associations. 221 * Params: 222 * obj = GObject containing the associations. 223 * Returns: the D Object if found, or a newly constructed object if no such Object exists. 224 */ 225 public static RT getDObject(T, RT=T, U)(U obj, bool ownedRef = false) 226 { 227 if ( obj is null ) 228 { 229 return null; 230 } 231 232 static if ( is(T : ObjectG) && !is(RT == interface) ) 233 { 234 auto p = g_object_get_data(cast(GObject*)obj, Str.toStringz("GObject")); 235 236 if ( p !is null ) 237 return cast(RT)cast(ObjectG)p; 238 else 239 return new T(obj, ownedRef); 240 } 241 else static if ( is(RT == interface) && hasMember!(RT, "getType") && is(ReturnType!(RT.getType) == GType) ) 242 { 243 auto p = g_object_get_data(cast(GObject*)obj, Str.toStringz("GObject")); 244 245 if ( p !is null ) 246 return cast(RT)cast(ObjectG)p; 247 else 248 return getInterfaceInstance!RT(cast(GObject*)obj); 249 } 250 else 251 { 252 return new T(obj, ownedRef); 253 } 254 } 255 256 private static I getInterfaceInstance(I)(GObject* instance) 257 { 258 static class Impl: ObjectG, I 259 { 260 public this (GObject* gObject, bool ownedRef = false) 261 { 262 super(gObject, ownedRef); 263 } 264 265 /** the main Gtk struct as a void* */ 266 protected override void* getStruct() 267 { 268 return cast(void*)gObject; 269 } 270 271 // add the interface capabilities 272 mixin("import "~ moduleName!I[0..$-2] ~"T;import "~ moduleName!I ~"; mixin "~ __traits(identifier, I)[0..$-2] ~"T!("~__traits(identifier, Impl)~");"); 273 } 274 275 ClassInfo ci = Impl.classinfo; 276 Impl iface; 277 void* p; 278 279 //Skip all the setup for the memory management, 280 //and only add an extra reference for the instance returned. 281 p = GC.malloc(ci.initializer.length, GC.BlkAttr.FINALIZE, ci); 282 p[0..ci.initializer.length] = ci.initializer; 283 iface = cast(Impl)p; 284 iface.gObject = instance; 285 iface.addToggleRef(cast(GToggleNotify)&toggleNotify, cast(void*)iface); 286 287 return iface; 288 } 289 290 /** */ 291 public void setProperty(T)(string propertyName, T value) 292 { 293 setProperty(propertyName, new Value(value)); 294 } 295 296 deprecated("Use the member function") 297 public static void unref(ObjectG obj) 298 { 299 obj.unref(); 300 } 301 302 deprecated("Use the member function") 303 public static ObjectG doref(ObjectG obj) 304 { 305 return obj.doref(); 306 } 307 308 /** 309 * The notify signal is emitted on an object when one of its 310 * properties has been changed. Note that getting this signal 311 * doesn't guarantee that the value of the property has actually 312 * changed, it may also be emitted when the setter for the property 313 * is called to reinstate the previous value. 314 * 315 * This signal is typically used to obtain change notification for a 316 * single property. 317 * 318 * It is important to note that you must use 319 * canonical parameter names for the property. 320 * 321 * Params: 322 * dlg = The callback. 323 * property = Set this if you only want to receive the signal for a specific property. 324 * connectFlags = The behavior of the signal's connection. 325 */ 326 gulong addOnNotify(void delegate(ParamSpec, ObjectG) dlg, string property = "", ConnectFlags connectFlags=cast(ConnectFlags)0) 327 { 328 string signalName; 329 330 if ( property == "" ) 331 signalName = "notify"; 332 else 333 signalName = "notify::"~ property; 334 335 return Signals.connect(this, signalName, dlg, connectFlags ^ ConnectFlags.SWAPPED); 336 } 337 338 /** 339 */ 340 341 /** */ 342 public static GType getType() 343 { 344 return g_initially_unowned_get_type(); 345 } 346 347 /** 348 * Creates a new instance of a #GObject subtype and sets its properties. 349 * 350 * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) 351 * which are not explicitly specified are set to their default values. 352 * 353 * Params: 354 * objectType = the type id of the #GObject subtype to instantiate 355 * firstPropertyName = the name of the first property 356 * varArgs = the value of the first property, followed optionally by more 357 * name/value pairs, followed by %NULL 358 * 359 * Returns: a new instance of @object_type 360 * 361 * Throws: ConstructionException GTK+ fails to create the object. 362 */ 363 public this(GType objectType, string firstPropertyName, void* varArgs) 364 { 365 auto p = g_object_new_valist(objectType, Str.toStringz(firstPropertyName), varArgs); 366 367 if(p is null) 368 { 369 throw new ConstructionException("null returned by new_valist"); 370 } 371 372 this(cast(GObject*) p, true); 373 } 374 375 /** 376 * Creates a new instance of a #GObject subtype and sets its properties using 377 * the provided arrays. Both arrays must have exactly @n_properties elements, 378 * and the names and values correspond by index. 379 * 380 * Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) 381 * which are not explicitly specified are set to their default values. 382 * 383 * Params: 384 * objectType = the object type to instantiate 385 * names = the names of each property to be set 386 * values = the values of each property to be set 387 * 388 * Returns: a new instance of 389 * @object_type 390 * 391 * Since: 2.54 392 * 393 * Throws: ConstructionException GTK+ fails to create the object. 394 */ 395 public this(GType objectType, string[] names, Value[] values) 396 { 397 GValue[] valuesArray = new GValue[values.length]; 398 for ( int i = 0; i < values.length; i++ ) 399 { 400 valuesArray[i] = *(values[i].getValueStruct()); 401 } 402 403 auto p = g_object_new_with_properties(objectType, cast(uint)values.length, Str.toStringzArray(names), valuesArray.ptr); 404 405 if(p is null) 406 { 407 throw new ConstructionException("null returned by new_with_properties"); 408 } 409 410 this(cast(GObject*) p, true); 411 } 412 413 /** 414 * Creates a new instance of a #GObject subtype and sets its properties. 415 * 416 * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) 417 * which are not explicitly specified are set to their default values. 418 * 419 * Deprecated: Use g_object_new_with_properties() instead. 420 * deprecated. See #GParameter for more information. 421 * 422 * Params: 423 * objectType = the type id of the #GObject subtype to instantiate 424 * parameters = an array of #GParameter 425 * 426 * Returns: a new instance of 427 * @object_type 428 * 429 * Throws: ConstructionException GTK+ fails to create the object. 430 */ 431 public this(GType objectType, GParameter[] parameters) 432 { 433 auto p = g_object_newv(objectType, cast(uint)parameters.length, parameters.ptr); 434 435 if(p is null) 436 { 437 throw new ConstructionException("null returned by newv"); 438 } 439 440 this(cast(GObject*) p, true); 441 } 442 443 /** */ 444 public static size_t compatControl(size_t what, void* data) 445 { 446 return g_object_compat_control(what, data); 447 } 448 449 /** 450 * Find the #GParamSpec with the given name for an 451 * interface. Generally, the interface vtable passed in as @g_iface 452 * will be the default vtable from g_type_default_interface_ref(), or, 453 * if you know the interface has already been loaded, 454 * g_type_default_interface_peek(). 455 * 456 * Params: 457 * gIface = any interface vtable for the 458 * interface, or the default vtable for the interface 459 * propertyName = name of a property to lookup. 460 * 461 * Returns: the #GParamSpec for the property of the 462 * interface with the name @property_name, or %NULL if no 463 * such property exists. 464 * 465 * Since: 2.4 466 */ 467 public static ParamSpec interfaceFindProperty(TypeInterface gIface, string propertyName) 468 { 469 auto p = g_object_interface_find_property((gIface is null) ? null : gIface.getTypeInterfaceStruct(), Str.toStringz(propertyName)); 470 471 if(p is null) 472 { 473 return null; 474 } 475 476 return ObjectG.getDObject!(ParamSpec)(cast(GParamSpec*) p); 477 } 478 479 /** 480 * Add a property to an interface; this is only useful for interfaces 481 * that are added to GObject-derived types. Adding a property to an 482 * interface forces all objects classes with that interface to have a 483 * compatible property. The compatible property could be a newly 484 * created #GParamSpec, but normally 485 * g_object_class_override_property() will be used so that the object 486 * class only needs to provide an implementation and inherits the 487 * property description, default value, bounds, and so forth from the 488 * interface property. 489 * 490 * This function is meant to be called from the interface's default 491 * vtable initialization function (the @class_init member of 492 * #GTypeInfo.) It must not be called after after @class_init has 493 * been called for any object types implementing this interface. 494 * 495 * If @pspec is a floating reference, it will be consumed. 496 * 497 * Params: 498 * gIface = any interface vtable for the 499 * interface, or the default 500 * vtable for the interface. 501 * pspec = the #GParamSpec for the new property 502 * 503 * Since: 2.4 504 */ 505 public static void interfaceInstallProperty(TypeInterface gIface, ParamSpec pspec) 506 { 507 g_object_interface_install_property((gIface is null) ? null : gIface.getTypeInterfaceStruct(), (pspec is null) ? null : pspec.getParamSpecStruct()); 508 } 509 510 /** 511 * Lists the properties of an interface.Generally, the interface 512 * vtable passed in as @g_iface will be the default vtable from 513 * g_type_default_interface_ref(), or, if you know the interface has 514 * already been loaded, g_type_default_interface_peek(). 515 * 516 * Params: 517 * gIface = any interface vtable for the 518 * interface, or the default vtable for the interface 519 * 520 * Returns: a 521 * pointer to an array of pointers to #GParamSpec 522 * structures. The paramspecs are owned by GLib, but the 523 * array should be freed with g_free() when you are done with 524 * it. 525 * 526 * Since: 2.4 527 */ 528 public static ParamSpec[] interfaceListProperties(TypeInterface gIface) 529 { 530 uint nPropertiesP; 531 532 auto p = g_object_interface_list_properties((gIface is null) ? null : gIface.getTypeInterfaceStruct(), &nPropertiesP); 533 534 if(p is null) 535 { 536 return null; 537 } 538 539 ParamSpec[] arr = new ParamSpec[nPropertiesP]; 540 for(int i = 0; i < nPropertiesP; i++) 541 { 542 arr[i] = ObjectG.getDObject!(ParamSpec)(cast(GParamSpec*) p[i]); 543 } 544 545 return arr; 546 } 547 548 /** 549 * Increases the reference count of the object by one and sets a 550 * callback to be called when all other references to the object are 551 * dropped, or when this is already the last reference to the object 552 * and another reference is established. 553 * 554 * This functionality is intended for binding @object to a proxy 555 * object managed by another memory manager. This is done with two 556 * paired references: the strong reference added by 557 * g_object_add_toggle_ref() and a reverse reference to the proxy 558 * object which is either a strong reference or weak reference. 559 * 560 * The setup is that when there are no other references to @object, 561 * only a weak reference is held in the reverse direction from @object 562 * to the proxy object, but when there are other references held to 563 * @object, a strong reference is held. The @notify callback is called 564 * when the reference from @object to the proxy object should be 565 * "toggled" from strong to weak (@is_last_ref true) or weak to strong 566 * (@is_last_ref false). 567 * 568 * Since a (normal) reference must be held to the object before 569 * calling g_object_add_toggle_ref(), the initial state of the reverse 570 * link is always strong. 571 * 572 * Multiple toggle references may be added to the same gobject, 573 * however if there are multiple toggle references to an object, none 574 * of them will ever be notified until all but one are removed. For 575 * this reason, you should only ever use a toggle reference if there 576 * is important state in the proxy object. 577 * 578 * Params: 579 * notify = a function to call when this reference is the 580 * last reference to the object, or is no longer 581 * the last reference. 582 * data = data to pass to @notify 583 * 584 * Since: 2.8 585 */ 586 public void addToggleRef(GToggleNotify notify, void* data) 587 { 588 g_object_add_toggle_ref(gObject, notify, data); 589 } 590 591 /** 592 * Adds a weak reference from weak_pointer to @object to indicate that 593 * the pointer located at @weak_pointer_location is only valid during 594 * the lifetime of @object. When the @object is finalized, 595 * @weak_pointer will be set to %NULL. 596 * 597 * Note that as with g_object_weak_ref(), the weak references created by 598 * this method are not thread-safe: they cannot safely be used in one 599 * thread if the object's last g_object_unref() might happen in another 600 * thread. Use #GWeakRef if thread-safety is required. 601 * 602 * Params: 603 * weakPointerLocation = The memory address 604 * of a pointer. 605 */ 606 public void addWeakPointer(ref void* weakPointerLocation) 607 { 608 g_object_add_weak_pointer(gObject, &weakPointerLocation); 609 } 610 611 /** 612 * Creates a binding between @source_property on @source and @target_property 613 * on @target. Whenever the @source_property is changed the @target_property is 614 * updated using the same value. For instance: 615 * 616 * |[ 617 * g_object_bind_property (action, "active", widget, "sensitive", 0); 618 * ]| 619 * 620 * Will result in the "sensitive" property of the widget #GObject instance to be 621 * updated with the same value of the "active" property of the action #GObject 622 * instance. 623 * 624 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: 625 * if @target_property on @target changes then the @source_property on @source 626 * will be updated as well. 627 * 628 * The binding will automatically be removed when either the @source or the 629 * @target instances are finalized. To remove the binding without affecting the 630 * @source and the @target you can just call g_object_unref() on the returned 631 * #GBinding instance. 632 * 633 * A #GObject can have multiple bindings. 634 * 635 * Params: 636 * sourceProperty = the property on @source to bind 637 * target = the target #GObject 638 * targetProperty = the property on @target to bind 639 * flags = flags to pass to #GBinding 640 * 641 * Returns: the #GBinding instance representing the 642 * binding between the two #GObject instances. The binding is released 643 * whenever the #GBinding reference count reaches zero. 644 * 645 * Since: 2.26 646 */ 647 public Binding bindProperty(string sourceProperty, ObjectG target, string targetProperty, GBindingFlags flags) 648 { 649 auto p = g_object_bind_property(gObject, Str.toStringz(sourceProperty), (target is null) ? null : target.getObjectGStruct(), Str.toStringz(targetProperty), flags); 650 651 if(p is null) 652 { 653 return null; 654 } 655 656 return ObjectG.getDObject!(Binding)(cast(GBinding*) p); 657 } 658 659 /** 660 * Complete version of g_object_bind_property(). 661 * 662 * Creates a binding between @source_property on @source and @target_property 663 * on @target, allowing you to set the transformation functions to be used by 664 * the binding. 665 * 666 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: 667 * if @target_property on @target changes then the @source_property on @source 668 * will be updated as well. The @transform_from function is only used in case 669 * of bidirectional bindings, otherwise it will be ignored 670 * 671 * The binding will automatically be removed when either the @source or the 672 * @target instances are finalized. To remove the binding without affecting the 673 * @source and the @target you can just call g_object_unref() on the returned 674 * #GBinding instance. 675 * 676 * A #GObject can have multiple bindings. 677 * 678 * The same @user_data parameter will be used for both @transform_to 679 * and @transform_from transformation functions; the @notify function will 680 * be called once, when the binding is removed. If you need different data 681 * for each transformation function, please use 682 * g_object_bind_property_with_closures() instead. 683 * 684 * Params: 685 * sourceProperty = the property on @source to bind 686 * target = the target #GObject 687 * targetProperty = the property on @target to bind 688 * flags = flags to pass to #GBinding 689 * transformTo = the transformation function 690 * from the @source to the @target, or %NULL to use the default 691 * transformFrom = the transformation function 692 * from the @target to the @source, or %NULL to use the default 693 * userData = custom data to be passed to the transformation functions, 694 * or %NULL 695 * notify = a function to call when disposing the binding, to free 696 * resources used by the transformation functions, or %NULL if not required 697 * 698 * Returns: the #GBinding instance representing the 699 * binding between the two #GObject instances. The binding is released 700 * whenever the #GBinding reference count reaches zero. 701 * 702 * Since: 2.26 703 */ 704 public Binding bindPropertyFull(string sourceProperty, ObjectG target, string targetProperty, GBindingFlags flags, GBindingTransformFunc transformTo, GBindingTransformFunc transformFrom, void* userData, GDestroyNotify notify) 705 { 706 auto p = g_object_bind_property_full(gObject, Str.toStringz(sourceProperty), (target is null) ? null : target.getObjectGStruct(), Str.toStringz(targetProperty), flags, transformTo, transformFrom, userData, notify); 707 708 if(p is null) 709 { 710 return null; 711 } 712 713 return ObjectG.getDObject!(Binding)(cast(GBinding*) p); 714 } 715 716 /** 717 * Creates a binding between @source_property on @source and @target_property 718 * on @target, allowing you to set the transformation functions to be used by 719 * the binding. 720 * 721 * This function is the language bindings friendly version of 722 * g_object_bind_property_full(), using #GClosures instead of 723 * function pointers. 724 * 725 * Params: 726 * sourceProperty = the property on @source to bind 727 * target = the target #GObject 728 * targetProperty = the property on @target to bind 729 * flags = flags to pass to #GBinding 730 * transformTo = a #GClosure wrapping the transformation function 731 * from the @source to the @target, or %NULL to use the default 732 * transformFrom = a #GClosure wrapping the transformation function 733 * from the @target to the @source, or %NULL to use the default 734 * 735 * Returns: the #GBinding instance representing the 736 * binding between the two #GObject instances. The binding is released 737 * whenever the #GBinding reference count reaches zero. 738 * 739 * Since: 2.26 740 */ 741 public Binding bindPropertyWithClosures(string sourceProperty, ObjectG target, string targetProperty, GBindingFlags flags, Closure transformTo, Closure transformFrom) 742 { 743 auto p = g_object_bind_property_with_closures(gObject, Str.toStringz(sourceProperty), (target is null) ? null : target.getObjectGStruct(), Str.toStringz(targetProperty), flags, (transformTo is null) ? null : transformTo.getClosureStruct(), (transformFrom is null) ? null : transformFrom.getClosureStruct()); 744 745 if(p is null) 746 { 747 return null; 748 } 749 750 return ObjectG.getDObject!(Binding)(cast(GBinding*) p); 751 } 752 753 /** 754 * This is a variant of g_object_get_data() which returns 755 * a 'duplicate' of the value. @dup_func defines the 756 * meaning of 'duplicate' in this context, it could e.g. 757 * take a reference on a ref-counted object. 758 * 759 * If the @key is not set on the object then @dup_func 760 * will be called with a %NULL argument. 761 * 762 * Note that @dup_func is called while user data of @object 763 * is locked. 764 * 765 * This function can be useful to avoid races when multiple 766 * threads are using object data on the same key on the same 767 * object. 768 * 769 * Params: 770 * key = a string, naming the user data pointer 771 * dupFunc = function to dup the value 772 * userData = passed as user_data to @dup_func 773 * 774 * Returns: the result of calling @dup_func on the value 775 * associated with @key on @object, or %NULL if not set. 776 * If @dup_func is %NULL, the value is returned 777 * unmodified. 778 * 779 * Since: 2.34 780 */ 781 public void* dupData(string key, GDuplicateFunc dupFunc, void* userData) 782 { 783 return g_object_dup_data(gObject, Str.toStringz(key), dupFunc, userData); 784 } 785 786 /** 787 * This is a variant of g_object_get_qdata() which returns 788 * a 'duplicate' of the value. @dup_func defines the 789 * meaning of 'duplicate' in this context, it could e.g. 790 * take a reference on a ref-counted object. 791 * 792 * If the @quark is not set on the object then @dup_func 793 * will be called with a %NULL argument. 794 * 795 * Note that @dup_func is called while user data of @object 796 * is locked. 797 * 798 * This function can be useful to avoid races when multiple 799 * threads are using object data on the same key on the same 800 * object. 801 * 802 * Params: 803 * quark = a #GQuark, naming the user data pointer 804 * dupFunc = function to dup the value 805 * userData = passed as user_data to @dup_func 806 * 807 * Returns: the result of calling @dup_func on the value 808 * associated with @quark on @object, or %NULL if not set. 809 * If @dup_func is %NULL, the value is returned 810 * unmodified. 811 * 812 * Since: 2.34 813 */ 814 public void* dupQdata(GQuark quark, GDuplicateFunc dupFunc, void* userData) 815 { 816 return g_object_dup_qdata(gObject, quark, dupFunc, userData); 817 } 818 819 /** 820 * This function is intended for #GObject implementations to re-enforce 821 * a [floating][floating-ref] object reference. Doing this is seldom 822 * required: all #GInitiallyUnowneds are created with a floating reference 823 * which usually just needs to be sunken by calling g_object_ref_sink(). 824 * 825 * Since: 2.10 826 */ 827 public void forceFloating() 828 { 829 g_object_force_floating(gObject); 830 } 831 832 /** 833 * Increases the freeze count on @object. If the freeze count is 834 * non-zero, the emission of "notify" signals on @object is 835 * stopped. The signals are queued until the freeze count is decreased 836 * to zero. Duplicate notifications are squashed so that at most one 837 * #GObject::notify signal is emitted for each property modified while the 838 * object is frozen. 839 * 840 * This is necessary for accessors that modify multiple properties to prevent 841 * premature notification while the object is still being modified. 842 */ 843 public void freezeNotify() 844 { 845 g_object_freeze_notify(gObject); 846 } 847 848 /** 849 * Gets a named field from the objects table of associations (see g_object_set_data()). 850 * 851 * Params: 852 * key = name of the key for that association 853 * 854 * Returns: the data if found, 855 * or %NULL if no such data exists. 856 */ 857 public void* getData(string key) 858 { 859 return g_object_get_data(gObject, Str.toStringz(key)); 860 } 861 862 /** 863 * Gets a property of an object. @value must have been initialized to the 864 * expected type of the property (or a type to which the expected type can be 865 * transformed) using g_value_init(). 866 * 867 * In general, a copy is made of the property contents and the caller is 868 * responsible for freeing the memory by calling g_value_unset(). 869 * 870 * Note that g_object_get_property() is really intended for language 871 * bindings, g_object_get() is much more convenient for C programming. 872 * 873 * Params: 874 * propertyName = the name of the property to get 875 * value = return location for the property value 876 */ 877 public void getProperty(string propertyName, Value value) 878 { 879 g_object_get_property(gObject, Str.toStringz(propertyName), (value is null) ? null : value.getValueStruct()); 880 } 881 882 /** 883 * This function gets back user data pointers stored via 884 * g_object_set_qdata(). 885 * 886 * Params: 887 * quark = A #GQuark, naming the user data pointer 888 * 889 * Returns: The user data pointer set, or %NULL 890 */ 891 public void* getQdata(GQuark quark) 892 { 893 return g_object_get_qdata(gObject, quark); 894 } 895 896 /** 897 * Gets properties of an object. 898 * 899 * In general, a copy is made of the property contents and the caller 900 * is responsible for freeing the memory in the appropriate manner for 901 * the type, for instance by calling g_free() or g_object_unref(). 902 * 903 * See g_object_get(). 904 * 905 * Params: 906 * firstPropertyName = name of the first property to get 907 * varArgs = return location for the first property, followed optionally by more 908 * name/return location pairs, followed by %NULL 909 */ 910 public void getValist(string firstPropertyName, void* varArgs) 911 { 912 g_object_get_valist(gObject, Str.toStringz(firstPropertyName), varArgs); 913 } 914 915 /** 916 * Gets @n_properties properties for an @object. 917 * Obtained properties will be set to @values. All properties must be valid. 918 * Warnings will be emitted and undefined behaviour may result if invalid 919 * properties are passed in. 920 * 921 * Params: 922 * names = the names of each property to get 923 * values = the values of each property to get 924 * 925 * Since: 2.54 926 */ 927 public void getv(string[] names, Value[] values) 928 { 929 GValue[] valuesArray = new GValue[values.length]; 930 for ( int i = 0; i < values.length; i++ ) 931 { 932 valuesArray[i] = *(values[i].getValueStruct()); 933 } 934 935 g_object_getv(gObject, cast(uint)values.length, Str.toStringzArray(names), valuesArray.ptr); 936 } 937 938 /** 939 * Checks whether @object has a [floating][floating-ref] reference. 940 * 941 * Returns: %TRUE if @object has a floating reference 942 * 943 * Since: 2.10 944 */ 945 public bool isFloating() 946 { 947 return g_object_is_floating(gObject) != 0; 948 } 949 950 /** 951 * Emits a "notify" signal for the property @property_name on @object. 952 * 953 * When possible, eg. when signaling a property change from within the class 954 * that registered the property, you should use g_object_notify_by_pspec() 955 * instead. 956 * 957 * Note that emission of the notify signal may be blocked with 958 * g_object_freeze_notify(). In this case, the signal emissions are queued 959 * and will be emitted (in reverse order) when g_object_thaw_notify() is 960 * called. 961 * 962 * Params: 963 * propertyName = the name of a property installed on the class of @object. 964 */ 965 public void notify(string propertyName) 966 { 967 g_object_notify(gObject, Str.toStringz(propertyName)); 968 } 969 970 /** 971 * Emits a "notify" signal for the property specified by @pspec on @object. 972 * 973 * This function omits the property name lookup, hence it is faster than 974 * g_object_notify(). 975 * 976 * One way to avoid using g_object_notify() from within the 977 * class that registered the properties, and using g_object_notify_by_pspec() 978 * instead, is to store the GParamSpec used with 979 * g_object_class_install_property() inside a static array, e.g.: 980 * 981 * |[<!-- language="C" --> 982 * enum 983 * { 984 * PROP_0, 985 * PROP_FOO, 986 * PROP_LAST 987 * }; 988 * 989 * static GParamSpec *properties[PROP_LAST]; 990 * 991 * static void 992 * my_object_class_init (MyObjectClass *klass) 993 * { 994 * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", 995 * 0, 100, 996 * 50, 997 * G_PARAM_READWRITE); 998 * g_object_class_install_property (gobject_class, 999 * PROP_FOO, 1000 * properties[PROP_FOO]); 1001 * } 1002 * ]| 1003 * 1004 * and then notify a change on the "foo" property with: 1005 * 1006 * |[<!-- language="C" --> 1007 * g_object_notify_by_pspec (self, properties[PROP_FOO]); 1008 * ]| 1009 * 1010 * Params: 1011 * pspec = the #GParamSpec of a property installed on the class of @object. 1012 * 1013 * Since: 2.26 1014 */ 1015 public void notifyByPspec(ParamSpec pspec) 1016 { 1017 g_object_notify_by_pspec(gObject, (pspec is null) ? null : pspec.getParamSpecStruct()); 1018 } 1019 1020 /** 1021 * Increases the reference count of @object. 1022 * 1023 * Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type 1024 * of @object will be propagated to the return type (using the GCC typeof() 1025 * extension), so any casting the caller needs to do on the return type must be 1026 * explicit. 1027 * 1028 * Returns: the same @object 1029 */ 1030 public ObjectG doref() 1031 { 1032 auto p = g_object_ref(gObject); 1033 1034 if(p is null) 1035 { 1036 return null; 1037 } 1038 1039 return ObjectG.getDObject!(ObjectG)(cast(GObject*) p); 1040 } 1041 1042 /** 1043 * Increase the reference count of @object, and possibly remove the 1044 * [floating][floating-ref] reference, if @object has a floating reference. 1045 * 1046 * In other words, if the object is floating, then this call "assumes 1047 * ownership" of the floating reference, converting it to a normal 1048 * reference by clearing the floating flag while leaving the reference 1049 * count unchanged. If the object is not floating, then this call 1050 * adds a new normal reference increasing the reference count by one. 1051 * 1052 * Since GLib 2.56, the type of @object will be propagated to the return type 1053 * under the same conditions as for g_object_ref(). 1054 * 1055 * Returns: @object 1056 * 1057 * Since: 2.10 1058 */ 1059 public ObjectG refSink() 1060 { 1061 auto p = g_object_ref_sink(gObject); 1062 1063 if(p is null) 1064 { 1065 return null; 1066 } 1067 1068 return ObjectG.getDObject!(ObjectG)(cast(GObject*) p); 1069 } 1070 1071 /** 1072 * Removes a reference added with g_object_add_toggle_ref(). The 1073 * reference count of the object is decreased by one. 1074 * 1075 * Params: 1076 * notify = a function to call when this reference is the 1077 * last reference to the object, or is no longer 1078 * the last reference. 1079 * data = data to pass to @notify 1080 * 1081 * Since: 2.8 1082 */ 1083 public void removeToggleRef(GToggleNotify notify, void* data) 1084 { 1085 g_object_remove_toggle_ref(gObject, notify, data); 1086 } 1087 1088 /** 1089 * Removes a weak reference from @object that was previously added 1090 * using g_object_add_weak_pointer(). The @weak_pointer_location has 1091 * to match the one used with g_object_add_weak_pointer(). 1092 * 1093 * Params: 1094 * weakPointerLocation = The memory address 1095 * of a pointer. 1096 */ 1097 public void removeWeakPointer(ref void* weakPointerLocation) 1098 { 1099 g_object_remove_weak_pointer(gObject, &weakPointerLocation); 1100 } 1101 1102 /** 1103 * Compares the user data for the key @key on @object with 1104 * @oldval, and if they are the same, replaces @oldval with 1105 * @newval. 1106 * 1107 * This is like a typical atomic compare-and-exchange 1108 * operation, for user data on an object. 1109 * 1110 * If the previous value was replaced then ownership of the 1111 * old value (@oldval) is passed to the caller, including 1112 * the registered destroy notify for it (passed out in @old_destroy). 1113 * It’s up to the caller to free this as needed, which may 1114 * or may not include using @old_destroy as sometimes replacement 1115 * should not destroy the object in the normal way. 1116 * 1117 * Params: 1118 * key = a string, naming the user data pointer 1119 * oldval = the old value to compare against 1120 * newval = the new value 1121 * destroy = a destroy notify for the new value 1122 * oldDestroy = destroy notify for the existing value 1123 * 1124 * Returns: %TRUE if the existing value for @key was replaced 1125 * by @newval, %FALSE otherwise. 1126 * 1127 * Since: 2.34 1128 */ 1129 public bool replaceData(string key, void* oldval, void* newval, GDestroyNotify destroy, out GDestroyNotify oldDestroy) 1130 { 1131 return g_object_replace_data(gObject, Str.toStringz(key), oldval, newval, destroy, &oldDestroy) != 0; 1132 } 1133 1134 /** 1135 * Compares the user data for the key @quark on @object with 1136 * @oldval, and if they are the same, replaces @oldval with 1137 * @newval. 1138 * 1139 * This is like a typical atomic compare-and-exchange 1140 * operation, for user data on an object. 1141 * 1142 * If the previous value was replaced then ownership of the 1143 * old value (@oldval) is passed to the caller, including 1144 * the registered destroy notify for it (passed out in @old_destroy). 1145 * It’s up to the caller to free this as needed, which may 1146 * or may not include using @old_destroy as sometimes replacement 1147 * should not destroy the object in the normal way. 1148 * 1149 * Params: 1150 * quark = a #GQuark, naming the user data pointer 1151 * oldval = the old value to compare against 1152 * newval = the new value 1153 * destroy = a destroy notify for the new value 1154 * oldDestroy = destroy notify for the existing value 1155 * 1156 * Returns: %TRUE if the existing value for @quark was replaced 1157 * by @newval, %FALSE otherwise. 1158 * 1159 * Since: 2.34 1160 */ 1161 public bool replaceQdata(GQuark quark, void* oldval, void* newval, GDestroyNotify destroy, out GDestroyNotify oldDestroy) 1162 { 1163 return g_object_replace_qdata(gObject, quark, oldval, newval, destroy, &oldDestroy) != 0; 1164 } 1165 1166 /** 1167 * Releases all references to other objects. This can be used to break 1168 * reference cycles. 1169 * 1170 * This function should only be called from object system implementations. 1171 */ 1172 public void runDispose() 1173 { 1174 g_object_run_dispose(gObject); 1175 } 1176 1177 /** 1178 * Each object carries around a table of associations from 1179 * strings to pointers. This function lets you set an association. 1180 * 1181 * If the object already had an association with that name, 1182 * the old association will be destroyed. 1183 * 1184 * Params: 1185 * key = name of the key 1186 * data = data to associate with that key 1187 */ 1188 public void setData(string key, void* data) 1189 { 1190 g_object_set_data(gObject, Str.toStringz(key), data); 1191 } 1192 1193 /** 1194 * Like g_object_set_data() except it adds notification 1195 * for when the association is destroyed, either by setting it 1196 * to a different value or when the object is destroyed. 1197 * 1198 * Note that the @destroy callback is not called if @data is %NULL. 1199 * 1200 * Params: 1201 * key = name of the key 1202 * data = data to associate with that key 1203 * destroy = function to call when the association is destroyed 1204 */ 1205 public void setDataFull(string key, void* data, GDestroyNotify destroy) 1206 { 1207 g_object_set_data_full(gObject, Str.toStringz(key), data, destroy); 1208 } 1209 1210 /** 1211 * Sets a property on an object. 1212 * 1213 * Params: 1214 * propertyName = the name of the property to set 1215 * value = the value 1216 */ 1217 public void setProperty(string propertyName, Value value) 1218 { 1219 g_object_set_property(gObject, Str.toStringz(propertyName), (value is null) ? null : value.getValueStruct()); 1220 } 1221 1222 /** 1223 * This sets an opaque, named pointer on an object. 1224 * The name is specified through a #GQuark (retrived e.g. via 1225 * g_quark_from_static_string()), and the pointer 1226 * can be gotten back from the @object with g_object_get_qdata() 1227 * until the @object is finalized. 1228 * Setting a previously set user data pointer, overrides (frees) 1229 * the old pointer set, using #NULL as pointer essentially 1230 * removes the data stored. 1231 * 1232 * Params: 1233 * quark = A #GQuark, naming the user data pointer 1234 * data = An opaque user data pointer 1235 */ 1236 public void setQdata(GQuark quark, void* data) 1237 { 1238 g_object_set_qdata(gObject, quark, data); 1239 } 1240 1241 /** 1242 * This function works like g_object_set_qdata(), but in addition, 1243 * a void (*destroy) (gpointer) function may be specified which is 1244 * called with @data as argument when the @object is finalized, or 1245 * the data is being overwritten by a call to g_object_set_qdata() 1246 * with the same @quark. 1247 * 1248 * Params: 1249 * quark = A #GQuark, naming the user data pointer 1250 * data = An opaque user data pointer 1251 * destroy = Function to invoke with @data as argument, when @data 1252 * needs to be freed 1253 */ 1254 public void setQdataFull(GQuark quark, void* data, GDestroyNotify destroy) 1255 { 1256 g_object_set_qdata_full(gObject, quark, data, destroy); 1257 } 1258 1259 /** 1260 * Sets properties on an object. 1261 * 1262 * Params: 1263 * firstPropertyName = name of the first property to set 1264 * varArgs = value for the first property, followed optionally by more 1265 * name/value pairs, followed by %NULL 1266 */ 1267 public void setValist(string firstPropertyName, void* varArgs) 1268 { 1269 g_object_set_valist(gObject, Str.toStringz(firstPropertyName), varArgs); 1270 } 1271 1272 /** 1273 * Sets @n_properties properties for an @object. 1274 * Properties to be set will be taken from @values. All properties must be 1275 * valid. Warnings will be emitted and undefined behaviour may result if invalid 1276 * properties are passed in. 1277 * 1278 * Params: 1279 * names = the names of each property to be set 1280 * values = the values of each property to be set 1281 * 1282 * Since: 2.54 1283 */ 1284 public void setv(string[] names, Value[] values) 1285 { 1286 GValue[] valuesArray = new GValue[values.length]; 1287 for ( int i = 0; i < values.length; i++ ) 1288 { 1289 valuesArray[i] = *(values[i].getValueStruct()); 1290 } 1291 1292 g_object_setv(gObject, cast(uint)values.length, Str.toStringzArray(names), valuesArray.ptr); 1293 } 1294 1295 /** 1296 * Remove a specified datum from the object's data associations, 1297 * without invoking the association's destroy handler. 1298 * 1299 * Params: 1300 * key = name of the key 1301 * 1302 * Returns: the data if found, or %NULL 1303 * if no such data exists. 1304 */ 1305 public void* stealData(string key) 1306 { 1307 return g_object_steal_data(gObject, Str.toStringz(key)); 1308 } 1309 1310 /** 1311 * This function gets back user data pointers stored via 1312 * g_object_set_qdata() and removes the @data from object 1313 * without invoking its destroy() function (if any was 1314 * set). 1315 * Usually, calling this function is only required to update 1316 * user data pointers with a destroy notifier, for example: 1317 * |[<!-- language="C" --> 1318 * void 1319 * object_add_to_user_list (GObject *object, 1320 * const gchar *new_string) 1321 * { 1322 * // the quark, naming the object data 1323 * GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); 1324 * // retrive the old string list 1325 * GList *list = g_object_steal_qdata (object, quark_string_list); 1326 * 1327 * // prepend new string 1328 * list = g_list_prepend (list, g_strdup (new_string)); 1329 * // this changed 'list', so we need to set it again 1330 * g_object_set_qdata_full (object, quark_string_list, list, free_string_list); 1331 * } 1332 * static void 1333 * free_string_list (gpointer data) 1334 * { 1335 * GList *node, *list = data; 1336 * 1337 * for (node = list; node; node = node->next) 1338 * g_free (node->data); 1339 * g_list_free (list); 1340 * } 1341 * ]| 1342 * Using g_object_get_qdata() in the above example, instead of 1343 * g_object_steal_qdata() would have left the destroy function set, 1344 * and thus the partial string list would have been freed upon 1345 * g_object_set_qdata_full(). 1346 * 1347 * Params: 1348 * quark = A #GQuark, naming the user data pointer 1349 * 1350 * Returns: The user data pointer set, or %NULL 1351 */ 1352 public void* stealQdata(GQuark quark) 1353 { 1354 return g_object_steal_qdata(gObject, quark); 1355 } 1356 1357 /** 1358 * Reverts the effect of a previous call to 1359 * g_object_freeze_notify(). The freeze count is decreased on @object 1360 * and when it reaches zero, queued "notify" signals are emitted. 1361 * 1362 * Duplicate notifications for each property are squashed so that at most one 1363 * #GObject::notify signal is emitted for each property, in the reverse order 1364 * in which they have been queued. 1365 * 1366 * It is an error to call this function when the freeze count is zero. 1367 */ 1368 public void thawNotify() 1369 { 1370 g_object_thaw_notify(gObject); 1371 } 1372 1373 /** 1374 * Decreases the reference count of @object. When its reference count 1375 * drops to 0, the object is finalized (i.e. its memory is freed). 1376 * 1377 * If the pointer to the #GObject may be reused in future (for example, if it is 1378 * an instance variable of another object), it is recommended to clear the 1379 * pointer to %NULL rather than retain a dangling pointer to a potentially 1380 * invalid #GObject instance. Use g_clear_object() for this. 1381 */ 1382 public void unref() 1383 { 1384 g_object_unref(gObject); 1385 } 1386 1387 /** 1388 * This function essentially limits the life time of the @closure to 1389 * the life time of the object. That is, when the object is finalized, 1390 * the @closure is invalidated by calling g_closure_invalidate() on 1391 * it, in order to prevent invocations of the closure with a finalized 1392 * (nonexisting) object. Also, g_object_ref() and g_object_unref() are 1393 * added as marshal guards to the @closure, to ensure that an extra 1394 * reference count is held on @object during invocation of the 1395 * @closure. Usually, this function will be called on closures that 1396 * use this @object as closure data. 1397 * 1398 * Params: 1399 * closure = GClosure to watch 1400 */ 1401 public void watchClosure(Closure closure) 1402 { 1403 g_object_watch_closure(gObject, (closure is null) ? null : closure.getClosureStruct()); 1404 } 1405 1406 /** 1407 * Adds a weak reference callback to an object. Weak references are 1408 * used for notification when an object is finalized. They are called 1409 * "weak references" because they allow you to safely hold a pointer 1410 * to an object without calling g_object_ref() (g_object_ref() adds a 1411 * strong reference, that is, forces the object to stay alive). 1412 * 1413 * Note that the weak references created by this method are not 1414 * thread-safe: they cannot safely be used in one thread if the 1415 * object's last g_object_unref() might happen in another thread. 1416 * Use #GWeakRef if thread-safety is required. 1417 * 1418 * Params: 1419 * notify = callback to invoke before the object is freed 1420 * data = extra data to pass to notify 1421 */ 1422 public void weakRef(GWeakNotify notify, void* data) 1423 { 1424 g_object_weak_ref(gObject, notify, data); 1425 } 1426 1427 /** 1428 * Removes a weak reference callback to an object. 1429 * 1430 * Params: 1431 * notify = callback to search for 1432 * data = data to search for 1433 */ 1434 public void weakUnref(GWeakNotify notify, void* data) 1435 { 1436 g_object_weak_unref(gObject, notify, data); 1437 } 1438 1439 /** 1440 * Clears a reference to a #GObject. 1441 * 1442 * @object_ptr must not be %NULL. 1443 * 1444 * If the reference is %NULL then this function does nothing. 1445 * Otherwise, the reference count of the object is decreased and the 1446 * pointer is set to %NULL. 1447 * 1448 * A macro is also included that allows this function to be used without 1449 * pointer casts. 1450 * 1451 * Params: 1452 * objectPtr = a pointer to a #GObject reference 1453 * 1454 * Since: 2.28 1455 */ 1456 public static void clearObject(ref ObjectG objectPtr) 1457 { 1458 GObject* outobjectPtr = objectPtr.getObjectGStruct(); 1459 1460 g_clear_object(&outobjectPtr); 1461 1462 objectPtr = ObjectG.getDObject!(ObjectG)(outobjectPtr); 1463 } 1464 }