GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkObject

## Name

GtkObject -- The base class of the Gtk type hierarchy.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkObject;
    #define     GTK_OBJECT_TYPE                 (obj)
    #define     GTK_OBJECT_SIGNALS              (obj)
    #define     GTK_OBJECT_NSIGNALS             (obj)
    enum        GtkObjectFlags;
    #define     GTK_OBJECT_FLAGS                (obj)
    #define     GTK_OBJECT_DESTROYED            (obj)
    #define     GTK_OBJECT_FLOATING             (obj)
    #define     GTK_OBJECT_CONNECTED            (obj)
    #define     GTK_OBJECT_CONSTRUCTED          (obj)
    #define     GTK_OBJECT_SET_FLAGS            (obj,flag)
    #define     GTK_OBJECT_UNSET_FLAGS          (obj,flag)
    enum        GtkArgFlags;
    guint       gtk_object_class_user_signal_new
                                                (GtkObjectClass *klass,
                                                 const gchar *name,
                                                 GtkSignalRunType signal_flags,
                                                 GtkSignalMarshaller marshaller,
                                                 GtkType return_val,
                                                 guint nparams,
                                                 ...);
    guint       gtk_object_class_user_signal_newv
                                                (GtkObjectClass *klass,
                                                 const gchar *name,
                                                 GtkSignalRunType signal_flags,
                                                 GtkSignalMarshaller marshaller,
                                                 GtkType return_val,
                                                 guint nparams,
                                                 GtkType *params);
    GtkObject*  gtk_object_new                  (GtkType type,
                                                 const gchar *first_arg_name,
                                                 ...);
    GtkObject*  gtk_object_newv                 (GtkType object_type,
                                                 guint n_args,
                                                 GtkArg *args);
    void        gtk_object_constructed          (GtkObject *object);
    void        gtk_object_default_construct    (GtkObject *object);
    void        gtk_object_sink                 (GtkObject *object);
    void        gtk_object_ref                  (GtkObject *object);
    void        gtk_object_unref                (GtkObject *object);
    void        gtk_object_weakref              (GtkObject *object,
                                                 GtkDestroyNotify notify,
                                                 gpointer data);
    void        gtk_object_weakunref            (GtkObject *object,
                                                 GtkDestroyNotify notify,
                                                 gpointer data);
    void        gtk_object_destroy              (GtkObject *object);
    void        gtk_object_getv                 (GtkObject *object,
                                                 guint n_args,
                                                 GtkArg *args);
    void        gtk_object_set                  (GtkObject *object,
                                                 const gchar *first_arg_name,
                                                 ...);
    void        gtk_object_setv                 (GtkObject *object,
                                                 guint n_args,
                                                 GtkArg *args);
    GtkArg*     gtk_object_query_args           (GtkType class_type,
                                                 guint32 **arg_flags,
                                                 guint *n_args);
    void        gtk_object_set_data             (GtkObject *object,
                                                 const gchar *key,
                                                 gpointer data);
    void        gtk_object_set_data_full        (GtkObject *object,
                                                 const gchar *key,
                                                 gpointer data,
                                                 GtkDestroyNotify destroy);
    void        gtk_object_remove_data          (GtkObject *object,
                                                 const gchar *key);
    gpointer    gtk_object_get_data             (GtkObject *object,
                                                 const gchar *key);
    void        gtk_object_remove_no_notify     (GtkObject *object,
                                                 const gchar *key);
    void        gtk_object_set_user_data        (GtkObject *object,
                                                 gpointer data);
    gpointer    gtk_object_get_user_data        (GtkObject *object);
    void        gtk_object_class_add_signals    (GtkObjectClass *klass,
                                                 guint *signals,
                                                 guint nsignals);
    void        gtk_object_add_arg_type         (const gchar *arg_name,
                                                 GtkType arg_type,
                                                 guint arg_flags,
                                                 guint arg_id);
    void        gtk_object_set_data_by_id       (GtkObject *object,
                                                 GQuark data_id,
                                                 gpointer data);
    void        gtk_object_set_data_by_id_full  (GtkObject *object,
                                                 GQuark data_id,
                                                 gpointer data,
                                                 GtkDestroyNotify destroy);
    gpointer    gtk_object_get_data_by_id       (GtkObject *object,
                                                 GQuark data_id);
    void        gtk_object_remove_data_by_id    (GtkObject *object,
                                                 GQuark data_id);
    void        gtk_object_remove_no_notify_by_id
                                                (GtkObject *object,
                                                 GQuark key_id);
    #define     gtk_object_data_try_key
    #define     gtk_object_data_force_id
    void        gtk_object_arg_set              (GtkObject *object,
                                                 GtkArg *arg,
                                                 GtkArgInfo *info);
    void        gtk_object_arg_get              (GtkObject *object,
                                                 GtkArg *arg,
                                                 GtkArgInfo *info);
    gchar*      gtk_object_args_collect         (GtkType object_type,
                                                 GSList **arg_list_p,
                                                 GSList **info_list_p,
                                                 const gchar *first_arg_name,
                                                 va_list var_args);
    gchar*      gtk_object_arg_get_info         (GtkType object_type,
                                                 const gchar *arg_name,
                                                 GtkArgInfo **info_p);
    void        gtk_trace_referencing           (GtkObject *object,
                                                 const gchar *func,
                                                 guint dummy,
                                                 guint line,
                                                 gboolean do_ref);

