Description

GtkObject is the base class for all widgets, and for a few non-widget objects such as GtkAdjustment. GtkObject predates GObject; non-widgets that derive from GtkObject rather than GObject do so for backward compatibility reasons.

The most interesting difference between GtkObject and GObject is the "floating" reference count. A GObject is created with a reference count of 1, owned by the creator of the GObject. (The owner of a reference is the code section that has the right to call g_object_unref() in order to remove that reference.) A GtkObject is created with a reference count of 1 also, but it isn't owned by anyone; calling g_object_unref() on the newly-created GtkObject is incorrect. Instead, the initial reference count of a GtkObject is "floating". The floating reference can be removed by anyone at any time, by calling gtk_object_sink(). gtk_object_sink() does nothing if an object is already sunk (has no floating reference).

When you add a widget to its parent container, the parent container will do this:

  g_object_ref (G_OBJECT (child_widget));
  gtk_object_sink (GTK_OBJECT (child_widget));

This means that the container now owns a reference to the child widget (since it called g_object_ref()), and the child widget has no floating reference.

The purpose of the floating reference is to keep the child widget alive until you add it to a parent container:

   button = gtk_button_new ();
   /* button has one floating reference to keep it alive */
   gtk_container_add (GTK_CONTAINER (container), button);
   /* button has one non-floating reference owned by the container */

GtkWindow is a special case, because GTK+ itself will ref/sink it on creation. That is, after calling gtk_window_new(), the GtkWindow will have one reference which is owned by GTK+, and no floating references.

One more factor comes into play: the "destroy" signal, emitted by the gtk_object_destroy() method. The "destroy" signal asks all code owning a reference to an object to release said reference. So, for example, if you call gtk_object_destroy() on a GtkWindow, GTK+ will release the reference count that it owns; if you call gtk_object_destroy() on a GtkButton, then the button will be removed from its parent container and the parent container will release its reference to the button. Because these references are released, calling gtk_object_destroy() should result in freeing all memory associated with an object, unless some buggy code fails to release its references in response to the "destroy" signal. Freeing memory (referred to as finalization only happens if the reference count reaches zero.

Some simple rules for handling GtkObject:

GtkObject

typedef struct _GtkObject GtkObject;

The object itself. You should never use these members directly - use the accessing macros instead.

GTK_OBJECT_TYPE()

#define GTK_OBJECT_TYPE(object)		  (G_TYPE_FROM_INSTANCE (object))

Gets the type of an object.

GTK_OBJECT_TYPE_NAME()

#define GTK_OBJECT_TYPE_NAME(object)	  (g_type_name (GTK_OBJECT_TYPE (object)))

Gets the name of an objects type.

enum GtkObjectFlags

typedef enum
{
  GTK_IN_DESTRUCTION	= 1 << 0, /* Used internally during dispose */
  GTK_FLOATING		= 1 << 1,
  GTK_RESERVED_1	= 1 << 2,
  GTK_RESERVED_2	= 1 << 3
} GtkObjectFlags;

Tells about the state of the object.

GTK_OBJECT_FLAGS()

#define GTK_OBJECT_FLAGS(obj)		  (GTK_OBJECT (obj)->flags)

Gets the GtkObjectFlags for an object without directly accessing its members.

GTK_OBJECT_FLOATING()

#define GTK_OBJECT_FLOATING(obj)	  ((GTK_OBJECT_FLAGS (obj) & GTK_FLOATING) != 0)

Evaluates to TRUE if the object still has its floating reference count. See the overview documentation for GtkObject.

enum GtkArgFlags

typedef enum
{
  GTK_ARG_READABLE	 = G_PARAM_READABLE,
  GTK_ARG_WRITABLE	 = G_PARAM_WRITABLE,
  GTK_ARG_CONSTRUCT	 = G_PARAM_CONSTRUCT,
  GTK_ARG_CONSTRUCT_ONLY = G_PARAM_CONSTRUCT_ONLY,
  GTK_ARG_CHILD_ARG	 = 1 << 4
} GtkArgFlags;

Possible flags indicating how an argument should be treated. Deprecated in favor of GParamSpec features.

gtk_object_new ()

GtkObject*  gtk_object_new                  (GtkType type,
                                             const gchar *first_property_name,
                                             ...);

Constructs an object given its arguments, enumerated in the call to the function.

gtk_object_sink ()

void        gtk_object_sink                 (GtkObject *object);

Removes the floating reference from a GtkObject, if it exists; otherwise does nothing. See the GtkObject overview documentation at the top of the page.

gtk_object_ref ()

GtkObject*  gtk_object_ref                  (GtkObject *object);

Increases the reference count of the object.

gtk_object_unref ()

void        gtk_object_unref                (GtkObject *object);

Decreases the reference count of an object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

gtk_object_weakref ()

void        gtk_object_weakref              (GtkObject *object,
                                             GtkDestroyNotify notify,
                                             gpointer data);

Adds a weak reference callback to an object. Weak references are used for notification when an object is finalized. They are called "weak references" because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a strong reference, that is, forces the object to stay alive).

gtk_object_weakunref ()

void        gtk_object_weakunref            (GtkObject *object,
                                             GtkDestroyNotify notify,
                                             gpointer data);

Removes a weak reference callback to an object.

gtk_object_destroy ()

void        gtk_object_destroy              (GtkObject *object);

