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