## Object Hierarchy

      GtkObject

## Args

      "user_data"            gpointer             : Read / Write
      "signal"               GtkSignalFunc, gpointer : Write
      "signal_after"         GtkSignalFunc, gpointer : Write
      "object_signal"        GtkSignalFunc, gpointer : Write
      "object_signal_after"  GtkSignalFunc, gpointer : Write

## Signal Prototypes

    "destroy"   void        user_function      (GtkObject *object,
                                                gpointer user_data);

## Description

GtkObject is the root of the gtk+ type hierarchy. It serves a similar roles as java's Object class. It is used by the type-casting system to represent the base composite type.

Objects have arguments that are name/typed-value pairs. They may be readable or writable (or both or neither). The special handlers in every object are responsible for setting and getting these parameters. If the handler for a given argument must be called before the object may be used, be sure the GTK_ARG_CONSTRUCT or GTK_ARG_CONSTRUCT_ONLY flags are set; otherwise they are set only when the user does so.

Object also store a simpler association table, sometimes called the object_data. This is just an efficient mapping from a fixed set of strings to a gpointer. This can be used as arbitrary extra members. Notice that each new field name allocates a new quark, so it is probably best only to use this for fields with fixed names.

The primary difference between object_data and arguments is that the object defines two functions which set and get each type of argument. The object just has a table to store its object data in: it does not receive notice when data changes.

Objects are reference counted; this means that we maintain a count of how many references (usually in the form of a pointer) are being held to this object. To indicate that you reference an object, call gtk_object_ref(). The object will not be freed until everyone calls gtk_object_unref().

In order to reduce the chances of a memory leak, gtk+ defines "floating objects". All objects created with gtk_object_new() start out floating with a reference count of 1. In order to reduce that initial reference count you should gtk_object_sink() them, but usually the parent widget you add the child to will sink the object.

So, because gtk_widget_set_parent() sinks the object from gtk_container_add(), there are no memory leaks in this code:

    	button = gtk_button_new_with_label("Hi Mom!");
    	gtk_container_add(GTK_CONTAINER(window), button);
    	/* Button may not be used anymore since we don't retain a reference
    	 * to it. */

Likewise, the following code attaches the same adjustment to two ranges:

    	adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
    	gtk_range_set_adjustment(range1, adjustment);
    	gtk_range_set_adjustment(range2, adjustment);

Note that we could put as many set_adjustments as we like: cleanup is easy because they all retain a reference but only one sinks the initial reference count. If it is possible for "range1" to stop retaining its reference then we need to enclose the lines using "adjustment" with ref/unref to guarantee the the object won't be deleted:

    	adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
    	gtk_object_ref(GTK_OBJECT(adjustment));
    	gtk_range_set_adjustment(range1, adjustment);
    	gtk_range_set_adjustment(range1, another_adjustment);
    	/* With the initial reference, `adjustment' would have
    	 * been deleted as `range1' lost its reference to it. */
    	gtk_range_set_adjustment(range2, adjustment);
    	gtk_object_unref(GTK_OBJECT(adjustment));

Be careful with reference counting: if two objects reference eachother then they will always have at least reference count 1, even if there are no other pointers to them. This means that they will never be freed. More precisely, you must be certain that your references never can form cycles.

