![]() | ![]() | ![]() | GTK+ Reference Manual | ![]() |
---|
GtkObject — The base class of the GTK+ type hierarchy.
#include <gtk/gtk.h> struct GtkObject; #define GTK_OBJECT_TYPE (object) #define GTK_OBJECT_TYPE_NAME (object) enum GtkObjectFlags; #define GTK_OBJECT_FLAGS (obj) #define GTK_OBJECT_FLOATING (obj) enum GtkArgFlags; GtkObject* gtk_object_new (GtkType type, constgchar *first_property_name, ...); void gtk_object_sink (GtkObject *object); GtkObject* 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_get (GtkObject *object, constgchar *first_property_name, ...); void gtk_object_set (GtkObject *object, constgchar *first_property_name, ...); void gtk_object_set_data (GtkObject *object, constgchar *key,gpointer data); void gtk_object_set_data_full (GtkObject *object, constgchar *key,gpointer data, GtkDestroyNotify destroy); void gtk_object_remove_data (GtkObject *object, constgchar *key);gpointer gtk_object_get_data (GtkObject *object, constgchar *key); void gtk_object_remove_no_notify (GtkObject *object, constgchar *key); void gtk_object_set_user_data (GtkObject *object,gpointer data);gpointer gtk_object_get_user_data (GtkObject *object); void gtk_object_add_arg_type (constgchar *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
GObject +----GtkObject
"user-data"gpointer : Read / Write
GtkObject is the base class for all widgets, and for a few
non-widget objects such as GtkAdjustment. GtkObject predates
The most interesting difference between GtkObject and
g_object_ref (G_OBJECT (child_widget)); gtk_object_sink (GTK_OBJECT (child_widget));
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.
Never call
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
struct GtkObject;
The object itself. You should never use these members directly - use the accessing macros instead.
#define GTK_OBJECT_TYPE(object) (G_TYPE_FROM_INSTANCE (object))
Gets the type of an object.
object : | a GtkObject. |
#define GTK_OBJECT_TYPE_NAME(object) (g_type_name (GTK_OBJECT_TYPE (object)))
Gets the name of an objects type.
object : | a GtkObject. |
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_IN_DESTRUCTION | the object is currently being destroyed. This is used internally by GTK+ to prevent reinvokations during destruction. |
GTK_FLOATING | the object is orphaned. Objects that take strong hold of an object may gtk_object_sink() it, after obtaining their own references, if they believe they are nearly primary ownership of the object. GTK_CONNECTED: signals are connected to this object. |
GTK_RESERVED_1 | reserved for future use |
GTK_RESERVED_2 | reserved for future use |
#define GTK_OBJECT_FLAGS(obj) (GTK_OBJECT (obj)->flags)
Gets the GtkObjectFlags for an object without directly accessing its members.
obj : | the object whose flags are returned. |
#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.
obj : | the object to examine. |
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;
GtkArgFlags is deprecated and should not be used in newly-written code.
Possible flags indicating how an argument should be treated.
Deprecated in favor of
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_CHILD_ARG | an argument type that applies to (and may be different for) each child. Used by GtkContainer. |
GtkObject* gtk_object_new (GtkType type, constgchar *first_property_name, ...);
Constructs an object given its arguments, enumerated in the call to the
function. Deprecated in favor of
type : | the type identifying this object. Returned by gtk_type_unique()
(although for a properly-written object it should be accessible through
a |
first_property_name : | name of the first property 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. |
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.
object : | the object to sink. |
GtkObject* gtk_object_ref (GtkObject *object);
gtk_object_ref is deprecated and should not be used in newly-written code.
Increases the reference count of the object.
Deprecated in favor of
object : | the object to reference. |
Returns : | object. |
void gtk_object_unref (GtkObject *object);
gtk_object_unref is deprecated and should not be used in newly-written code.
Decreases the reference count of an object. When its reference count drops
to 0, the object is finalized (i.e. its memory is freed). Deprecated in
favor of
object : | the object to dereference. |
void gtk_object_weakref (GtkObject *object, GtkDestroyNotify notify,gpointer data);
gtk_object_weakref is deprecated and should not be used in newly-written code.
Adds a weak reference callback to an object. Deprecated in favor of
object : | object to weakly reference. |
notify : | callback to invoke before the object is freed. |
data : | extra data to pass to |
void gtk_object_weakunref (GtkObject *object, GtkDestroyNotify notify,gpointer data);
gtk_object_weakunref is deprecated and should not be used in newly-written code.
Removes a weak reference callback to an object.
object : | object stop weakly referencing. |
notify : | callback to search for. |
data : | data to search for. |
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. |
void gtk_object_get (GtkObject *object, constgchar *first_property_name, ...);
gtk_object_get is deprecated and should not be used in newly-written code.
Gets properties of an object. Deprecated in favor of
object : | a GtkObject. |
first_property_name : | name of first property to get the value for. |
... : | NULL-terminated list of name-return location pairs. |
void gtk_object_set (GtkObject *object, constgchar *first_property_name, ...);
gtk_object_set is deprecated and should not be used in newly-written code.
Sets properties on an object. Deprecated in favor of
void set_box_properties (GtkBox* box) { gtk_object_set (GTK_OBJECT (box), "homogeneous", TRUE, "spacing", 8, NULL); }
object : | a GtkObject. |
first_property_name : | name of the first property to set |
... : | the value of the first argument, followed optionally by more name/value pairs, followed by NULL. |
void gtk_object_set_data (GtkObject *object, constgchar *key,gpointer data);
gtk_object_set_data is deprecated and should not be used in newly-written code.
Deprecated in favor of
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. |
void gtk_object_set_data_full (GtkObject *object, constgchar *key,gpointer data, GtkDestroyNotify destroy);
gtk_object_set_data_full is deprecated and should not be used in newly-written code.
Deprecated in favor of
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. |
void gtk_object_remove_data (GtkObject *object, constgchar *key);
gtk_object_remove_data is deprecated and should not be used in newly-written code.
Deprecated in favor of setting object data to NULL using
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. |
gpointer gtk_object_get_data (GtkObject *object, constgchar *key);
gtk_object_get_data is deprecated and should not be used in newly-written code.
Deprecated in favor of
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. |
void gtk_object_remove_no_notify (GtkObject *object, constgchar *key);
gtk_object_remove_no_notify is deprecated and should not be used in newly-written code.
Deprecated in favor of
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. |
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.
Deprecated in favor of
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. |
gpointer gtk_object_get_user_data (GtkObject *object);
gtk_object_get_user_data is deprecated and should not be used in newly-written code.
Deprecated in favor of
This is intended to be a pointer for your convenience in writing applications.
object : | the object. |
Returns : | the user data field for object. |
void gtk_object_add_arg_type (constgchar *arg_name, GtkType 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
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. |
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.
Deprecated in favor of
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. |
void gtk_object_set_data_by_id_full (GtkObject *object,GQuark data_id,gpointer data, GtkDestroyNotify destroy);
gtk_object_set_data_by_id_full is deprecated and should not be used in newly-written code.
Deprecated in favor of
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. |
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.
Deprecated in favor of
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. |
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.
Deprecated in favor of
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. |
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.
Deprecated in favor of
Use gtk_object_data_try_key() and gtk_object_data_force_id() to get an id from a string.
object : | object containing the associations. |
key_id : | quark of the 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.
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.
object : | the object which received the signal. |
user_data : | user data set when the signal handler was connected. |
<< GtkMisc | GtkPaned >> |