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