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:
 214 @GTK_CONSTRUCTED: refers to whether the arguments for this object are
 215 ready.
 216
 217 <!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
 218 <para>
 219 Get the #GtkObjectFlags for an object without directly
 220 accessing its members.
 221 </para>
 222
 223 @obj: the object whose flags are returned.
 224
 225
 226 <!-- ##### MACRO GTK_OBJECT_DESTROYED ##### -->
 227 <para>
 228 Test whether a GtkObject has had gtk_object_destroyed() invoked on it.
 229 </para>
 230
 231 @obj: the object to examine.
 232
 233
 234 <!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
 235 <para>
 236 When an object is created, it has an initial reference count
 237 of 1 and is floating.  <wordasword>Sinking</wordasword> the object
 238 refers to decrementing that original reference count.
 239 </para>
 240
 241 @obj: the object to examine.
 242
 243
 244 <!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->
 245 <para>
 246 Test whether a GtkObject has had a signal connected to it.
 247 </para>
 248
 249 @obj: the object to examine.
 250
 251
 252 <!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->
 253 <para>
 254 Test whether a GtkObject's arguments have been prepared.
 255 </para>
 256
 257 @obj: the object to examine.
 258
 259
 260 <!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->
 261 <para>
 262 Turn on certain object flags.  (Private)
 263 </para>
 264
 265 @obj: the object to affect.
 266 @flag: the flags to set.
 267
 268
 269 <!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->
 270 <para>
 271 Turn off certain object flags.  (Private)
 272 </para>
 273
 274 @obj: the object to affect.
 275 @flag: the flags to unset.
 276
 277
 278 <!-- ##### ENUM GtkArgFlags ##### -->
 279 <para>
 280 Possible flags indicating how an argument should be treated.
 281 </para>
 282
 283 @GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)
 284 @GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)
 285 @GTK_ARG_CONSTRUCT: the argument needs construction.
 286 @GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will
 287 be set once during object creation), but is otherwise cannot be
 288 set.  Hence this flag is not allowed with #GTK_ARG_WRITABLE,
 289 and is redundant with #GTK_ARG_CONSTRUCT.
 290 @GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)
 291 each child.  Used by #GtkContainer.
 292 @GTK_ARG_MASK: the bitwise-OR of all the flags.
 293 @GTK_ARG_READWRITE: the argument is readable and writable.
 294
 295 <!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->
 296 <para>
 297 Define a signal-handler for a new signal on an already defined
 298 object.
 299 </para>
 300 <para>
 301 See the signal documentation for more general information.
 302 </para>
 303
 304 @klass: the object class to define the signal for.
 305 @name: the name of the signal.
 306 @signal_flags: the default emission behavior for the signal.
 307 See gtk_signal_new().
 308 @marshaller: a function that will take an array of GtkArgs
 309 and invoke the appropriate handler with the normal calling
 310 conventions.
 311 @return_val: specify the return-value type for the signal
 312 (or GTK_TYPE_NONE for no return-value).
 313 @nparams: specify the number of parameters the signal
 314 receives from the caller of gtk_signal_emit().
 315 @Varargs: list of nparams #GtkTypes to pass to the signal handlers.
 316 @Returns: the signal id.  (See #GtkSignals)
 317
 318
 319 <!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->
 320 <para>
 321 Define a signal-handler for a new signal on an already defined
 322 object.
 323 </para>
 324
 325 @klass: the object class to define the signal for.
 326 @name: the name of the signal.
 327 @signal_flags: the default emission behavior for the signal.
 328 See gtk_signal_new().
 329 @marshaller: takes a GtkObject, a #GtkSignalFunc, and an array
 330 of arguments, and invokes the function using the appropriate
 331 calling conventions.  Usually just select a function
 332 out of gtkmarshal.h.
 333 @return_val: specify the return-value type for the signal (possibly
 334 #GTK_TYPE_NONE).
 335 @nparams: specify the number of parameters the signal
 336 receives from the caller of gtk_signal_emit().
 337 @params: array of #GtkTypes the signal handlers for this signal
 338 should have in their prototype (of length nparams).
 339 @Returns: the signal id.  (See #GtkSignals)
 340
 341
 342 <!-- ##### FUNCTION gtk_object_new ##### -->
 343 <para>
 344 Construct an object given its arguments, enumerated in the call to the
 345 function.
 346 </para>
 347
 348 @type: the type identifying this object.  Returned by gtk_type_unique()
 349 although (for a properly-written object it should be accessible through
 350 #GTK_TYPE_FOO.)
 351 @first_arg_name: name of the first argument to set when constructing
 352 the object.
 353 @Varargs: the first argument's value, followed by any number of
 354 name/argument-value pairs, terminated with NULL.
 355 @Returns: the new GtkObject.
 356
 357
 358 <!-- ##### FUNCTION gtk_object_newv ##### -->
 359 <para>
 360 Construct an object with an array of arguments.
 361 </para>
 362
 363 @object_type: the type of the object to create.
 364 @n_args: the number of arguments to set.
 365 @args: an array of n_args arguments (which are name and value pairs).
 366 @Returns: the new GtkObject.
 367
 368
 369 <!-- ##### FUNCTION gtk_object_constructed ##### -->
 370 <para>
 371 Mark an allocated object as constructed.
 372 This is used for situations
 373 that require precise control of the construction process.
 374 </para>
 375 <para>
 376 This is done when gtk_object_default_construct() is inadequate.
 377 In #GtkCList the need arises because #GtkCList does construction work that
 378 must happen <emphasis>after</emphasis> its derivers.  This work
 379 cannot be done in an initializer function, so an alternate
 380 constructor is mandatory.  It calls gtk_object_constructed() to
 381 indicate it has done its job, so that no other constructor will
 382 be invoked.
 383 </para>
 384 <para>
 385 Normally this function is just automatically run from
 386 gtk_object_default_construct().
 387 </para>
 388
 389 @object: object which has been constructed.  This is usually
 390 done automatically by gtk_object_new() and gtk_object_newv().
 391
 392
 393 <!-- ##### FUNCTION gtk_object_default_construct ##### -->
 394 <para>
 395 This function is called to construct arguments that haven't been initialized
 396 but have the #GTK_ARG_CONSTRUCT flag set.
 397 </para>
 398 <para>
 399 All number arguments are set to 0.  All pointers and strings
 400 are set to NULL.
 401 </para>
 402 <para>
 403 Normally invoked by gtk_object_new() automatically; gtk_type_new() can
 404 be used to bypass it.
 405 </para>
 406
 407 @object: the object to initialize.
 408
 409
 410 <!-- ##### FUNCTION gtk_object_sink ##### -->
 411 <para>
 412 Decrement the initial count given to the object.
 413 Additional invocations have no effect.
 414 </para>
 415 <para>
 416 This is designed to free the user from worrying about
 417 dereferencing an object that they have just created.
 418 So long as the object is sunk at some point, the reference count
 419 will be set properly.
 420 </para>
 421 <para>
 422 furthermore it may be sunk multiple times.
 423 Only the first time will actually dereference.
 424 </para>
 425 <para>
 426 The basic outline is: when you create an object it is floating.
 427 Setting its parent causes it to be sunk, however its parent
 428 has obtained a reference, so its reference count is one.
 429 </para>
 430
 431 @object: the object to sink.
 432
 433
 434 <!-- ##### FUNCTION gtk_object_ref ##### -->
 435 <para>
 436 Increase the reference count of the object.
 437 </para>
 438
 439 @object: the object to reference.
 440 @Returns:
 441
 442
 443 <!-- ##### FUNCTION gtk_object_unref ##### -->
 444 <para>
 445 Decrease the reference count of an object.  When its reference
 446 count drops to 0, the object is deleted.
 447 </para>
 448 <para>
 449 If it was not already destroyed, it will be, with gtk_object_destroy(),
 450 then weak links are notified, then the object-data is freed
 451 and the memory for the object itself is freed using gtk_type_free().
 452 </para>
 453
 454 @object: the object to dereference.
 455
 456
 457 <!-- ##### FUNCTION gtk_object_weakref ##### -->
 458 <para>
 459 Adds a weak reference callback to an object.
 460 </para>
 461 <para>
 462 Weak references are a mechanism to safely keep a pointer to
 463 an object without using the reference counting
 464 mechansim.  They use a callback function to receive
 465 notice that the object is about to be freed (aka finalized).
 466 This happens <emphasis>after</emphasis> the destroy
 467 callback has been run.
 468 </para>
 469
 470 @object: object to weakly reference.
 471 @notify: callback to invoke before the object is freed.
 472 @data: extra data to pass to #notify.
 473
 474
 475 <!-- ##### FUNCTION gtk_object_weakunref ##### -->
 476 <para>
 477 Removes a weak reference callback to an object.
 478 </para>
 479
 480 @object: object stop weakly referencing.
 481 @notify: callback to search for.
 482 @data: data to search for.
 483
 484
 485 <!-- ##### FUNCTION gtk_object_destroy ##### -->
 486 <para>
 487 Calls the object's shutdown handler.
 488 </para>
 489 <para>
 490 The memory for the object itself won't be deleted until
 491 its reference count drops to 0, though.
 492 See gtk_object_unref().
 493 </para>
 494
 495 @object: the object to destroy.
 496
 497
 498 <!-- ##### FUNCTION gtk_object_get ##### -->
 499 <para>
 500
 501 </para>
 502
 503 @object:
 504 @first_arg_name:
 505 @Varargs:
 506
 507
 508 <!-- ##### FUNCTION gtk_object_getv ##### -->
 509 <para>
 510 Gets an array of argument values from an object.
 511 </para>
 512
 513 @object: the object to get arguments from.
 514 @n_args: the number of arguments to query.
 515 @args: the arguments to fill in.
 516
 517
 518 <!-- ##### FUNCTION gtk_object_set ##### -->
 519 <para>
 520 This function sets multiple arguments of an object.
 521 </para>
 522 <para>
 523 It takes an object, then a list of name/value pairs
 524 in a list, followed by NULL.
 525 </para>
 526 <para>
 527 <informalexample>
 528 <programlisting>
 529 void set_box_properties(GtkBox* box)
 530 {
 531   gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,
 532                                   "spacing", 8,
 533                                   NULL);
 534 }
 535 </programlisting>
 536 </informalexample>
 537 </para>
 538
 539 @object: the object whose arguments should be set.
 540 @first_arg_name: the name of the first argument to set.
 541 @Varargs: the value of the first argument, followed optionally
 542 by more name/value pairs, followed by NULL.
 543
 544
 545 <!-- ##### FUNCTION gtk_object_setv ##### -->
 546 <para>
 547 Set an array of arguments.
 548 </para>
 549
 550 @object: the object whose arguments should be set.
 551 @n_args: the number of arguments to set.
 552 @args: the desired values, as an array of #GtkArgs (which contain
 553 the names, types, and values of the arguments).
 554
 555
 556 <!-- ##### FUNCTION gtk_object_query_args ##### -->
 557 <para>
 558 Get all the arguments that may be used for a given type.
 559 </para>
 560 <para>
 561 In Java, this type of mechanism is called
 562 <wordasword>introspection</wordasword>.  It is used by applications
 563 like Glade, that have to determine what can be done to an object
 564 at run-time.
 565 </para>
 566
 567 @class_type: the GtkType of the ObjectClass
 568 (returned from GTK_OBJECT_CLASS(class)-&gt;type for example).
 569 @arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to
 570 each argument.  You must g_free() this if you request it.
 571 @n_args: the number of arguments is returned in this field.
 572 @Returns: an array of arguments, that you must deallocate with g_free().
 573
 574
 575 <!-- ##### FUNCTION gtk_object_set_data ##### -->
 576 <para>
 577 Each object carries around a table of associations from
 578 strings to pointers.  This function lets you set an association.
 579 </para>
 580 <para>
 581 If the object already had an association with that name,
 582 the old association will be destroyed.
 583 </para>
 584
 585 @object: object containing the associations.
 586 @key: name of the key.
 587 @data: data to associate with that key.
 588
 589
 590 <!-- ##### FUNCTION gtk_object_set_data_full ##### -->
 591 <para>
 592 Like gtk_object_set_data() except it adds notification
 593 for when the association is destroyed, either by
 594 gtk_object_remove_data() or when the object is destroyed.
 595 </para>
 596
 597 @object: object containing the associations.
 598 @key: name of the key.
 599 @data: data to associate with that key.
 600 @destroy: function to call when the association is destroyed.
 601
 602
 603 <!-- ##### FUNCTION gtk_object_remove_data ##### -->
 604 <para>
 605 Remove a specified datum from the object's data associations (the object_data).
 606 Subsequent calls to gtk_object_get_data() will return NULL.
 607 </para>
 608 <para>
 609 If you specified a destroy handler with gtk_object_set_data_full(),
 610 it will be invoked.
 611 </para>
 612
 613 @object: the object maintaining the association.
 614 @key: name of the key for that association.
 615
 616
 617 <!-- ##### FUNCTION gtk_object_get_data ##### -->
 618 <para>
 619 Get a named field from the object's table of associations (the object_data).
 620 </para>
 621
 622 @object: the object maintaining the associations.
 623 @key: name of the key for that association.
 624 @Returns: the data if found, or NULL if no such data exists.
 625
 626
 627 <!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
 628 <para>
 629 Remove a specified datum from the object's data associations (the object_data),
 630 without invoking the association's destroy handler.
 631 </para>
 632 <para>
 633 Just like gtk_object_remove_data() except that any destroy handler
 634 will be ignored.
 635 Therefore this only affects data set using gtk_object_set_data_full().
 636 </para>
 637
 638 @object: the object maintaining the association.
 639 @key: name of the key for that association.
 640
 641
 642 <!-- ##### FUNCTION gtk_object_set_user_data ##### -->
 643 <para>
 644 For convenience, every object offers a generic user data
 645 pointer.  The function set it.
 646 </para>
 647 <para>
 648 This function is equivalent to:
 649 <informalexample>
 650 <programlisting>
 651         gtk_object_set_data(object, "user_data", data);
 652 </programlisting>
 653 </informalexample>
 654 </para>
 655
 656 @object: the object whose user data should be set.
 657 @data: the new value for the user data.
 658
 659
 660 <!-- ##### FUNCTION gtk_object_get_user_data ##### -->
 661 <para>
 662 Get the object's user data pointer.
 663 </para>
 664 <para>
 665 This is intended to be a pointer for your convenience in
 666 writing applications.
 667 </para>
 668
 669 @object: the object.
 670 @Returns: the user data field for object.
 671
 672
 673 <!-- ##### FUNCTION gtk_object_class_add_signals ##### -->
 674 <para>
 675 Add an array of signals to a #GtkObjectClass.
 676 Usually this is called when registering a new type of object.
 677 </para>
 678
 679 @klass: the object class to append signals to.
 680 @signals: the signals to append.
 681 @nsignals: the number of signals being appended.
 682
 683
 684 <!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
 685 <para>
 686 Add a new type of argument to an object class.
 687 Usually this is called when registering a new type of object.
 688 </para>
 689
 690 @arg_name: fully qualify object name, for example GtkObject::user_data.
 691 @arg_type: type of the argument.
 692 @arg_flags: bitwise-OR of the #GtkArgFlags enum.  (Whether the argument is
 693 settable or gettable, whether it is set when the object is constructed.)
 694 @arg_id: an internal number, passed in from here to the "set_arg" and
 695 "get_arg" handlers of the object.
 696
 697
 698 <!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
 699 <para>
 700 Just like gtk_object_set_data() except that it takes
 701 a #GQuark instead of a string, so it is slightly faster.
 702 </para>
 703 <para>
 704 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 705 to get an id from a string.
 706 </para>
 707
 708 @object: object containing the associations.
 709 @data_id: quark of the key.
 710 @data: data to associate with that key.
 711
 712
 713 <!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
 714 <para>
 715 Just like gtk_object_set_data_full() except that it takes
 716 a #GQuark instead of a string, so it is slightly faster.
 717 </para>
 718 <para>
 719 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 720 to get an id from a string.
 721 </para>
 722
 723 @object: object containing the associations.
 724 @data_id: quark of the key.
 725 @data: data to associate with that key.
 726 @destroy: function to call when the association is destroyed.
 727
 728
 729 <!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
 730 <para>
 731 Just like gtk_object_get_data() except that it takes
 732 a #GQuark instead of a string, so it is slightly faster.
 733 </para>
 734 <para>
 735 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 736 to get an id from a string.
 737 </para>
 738
 739 @object: object containing the associations.
 740 @data_id: quark of the key.
 741 @Returns: the data if found, or NULL if no such data exists.
 742
 743
 744 <!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
 745 <para>
 746 Just like gtk_object_remove_data() except that it takes
 747 a #GQuark instead of a string, so it is slightly faster.
 748 </para>
 749 <para>
 750 Remove a specified datum from the object's data associations.
 751 Subsequent calls to gtk_object_get_data() will return NULL.
 752 </para>
 753 <para>
 754 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 755 to get an id from a string.
 756 </para>
 757
 758 @object: object containing the associations.
 759 @data_id: quark of the key.
 760
 761
 762 <!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
 763 <para>
 764 Just like gtk_object_remove_no_notify() except that it takes
 765 a #GQuark instead of a string, so it is slightly faster.
 766 </para>
 767 <para>
 768 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 769 to get an id from a string.
 770 </para>
 771
 772 @object: object containing the associations.
 773 @key_id:
 774 <!-- # Unused Parameters # -->
 775 @data_id: quark of the key.
 776
 777
 778 <!-- ##### MACRO gtk_object_data_try_key ##### -->
 779 <para>
 780 Sees whether a certain quark exists.
 781 Returns that quark if so.
 782 </para>
 783 <para>
 784 Although this is currently the same as g_quark_try_string(),
 785 it might someday be different, for example, if GQuarks
 786 and object data are converted to separate mechanisms,
 787 so it is good to use this macro.
 788 </para>
 789
 790
 791
 792 <!-- ##### MACRO gtk_object_data_force_id ##### -->
 793 <para>
 794 Makes a quark from a string, possibly allocating a new quark.
 795 </para>
 796 <para>
 797 Although this is currently the same as g_quark_from_string(),
 798 it might someday be different, for example, if GQuarks
 799 and object data are converted to separate mechanisms,
 800 so it is good to use this macro.
 801 </para>
 802
 803
 804
 805 <!-- ##### FUNCTION gtk_object_arg_set ##### -->
 806 <para>
 807 Private function to set an argument and argument info to an object.
 808 </para>
 809
 810 @object: the object whose argument should be set.
 811 @arg: the argument.
 812 @info: infomation about this type of argument in general.
 813
 814
 815 <!-- ##### FUNCTION gtk_object_arg_get ##### -->
 816 <para>
 817 Private function to get an argument and argument info from an object.
 818 </para>
 819
 820 @object: the object whose argument should be retrieved.
 821 @arg: the argument, for the name on input, the rest is filled on output.
 822 @info: a #GtkArgInfo structure to optionally fill in.
 823
 824
 825 <!-- ##### FUNCTION gtk_object_args_collect ##### -->
 826 <para>
 827 Private: Gets an array of #GtkArgs from a va_list C structure.
 828 </para>
 829
 830 @object_type: the type of object to collect arguments for.
 831 @arg_list_p: pointer to be filled in with a list of parsed arguments.
 832 @info_list_p: optional pointer for a returned list #GtkArgInfos.
 833 @first_arg_name: name of first argument.
 834 @var_args: value of first argument, followed by more key/value pairs,
 835 terminated by NULL.
 836 @Returns: an error message, or NULL on success.
 837 It is the caller's responsibility to call g_free() in the event of error.
 838
 839
 840 <!-- ##### FUNCTION gtk_object_arg_get_info ##### -->
 841 <para>
 842 Query information about an argument type.
 843 </para>
 844
 845 @object_type: type of object to query about.
 846 @arg_name: name of the argument.
 847 @info_p: pointer to be filled in with a pointer to the GtkArgInfo.
 848 @Returns: an error message, or NULL on success.
 849 It is the caller's responsibility to call g_free() in the event of error.
 850
 851
 852 <!-- ##### SIGNAL GtkObject::destroy ##### -->
 853 <para>
 854 Indicates that an object is being destroyed.
 855 </para>
 856
 857 @object: the object which received the signal.
 858
 859 <!-- ##### ARG GtkObject:user_data ##### -->
 860 <para>
 861 A pointer for convenience when programming applications.
 862 </para>
 863
 864 <!-- ##### ARG GtkObject:signal ##### -->
 865 <para>
 866 Setting this with a GtkType of GTK_TYPE_SIGNAL connects
 867 the signal to the object.
 868 </para>
 869
 870 <!-- ##### ARG GtkObject:signal_after ##### -->
 871 <para>
 872 Setting this with a GtkType of GTK_TYPE_SIGNAL connects
 873 the signal to the object, so that the signal is always run
 874 after other user handlers and the default handler.
 875 </para>
 876
 877 <!-- ##### ARG GtkObject:object_signal ##### -->
 878 <para>
 879 Setting this with a GtkType of GTK_TYPE_SIGNAL connects
 880 the signal to the object, so that the user data and objects
 881 and swapped when the signal handler is invoked.
 882 </para>
 883 <para>
 884 This is useful for handlers that are primarily notifying
 885 other objects and could just invoke an already existing function
 886 if the parameters were swapped.
 887 See gtk_signal_connect_object() for more details.
 888 </para>
 889
 890 <!-- ##### ARG GtkObject:object_signal_after ##### -->
 891 <para>
 892 Setting this with a GtkType of GTK_TYPE_SIGNAL connects
 893 the signal to the object, so that the user data and objects
 894 and swapped when the signal handler is invoked,
 895 and so that the handler is invoked after all others.
 896 </para>
 897 <para>
 898 See gtk_signal_connect_object_after() for more details.
 899 </para>
 900