Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkobject.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkObject
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 The base class of the Gtk type hierarchy.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <refsect2>
   9 <title>Description</title>
  10 <para>
  11 GtkObject is the root of the gtk+ type hierarchy.  It serves
  12 a similar roles as java's Object class.  It is used
  13 by the type-casting system to represent the base composite type.
  14 </para>
  15 <para>
  16 Objects have <wordasword>arguments</wordasword> that are
  17 name/typed-value pairs.
  18 They may be readable or writable (or both or neither).
  19 The special handlers in every object are responsible for
  20 setting and getting these parameters.
  21 If the handler for a given argument <emphasis>must</emphasis>
  22 be called before the object may be used, be sure the
  23 #GTK_ARG_CONSTRUCT or #GTK_ARG_CONSTRUCT_ONLY flags
  24 are set;  otherwise they are set only when the user does so.
  25 </para>
  26 <para>
  27 Object also store a simpler association table, sometimes
  28 called the object_data.  This is just an efficient mapping from
  29 a fixed set of strings to a gpointer.  This can be used as
  30 arbitrary extra members.  Notice that each new field name
  31 allocates a new quark, so it is probably best only to use
  32 this for fields with fixed names.
  33 </para>
  34 <para>
  35 The primary difference between object_data and arguments is that
  36 the object defines two functions which set and get each type of argument.
  37 The object just has a table to store its object data in:  it does not
  38 receive notice when data changes.
  39 </para>
  40 <para>
  41 Objects are reference counted;  this means that we maintain
  42 a count of how many references (usually in the form of a pointer)
  43 are being held to this object.
  44 To indicate that you reference an object, call gtk_object_ref().
  45 The object will not be freed until everyone calls
  46 gtk_object_unref().
  47 </para>
  48 <para>
  49 In order to reduce the chances of a memory leak, gtk+ defines
  50 "floating objects".  All objects created with gtk_object_new()
  51 start out floating with a reference count of 1.
  52 In order to reduce that initial reference count you should gtk_object_sink()
  53 them, but usually the parent widget you add the child to will
  54 sink the object.
  55 </para>
  56 <para>So, because gtk_widget_set_parent() sinks the object from
  57 gtk_container_add(), there are no memory leaks in this code:
  58 <informalexample>
  59 <programlisting>
  60         button = gtk_button_new_with_label("Hi Mom!");
  61         gtk_container_add(GTK_CONTAINER(window), button);
  62         /* Button may not be used anymore since we don't retain a reference
  63          * to it. */
  64 </programlisting>
  65 </informalexample>
  66 Likewise, the following code attaches the same adjustment to two
  67 ranges:
  68 <informalexample>
  69 <programlisting>
  70         adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
  71         gtk_range_set_adjustment(range1, adjustment);
  72         gtk_range_set_adjustment(range2, adjustment);
  73 </programlisting>
  74 </informalexample>
  75 Note that we could put as many set_adjustments as we like:  cleanup is easy
  76 because they all retain a reference but only one sinks the initial reference
  77 count.  If it is possible for "range1" to stop retaining its reference
  78 then we need to enclose the lines using "adjustment" with ref/unref
  79 to guarantee the the object won't be deleted:
  80 <informalexample>
  81 <programlisting>
  82         adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
  83         gtk_object_ref(GTK_OBJECT(adjustment));
  84         gtk_range_set_adjustment(range1, adjustment);
  85         gtk_range_set_adjustment(range1, another_adjustment);
  86         /* With the initial reference, `adjustment' would have
  87          * been deleted as `range1' lost its reference to it. */
  88         gtk_range_set_adjustment(range2, adjustment);
  89         gtk_object_unref(GTK_OBJECT(adjustment));
  90 </programlisting>
  91 </informalexample>
  92 </para>
  93 <para>
  94 Be careful with reference counting:  if two objects reference eachother
  95 then they will always have at least reference count 1, even if
  96 there are no other pointers to them.  This means that they
  97 will never be freed.  More precisely, you must be certain that
  98 your references <emphasis>never</emphasis> can form cycles.
  99 </para>
 100 <para>
 101 If you find yourself forming cyclic references, perhaps you
 102 can convert some of them to <wordasword>weak-references</wordasword>.
 103 A weak-reference is one that holds a pointer to an object,
 104 but doesn't increase the reference count.  To insure
 105 the object is valid when the referer tries to use it,
 106 the referer registers a callback that will be invoked
 107 after the object has been destroyed (but before its memory is actually
 108 deallocated).  This callback must prevent the weak-reference from
 109 being used again.
 110 </para>
 111 </refsect2>
 112 <refsect2>
 113 <title>Brief Glossary</title>
 114 <variablelist>
 115
 116 <varlistentry>
 117 <term>argument</term>
 118 <listitem><para>
 119 A typed-variable identified by ObjectType::argument_name.  It may be
 120 readable, writable, both or none.  For example,
 121 "GtkButton::label" is a read/write string-valued argument.
 122 </para></listitem>
 123 </varlistentry>
 124
 125 <varlistentry>
 126 <term>constructed</term>
 127 <listitem><para>
 128 </para></listitem>
 129 </varlistentry>
 130
 131 <varlistentry>
 132 <term>destroyed</term>
 133 <listitem><para>
 134 </para></listitem>
 135 </varlistentry>
 136
 137 <varlistentry>
 138 <term>finalization</term>
 139 <listitem><para>
 140 </para></listitem>
 141 </varlistentry>
 142
 143 <varlistentry>
 144 <term>floating</term>
 145 <listitem><para>
 146 </para></listitem>
 147 </varlistentry>
 148
 149 <varlistentry>
 150 <term>object data</term>
 151 <listitem><para>
 152 </para></listitem>
 153 </varlistentry>
 154
 155 <varlistentry>
 156 <term>reference count</term>
 157 <listitem><para>
 158 </para></listitem>
 159 </varlistentry>
 160
 161 <varlistentry>
 162 <term>weak-reference</term>
 163 <listitem><para>
 164 </para></listitem>
 165 </varlistentry>
 166
 167 </variablelist>
 168 </refsect2>
 169
 170 <!-- ##### SECTION See_Also ##### -->
 171 <para>
 172 GtkType, GtkArg, gtk-signals.
 173 </para>
 174
 175 <!-- ##### STRUCT GtkObject ##### -->
 176 <para>
 177 The object itself.  You should never use these members directly-
 178 instead you the accessing macros.
 179 </para>
 180
 181
 182 <!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
 183 <para>
 184 Get the type of an object.
 185 </para>
 186
 187 @object:
 188 <!-- # Unused Parameters # -->
 189 @obj: the object whose type we wish to get.
 190
 191
 192 <!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### -->
 193 <para>
 194
 195 </para>
 196
 197 @object:
 198
 199
 200 <!-- ##### ENUM GtkObjectFlags ##### -->
 201 <para>
 202 Tells about the state of the object.
 203 </para>
 204
 205 @GTK_DESTROYED: the GtkObject has had gtk_object_destroyed() invoked on it
 206 and is processing the shutdown callback.
 207 @GTK_FLOATING: whether the object is orphaned.  Objects that take
 208 strong hold of an object may gtk_object_sink() it, after obtaining
 209 there own references, if they believe they are nearly primary
 210 ownership of the object.
 211 GTK_CONNECTED: refers to whether are signals are connected to this
 212 object.
 213 @GTK_RESERVED_1:
 214 @GTK_RESERVED_2:
 215
 216 <!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
 217 <para>
 218 Get the #GtkObjectFlags for an object without directly
 219 accessing its members.
 220 </para>
 221
 222 @obj: the object whose flags are returned.
 223
 224
 225 <!-- ##### MACRO GTK_OBJECT_DESTROYED ##### -->
 226 <para>
 227 Test whether a GtkObject has had gtk_object_destroyed() invoked on it.
 228 </para>
 229
 230 @obj: the object to examine.
 231
 232
 233 <!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
 234 <para>
 235 When an object is created, it has an initial reference count
 236 of 1 and is floating.  <wordasword>Sinking</wordasword> the object
 237 refers to decrementing that original reference count.
 238 </para>
 239
 240 @obj: the object to examine.
 241
 242
 243 <!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->
 244 <para>
 245 Test whether a GtkObject has had a signal connected to it.
 246 </para>
 247
 248 @obj: the object to examine.
 249
 250
 251 <!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->
 252 <para>
 253 Turn on certain object flags.  (Private)
 254 </para>
 255
 256 @obj: the object to affect.
 257 @flag: the flags to set.
 258
 259
 260 <!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->
 261 <para>
 262 Turn off certain object flags.  (Private)
 263 </para>
 264
 265 @obj: the object to affect.
 266 @flag: the flags to unset.
 267
 268
 269 <!-- ##### ENUM GtkArgFlags ##### -->
 270 <para>
 271 Possible flags indicating how an argument should be treated.
 272 </para>
 273
 274 @GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)
 275 @GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)
 276 @GTK_ARG_CONSTRUCT: the argument needs construction.
 277 @GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will
 278 be set once during object creation), but is otherwise cannot be
 279 set.  Hence this flag is not allowed with #GTK_ARG_WRITABLE,
 280 and is redundant with #GTK_ARG_CONSTRUCT.
 281 @GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)
 282 each child.  Used by #GtkContainer.
 283
 284 <!-- ##### FUNCTION gtk_object_new ##### -->
 285 <para>
 286 Construct an object given its arguments, enumerated in the call to the
 287 function.
 288 </para>
 289
 290 @type: the type identifying this object.  Returned by gtk_type_unique()
 291 although (for a properly-written object it should be accessible through
 292 #GTK_TYPE_FOO.)
 293 @first_property_name:
 294 @Varargs: the first argument's value, followed by any number of
 295 name/argument-value pairs, terminated with NULL.
 296 @Returns: the new GtkObject.
 297 <!-- # Unused Parameters # -->
 298 @first_arg_name: name of the first argument to set when constructing
 299 the object.
 300
 301
 302 <!-- ##### FUNCTION gtk_object_sink ##### -->
 303 <para>
 304 Decrement the initial count given to the object.
 305 Additional invocations have no effect.
 306 </para>
 307 <para>
 308 This is designed to free the user from worrying about
 309 dereferencing an object that they have just created.
 310 So long as the object is sunk at some point, the reference count
 311 will be set properly.
 312 </para>
 313 <para>
 314 furthermore it may be sunk multiple times.
 315 Only the first time will actually dereference.
 316 </para>
 317 <para>
 318 The basic outline is: when you create an object it is floating.
 319 Setting its parent causes it to be sunk, however its parent
 320 has obtained a reference, so its reference count is one.
 321 </para>
 322
 323 @object: the object to sink.
 324
 325
 326 <!-- ##### FUNCTION gtk_object_ref ##### -->
 327 <para>
 328 Increase the reference count of the object.
 329 </para>
 330
 331 @object: the object to reference.
 332 @Returns:
 333
 334
 335 <!-- ##### FUNCTION gtk_object_unref ##### -->
 336 <para>
 337 Decrease the reference count of an object.  When its reference
 338 count drops to 0, the object is deleted.
 339 </para>
 340 <para>
 341 If it was not already destroyed, it will be, with gtk_object_destroy(),
 342 then weak links are notified, then the object-data is freed
 343 and the memory for the object itself is freed using gtk_type_free().
 344 </para>
 345
 346 @object: the object to dereference.
 347
 348
 349 <!-- ##### FUNCTION gtk_object_weakref ##### -->
 350 <para>
 351 Adds a weak reference callback to an object.
 352 </para>
 353 <para>
 354 Weak references are a mechanism to safely keep a pointer to
 355 an object without using the reference counting
 356 mechansim.  They use a callback function to receive
 357 notice that the object is about to be freed (aka finalized).
 358 This happens <emphasis>after</emphasis> the destroy
 359 callback has been run.
 360 </para>
 361
 362 @object: object to weakly reference.
 363 @notify: callback to invoke before the object is freed.
 364 @data: extra data to pass to #notify.
 365
 366
 367 <!-- ##### FUNCTION gtk_object_weakunref ##### -->
 368 <para>
 369 Removes a weak reference callback to an object.
 370 </para>
 371
 372 @object: object stop weakly referencing.
 373 @notify: callback to search for.
 374 @data: data to search for.
 375
 376
 377 <!-- ##### FUNCTION gtk_object_destroy ##### -->
 378 <para>
 379 Calls the object's shutdown handler.
 380 </para>
 381 <para>
 382 The memory for the object itself won't be deleted until
 383 its reference count drops to 0, though.
 384 See gtk_object_unref().
 385 </para>
 386
 387 @object: the object to destroy.
 388
 389
 390 <!-- ##### FUNCTION gtk_object_get ##### -->
 391 <para>
 392
 393 </para>
 394
 395 @object:
 396 @first_property_name:
 397 @Varargs:
 398 <!-- # Unused Parameters # -->
 399 @first_arg_name:
 400
 401
 402 <!-- ##### FUNCTION gtk_object_set ##### -->
 403 <para>
 404 This function sets multiple arguments of an object.
 405 </para>
 406 <para>
 407 It takes an object, then a list of name/value pairs
 408 in a list, followed by NULL.
 409 </para>
 410 <para>
 411 <informalexample>
 412 <programlisting>
 413 void set_box_properties(GtkBox* box)
 414 {
 415   gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,
 416                                   "spacing", 8,
 417                                   NULL);
 418 }
 419 </programlisting>
 420 </informalexample>
 421 </para>
 422
 423 @object: the object whose arguments should be set.
 424 @first_property_name:
 425 @Varargs: the value of the first argument, followed optionally
 426 by more name/value pairs, followed by NULL.
 427 <!-- # Unused Parameters # -->
 428 @first_arg_name: the name of the first argument to set.
 429
 430
 431 <!-- ##### FUNCTION gtk_object_set_data ##### -->
 432 <para>
 433 Each object carries around a table of associations from
 434 strings to pointers.  This function lets you set an association.
 435 </para>
 436 <para>
 437 If the object already had an association with that name,
 438 the old association will be destroyed.
 439 </para>
 440
 441 @object: object containing the associations.
 442 @key: name of the key.
 443 @data: data to associate with that key.
 444
 445
 446 <!-- ##### FUNCTION gtk_object_set_data_full ##### -->
 447 <para>
 448 Like gtk_object_set_data() except it adds notification
 449 for when the association is destroyed, either by
 450 gtk_object_remove_data() or when the object is destroyed.
 451 </para>
 452
 453 @object: object containing the associations.
 454 @key: name of the key.
 455 @data: data to associate with that key.
 456 @destroy: function to call when the association is destroyed.
 457
 458
 459 <!-- ##### FUNCTION gtk_object_remove_data ##### -->
 460 <para>
 461 Remove a specified datum from the object's data associations (the object_data).
 462 Subsequent calls to gtk_object_get_data() will return NULL.
 463 </para>
 464 <para>
 465 If you specified a destroy handler with gtk_object_set_data_full(),
 466 it will be invoked.
 467 </para>
 468
 469 @object: the object maintaining the association.
 470 @key: name of the key for that association.
 471
 472
 473 <!-- ##### FUNCTION gtk_object_get_data ##### -->
 474 <para>
 475 Get a named field from the object's table of associations (the object_data).
 476 </para>
 477
 478 @object: the object maintaining the associations.
 479 @key: name of the key for that association.
 480 @Returns: the data if found, or NULL if no such data exists.
 481
 482
 483 <!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
 484 <para>
 485 Remove a specified datum from the object's data associations (the object_data),
 486 without invoking the association's destroy handler.
 487 </para>
 488 <para>
 489 Just like gtk_object_remove_data() except that any destroy handler
 490 will be ignored.
 491 Therefore this only affects data set using gtk_object_set_data_full().
 492 </para>
 493
 494 @object: the object maintaining the association.
 495 @key: name of the key for that association.
 496
 497
 498 <!-- ##### FUNCTION gtk_object_set_user_data ##### -->
 499 <para>
 500 For convenience, every object offers a generic user data
 501 pointer.  The function set it.
 502 </para>
 503 <para>
 504 This function is equivalent to:
 505 <informalexample>
 506 <programlisting>
 507         gtk_object_set_data(object, "user_data", data);
 508 </programlisting>
 509 </informalexample>
 510 </para>
 511
 512 @object: the object whose user data should be set.
 513 @data: the new value for the user data.
 514
 515
 516 <!-- ##### FUNCTION gtk_object_get_user_data ##### -->
 517 <para>
 518 Get the object's user data pointer.
 519 </para>
 520 <para>
 521 This is intended to be a pointer for your convenience in
 522 writing applications.
 523 </para>
 524
 525 @object: the object.
 526 @Returns: the user data field for object.
 527
 528
 529 <!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
 530 <para>
 531 Add a new type of argument to an object class.
 532 Usually this is called when registering a new type of object.
 533 </para>
 534
 535 @arg_name: fully qualify object name, for example GtkObject::user_data.
 536 @arg_type: type of the argument.
 537 @arg_flags: bitwise-OR of the #GtkArgFlags enum.  (Whether the argument is
 538 settable or gettable, whether it is set when the object is constructed.)
 539 @arg_id: an internal number, passed in from here to the "set_arg" and
 540 "get_arg" handlers of the object.
 541
 542
 543 <!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
 544 <para>
 545 Just like gtk_object_set_data() except that it takes
 546 a #GQuark instead of a string, so it is slightly faster.
 547 </para>
 548 <para>
 549 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 550 to get an id from a string.
 551 </para>
 552
 553 @object: object containing the associations.
 554 @data_id: quark of the key.
 555 @data: data to associate with that key.
 556
 557
 558 <!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
 559 <para>
 560 Just like gtk_object_set_data_full() except that it takes
 561 a #GQuark instead of a string, so it is slightly faster.
 562 </para>
 563 <para>
 564 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 565 to get an id from a string.
 566 </para>
 567
 568 @object: object containing the associations.
 569 @data_id: quark of the key.
 570 @data: data to associate with that key.
 571 @destroy: function to call when the association is destroyed.
 572
 573
 574 <!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
 575 <para>
 576 Just like gtk_object_get_data() except that it takes
 577 a #GQuark instead of a string, so it is slightly faster.
 578 </para>
 579 <para>
 580 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 581 to get an id from a string.
 582 </para>
 583
 584 @object: object containing the associations.
 585 @data_id: quark of the key.
 586 @Returns: the data if found, or NULL if no such data exists.
 587
 588
 589 <!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
 590 <para>
 591 Just like gtk_object_remove_data() except that it takes
 592 a #GQuark instead of a string, so it is slightly faster.
 593 </para>
 594 <para>
 595 Remove a specified datum from the object's data associations.
 596 Subsequent calls to gtk_object_get_data() will return NULL.
 597 </para>
 598 <para>
 599 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 600 to get an id from a string.
 601 </para>
 602
 603 @object: object containing the associations.
 604 @data_id: quark of the key.
 605
 606
 607 <!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
 608 <para>
 609 Just like gtk_object_remove_no_notify() except that it takes
 610 a #GQuark instead of a string, so it is slightly faster.
 611 </para>
 612 <para>
 613 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 614 to get an id from a string.
 615 </para>
 616
 617 @object: object containing the associations.
 618 @key_id:
 619 <!-- # Unused Parameters # -->
 620 @data_id: quark of the key.
 621
 622
 623 <!-- ##### MACRO gtk_object_data_try_key ##### -->
 624 <para>
 625 Sees whether a certain quark exists.
 626 Returns that quark if so.
 627 </para>
 628 <para>
 629 Although this is currently the same as g_quark_try_string(),
 630 it might someday be different, for example, if GQuarks
 631 and object data are converted to separate mechanisms,
 632 so it is good to use this macro.
 633 </para>
 634
 635
 636
 637 <!-- ##### MACRO gtk_object_data_force_id ##### -->
 638 <para>
 639 Makes a quark from a string, possibly allocating a new quark.
 640 </para>
 641 <para>
 642 Although this is currently the same as g_quark_from_string(),
 643 it might someday be different, for example, if GQuarks
 644 and object data are converted to separate mechanisms,
 645 so it is good to use this macro.
 646 </para>
 647
 648
 649
 650 <!-- ##### SIGNAL GtkObject::destroy ##### -->
 651 <para>
 652 Indicates that an object is being destroyed.
 653 </para>
 654
 655 @object: the object which received the signal.
 656
 657 <!-- ##### ARG GtkObject:user-data ##### -->
 658 <para>
 659 A pointer for convenience when programming applications.
 660 </para>
 661