manpagez: man pages & more
html files: gtk2
Home | html | info | man

GtkObject

GtkObject — The base class of the GTK+ type hierarchy

Properties

gpointer user-data Read / Write

Signals

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ├── GtkWidget
            ├── GtkAdjustment
            ├── GtkCellRenderer
            ├── GtkFileFilter
            ├── GtkItemFactory
            ├── GtkTooltips
            ├── GtkTreeViewColumn
            ╰── GtkRecentFilter

Includes

#include <gtk/gtk.h>

Description

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.

Functions

GTK_OBJECT_FLAGS()

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

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.

Parameters

obj

the object whose flags are returned.

 

GTK_OBJECT_FLOATING()

#define GTK_OBJECT_FLOATING(obj)	  (g_object_is_floating (obj))

GTK_OBJECT_FLOATING is deprecated and should not be used in newly-written code.

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

Parameters

obj

the object to examine.

 

gtk_object_new ()

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

gtk_object_new is deprecated and should not be used in newly-written code.

Use g_object_new() instead.

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

Parameters

type

the type identifying this object. Returned by gtk_type_unique() (although for a properly-written object it should be accessible through a GTK_TYPE_FOO macro.)

 

first_property_name

name of the first property to set when constructing the object.

 

Returns

the new GtkObject.


gtk_object_sink ()

void
gtk_object_sink (GtkObject *object);

gtk_object_sink has been deprecated since version 2.10 and should not be used in newly-written code.

Use g_object_ref_sink() instead

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

Parameters

object

the object to sink.

 

gtk_object_ref ()

GtkObject *
gtk_object_ref (GtkObject *object);

gtk_object_ref is deprecated and should not be used in newly-written code.

Use g_object_ref() instead.

Increases the reference count of the object.

Parameters

object

the object to reference.

 

Returns

object .


gtk_object_unref ()

void
gtk_object_unref (GtkObject *object);

gtk_object_unref is deprecated and should not be used in newly-written code.

Use g_object_unref() instead.

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

Parameters

object

the object to dereference.

 

gtk_object_weakref ()

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

gtk_object_weakref is deprecated and should not be used in newly-written code.

Use g_object_weak_ref() instead.

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

Parameters

object

object to weakly reference.

 

notify

callback to invoke before the object is freed.

 

data

extra data to pass to notify.

 

gtk_object_weakunref ()

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

gtk_object_weakunref is deprecated and should not be used in newly-written code.

Use g_object_weak_unref() instead.

Removes a weak reference callback to an object.

Parameters

object

object stop weakly referencing.

 

notify

callback to search for.

 

data

data to search for.

 

gtk_object_destroy ()

void
gtk_object_destroy (GtkObject *object);

gtk_object_destroy has been deprecated since version 2.24 and should not be used in newly-written code.

Use gtk_widget_destroy() instead (if object is a widget)

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.

Parameters

object

the object to destroy.

 

gtk_object_get ()

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

gtk_object_get is deprecated and should not be used in newly-written code.

Use g_object_get() instead.

Gets properties of an object.

Parameters

object

a GtkObject.

 

first_property_name

name of first property to get the value for.

 

gtk_object_set ()

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

gtk_object_set is deprecated and should not be used in newly-written code.

Use g_object_set() instead.

Sets properties on an object.

1
2
3
4
5
6
void set_box_properties (GtkBox* box)
{
  gtk_object_set (GTK_OBJECT (box), "homogeneous", TRUE,
                                    "spacing", 8,
                    NULL);
}

Parameters

object

a GtkObject.

 

first_property_name

name of the first property to set

 

gtk_object_set_data ()

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

gtk_object_set_data is deprecated and should not be used in newly-written code.

Use g_object_set_data() instead.

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.

Parameters

object

object containing the associations.

 

key

name of the key.

 

data

data to associate with that key.

 

gtk_object_set_data_full ()

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

gtk_object_set_data_full is deprecated and should not be used in newly-written code.

Use g_object_set_data_full() instead.

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.

Parameters

object

object containing the associations.

 

key

name of the key.

 

data

data to associate with that key.

 

destroy

function to call when the association is destroyed.

 

gtk_object_remove_data ()

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

gtk_object_remove_data is deprecated and should not be used in newly-written code.

Use g_object_set_data() to set the object data to NULL instead.

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.

Parameters

object

the object maintaining the association.

 

key

name of the key for that association.

 

gtk_object_get_data ()

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

gtk_object_get_data is deprecated and should not be used in newly-written code.

Use g_object_get_data() instead.

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

Parameters

object

the object maintaining the associations.

 

key

name of the key for that association.

 

Returns

the data if found, or NULL if no such data exists.


gtk_object_remove_no_notify ()

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

gtk_object_remove_no_notify is deprecated and should not be used in newly-written code.

Use g_object_steal_data() instead.

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().

Parameters

object

the object maintaining the association.

 

key

name of the key for that association.

 

gtk_object_set_user_data ()

void
gtk_object_set_user_data (GtkObject *object,
                          gpointer data);

