Synopsis#include <glib-object.h> GObject; GObjectClass; GObjectConstructParam; void (*GObjectGetPropertyFunc) (GObject *object, guint property_id, GValue *value, GParamSpec *pspec); void (*GObjectSetPropertyFunc) (GObject *object, guint property_id, const GValue *value, GParamSpec *pspec); void (*GObjectFinalizeFunc) (GObject *object); #define G_TYPE_IS_OBJECT (type) #define G_OBJECT (object) #define G_IS_OBJECT (object) #define G_OBJECT_CLASS (class) #define G_IS_OBJECT_CLASS (class) #define G_OBJECT_GET_CLASS (object) #define G_OBJECT_TYPE (object) #define G_OBJECT_TYPE_NAME (object) #define G_OBJECT_CLASS_TYPE (class) #define G_OBJECT_CLASS_NAME (class) void g_object_class_install_property (GObjectClass *oclass, guint property_id, GParamSpec *pspec); GParamSpec* g_object_class_find_property (GObjectClass *oclass, const gchar *property_name); GParamSpec** g_object_class_list_properties (GObjectClass *oclass, guint *n_properties); void g_object_class_override_property (GObjectClass *oclass, guint property_id, const gchar *name); void g_object_interface_install_property (gpointer g_iface, GParamSpec *pspec); GParamSpec* g_object_interface_find_property (gpointer g_iface, const gchar *property_name); GParamSpec** g_object_interface_list_properties (gpointer g_iface, guint *n_properties_p); gpointer g_object_new (GType object_type, const gchar *first_property_name, ...); gpointer g_object_newv (GType object_type, guint n_parameters, GParameter *parameters); GParameter; gpointer g_object_ref (gpointer object); void g_object_unref (gpointer object); gpointer g_object_ref_sink (gpointer object); typedef GInitiallyUnowned; typedef GInitiallyUnownedClass; #define G_TYPE_INITIALLY_UNOWNED gboolean g_object_is_floating (gpointer object); void g_object_force_floating (GObject *object); void (*GWeakNotify) (gpointer data, GObject *where_the_object_was); void g_object_weak_ref (GObject *object, GWeakNotify notify, gpointer data); void g_object_weak_unref (GObject *object, GWeakNotify notify, gpointer data); void g_object_add_weak_pointer (GObject *object, gpointer *weak_pointer_location); void g_object_remove_weak_pointer (GObject *object, gpointer *weak_pointer_location); void (*GToggleNotify) (gpointer data, GObject *object, gboolean is_last_ref); void g_object_add_toggle_ref (GObject *object, GToggleNotify notify, gpointer data); void g_object_remove_toggle_ref (GObject *object, GToggleNotify notify, gpointer data); gpointer g_object_connect (gpointer object, const gchar *signal_spec, ...); void g_object_disconnect (gpointer object, const gchar *signal_spec, ...); void g_object_set (gpointer object, const gchar *first_property_name, ...); void g_object_get (gpointer object, const gchar *first_property_name, ...); void g_object_notify (GObject *object, const gchar *property_name); void g_object_freeze_notify (GObject *object); void g_object_thaw_notify (GObject *object); gpointer g_object_get_data (GObject *object, const gchar *key); void g_object_set_data (GObject *object, const gchar *key, gpointer data); void g_object_set_data_full (GObject *object, const gchar *key, gpointer data, GDestroyNotify destroy); gpointer g_object_steal_data (GObject *object, const gchar *key); gpointer g_object_get_qdata (GObject *object, GQuark quark); void g_object_set_qdata (GObject *object, GQuark quark, gpointer data); void g_object_set_qdata_full (GObject *object, GQuark quark, gpointer data, GDestroyNotify destroy); gpointer g_object_steal_qdata (GObject *object, GQuark quark); void g_object_set_property (GObject *object, const gchar *property_name, const GValue *value); void g_object_get_property (GObject *object, const gchar *property_name, GValue *value); GObject* g_object_new_valist (GType object_type, const gchar *first_property_name, va_list var_args); void g_object_set_valist (GObject *object, const gchar *first_property_name, va_list var_args); void g_object_get_valist (GObject *object, const gchar *first_property_name, va_list var_args); void g_object_watch_closure (GObject *object, GClosure *closure); void g_object_run_dispose (GObject *object); #define G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec) DescriptionGObject is the fundamental type providing the common attributes and methods for all object types in GTK+, Pango and other libraries based on GObject. The GObject class provides methods for object construction and destruction, property access methods, and signal support. Signals are described in detail in Signals(3).
GInitiallyUnowned is derived from GObject. The only difference between the two is that the initial reference of a GInitiallyUnowned is flagged as a floating reference. This means that it is not specifically claimed to be "owned" by any code portion. The main motivation for providing floating references is C convenience. In particular, it allows code to be written as: container = create_container(); container_add_child (container, create_child());
If Child *child; container = create_container(); child = create_child(); container_add_child (container, child); g_object_unref (child);
The floating reference can be converted into
an ordinary reference by calling
Some object implementations may need to save an objects floating state across certain code portions (an example is GtkMenu), to achive this, the following sequence can be used:
// save floating state gboolean was_floating = g_object_is_floating (object); g_object_ref_sink (object); // protected code portion ...; // restore floating state if (was_floating) g_object_force_floating (object); g_obejct_unref (object); // release previously acquired reference
DetailsGObjecttypedef struct _GObject GObject; All the fields in the GObject structure are private to the GObject implementation and should never be accessed directly.
GObjectClasstypedef struct { GTypeClass g_type_class; /* seldomly overidden */ GObject* (*constructor) (GType type, guint n_construct_properties, GObjectConstructParam *construct_properties); /* overridable methods */ void (*set_property) (GObject *object, guint property_id, const GValue *value, GParamSpec *pspec); void (*get_property) (GObject *object, guint property_id, GValue *value, GParamSpec *pspec); void (*dispose) (GObject *object); void (*finalize) (GObject *object); /* seldomly overidden */ void (*dispatch_properties_changed) (GObject *object, guint n_pspecs, GParamSpec **pspecs); /* signals */ void (*notify) (GObject *object, GParamSpec *pspec); /* called when done constructing */ void (*constructed) (GObject *object); } GObjectClass; The class structure for the GObject type.
Example 1. Implementing singletons using a constructor static MySingleton *the_singleton = NULL; static GObject* my_singleton_constructor (GType type, guint n_construct_params, GObjectConstructParam *construct_params) { GObject *object; if (!the_singleton) { object = G_OBJECT_CLASS (parent_class)->constructor (type, n_construct_params, construct_params); the_singleton = MY_SINGLETON (object); } else object = g_object_ref (G_OBJECT (the_singleton)); return object; }
GObjectConstructParamtypedef struct { GParamSpec *pspec; GValue *value; } GObjectConstructParam;
The GObjectConstructParam struct is an auxiliary
structure used to hand GParamSpec/GValue pairs to the
GObjectGetPropertyFunc ()void (*GObjectGetPropertyFunc) (GObject *object, guint property_id, GValue *value, GParamSpec *pspec);
The type of the
GObjectSetPropertyFunc ()void (*GObjectSetPropertyFunc) (GObject *object, guint property_id, const GValue *value, GParamSpec *pspec);
The type of the
GObjectFinalizeFunc ()void (*GObjectFinalizeFunc) (GObject *object);
The type of the
G_TYPE_IS_OBJECT()#define G_TYPE_IS_OBJECT(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_OBJECT)
Check if the passed in type id is a
G_OBJECT()#define G_OBJECT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject)) Casts a GObject or derived pointer into a (GObject*) pointer. Depending on the current debugging level, this function may invoke certain runtime checks to identify invalid casts.
G_IS_OBJECT()#define G_IS_OBJECT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_OBJECT))
Checks whether a valid GTypeInstance pointer is of type
G_OBJECT_CLASS()#define G_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass)) Casts a derived GObjectClass structure into a GObjectClass structure.
G_IS_OBJECT_CLASS()#define G_IS_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_OBJECT))
Checks whether
G_OBJECT_GET_CLASS()#define G_OBJECT_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_OBJECT, GObjectClass)) Get the class structure associated to a GObject instance.
G_OBJECT_TYPE()#define G_OBJECT_TYPE(object) (G_TYPE_FROM_INSTANCE (object)) Get the type id of an object.
G_OBJECT_TYPE_NAME()#define G_OBJECT_TYPE_NAME(object) (g_type_name (G_OBJECT_TYPE (object))) Get the name of an object's type.
G_OBJECT_CLASS_TYPE()#define G_OBJECT_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class)) Get the type id of a class structure.
G_OBJECT_CLASS_NAME()#define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class))) Return the name of a class structure's type.
g_object_class_install_property ()void g_object_class_install_property (GObjectClass *oclass, guint property_id, GParamSpec *pspec); Installs a new property. This is usually done in the class initializer.
g_object_class_find_property ()GParamSpec* g_object_class_find_property (GObjectClass *oclass, const gchar *property_name); Looks up the GParamSpec for a property of a class.
g_object_class_list_properties ()GParamSpec** g_object_class_list_properties (GObjectClass *oclass, guint *n_properties); Get an array of GParamSpec* for all properties of a class.
g_object_class_override_property ()void g_object_class_override_property (GObjectClass *oclass, guint property_id, const gchar *name);
Registers
NoteInternally, overriding is implemented by creating a property of type GParamSpecOverride; generally operations that query the properties of the object class, such asg_object_class_find_property() or
g_object_class_list_properties() will return the overridden
property. However, in one case, the construct_properties argument of
the constructor virtual function, the GParamSpecOverride is passed
instead, so that the param_id field of the GParamSpec will be
correct. For virtually all uses, this makes no difference. If you
need to get the overridden property, you can call
g_param_spec_get_redirect_target() .
Since 2.4 g_object_interface_install_property ()void g_object_interface_install_property (gpointer g_iface, GParamSpec *pspec);
Add a property to an interface; this is only useful for interfaces
that are added to GObject-derived types. Adding a property to an
interface forces all objects classes with that interface to have a
compatible property. The compatible property could be a newly
created GParamSpec, but normally
This function is meant to be called from the interface's default
vtable initialization function (the
Since 2.4 g_object_interface_find_property ()GParamSpec* g_object_interface_find_property (gpointer g_iface, const gchar *property_name);
Find the GParamSpec with the given name for an
interface. Generally, the interface vtable passed in as
Since 2.4 g_object_interface_list_properties ()GParamSpec** g_object_interface_list_properties (gpointer g_iface, guint *n_properties_p);
Lists the properties of an interface.Generally, the interface
vtable passed in as
Since 2.4 g_object_new ()gpointer g_object_new (GType object_type, const gchar *first_property_name, ...); Creates a new instance of a GObject subtype and sets its properties. Construction parameters (see G_PARAM_CONSTRUCT, G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.
g_object_newv ()gpointer g_object_newv (GType object_type, guint n_parameters, GParameter *parameters); Creates a new instance of a GObject subtype and sets its properties. Construction parameters (see G_PARAM_CONSTRUCT, G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.
GParametertypedef struct { const gchar *name; GValue value; } GParameter;
The GParameter struct is an auxiliary structure used
to hand parameter name/value pairs to
g_object_ref ()gpointer g_object_ref (gpointer object);
Increases the reference count of
g_object_unref ()void g_object_unref (gpointer object);
Decreases the reference count of
g_object_ref_sink ()gpointer g_object_ref_sink (gpointer object);
Increase the reference count of In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since 2.10 GInitiallyUnownedtypedef struct _GObject GInitiallyUnowned; All the fields in the GInitiallyUnowned structure are private to the GInitiallyUnowned implementation and should never be accessed directly.
GInitiallyUnownedClasstypedef struct _GObjectClass GInitiallyUnownedClass; The class structure for the GInitiallyUnowned type.
G_TYPE_INITIALLY_UNOWNED#define G_TYPE_INITIALLY_UNOWNED (g_initially_unowned_get_type()) The type for GInitiallyUnowned.
g_object_is_floating ()gboolean g_object_is_floating (gpointer object);
Checks wether
Since 2.10 g_object_force_floating ()void g_object_force_floating (GObject *object);
This function is intended for GObject implementations to re-enforce a
floating object reference.
Doing this is seldomly required, all
GInitiallyUnowneds are created with a floating reference which
usually just needs to be sunken by calling
Since 2.10 GWeakNotify ()void (*GWeakNotify) (gpointer data, GObject *where_the_object_was); A GWeakNotify function can be added to an object as a callback that gets triggered when the object is finalized. Since the object is already being finalized when the GWeakNotify is called, there's not much you could do with the object, apart from e.g. using its adress as hash-index or the like.
g_object_weak_ref ()void g_object_weak_ref (GObject *object, GWeakNotify 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_weak_unref ()void g_object_weak_unref (GObject *object, GWeakNotify notify, gpointer data); Removes a weak reference callback to an object.
g_object_add_weak_pointer ()void g_object_add_weak_pointer (GObject *object, gpointer *weak_pointer_location);
Adds a weak reference from weak_pointer to
g_object_remove_weak_pointer ()void g_object_remove_weak_pointer (GObject *object, gpointer *weak_pointer_location);
Removes a weak reference from
GToggleNotify ()void (*GToggleNotify) (gpointer data, GObject *object, gboolean is_last_ref);
A callback function used for notification when the state
of a toggle reference changes. See
g_object_add_toggle_ref ()void g_object_add_toggle_ref (GObject *object, GToggleNotify notify, gpointer data); Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established.
This functionality is intended for binding
The setup is that when there are no other references to
Since a (normal) reference must be held to the object before
calling Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed. For this reason, you should only ever use a toggle reference if there is important state in the proxy object.
Since 2.8 g_object_remove_toggle_ref ()void g_object_remove_toggle_ref (GObject *object, GToggleNotify notify, gpointer data);
Removes a reference added with
Since 2.8 g_object_connect ()gpointer g_object_connect (gpointer object, const gchar *signal_spec, ...); A convenience function to connect multiple signals at once. The signal specs expected by this function have the form "modifier::signal_name", where modifier can be one of the following:
menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, "type", GTK_WINDOW_POPUP, "child", menu, NULL), "signal::event", gtk_menu_window_event, menu, "signal::size_request", gtk_menu_window_size_request, menu, "signal::destroy", gtk_widget_destroyed, &menu->toplevel, NULL);
g_object_disconnect ()void g_object_disconnect (gpointer object, const gchar *signal_spec, ...); A convenience function to disconnect multiple signals at once. The signal specs expected by this function have the form "any_signal", which means to disconnect any signal with matching callback and data, or "any_signal::signal_name", which only disconnects the signal named "signal_name".
g_object_set ()void g_object_set (gpointer object, const gchar *first_property_name, ...); Sets properties on an object.
g_object_get ()void g_object_get (gpointer object, const gchar *first_property_name, ...); Gets properties of an object.
In general, a copy is made of the property contents and the caller
is responsible for freeing the memory in the appropriate manner for
the type, for instance by calling
Example 2. Using g_object_get()
An example of using
g_object_get() to get the contents
of three properties - one of type G_TYPE_INT,
one of type G_TYPE_STRING, and one of type ""gint intval; gchar *strval; GObject *objval; g_object_get (my_object, "int-property", &intval, "str-property", &strval, "obj-property", &objval, NULL); // Do something with intval, strval, objval g_free (strval); g_object_unref (objval);
g_object_notify ()void g_object_notify (GObject *object, const gchar *property_name);
Emits a "notify" signal for the property
g_object_freeze_notify ()void g_object_freeze_notify (GObject *object);
Increases the freeze count on This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
g_object_thaw_notify ()void g_object_thaw_notify (GObject *object);
Reverts the effect of a previous call to
It is an error to call this function when the freeze count is zero.
g_object_get_data ()gpointer g_object_get_data (GObject *object, const gchar *key);
Gets a named field from the objects table of associations (see
g_object_set_data ()void g_object_set_data (GObject *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.
g_object_set_data_full ()void g_object_set_data_full (GObject *object, const gchar *key, gpointer data, GDestroyNotify destroy);
Like
Note that the
g_object_steal_data ()gpointer g_object_steal_data (GObject *object, const gchar *key); Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
g_object_get_qdata ()gpointer g_object_get_qdata (GObject *object, GQuark quark);
This function gets back user data pointers stored via
g_object_set_qdata ()void g_object_set_qdata (GObject *object, GQuark quark, gpointer data);
This sets an opaque, named pointer on an object.
The name is specified through a GQuark (retrived e.g. via
g_object_set_qdata_full ()void g_object_set_qdata_full (GObject *object, GQuark quark, gpointer data, GDestroyNotify destroy);
This function works like
g_object_steal_qdata ()gpointer g_object_steal_qdata (GObject *object, GQuark quark);
This function gets back user data pointers stored via
void object_add_to_user_list (GObject *object, const gchar *new_string) { // the quark, naming the object data GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); // retrive the old string list GList *list = g_object_steal_qdata (object, quark_string_list); // prepend new string list = g_list_prepend (list, g_strdup (new_string)); // this changed 'list', so we need to set it again g_object_set_qdata_full (object, quark_string_list, list, free_string_list); } static void free_string_list (gpointer data) { GList *node, *list = data; for (node = list; node; node = node->next) g_free (node->data); g_list_free (list); }
Using
g_object_set_property ()void g_object_set_property (GObject *object, const gchar *property_name, const GValue *value); Sets a property on an object.
g_object_get_property ()void g_object_get_property (GObject *object, const gchar *property_name, GValue *value); Gets a property of an object.
In general, a copy is made of the property contents and the caller is
responsible for freeing the memory by calling
Note that
g_object_new_valist ()GObject* g_object_new_valist (GType object_type, const gchar *first_property_name, va_list var_args); Creates a new instance of a GObject subtype and sets its properties. Construction parameters (see G_PARAM_CONSTRUCT, G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.
g_object_set_valist ()void g_object_set_valist (GObject *object, const gchar *first_property_name, va_list var_args); Sets properties on an object.
g_object_get_valist ()void g_object_get_valist (GObject *object, const gchar *first_property_name, va_list var_args); Gets properties of an object.
In general, a copy is made of the property contents and the caller
is responsible for freeing the memory in the appropriate manner for
the type, for instance by calling
See
g_object_watch_closure ()void g_object_watch_closure (GObject *object, GClosure *closure);
This function essentially limits the life time of the
g_object_run_dispose ()void g_object_run_dispose (GObject *object); Releases all references to other objects. This can be used to break reference cycles. This functions should only be called from object system implementations.
G_OBJECT_WARN_INVALID_PROPERTY_ID()#define G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec)
This macro should be used to emit a standard warning about unexpected
properties in
Signal DetailsThe
|
|
the GParamSpec of the property which changed |
|
the object which received the signal. |
|
user data set when the signal handler was connected. |