Emits the "destroy" signal notifying all reference holders that they should release the GtkObject. See the overview documentation at the top of the page for more details.

The memory for the object itself won't be deleted until its reference count actually drops to 0; gtk_object_destroy() merely asks reference holders to release their references, it does not free the object.

gtk_object_get ()

void        gtk_object_get                  (GtkObject *object,
                                             const gchar *first_property_name,
                                             ...);

Gets properties of an object.

gtk_object_set ()

void        gtk_object_set                  (GtkObject *object,
                                             const gchar *first_property_name,
                                             ...);

Sets properties on an object.

void set_box_properties (GtkBox* box)
{
  gtk_object_set (GTK_OBJECT (box), "homogeneous", TRUE,
                                    "spacing", 8,
				    NULL);
}

gtk_object_set_data ()

void        gtk_object_set_data             (GtkObject *object,
                                             const gchar *key,
                                             gpointer data);

Each object carries around a table of associations from strings to pointers. This function lets you set an association.

If the object already had an association with that name, the old association will be destroyed.

gtk_object_set_data_full ()

void        gtk_object_set_data_full        (GtkObject *object,
                                             const gchar *key,
                                             gpointer data,
                                             GtkDestroyNotify destroy);

Like gtk_object_set_data() except it adds notification for when the association is destroyed, either by gtk_object_remove_data() or when the object is destroyed.

gtk_object_remove_data ()

void        gtk_object_remove_data          (GtkObject *object,
                                             const gchar *key);

Removes a specified datum from the object's data associations (the object_data). Subsequent calls to gtk_object_get_data() will return NULL.

If you specified a destroy handler with gtk_object_set_data_full(), it will be invoked.

gtk_object_get_data ()

gpointer    gtk_object_get_data             (GtkObject *object,
                                             const gchar *key);

Get a named field from the object's table of associations (the object_data).

gtk_object_remove_no_notify ()

void        gtk_object_remove_no_notify     (GtkObject *object,
                                             const gchar *key);

Remove a specified datum from the object's data associations (the object_data), without invoking the association's destroy handler.

Just like gtk_object_remove_data() except that any destroy handler will be ignored. Therefore this only affects data set using gtk_object_set_data_full().

gtk_object_set_user_data ()

void        gtk_object_set_user_data        (GtkObject *object,
                                             gpointer data);

For convenience, every object offers a generic user data pointer. This function sets it.

gtk_object_get_user_data ()

gpointer    gtk_object_get_user_data        (GtkObject *object);

Get the object's user data pointer.

This is intended to be a pointer for your convenience in writing applications.

gtk_object_add_arg_type ()

void        gtk_object_add_arg_type         (const gchar *arg_name,
                                             GtkType arg_type,
                                             guint arg_flags,
                                             guint arg_id);

Deprecated in favor of the GObject property system including GParamSpec. Add a new type of argument to an object class. Usually this is called when registering a new type of object.

gtk_object_set_data_by_id ()

void        gtk_object_set_data_by_id       (GtkObject *object,
                                             GQuark data_id,
                                             gpointer data);

Just like gtk_object_set_data() except that it takes a GQuark instead of a string, so it is slightly faster.

Use gtk_object_data_try_key() and gtk_object_data_force_id() to get an id from a string.

gtk_object_set_data_by_id_full ()

void        gtk_object_set_data_by_id_full  (GtkObject *object,
                                             GQuark data_id,
                                             gpointer data,
                                             GtkDestroyNotify destroy);

Just like gtk_object_set_data_full() except that it takes a GQuark instead of a string, so it is slightly faster.

Use gtk_object_data_try_key() and gtk_object_data_force_id() to get an id from a string.

gtk_object_get_data_by_id ()

gpointer    gtk_object_get_data_by_id       (GtkObject *object,
                                             GQuark data_id);

Just like gtk_object_get_data() except that it takes a GQuark instead of a string, so it is slightly faster.

Use gtk_object_data_try_key() and gtk_object_data_force_id() to get an id from a string.

gtk_object_remove_data_by_id ()

void        gtk_object_remove_data_by_id    (GtkObject *object,
                                             GQuark data_id);

Just like gtk_object_remove_data() except that it takes a GQuark instead of a string, so it is slightly faster.

Remove a specified datum from the object's data associations. Subsequent calls to gtk_object_get_data() will return NULL.

Use gtk_object_data_try_key() and gtk_object_data_force_id() to get an id from a string.

gtk_object_remove_no_notify_by_id ()

void        gtk_object_remove_no_notify_by_id
                                            (GtkObject *object,
                                             GQuark key_id);

Just like gtk_object_remove_no_notify() except that it takes a GQuark instead of a string, so it is slightly faster.

Use gtk_object_data_try_key() and gtk_object_data_force_id() to get an id from a string.

gtk_object_data_try_key

#define	gtk_object_data_try_key	    g_quark_try_string

Useless deprecated macro. Ignore it.

gtk_object_data_force_id

#define	gtk_object_data_force_id    g_quark_from_string

Useless deprecated macro. Ignore it.

The "user-data" property

  "user-data"            gpointer              : Read / Write

Anonymous User Data Pointer.

The "destroy" signal

void        user_function                  (GtkObject *object,
                                            gpointer user_data);

Signals that all holders of a reference to the GtkObject should release the reference that they hold. May result in finalization of the object if all references are released.