If you find yourself forming cyclic references, perhaps you can convert some of them to weak-references. A weak-reference is one that holds a pointer to an object, but doesn't increase the reference count. To insure the object is valid when the referer tries to use it, the referer registers a callback that will be invoked after the object has been destroyed (but before its memory is actually deallocated). This callback must prevent the weak-reference from being used again.

### Brief Glossary

argument

  A typed-variable identified by ObjectType::argument_name. It may be readable, writable, both or none. For example, "GtkButton::label" is a read/write string-valued argument.

constructed

destroyed

finalization

floating

object data

reference count

weak-reference

## Details

### struct GtkObject

    struct GtkObject;

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

### GTK_OBJECT_TYPE()

    #define GTK_OBJECT_TYPE(obj)		  (GTK_OBJECT (obj)->klass->type)

Get the type of an object.

`obj` : | the object whose type we wish to get.

### GTK_OBJECT_SIGNALS()

    #define GTK_OBJECT_SIGNALS(obj)		  (GTK_OBJECT (obj)->klass->signals)

Get the array of signals defined for this object.

`obj` : | the object to fetch the signals from.

### GTK_OBJECT_NSIGNALS()

    #define GTK_OBJECT_NSIGNALS(obj)	  (GTK_OBJECT (obj)->klass->nsignals)

Get the number of signals defined by this object.

`obj` : | the object to query.

### enum GtkObjectFlags

    typedef enum
    {
      GTK_DESTROYED		= 1 << 0,
      GTK_FLOATING		= 1 << 1,
      GTK_CONNECTED		= 1 << 2,
      GTK_CONSTRUCTED	= 1 << 3
    } GtkObjectFlags;

Tells about the state of the object.

`GTK_DESTROYED` | the GtkObject has had gtk_object_destroyed() invoked on it and is processing the shutdown callback.
`GTK_FLOATING` | whether the object is orphaned. Objects that take strong hold of an object may gtk_object_sink() it, after obtaining there own references, if they believe they are nearly primary ownership of the object. GTK_CONNECTED: refers to whether are signals are connected to this object.
`GTK_CONNECTED` |
`GTK_CONSTRUCTED` | refers to whether the arguments for this object are ready.

### GTK_OBJECT_FLAGS()

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

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

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

### GTK_OBJECT_DESTROYED()

    #define GTK_OBJECT_DESTROYED(obj)	  ((GTK_OBJECT_FLAGS (obj) & GTK_DESTROYED) != 0)

Test whether a GtkObject has had gtk_object_destroyed() invoked on it.

`obj` : | the object to examine.

### GTK_OBJECT_FLOATING()

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

When an object is created, it has an initial reference count of 1 and is floating. Sinking the object refers to decrementing that original reference count.

`obj` : | the object to examine.

### GTK_OBJECT_CONNECTED()

    #define GTK_OBJECT_CONNECTED(obj)	  ((GTK_OBJECT_FLAGS (obj) & GTK_CONNECTED) != 0)

Test whether a GtkObject has had a signal connected to it.

`obj` : | the object to examine.

### GTK_OBJECT_CONSTRUCTED()

    #define GTK_OBJECT_CONSTRUCTED(obj)	  ((GTK_OBJECT_FLAGS (obj) & GTK_CONSTRUCTED) != 0)

Test whether a GtkObject's arguments have been prepared.

`obj` : | the object to examine.

### GTK_OBJECT_SET_FLAGS()

    #define GTK_OBJECT_SET_FLAGS(obj,flag)	  G_STMT_START{ (GTK_OBJECT_FLAGS (obj) |= (flag)); }G_STMT_END

Turn on certain object flags. (Private)

`obj` : | the object to affect.
`flag` : | the flags to set.

### GTK_OBJECT_UNSET_FLAGS()

    #define GTK_OBJECT_UNSET_FLAGS(obj,flag)  G_STMT_START{ (GTK_OBJECT_FLAGS (obj) &= ~(flag)); }G_STMT_END

Turn off certain object flags. (Private)

`obj` : | the object to affect.
`flag` : | the flags to unset.

### enum GtkArgFlags

    typedef enum
    {
      GTK_ARG_READABLE	 = 1 << 0,
      GTK_ARG_WRITABLE	 = 1 << 1,
      GTK_ARG_CONSTRUCT	 = 1 << 2,
      GTK_ARG_CONSTRUCT_ONLY = 1 << 3,
      GTK_ARG_CHILD_ARG	 = 1 << 4,
      GTK_ARG_MASK		 = 0x1f,

      /* aliases
       */
      GTK_ARG_READWRITE	 = GTK_ARG_READABLE | GTK_ARG_WRITABLE
    } GtkArgFlags;

