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