## GtkObject

GtkObject — The base class of the GTK+ type hierarchy

## Synopsis

    #include <gtk/gtk.h>

                        GtkObject;
    enum                GtkObjectFlags;
    #define             GTK_OBJECT_FLAGS                    (obj)
    void                gtk_object_destroy                  (GtkObject *object);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                   +----GtkAdjustment
                   +----GtkCellRenderer
                   +----GtkFileFilter
                   +----GtkTreeViewColumn
                   +----GtkRecentFilter

## Signals

      "destroy"                                        : Cleanup / No Recursion / No Hooks

## 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.

GtkObjects are created with a "floating" reference count. This means that the initial reference is not owned by anyone. Calling `g_object_unref()` on a newly-created GtkObject is incorrect, the floating reference has to be removed first. This can be done by anyone at any time, by calling `g_object_ref_sink()` to convert the floating reference into a regular reference. `g_object_ref_sink()` returns a new reference 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:

    1

    g_object_ref_sink (G_OBJECT (child_widget));

This means that the container now owns a reference to the child widget 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:

    1
    2
    3
    4

    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:

- Never call `g_object_unref()` unless you have previously called `g_object_ref()`, even if you created the GtkObject. (Note: this is not true for GObject; for GObject, the creator of the object owns a reference.)

- Call `gtk_object_destroy()` to get rid of most objects in most cases. In particular, widgets are almost always destroyed in this way.

- Because of the floating reference count, you don't need to worry about reference counting for widgets and toplevel windows, unless you explicitly call `g_object_ref()` yourself.

## Details

### GtkObject

    typedef struct _GtkObject GtkObject;

### enum GtkObjectFlags

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

### Warning

`GtkObjectFlags` has been deprecated since version 2.22 and should not be used in newly-written code. Do not re-use GtkObject flags but use your own variable to store flags.

Tells about the state of the object.

`GTK_IN_DESTRUCTION` | the object is currently being destroyed. This is used internally by GTK+ to prevent reinvokations during destruction.
`GTK_RESERVED_1` | reserved for future use
`GTK_RESERVED_2` | reserved for future use

### GTK_OBJECT_FLAGS()

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

### Warning

`GTK_OBJECT_FLAGS` has been deprecated since version 2.22 and should not be used in newly-written code. Do not re-use GtkObject flags but use your own variable to store flags.

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

`obj` : | the object whose flags are returned.

### 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.

`object` : | the object to destroy.

## Signal Details

### The `"destroy"` signal

    void                user_function                      (GtkObject *object,
                                                            gpointer   user_data)      : Cleanup / No Recursion / No Hooks

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.

`object` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

GObject