Possible flags indicating how an argument should be treated.

`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_ARG_MASK` | the bitwise-OR of all the flags.
`GTK_ARG_READWRITE` | the argument is readable and writable.

### gtk_object_class_user_signal_new ()

    guint       gtk_object_class_user_signal_new
                                                (GtkObjectClass *klass,
                                                 const gchar *name,
                                                 GtkSignalRunType signal_flags,
                                                 GtkSignalMarshaller marshaller,
                                                 GtkType return_val,
                                                 guint nparams,
                                                 ...);

Define a signal-handler for a new signal on an already defined object.

See the signal documentation for more general information.

`klass` : | the object class to define the signal for.
`name` : | the name of the signal.
`signal_flags` : | the default emission behavior for the signal. See gtk_signal_new().
`marshaller` : | a function that will take an array of GtkArgs and invoke the appropriate handler with the normal calling conventions.
`return_val` : | specify the return-value type for the signal (or GTK_TYPE_NONE for no return-value).
`nparams` : | specify the number of parameters the signal receives from the caller of gtk_signal_emit().
`...` : | list of nparams GtkTypes to pass to the signal handlers.
Returns : | the signal id. (See GtkSignals)

### gtk_object_class_user_signal_newv ()

    guint       gtk_object_class_user_signal_newv
                                                (GtkObjectClass *klass,
                                                 const gchar *name,
                                                 GtkSignalRunType signal_flags,
                                                 GtkSignalMarshaller marshaller,
                                                 GtkType return_val,
                                                 guint nparams,
                                                 GtkType *params);

Define a signal-handler for a new signal on an already defined object.

`klass` : | the object class to define the signal for.
`name` : | the name of the signal.
`signal_flags` : | the default emission behavior for the signal. See gtk_signal_new().
`marshaller` : | takes a GtkObject, a GtkSignalFunc, and an array of arguments, and invokes the function using the appropriate calling conventions. Usually just select a function out of gtkmarshal.h.
`return_val` : | specify the return-value type for the signal (possibly GTK_TYPE_NONE).
`nparams` : | specify the number of parameters the signal receives from the caller of gtk_signal_emit().
`params` : | array of GtkTypes the signal handlers for this signal should have in their prototype (of length nparams).
Returns : | the signal id. (See GtkSignals)

### gtk_object_new ()

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

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

`type` : | the type identifying this object. Returned by gtk_type_unique() although (for a properly-written object it should be accessible through GTK_TYPE_FOO.)
`first_arg_name` : | name of the first argument to set when constructing the object.
`...` : | the first argument's value, followed by any number of name/argument-value pairs, terminated with NULL.
Returns : | the new GtkObject.

### gtk_object_newv ()

    GtkObject*  gtk_object_newv                 (GtkType object_type,
                                                 guint n_args,
                                                 GtkArg *args);

Construct an object with an array of arguments.

`object_type` : | the type of the object to create.
`n_args` : | the number of arguments to set.
`args` : | an array of n_args arguments (which are name and value pairs).
Returns : | the new GtkObject.

### gtk_object_constructed ()

    void        gtk_object_constructed          (GtkObject *object);

Mark an allocated object as constructed. This is used for situations that require precise control of the construction process.

This is done when gtk_object_default_construct() is inadequate. In GtkCList the need arises because GtkCList does construction work that must happen after its derivers. This work cannot be done in an initializer function, so an alternate constructor is mandatory. It calls gtk_object_constructed() to indicate it has done its job, so that no other constructor will be invoked.

Normally this function is just automatically run from gtk_object_default_construct().

`object` : | object which has been constructed. This is usually done automatically by gtk_object_new() and gtk_object_newv().

### gtk_object_default_construct ()

    void        gtk_object_default_construct    (GtkObject *object);

This function is called to construct arguments that haven't been initialized but have the GTK_ARG_CONSTRUCT flag set.

All number arguments are set to 0. All pointers and strings are set to NULL.

Normally invoked by gtk_object_new() automatically; gtk_type_new() can be used to bypass it.

`object` : | the object to initialize.

### gtk_object_sink ()

    void        gtk_object_sink                 (GtkObject *object);

Decrement the initial count given to the object. Additional invocations have no effect.