gtk_object_set_user_data is deprecated and should not be used in newly-written code.

Use g_object_set_data() instead.

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

Parameters

object

the object whose user data should be set.

 

data

the new value for the user data.

 

gtk_object_get_user_data ()

gpointer
gtk_object_get_user_data (GtkObject *object);

gtk_object_get_user_data is deprecated and should not be used in newly-written code.

Use g_object_get_data() instead.

Get the object's user data pointer.

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

Parameters

object

the object.

 

Returns

the user data field for object.


gtk_object_add_arg_type ()

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

gtk_object_add_arg_type is deprecated and should not be used in newly-written code.

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.

Parameters

arg_name

fully qualify object name, for example GtkObject::user_data.

 

arg_type

type of the argument.

 

arg_flags

bitwise-OR of the GtkArgFlags enum. (Whether the argument is settable or gettable, whether it is set when the object is constructed.)

 

arg_id

an internal number, passed in from here to the "set_arg" and "get_arg" handlers of the object.

 

gtk_object_set_data_by_id ()

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

gtk_object_set_data_by_id is deprecated and should not be used in newly-written code.

Use g_object_set_qdata() instead.

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.

Parameters

object

object containing the associations.

 

data_id

quark of the key.

 

data

data to associate with that key.

 

gtk_object_set_data_by_id_full ()

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

gtk_object_set_data_by_id_full is deprecated and should not be used in newly-written code.

Use g_object_set_qdata_full() instead.

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.

Parameters

object

object containing the associations.

 

data_id

quark of the key.

 

data

data to associate with that key.

 

destroy

function to call when the association is destroyed.

 

gtk_object_get_data_by_id ()

gpointer
gtk_object_get_data_by_id (GtkObject *object,
                           GQuark data_id);

gtk_object_get_data_by_id is deprecated and should not be used in newly-written code.

Use g_object_get_qdata() instead.

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.

Parameters

object

object containing the associations.

 

data_id

quark of the key.

 

Returns

the data if found, or NULL if no such data exists.


gtk_object_remove_data_by_id ()

void
gtk_object_remove_data_by_id (GtkObject *object,
                              GQuark data_id);

gtk_object_remove_data_by_id is deprecated and should not be used in newly-written code.

Use g_object_set_qdata() with data of NULL instead.

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.

Parameters

object

object containing the associations.

 

data_id

quark of the key.

 

gtk_object_remove_no_notify_by_id ()

void
gtk_object_remove_no_notify_by_id (GtkObject *object,
                                   GQuark key_id);

gtk_object_remove_no_notify_by_id is deprecated and should not be used in newly-written code.

Use g_object_steal_qdata() instead.

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.

Parameters

object

object containing the associations.

 

key_id

quark of the key.

 

Types and Values

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                   G_OBJECT_TYPE

GTK_OBJECT_TYPE has been deprecated since version 2.20 and should not be used in newly-written code.

Use G_OBJECT_TYPE() instead.

Gets the type of an object.

Parameters

object

a GtkObject.

 

GTK_OBJECT_TYPE_NAME

#define GTK_OBJECT_TYPE_NAME              G_OBJECT_TYPE_NAME

GTK_OBJECT_TYPE_NAME has been deprecated since version 2.20 and should not be used in newly-written code.

Use G_OBJECT_TYPE_NAME() instead.

Gets the name of an object's type.

Parameters

object

a GtkObject.

 

enum GtkObjectFlags

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.

Members

GTK_IN_DESTRUCTION

the object is currently being destroyed. This is used internally by GTK+ to prevent reinvokations during destruction.

 

GTK_FLOATING

   

GTK_RESERVED_1

   

GTK_RESERVED_2

reserved for future use

 

enum GtkArgFlags

GtkArgFlags is deprecated and should not be used in newly-written code.

Use corresponding GParamSpec features instead

Possible flags indicating how an argument should be treated.

Members

GTK_ARG_READABLE

the argument is readable. (i.e. can be queried)

 

GTK_ARG_WRITABLE

the argument is writable. (i.e. settable)

 

GTK_ARG_CONSTRUCT

the argument needs construction.

 

GTK_ARG_CONSTRUCT_ONLY

the argument needs construction (and will be set once during object creation), but is otherwise cannot be set. Hence this flag is not allowed with GTK_ARG_WRITABLE, and is redundant with GTK_ARG_CONSTRUCT.

 

GTK_ARG_CHILD_ARG

an argument type that applies to (and may be different for) each child. Used by GtkContainer.

 

gtk_object_data_try_key

#define gtk_object_data_try_key	    g_quark_try_string

gtk_object_data_try_key is deprecated and should not be used in newly-written code.

Useless deprecated macro. Ignore it.


gtk_object_data_force_id

#define gtk_object_data_force_id    g_quark_from_string

gtk_object_data_force_id is deprecated and should not be used in newly-written code.

Useless deprecated macro. Ignore it.

Property Details

The “user-data” property

  “user-data”                gpointer

Anonymous User Data Pointer.

Flags: Read / Write

Signal Details

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.

Parameters

object

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

See Also

GObject

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.