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