This is designed to free the user from worrying about dereferencing an object that they have just created. So long as the object is sunk at some point, the reference count will be set properly.

furthermore it may be sunk multiple times. Only the first time will actually dereference.

The basic outline is: when you create an object it is floating. Setting its parent causes it to be sunk, however its parent has obtained a reference, so its reference count is one.

`object` : | the object to sink.

### gtk_object_ref ()

    void        gtk_object_ref                  (GtkObject *object);

Increase the reference count of the object.

`object` : | the object to reference.

### gtk_object_unref ()

    void        gtk_object_unref                (GtkObject *object);

Decrease the reference count of an object. When its reference count drops to 0, the object is deleted.

If it was not already destroyed, it will be, with gtk_object_destroy(), then weak links are notified, then the object-data is freed and the memory for the object itself is freed using gtk_type_free().

`object` : | the object to dereference.

### gtk_object_weakref ()

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

Adds a weak reference callback to an object.

Weak references are a mechanism to safely keep a pointer to an object without using the reference counting mechansim. They use a callback function to receive notice that the object is about to be freed (aka finalized). This happens after the destroy callback has been run.

`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,
                                                 GtkDestroyNotify notify,
                                                 gpointer data);

Removes a weak reference callback to an object.

`object` : | object stop weakly referencing.
`notify` : | callback to search for.
`data` : | data to search for.

### gtk_object_destroy ()

    void        gtk_object_destroy              (GtkObject *object);

Calls the object's shutdown handler.

The memory for the object itself won't be deleted until its reference count drops to 0, though. See gtk_object_unref().

`object` : | the object to destroy.

### gtk_object_getv ()

    void        gtk_object_getv                 (GtkObject *object,
                                                 guint n_args,
                                                 GtkArg *args);

Gets an array of argument values from an object.

`object` : | the object to get arguments from.
`n_args` : | the number of arguments to query.
`args` : | the arguments to fill in.

### gtk_object_set ()

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

This function sets multiple arguments of an object.

It takes an object, then a list of name/value pairs in a list, followed by NULL.

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

`object` : | the object whose arguments should be set.
`first_arg_name` : | the name of the first argument to set.
`...` : | the value of the first argument, followed optionally by more name/value pairs, followed by NULL.

### gtk_object_setv ()

    void        gtk_object_setv                 (GtkObject *object,
                                                 guint n_args,
                                                 GtkArg *args);

Set an array of arguments.

`object` : | the object whose arguments should be set.
`n_args` : | the number of arguments to set.
`args` : | the desired values, as an array of GtkArgs (which contain the names, types, and values of the arguments).

### gtk_object_query_args ()

    GtkArg*     gtk_object_query_args           (GtkType class_type,
                                                 guint32 **arg_flags,
                                                 guint *n_args);

Get all the arguments that may be used for a given type.

In Java, this type of mechanism is called introspection. It is used by applications like Glade, that have to determine what can be done to an object at run-time.

`class_type` : | the GtkType of the ObjectClass (returned from GTK_OBJECT_CLASS(class)->type for example).
`arg_flags` : | if non-NULL, obtains the GtkArgFlags that apply to each argument. You must g_free() this if you request it.
`n_args` : | the number of arguments is returned in this field.
Returns : | an array of arguments, that you must deallocate with g_free().

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

`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,
                                                 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.

`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);

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

`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);

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

`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);

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

`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);

For convenience, every object offers a generic user data pointer. The function set it.

This function is equivalent to:

    	gtk_object_set_data(object, "user_data", data);

`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);

Get the object's user data pointer.

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

`object` : | the object.
Returns : | the user data field for object.

### gtk_object_class_add_signals ()

    void        gtk_object_class_add_signals    (GtkObjectClass *klass,
                                                 guint *signals,
                                                 guint nsignals);

Add an array of signals to a GtkObjectClass. Usually this is called when registering a new type of object.

`klass` : | the object class to append signals to.
`signals` : | the signals to append.
`nsignals` : | the number of signals being appended.

### gtk_object_add_arg_type ()

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

Add a new type of argument to an object class. Usually this is called when registering a new type of object.

`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);

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.

`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,
                                                 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.

`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);

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.

`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);

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.

`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);

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.

`object` : | object containing the associations.
`data_id` : | quark of the key.

### gtk_object_data_try_key

    #define	gtk_object_data_try_key	    g_quark_try_string

