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