1/* GObject - GLib Type, Object, Parameter and Signal Library 2 * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc. 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General 15 * Public License along with this library; if not, write to the 16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 17 * Boston, MA 02111-1307, USA. 18 */ 19#if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) 20#error "Only <glib-object.h> can be included directly." 21#endif 22 23#ifndef __G_OBJECT_H__ 24#define __G_OBJECT_H__ 25 26#include <gobject/gtype.h> 27#include <gobject/gvalue.h> 28#include <gobject/gparam.h> 29#include <gobject/gclosure.h> 30#include <gobject/gsignal.h> 31 32G_BEGIN_DECLS 33 34/* --- type macros --- */ 35/** 36 * G_TYPE_IS_OBJECT: 37 * @type: Type id to check 38 * 39 * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. 40 * 41 * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. 42 */ 43#define G_TYPE_IS_OBJECT(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_OBJECT) 44/** 45 * G_OBJECT: 46 * @object: Object which is subject to casting. 47 * 48 * Casts a #GObject or derived pointer into a (GObject*) pointer. 49 * Depending on the current debugging level, this function may invoke 50 * certain runtime checks to identify invalid casts. 51 */ 52#define G_OBJECT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject)) 53/** 54 * G_OBJECT_CLASS: 55 * @class: a valid #GObjectClass 56 * 57 * Casts a derived #GObjectClass structure into a #GObjectClass structure. 58 */ 59#define G_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass)) 60/** 61 * G_IS_OBJECT: 62 * @object: Instance to check for being a %G_TYPE_OBJECT. 63 * 64 * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. 65 */ 66#define G_IS_OBJECT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_OBJECT)) 67/** 68 * G_IS_OBJECT_CLASS: 69 * @class: a #GObjectClass 70 * 71 * Checks whether @class "is a" valid #GObjectClass structure of type 72 * %G_TYPE_OBJECT or derived. 73 */ 74#define G_IS_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_OBJECT)) 75/** 76 * G_OBJECT_GET_CLASS: 77 * @object: a #GObject instance. 78 * 79 * Get the class structure associated to a #GObject instance. 80 * 81 * Returns: pointer to object class structure. 82 */ 83#define G_OBJECT_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_OBJECT, GObjectClass)) 84/** 85 * G_OBJECT_TYPE: 86 * @object: Object to return the type id for. 87 * 88 * Get the type id of an object. 89 * 90 * Returns: Type id of @object. 91 */ 92#define G_OBJECT_TYPE(object) (G_TYPE_FROM_INSTANCE (object)) 93/** 94 * G_OBJECT_TYPE_NAME: 95 * @object: Object to return the type name for. 96 * 97 * Get the name of an object's type. 98 * 99 * Returns: Type name of @object. The string is owned by the type system and 100 * should not be freed. 101 */ 102#define G_OBJECT_TYPE_NAME(object) (g_type_name (G_OBJECT_TYPE (object))) 103/** 104 * G_OBJECT_CLASS_TYPE: 105 * @class: a valid #GObjectClass 106 * 107 * Get the type id of a class structure. 108 * 109 * Returns: Type id of @class. 110 */ 111#define G_OBJECT_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class)) 112/** 113 * G_OBJECT_CLASS_NAME: 114 * @class: a valid #GObjectClass 115 * 116 * Return the name of a class structure's type. 117 * 118 * Returns: Type name of @class. The string is owned by the type system and 119 * should not be freed. 120 */ 121#define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class))) 122/** 123 * G_VALUE_HOLDS_OBJECT: 124 * @value: a valid #GValue structure 125 * 126 * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. 127 * 128 * Returns: %TRUE on success. 129 */ 130#define G_VALUE_HOLDS_OBJECT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_OBJECT)) 131 132/* --- type macros --- */ 133/** 134 * G_TYPE_INITIALLY_UNOWNED: 135 * 136 * The type for #GInitiallyUnowned. 137 */ 138#define G_TYPE_INITIALLY_UNOWNED (g_initially_unowned_get_type()) 139/** 140 * G_INITIALLY_UNOWNED: 141 * @object: Object which is subject to casting. 142 * 143 * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) 144 * pointer. Depending on the current debugging level, this function may invoke 145 * certain runtime checks to identify invalid casts. 146 */ 147#define G_INITIALLY_UNOWNED(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnowned)) 148/** 149 * G_INITIALLY_UNOWNED_CLASS: 150 * @class: a valid #GInitiallyUnownedClass 151 * 152 * Casts a derived #GInitiallyUnownedClass structure into a 153 * #GInitiallyUnownedClass structure. 154 */ 155#define G_INITIALLY_UNOWNED_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnownedClass)) 156/** 157 * G_IS_INITIALLY_UNOWNED: 158 * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. 159 * 160 * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. 161 */ 162#define G_IS_INITIALLY_UNOWNED(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_INITIALLY_UNOWNED)) 163/** 164 * G_IS_INITIALLY_UNOWNED_CLASS: 165 * @class: a #GInitiallyUnownedClass 166 * 167 * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type 168 * %G_TYPE_INITIALLY_UNOWNED or derived. 169 */ 170#define G_IS_INITIALLY_UNOWNED_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_INITIALLY_UNOWNED)) 171/** 172 * G_INITIALLY_UNOWNED_GET_CLASS: 173 * @object: a #GInitiallyUnowned instance. 174 * 175 * Get the class structure associated to a #GInitiallyUnowned instance. 176 * 177 * Returns: pointer to object class structure. 178 */ 179#define G_INITIALLY_UNOWNED_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnownedClass)) 180/* GInitiallyUnowned ia a GObject with initially floating reference count */ 181 182 183/* --- typedefs & structures --- */ 184typedef struct _GObject GObject; 185typedef struct _GObjectClass GObjectClass; 186typedef struct _GObject GInitiallyUnowned; 187typedef struct _GObjectClass GInitiallyUnownedClass; 188typedef struct _GObjectConstructParam GObjectConstructParam; 189/** 190 * GObjectGetPropertyFunc: 191 * @object: a #GObject 192 * @property_id: the numeric id under which the property was registered with 193 * g_object_class_install_property(). 194 * @value: a #GValue to return the property value in 195 * @pspec: the #GParamSpec describing the property 196 * 197 * The type of the @get_property function of #GObjectClass. 198 */ 199typedef void (*GObjectGetPropertyFunc) (GObject *object, 200 guint property_id, 201 GValue *value, 202 GParamSpec *pspec); 203/** 204 * GObjectSetPropertyFunc: 205 * @object: a #GObject 206 * @property_id: the numeric id under which the property was registered with 207 * g_object_class_install_property(). 208 * @value: the new value for the property 209 * @pspec: the #GParamSpec describing the property 210 * 211 * The type of the @set_property function of #GObjectClass. 212 */ 213typedef void (*GObjectSetPropertyFunc) (GObject *object, 214 guint property_id, 215 const GValue *value, 216 GParamSpec *pspec); 217/** 218 * GObjectFinalizeFunc: 219 * @object: the #GObject being finalized 220 * 221 * The type of the @finalize function of #GObjectClass. 222 */ 223typedef void (*GObjectFinalizeFunc) (GObject *object); 224/** 225 * GWeakNotify: 226 * @data: data that was provided when the weak reference was established 227 * @where_the_object_was: the object being finalized 228 * 229 * A #GWeakNotify function can be added to an object as a callback that gets 230 * triggered when the object is finalized. Since the object is already being 231 * finalized when the #GWeakNotify is called, there's not much you could do 232 * with the object, apart from e.g. using its adress as hash-index or the like. 233 */ 234typedef void (*GWeakNotify) (gpointer data, 235 GObject *where_the_object_was); 236/** 237 * GObject: 238 * 239 * All the fields in the <structname>GObject</structname> structure are private 240 * to the #GObject implementation and should never be accessed directly. 241 */ 242struct _GObject 243{ 244 GTypeInstance g_type_instance; 245 246 /*< private >*/ 247 volatile guint ref_count; 248 GData *qdata; 249}; 250/** 251 * GObjectClass: 252 * @g_type_class: the parent class 253 * @constructor: the @constructor function is called by g_object_new () to 254 * complete the object initialization after all the construction properties are 255 * set. The first thing a @constructor implementation must do is chain up to the 256 * @constructor of the parent class. Overriding @constructor should be rarely 257 * needed, e.g. to handle construct properties, or to implement singletons. 258 * @set_property: the generic setter for all properties of this type. Should be 259 * overridden for every type with properties. Implementations of @set_property 260 * don't need to emit property change notification explicitly, this is handled 261 * by the type system. 262 * @get_property: the generic getter for all properties of this type. Should be 263 * overridden for every type with properties. 264 * @dispose: the @dispose function is supposed to drop all references to other 265 * objects, but keep the instance otherwise intact, so that client method 266 * invocations still work. It may be run multiple times (due to reference 267 * loops). Before returning, @dispose should chain up to the @dispose method 268 * of the parent class. 269 * @finalize: instance finalization function, should finish the finalization of 270 * the instance begun in @dispose and chain up to the @finalize method of the 271 * parent class. 272 * @dispatch_properties_changed: emits property change notification for a bunch 273 * of properties. Overriding @dispatch_properties_changed should be rarely 274 * needed. 275 * @notify: the class closure for the notify signal 276 * @constructed: the @constructed function is called by g_object_new() as the 277 * final step of the object creation process. At the point of the call, all 278 * construction properties have been set on the object. The purpose of this 279 * call is to allow for object initialisation steps that can only be performed 280 * after construction properties have been set. @constructed implementors 281 * should chain up to the @constructed call of their parent class to allow it 282 * to complete its initialisation. 283 * 284 * The class structure for the <structname>GObject</structname> type. 285 * 286 * <example> 287 * <title>Implementing singletons using a constructor</title> 288 * <programlisting> 289 * static MySingleton *the_singleton = NULL; 290 * 291 * static GObject* 292 * my_singleton_constructor (GType type, 293 * guint n_construct_params, 294 * GObjectConstructParam *construct_params) 295 * { 296 * GObject *object; 297 * 298 * if (!the_singleton) 299 * { 300 * object = G_OBJECT_CLASS (parent_class)->constructor (type, 301 * n_construct_params, 302 * construct_params); 303 * the_singleton = MY_SINGLETON (object); 304 * } 305 * else 306 * object = g_object_ref (G_OBJECT (the_singleton)); 307 * 308 * return object; 309 * } 310 * </programlisting></example> 311 */ 312struct _GObjectClass 313{ 314 GTypeClass g_type_class; 315 316 /*< private >*/ 317 GSList *construct_properties; 318 319 /*< public >*/ 320 /* seldomly overidden */ 321 GObject* (*constructor) (GType type, 322 guint n_construct_properties, 323 GObjectConstructParam *construct_properties); 324 /* overridable methods */ 325 void (*set_property) (GObject *object, 326 guint property_id, 327 const GValue *value, 328 GParamSpec *pspec); 329 void (*get_property) (GObject *object, 330 guint property_id, 331 GValue *value, 332 GParamSpec *pspec); 333 void (*dispose) (GObject *object); 334 void (*finalize) (GObject *object); 335 /* seldomly overidden */ 336 void (*dispatch_properties_changed) (GObject *object, 337 guint n_pspecs, 338 GParamSpec **pspecs); 339 /* signals */ 340 void (*notify) (GObject *object, 341 GParamSpec *pspec); 342 343 /* called when done constructing */ 344 void (*constructed) (GObject *object); 345 346 /*< private >*/ 347 /* padding */ 348 gpointer pdummy[7]; 349}; 350/** 351 * GObjectConstructParam: 352 * @pspec: the #GParamSpec of the construct parameter 353 * @value: the value to set the parameter to 354 * 355 * The <structname>GObjectConstructParam</structname> struct is an auxiliary 356 * structure used to hand #GParamSpec/#GValue pairs to the @constructor of 357 * a #GObjectClass. 358 */ 359struct _GObjectConstructParam 360{ 361 GParamSpec *pspec; 362 GValue *value; 363}; 364 365/** 366 * GInitiallyUnowned: 367 * 368 * All the fields in the <structname>GInitiallyUnowned</structname> structure 369 * are private to the #GInitiallyUnowned implementation and should never be 370 * accessed directly. 371 */ 372/** 373 * GInitiallyUnownedClass: 374 * 375 * The class structure for the <structname>GInitiallyUnowned</structname> type. 376 */ 377 378 379/* --- prototypes --- */ 380GType g_initially_unowned_get_type (void); 381void g_object_class_install_property (GObjectClass *oclass, 382 guint property_id, 383 GParamSpec *pspec); 384GParamSpec* g_object_class_find_property (GObjectClass *oclass, 385 const gchar *property_name); 386GParamSpec**g_object_class_list_properties (GObjectClass *oclass, 387 guint *n_properties); 388void g_object_class_override_property (GObjectClass *oclass, 389 guint property_id, 390 const gchar *name); 391 392void g_object_interface_install_property (gpointer g_iface, 393 GParamSpec *pspec); 394GParamSpec* g_object_interface_find_property (gpointer g_iface, 395 const gchar *property_name); 396GParamSpec**g_object_interface_list_properties (gpointer g_iface, 397 guint *n_properties_p); 398 399GType g_object_get_type (void) G_GNUC_CONST; 400gpointer g_object_new (GType object_type, 401 const gchar *first_property_name, 402 ...); 403gpointer g_object_newv (GType object_type, 404 guint n_parameters, 405 GParameter *parameters); 406GObject* g_object_new_valist (GType object_type, 407 const gchar *first_property_name, 408 va_list var_args); 409void g_object_set (gpointer object, 410 const gchar *first_property_name, 411 ...) G_GNUC_NULL_TERMINATED; 412void g_object_get (gpointer object, 413 const gchar *first_property_name, 414 ...) G_GNUC_NULL_TERMINATED; 415gpointer g_object_connect (gpointer object, 416 const gchar *signal_spec, 417 ...) G_GNUC_NULL_TERMINATED; 418void g_object_disconnect (gpointer object, 419 const gchar *signal_spec, 420 ...) G_GNUC_NULL_TERMINATED; 421void g_object_set_valist (GObject *object, 422 const gchar *first_property_name, 423 va_list var_args); 424void g_object_get_valist (GObject *object, 425 const gchar *first_property_name, 426 va_list var_args); 427void g_object_set_property (GObject *object, 428 const gchar *property_name, 429 const GValue *value); 430void g_object_get_property (GObject *object, 431 const gchar *property_name, 432 GValue *value); 433void g_object_freeze_notify (GObject *object); 434void g_object_notify (GObject *object, 435 const gchar *property_name); 436void g_object_thaw_notify (GObject *object); 437gboolean g_object_is_floating (gpointer object); 438gpointer g_object_ref_sink (gpointer object); 439gpointer g_object_ref (gpointer object); 440void g_object_unref (gpointer object); 441void g_object_weak_ref (GObject *object, 442 GWeakNotify notify, 443 gpointer data); 444void g_object_weak_unref (GObject *object, 445 GWeakNotify notify, 446 gpointer data); 447void g_object_add_weak_pointer (GObject *object, 448 gpointer *weak_pointer_location); 449void g_object_remove_weak_pointer (GObject *object, 450 gpointer *weak_pointer_location); 451 452/** 453 * GToggleNotify: 454 * @data: Callback data passed to g_object_add_toggle_ref() 455 * @object: The object on which g_object_add_toggle_ref() was called. 456 * @is_last_ref: %TRUE if the toggle reference is now the 457 * last reference to the object. %FALSE if the toggle 458 * reference was the last reference and there are now other 459 * references. 460 * 461 * A callback function used for notification when the state 462 * of a toggle reference changes. See g_object_add_toggle_ref(). 463 */ 464typedef void (*GToggleNotify) (gpointer data, 465 GObject *object, 466 gboolean is_last_ref); 467 468void g_object_add_toggle_ref (GObject *object, 469 GToggleNotify notify, 470 gpointer data); 471void g_object_remove_toggle_ref (GObject *object, 472 GToggleNotify notify, 473 gpointer data); 474 475gpointer g_object_get_qdata (GObject *object, 476 GQuark quark); 477void g_object_set_qdata (GObject *object, 478 GQuark quark, 479 gpointer data); 480void g_object_set_qdata_full (GObject *object, 481 GQuark quark, 482 gpointer data, 483 GDestroyNotify destroy); 484gpointer g_object_steal_qdata (GObject *object, 485 GQuark quark); 486gpointer g_object_get_data (GObject *object, 487 const gchar *key); 488void g_object_set_data (GObject *object, 489 const gchar *key, 490 gpointer data); 491void g_object_set_data_full (GObject *object, 492 const gchar *key, 493 gpointer data, 494 GDestroyNotify destroy); 495gpointer g_object_steal_data (GObject *object, 496 const gchar *key); 497void g_object_watch_closure (GObject *object, 498 GClosure *closure); 499GClosure* g_cclosure_new_object (GCallback callback_func, 500 GObject *object); 501GClosure* g_cclosure_new_object_swap (GCallback callback_func, 502 GObject *object); 503GClosure* g_closure_new_object (guint sizeof_closure, 504 GObject *object); 505void g_value_set_object (GValue *value, 506 gpointer v_object); 507gpointer g_value_get_object (const GValue *value); 508gpointer g_value_dup_object (const GValue *value); 509gulong g_signal_connect_object (gpointer instance, 510 const gchar *detailed_signal, 511 GCallback c_handler, 512 gpointer gobject, 513 GConnectFlags connect_flags); 514 515/*< protected >*/ 516void g_object_force_floating (GObject *object); 517void g_object_run_dispose (GObject *object); 518 519 520void g_value_take_object (GValue *value, 521 gpointer v_object); 522#ifndef G_DISABLE_DEPRECATED 523void g_value_set_object_take_ownership (GValue *value, 524 gpointer v_object); 525#endif 526 527#if !defined(G_DISABLE_DEPRECATED) || defined(GTK_COMPILATION) 528gsize g_object_compat_control (gsize what, 529 gpointer data); 530#endif 531 532/* --- implementation macros --- */ 533#define G_OBJECT_WARN_INVALID_PSPEC(object, pname, property_id, pspec) \ 534G_STMT_START { \ 535 GObject *_object = (GObject*) (object); \ 536 GParamSpec *_pspec = (GParamSpec*) (pspec); \ 537 guint _property_id = (property_id); \ 538 g_warning ("%s: invalid %s id %u for \"%s\" of type `%s' in `%s'", \ 539 G_STRLOC, \ 540 (pname), \ 541 _property_id, \ 542 _pspec->name, \ 543 g_type_name (G_PARAM_SPEC_TYPE (_pspec)), \ 544 G_OBJECT_TYPE_NAME (_object)); \ 545} G_STMT_END 546/** 547 * G_OBJECT_WARN_INVALID_PROPERTY_ID: 548 * @object: the #GObject on which set_property() or get_property() was called 549 * @property_id: the numeric id of the property 550 * @pspec: the #GParamSpec of the property 551 * 552 * This macro should be used to emit a standard warning about unexpected 553 * properties in set_property() and get_property() implementations. 554 */ 555#define G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec) \ 556 G_OBJECT_WARN_INVALID_PSPEC ((object), "property", (property_id), (pspec)) 557 558G_END_DECLS 559 560#endif /* __G_OBJECT_H__ */ 561