Sees whether a certain quark exists. Returns that quark if so.

Although this is currently the same as g_quark_try_string(), it might someday be different, for example, if GQuarks and object data are converted to separate mechanisms, so it is good to use this macro.

### gtk_object_data_force_id

    #define	gtk_object_data_force_id    g_quark_from_string

Makes a quark from a string, possibly allocating a new quark.

Although this is currently the same as g_quark_from_string(), it might someday be different, for example, if GQuarks and object data are converted to separate mechanisms, so it is good to use this macro.

### gtk_object_arg_set ()

    void        gtk_object_arg_set              (GtkObject *object,
                                                 GtkArg *arg,
                                                 GtkArgInfo *info);

Private function to set an argument and argument info to an object.

`object` : | the object whose argument should be set.
`arg` : | the argument.
`info` : | infomation about this type of argument in general.

### gtk_object_arg_get ()

    void        gtk_object_arg_get              (GtkObject *object,
                                                 GtkArg *arg,
                                                 GtkArgInfo *info);

Private function to get an argument and argument info from an object.

`object` : | the object whose argument should be retrieved.
`arg` : | the argument, for the name on input, the rest is filled on output.
`info` : | a GtkArgInfo structure to optionally fill in.

### gtk_object_args_collect ()

    gchar*      gtk_object_args_collect         (GtkType object_type,
                                                 GSList **arg_list_p,
                                                 GSList **info_list_p,
                                                 const gchar *first_arg_name,
                                                 va_list var_args);

Private: Gets an array of GtkArgs from a va_list C structure.

`object_type` : | the type of object to collect arguments for.
`arg_list_p` : | pointer to be filled in with a list of parsed arguments.
`info_list_p` : | optional pointer for a returned list GtkArgInfos.
`first_arg_name` : | name of first argument.
`var_args` : | value of first argument, followed by more key/value pairs, terminated by NULL.
Returns : | an error message, or NULL on success. It is the caller's responsibility to call g_free() in the event of error.

### gtk_object_arg_get_info ()

    gchar*      gtk_object_arg_get_info         (GtkType object_type,
                                                 const gchar *arg_name,
                                                 GtkArgInfo **info_p);

Query information about an argument type.

`object_type` : | type of object to query about.
`arg_name` : | name of the argument.
`info_p` : | pointer to be filled in with a pointer to the GtkArgInfo.
Returns : | an error message, or NULL on success. It is the caller's responsibility to call g_free() in the event of error.

### gtk_trace_referencing ()

    void        gtk_trace_referencing           (GtkObject *object,
                                                 const gchar *func,
                                                 guint dummy,
                                                 guint line,
                                                 gboolean do_ref);

Private: print debugging information while doing a gtk_object_ref() or a gtk_object_unref().

`object` : | object to reference or unreference.
`func` : | name of caller's function to print (used within macros).
`dummy` : | unused.
`line` : | line number (used within macros).
`do_ref` : | whether to reference or unreference.

## Args

"`user_data`" (gpointer : Read / Write)

  A pointer for convenience when programming applications.

"`signal`" (GtkSignalFunc, gpointer : Write)

  Setting this with a GtkType of GTK_TYPE_SIGNAL connects the signal to the object.

"`signal_after`" (GtkSignalFunc, gpointer : Write)

  Setting this with a GtkType of GTK_TYPE_SIGNAL connects the signal to the object, so that the signal is always run after other user handlers and the default handler.

"`object_signal`" (GtkSignalFunc, gpointer : Write)

  Setting this with a GtkType of GTK_TYPE_SIGNAL connects the signal to the object, so that the user data and objects and swapped when the signal handler is invoked.

  This is useful for handlers that are primarily notifying other objects and could just invoke an already existing function if the parameters were swapped. See gtk_signal_connect_object() for more details.

"`object_signal_after`" (GtkSignalFunc, gpointer : Write)

  Setting this with a GtkType of GTK_TYPE_SIGNAL connects the signal to the object, so that the user data and objects and swapped when the signal handler is invoked, and so that the handler is invoked after all others.

  See gtk_signal_connect_object_after() for more details.

## Signals

### The "destroy" signal

    void        user_function                  (GtkObject *object,
                                                gpointer user_data);

Indicates that an object is being destroyed.

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

## See Also

GtkType, GtkArg, gtk-signals.

<<< Previous Page | Home | Up | Next Page >>>
GtkNotebook | GtkOptionMenu