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