diff --git a/ChangeLog b/ChangeLog index d5bdbab9e..7f71c8195 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2008-06-21 Stefan Kost + + * docs/reference/gobject/tmpl/objects.sgml: + * gobject/gobject.c: + * gobject/gobject.h: + * gobject/gparam.h: + Migrating docs. + 2008-06-21 Stefan Kost * docs/reference/gobject/tmpl/gtypeplugin.sgml: diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml deleted file mode 100644 index 6465e0088..000000000 --- a/docs/reference/gobject/tmpl/objects.sgml +++ /dev/null @@ -1,1111 +0,0 @@ - -GObject - - -The base object type - - - -GObject 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 . - - -#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 container_add_child() will g_object_ref_sink() the -passed in child, no reference of the newly created child is leaked. -Without floating references, container_add_child() -can only g_object_ref() the new child, so to implement this code without -reference leaks, it would have to be written as: - - 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 g_object_ref_sink(). -For already sunken objects (objects that don't have a floating reference -anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns -a new reference. -Since floating references are useful almost exclusively for C convenience, -language bindings that provide automated reference and memory ownership -maintenance (such as smart pointers or garbage collection) therefore don't -need to expose floating references in their API. - - -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 */ - - - - -#GParamSpecObject, g_param_spec_object() - - - - - - - -All the fields in the GObject structure are private -to the #GObject implementation and should never be accessed directly. - - - - - -The notify signal is emitted on an object when one of its properties -has been changed. Note that getting this signal doesn't guarantee that the -value of the property has actually changed, it may also be emitted when -the setter for the property is called to reinstate the previous value. - - -This signal is typically used to obtain change notification for a -single property, by specifying the property name as a detail in the -g_signal_connect() call, like this: - -g_signal_connect (text_view->buffer, "notify::paste-target-list", - G_CALLBACK (gtk_text_view_target_list_notify), - text_view) - -It is important to note that you must use -canonical parameter names as -detail strings for the notify signal. - - -@pspec: the #GParamSpec of the property which changed -@gobject: the object which received the signal. - - - -The class structure for the GObject type. - - -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; -} - - -@g_type_class: the parent class -@constructor: the @constructor function is called by g_object_new () to - complete the object initialization after all the construction properties are - set. The first thing a @constructor implementation must do is chain up to the - @constructor of the parent class. Overriding @constructor should be rarely - needed, e.g. to handle construct properties, or to implement singletons. -@set_property: the generic setter for all properties of this type. Should be - overridden for every type with properties. Implementations of @set_property - don't need to emit property change notification explicitly, this is handled - by the type system. -@get_property: the generic getter for all properties of this type. Should be - overridden for every type with properties. -@dispose: the @dispose function is supposed to drop all references to other - objects, but keep the instance otherwise intact, so that client method - invocations still work. It may be run multiple times (due to reference - loops). Before returning, @dispose should chain up to the @dispose method - of the parent class. -@finalize: instance finalization function, should finish the finalization of - the instance begun in @dispose and chain up to the @finalize method of the - parent class. -@dispatch_properties_changed: emits property change notification for a bunch - of properties. Overriding @dispatch_properties_changed should be rarely - needed. -@notify: the class closure for the notify signal -@constructed: the @constructed function is called by g_object_new() as the - final step of the object creation process. At the point of the call, all - construction properties have been set on the object. The purpose of this - call is to allow for object initialisation steps that can only be performed - after construction properties have been set. @constructed implementors - should chain up to the @constructed call of their parent class to allow it - to complete its initialisation. - - - -The GObjectConstructParam struct is an auxiliary -structure used to hand #GParamSpec/#GValue pairs to the @constructor of -a #GObjectClass. - - -@pspec: the #GParamSpec of the construct parameter -@value: the value to set the parameter to - - - -The type of the @get_property function of #GObjectClass. - - -@object: a #GObject -@property_id: the numeric id under which the property was registered with - g_object_class_install_property(). -@value: a #GValue to return the property value in -@pspec: the #GParamSpec describing the property - - - - -The type of the @set_property function of #GObjectClass. - - -@object: a #GObject -@property_id: the numeric id under which the property was registered with - g_object_class_install_property(). -@value: the new value for the property -@pspec: the #GParamSpec describing the property - - - - -The type of the @finalize function of #GObjectClass. - - -@object: the #GObject being finalized - - - - -Returns a boolean value of %FALSE or %TRUE indicating whether -the passed in type id is a %G_TYPE_OBJECT or derived from it. - - -@type: Type id to check for is a %G_TYPE_OBJECT relationship. -@Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. - - - - -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. - - -@object: Object which is subject to casting. - - - - -Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. - - -@object: Instance to check for being a %G_TYPE_OBJECT. - - - - -Casts a derived #GObjectClass structure into a #GObjectClass structure. - - -@class: a valid #GObjectClass - - - - -Checks whether @class "is a" valid #GObjectClass structure of type -%G_TYPE_OBJECT or derived. - - -@class: a #GObjectClass - - - - -Returns the class structure associated to a #GObject instance. - - -@object: a #GObject instance. - - - - -Return the type id of an object. - - -@object: Object to return the type id for. -@Returns: Type id of @object. - - - - -Returns the name of an object's type. - - -@object: Object to return the type name for. -@Returns: Type name of @object. The string is owned by the type system and -should not be freed. - - - - -Return the type id of a class structure. - - -@class: a valid #GObjectClass -@Returns: Type id of @class. - - - - -Return the name of a class structure's type. - - -@class: a valid #GObjectClass -@Returns: Type name of @class. The string is owned by the type system and -should not be freed. - - - - -Installs a new property. This is usually done in the class initializer. - - -@oclass: a #GObjectClass -@property_id: the id for the new property -@pspec: the #GParamSpec for the new property - - - - -Looks up the #GParamSpec for a property of a class. - - -@oclass: a #GObjectClass -@property_name: the name of the property to look up -@Returns: the #GParamSpec for the property, or %NULL if the class doesn't have -a property of that name - - - - -Returns an array of #GParamSpec* for all properties of a class. - - -@oclass: a #GObjectClass -@n_properties: return location for the length of the returned array -@Returns: an array of #GParamSpec* which should be freed after use - - - - -Registers @property_id as referring to a property with the -name @name in a parent class or in an interface implemented -by @oclass. This allows this class to override -a property implementation in a parent class or to provide -the implementation of a property from an interface. - - - -Internally, overriding is implemented by creating a property of type -#GParamSpecOverride; generally operations that query the properties of -the object class, such as g_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(). - - - -@oclass: a #GObjectClass -@property_id: the new property ID -@name: the name of a property registered in a parent class or - in an interface of this class. -@Since: 2.4 - - - - -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 -g_object_class_override_property() will be used so that the object -class only needs to provide an implementation and inherits the -property description, default value, bounds, and so forth from the -interface property. - - -This function is meant to be called from the interface's default -vtable initialization function (the @class_init member of -#GTypeInfo.) It must not be called after after @class_init has -been called for any object types implementing this interface. - - -@g_iface: any interface vtable for the interface, or the default - vtable for the interface. -@pspec: the #GParamSpec for the new property -@Since: 2.4 - - - - -Find the #GParamSpec with the given name for an -interface. Generally, the interface vtable passed in as @g_iface -will be the default vtable from g_type_default_interface_ref(), or, -if you know the interface has already been loaded, -g_type_default_interface_peek(). - - -@g_iface: any interface vtable for the interface, or the default - vtable for the interface -@property_name: name of a property to lookup. -@Returns: the #GParamSpec for the property of the - interface with the name @property_name, or %NULL - if no such property exists. -@Since: 2.4 - - - - -Lists the properties of an interface.Generally, the interface -vtable passed in as @g_iface will be the default vtable from -g_type_default_interface_ref(), or, if you know the interface has -already been loaded, g_type_default_interface_peek(). - - -@g_iface: any interface vtable for the interface, or the default - vtable for the interface -@n_properties_p: location to store number of properties returned. -@Returns: a pointer to an array of pointers to #GParamSpec structures. - The paramspecs are owned by GLib, but the array should - be freed with g_free() when you are done with it. -@Since: 2.4 - - - - -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. - - -@object_type: the type id of the #GObject subtype to instantiate -@first_property_name: the name of the first property -@Varargs: the value of the first property, followed optionally by more - name/value pairs, followed by %NULL -@Returns: a new instance of @object_type - - - - -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. - - -@object_type: the type id of the #GObject subtype to instantiate -@n_parameters: the length of the @parameters array -@parameters: an array of #GParameter -@Returns: a new instance of @object_type - - - - -The GParameter struct is an auxiliary structure used -to hand parameter name/value pairs to g_object_newv(). - - -@name: the parameter name -@value: the parameter value - - - -Increases the reference count of @object. - - -@object: a #GObject -@Returns: the same @object - - - - -Decreases the reference count of @object. -When its reference count drops to 0, the object is finalized -(i.e. its memory is freed). - - -@object: a #GObject - - - - -Increase the reference count of @object, and possibly remove the -floating reference, if @object -has a floating reference. - - -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. - - -@object: a #GObject -@Returns: @object -@Since: 2.10 - - - - -All the fields in the GInitiallyUnowned structure -are private to the #GInitiallyUnowned implementation and should never be -accessed directly. - - - - - -The class structure for the GInitiallyUnowned type. - - - - - -The type for #GInitiallyUnowned. - - - - - - -Checks wether @object has a floating -reference. - - -@object: a #GObject -@Returns: %TRUE if @object has a floating reference -@Since: 2.10 - - - - -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 g_object_ref_sink(). - - -@object: a #GObject -@Since: 2.10 - - - - -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. - - -@data: data that was provided when the weak reference was established -@where_the_object_was: the object being finalized - - - - -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). - - -@object: #GObject to reference weakly -@notify: callback to invoke before the object is freed -@data: extra data to pass to notify - - - - -Removes a weak reference callback to an object. - - -@object: #GObject to remove a weak reference from -@notify: callback to search for -@data: data to search for - - - - -Adds a weak reference from weak_pointer to @object to indicate that -the pointer located at @weak_pointer_location is only valid during the -lifetime of @object. When the @object is finalized, @weak_pointer will -be set to %NULL. - - -@object: The object that should be weak referenced. -@weak_pointer_location: The memory address of a pointer. - - - - -Removes a weak reference from @object that was previously added -using g_object_add_weak_pointer(). The @weak_pointer_location has -to match the one used with g_object_add_weak_pointer(). - - -@object: The object that is weak referenced. -@weak_pointer_location: The memory address of a pointer. - - - - -A callback function used for notification when the state -of a toggle reference changes. See g_object_add_toggle_ref(). - - -@data: Callback data passed to g_object_add_toggle_ref() -@object: The object on which g_object_add_toggle_ref() was called. -@is_last_ref: %TRUE if the toggle reference is now the - last reference to the object. %FALSE if the toggle - reference was the last reference and there are now other - references. - - - - -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 @object to a proxy -object managed by another memory manager. This is done with two -paired references: the strong reference added by -g_object_add_toggle_ref() and a reverse reference to the proxy -object which is either a strong reference or weak reference. - - -The setup is that when there are no other references to @object, -only a weak reference is held in the reverse direction from @object -to the proxy object, but when there are other references held to -@object, a strong reference is held. The @notify callback is called -when the reference from @object to the proxy object should be -toggled from strong to weak (@is_last_ref -true) or weak to strong (@is_last_ref false). - - -Since a (normal) reference must be held to the object before -calling g_object_toggle_ref(), the initial state of the reverse -link is always strong. - - -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. - - -@object: a #GObject -@notify: a function to call when this reference is the - last reference to the object, or is no longer - the last reference. -@data: data to pass to @notify -@Since: 2.8 - - - - -Removes a reference added with g_object_add_toggle_ref(). The -reference count of the object is decreased by one. - - -@object: a #GObject -@notify: a function to call when this reference is the - last reference to the object, or is no longer - the last reference. -@data: data to pass to @notify -@Since: 2.8 - - - - -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: - - -signal - -equivalent to g_signal_connect_data (..., NULL, 0) - - - -object_signal -object-signal - -equivalent to g_signal_connect_object (..., 0) - - - -swapped_signal -swapped-signal - -equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) - - - -swapped_object_signal -swapped-object-signal - -equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) - - - -signal_after -signal-after - -equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) - - - -object_signal_after -object-signal-after - -equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) - - - -swapped_signal_after -swapped-signal-after - -equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) - - - -swapped_object_signal_after -swapped-object-signal-after - -equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) - - - - - - - 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); - - - -@object: a #GObject -@signal_spec: the spec for the first signal -@Varargs: #GCallback for the first signal, followed by data for the first signal, - followed optionally by more signal spec/callback/data triples, - followed by %NULL -@Returns: @object - - - - -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". - - -@object: a #GObject -@signal_spec: the spec for the first signal -@Varargs: #GCallback for the first signal, followed by data for the first signal, - followed optionally by more signal spec/callback/data triples, - followed by %NULL - - - - -Sets properties on an object. - - -@object: a #GObject -@first_property_name: name of the first property to set -@Varargs: value for the first property, followed optionally by more - name/value pairs, followed by %NULL - - - - -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 g_free() or g_object_unref(). - - -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 #G_TYPE_OBJECT: - - - gint intval; - gchar *strval; - GObject *objval; - - g_object_get (my_object, - "intproperty", &intval, - "strproperty", &strval, - "objproperty", &objval, - NULL); - - /* Do something with intval, strval, objval */ - - g_free (strval); - g_object_unref (objval); - - - -@object: a #GObject -@first_property_name: name of the first property to get -@Varargs: return location for the first property, followed optionally by more - name/return location pairs, followed by %NULL - - - - -Emits a "notify" signal for the property @property_name on @object. - - -@object: a #GObject -@property_name: the name of a property installed on the class of @object. - - - - -Stops emission of "notify" signals on @object. The signals are -queued until g_object_thaw_notify() is called on @object. - - -This is necessary for accessors that modify multiple properties to prevent -premature notification while the object is still being modified. - - -@object: a #GObject - - - - -Reverts the effect of a previous call to g_object_freeze_notify(). -This causes all queued "notify" signals on @object to be emitted. - - -@object: a #GObject - - - - -Gets a named field from the objects table of associations (see g_object_set_data()). - - -@object: #GObject containing the associations -@key: name of the key for that association -@Returns: the data if found, or %NULL if no such data exists. - - - - -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: #GObject containing the associations. -@key: name of the key -@data: data to associate with that key - - - - -Like g_object_set_data() except it adds notification -for when the association is destroyed, either by setting it -to a different value or when the object is destroyed. - - -Note that the @destroy callback is not called if @data is %NULL. - - -@object: #GObject containing the associations -@key: name of the key -@data: data to associate with that key -@destroy: function to call when the association is destroyed - - - - -Remove a specified datum from the object's data associations, -without invoking the association's destroy handler. - - -@object: #GObject containing the associations -@key: name of the key -@Returns: the data if found, or %NULL if no such data exists. - - - - -This function gets back user data pointers stored via -g_object_set_qdata(). - - -@object: The GObject to get a stored user data pointer from -@quark: A #GQuark, naming the user data pointer -@Returns: The user data pointer set, or %NULL - - - - -This sets an opaque, named pointer on an object. -The name is specified through a #GQuark (retrived e.g. via -g_quark_from_static_string()), and the pointer -can be gotten back from the @object with g_object_get_qdata() -until the @object is finalized. -Setting a previously set user data pointer, overrides (frees) -the old pointer set, using #NULL as pointer essentially -removes the data stored. - - -@object: The GObject to set store a user data pointer -@quark: A #GQuark, naming the user data pointer -@data: An opaque user data pointer - - - - -This function works like g_object_set_qdata(), but in addition, -a void (*destroy) (gpointer) function may be specified which is -called with @data as argument when the @object is finalized, or -the data is being overwritten by a call to g_object_set_qdata() -with the same @quark. - - -@object: The GObject to set store a user data pointer -@quark: A #GQuark, naming the user data pointer -@data: An opaque user data pointer -@destroy: Function to invoke with @data as argument, when @data needs to be freed - - - - -This function gets back user data pointers stored via -g_object_set_qdata() and removes the @data from object -without invoking it's destroy() function (if any was -set). -Usually, calling this function is only required to update -user data pointers with a destroy notifier, for example: - -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_get_qdata() in the above example, instead of g_object_steal_qdata() -would have left the destroy function set, and thus the partial string list would -have been freed upon g_object_set_qdata_full(). - - -@object: The GObject to get a stored user data pointer from -@quark: A #GQuark, naming the user data pointer -@Returns: The user data pointer set, or %NULL - - - - -Sets a property on an object. - - -@object: a #GObject -@property_name: the name of the property to set -@value: the 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 g_value_unset(). - - -Note that g_object_get_property() is really intended for language -bindings, g_object_get() is much more convenient for C programming. - - -@object: a #GObject -@property_name: the name of the property to get -@value: return location for the property value - - - - -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. - - -@object_type: the type id of the #GObject subtype to instantiate -@first_property_name: the name of the first property -@var_args: the value of the first property, followed optionally by more - name/value pairs, followed by %NULL -@Returns: a new instance of @object_type - - - - -Sets properties on an object. - - -@object: a #GObject -@first_property_name: name of the first property to set -@var_args: value for the first property, followed optionally by more - name/value pairs, followed by %NULL - - - - -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 g_free() or g_object_unref(). - - -See g_object_get(). - - -@object: a #GObject -@first_property_name: name of the first property to get -@var_args: return location for the first property, followed optionally by more - name/return location pairs, followed by %NULL - - - - -This function essentially limits the life time of the @closure -to the life time of the object. That is, when the object is finalized, -the @closure is invalidated by calling g_closure_invalidate() on it, -in order to prevent invocations of the closure with a finalized -(nonexisting) object. Also, g_object_ref() and g_object_unref() are added -as marshal guards to the @closure, to ensure that an extra reference -count is held on @object during invocation of the @closure. -Usually, this function will be called on closures that use this @object -as closure data. - - -@object: GObject restricting lifetime of @closure -@closure: GClosure to watch - - - - -Releases all references to other objects. This can be used to break -reference cycles. - - -This functions should only be called from object system implementations. - - -@object: a #GObject - - - - -This macro should be used to emit a standard warning about unexpected -properties in set_property() and get_property() implementations. - - -@object: the #GObject on which set_property() or get_property() was called -@property_id: the numeric id of the property -@pspec: the #GParamSpec of the property - - diff --git a/gobject/gobject.c b/gobject/gobject.c index 87f09bcdc..ac6cb77b6 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -16,6 +16,68 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:objects + * @Short_description: The base object type + * @See_also:#GParamSpecObject, g_param_spec_object() + * @Title: The Base Object Type + * + * GObject 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 . + * + * + * #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 container_add_child() will g_object_ref_sink() the + * passed in child, no reference of the newly created child is leaked. + * Without floating references, container_add_child() + * can only g_object_ref() the new child, so to implement this code without + * reference leaks, it would have to be written as: + * |[ + * 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 g_object_ref_sink(). + * For already sunken objects (objects that don't have a floating reference + * anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns + * a new reference. + * Since floating references are useful almost exclusively for C convenience, + * language bindings that provide automated reference and memory ownership + * maintenance (such as smart pointers or garbage collection) therefore don't + * need to expose floating references in their API. + * + * + * 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 + * ]| + */ #include "gobject.h" #include @@ -265,6 +327,28 @@ g_object_do_class_init (GObjectClass *class) class->dispatch_properties_changed = g_object_dispatch_properties_changed; class->notify = NULL; + /** + * GObject::notify: + * @pspec: the #GParamSpec of the property which changed + * @gobject: the object which received the signal. + * + * The notify signal is emitted on an object when one of its properties + * has been changed. Note that getting this signal doesn't guarantee that the + * value of the property has actually changed, it may also be emitted when + * the setter for the property is called to reinstate the previous value. + * + * This signal is typically used to obtain change notification for a + * single property, by specifying the property name as a detail in the + * g_signal_connect() call, like this: + * |[ + * g_signal_connect (text_view->buffer, "notify::paste-target-list", + * G_CALLBACK (gtk_text_view_target_list_notify), + * text_view) + * ]| + * It is important to note that you must use + * canonical parameter names as + * detail strings for the notify signal. + */ gobject_signals[NOTIFY] = g_signal_new (g_intern_static_string ("notify"), G_TYPE_FROM_CLASS (class), @@ -300,6 +384,14 @@ install_property_internal (GType g_type, g_param_spec_pool_insert (pspec_pool, pspec, g_type); } +/** + * g_object_class_install_property: + * @oclass: a #GObjectClass + * @property_id: the id for the new property + * @pspec: the #GParamSpec for the new property + * + * Installs a new property. This is usually done in the class initializer. + */ void g_object_class_install_property (GObjectClass *class, guint property_id, @@ -331,6 +423,29 @@ g_object_class_install_property (GObjectClass *class, class->construct_properties = g_slist_remove (class->construct_properties, pspec); } +/** + * g_object_interface_install_property: + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface. + * @pspec: the #GParamSpec for the new property + * + * 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 + * g_object_class_override_property() will be used so that the object + * class only needs to provide an implementation and inherits the + * property description, default value, bounds, and so forth from the + * interface property. + * + * This function is meant to be called from the interface's default + * vtable initialization function (the @class_init member of + * #GTypeInfo.) It must not be called after after @class_init has + * been called for any object types implementing this interface. + * + * Since: 2.4 + */ void g_object_interface_install_property (gpointer g_iface, GParamSpec *pspec) @@ -345,6 +460,16 @@ g_object_interface_install_property (gpointer g_iface, install_property_internal (iface_class->g_type, 0, pspec); } +/** + * g_object_class_find_property: + * @oclass: a #GObjectClass + * @property_name: the name of the property to look up + * + * Looks up the #GParamSpec for a property of a class. + * + * Returns: the #GParamSpec for the property, or %NULL if the class doesn't have + * a property of that name + */ GParamSpec* g_object_class_find_property (GObjectClass *class, const gchar *property_name) @@ -371,6 +496,23 @@ g_object_class_find_property (GObjectClass *class, return NULL; } +/** + * g_object_interface_find_property: + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface + * @property_name: name of a property to lookup. + * + * Find the #GParamSpec with the given name for an + * interface. Generally, the interface vtable passed in as @g_iface + * will be the default vtable from g_type_default_interface_ref(), or, + * if you know the interface has already been loaded, + * g_type_default_interface_peek(). + * + * Since: 2.4 + * Returns: the #GParamSpec for the property of the + * interface with the name @property_name, or %NULL + * if no such property exists. + */ GParamSpec* g_object_interface_find_property (gpointer g_iface, const gchar *property_name) @@ -386,6 +528,34 @@ g_object_interface_find_property (gpointer g_iface, FALSE); } +/** + * g_object_class_override_property: + * @oclass: a #GObjectClass + * @property_id: the new property ID + * @name: the name of a property registered in a parent class or + * in an interface of this class. + * + * Registers @property_id as referring to a property with the + * name @name in a parent class or in an interface implemented + * by @oclass. This allows this class to override + * a property implementation in a parent class or to provide + * the implementation of a property from an interface. + * + * + * Internally, overriding is implemented by creating a property of type + * #GParamSpecOverride; generally operations that query the properties of + * the object class, such as g_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 + */ void g_object_class_override_property (GObjectClass *oclass, guint property_id, @@ -437,6 +607,15 @@ g_object_class_override_property (GObjectClass *oclass, g_object_class_install_property (oclass, property_id, new); } +/** + * g_object_class_list_properties: + * @oclass: a #GObjectClass + * @n_properties: return location for the length of the returned array + * + * Get an array of #GParamSpec* for all properties of a class. + * + * Returns: an array of #GParamSpec* which should be freed after use + */ GParamSpec** /* free result */ g_object_class_list_properties (GObjectClass *class, guint *n_properties_p) @@ -455,7 +634,23 @@ g_object_class_list_properties (GObjectClass *class, return pspecs; } -GParamSpec** /* free result */ +/** + * g_object_interface_list_properties: + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface + * @n_properties_p: location to store number of properties returned. + * + * Lists the properties of an interface.Generally, the interface + * vtable passed in as @g_iface will be the default vtable from + * g_type_default_interface_ref(), or, if you know the interface has + * already been loaded, g_type_default_interface_peek(). + * + * Since: 2.4 + * Returns: a pointer to an array of pointers to #GParamSpec structures. + * The paramspecs are owned by GLib, but the array should + * be freed with g_free() when you are done with it. + */ +GParamSpec** g_object_interface_list_properties (gpointer g_iface, guint *n_properties_p) { @@ -563,6 +758,15 @@ g_object_dispatch_properties_changed (GObject *object, g_signal_emit (object, gobject_signals[NOTIFY], g_quark_from_string (pspecs[i]->name), pspecs[i]); } +/** + * g_object_run_dispose: + * @object: a #GObject + * + * Releases all references to other objects. This can be used to break + * reference cycles. + * + * This functions should only be called from object system implementations. + */ void g_object_run_dispose (GObject *object) { @@ -574,6 +778,16 @@ g_object_run_dispose (GObject *object) g_object_unref (object); } +/** + * g_object_freeze_notify: + * @object: a #GObject + * + * Stops emission of "notify" signals on @object. The signals are + * queued until g_object_thaw_notify() is called on @object. + * + * This is necessary for accessors that modify multiple properties to prevent + * premature notification while the object is still being modified. + */ void g_object_freeze_notify (GObject *object) { @@ -587,6 +801,13 @@ g_object_freeze_notify (GObject *object) g_object_unref (object); } +/** + * g_object_notify: + * @object: a #GObject + * @property_name: the name of a property installed on the class of @object. + * + * Emits a "notify" signal for the property @property_name on @object. + */ void g_object_notify (GObject *object, const gchar *property_name) @@ -624,6 +845,13 @@ g_object_notify (GObject *object, g_object_unref (object); } +/** + * g_object_thaw_notify: + * @object: a #GObject + * + * Reverts the effect of a previous call to g_object_freeze_notify(). + * This causes all queued "notify" signals on @object to be emitted. + */ void g_object_thaw_notify (GObject *object) { @@ -781,6 +1009,20 @@ object_interface_check_properties (gpointer func_data, g_free (pspecs); } +/** + * g_object_new: + * @object_type: the type id of the #GObject subtype to instantiate + * @first_property_name: the name of the first property + * @...: the value of the first property, followed optionally by more + * name/value pairs, followed by %NULL + * + * 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. + * + * Returns: a new instance of @object_type + */ gpointer g_object_new (GType object_type, const gchar *first_property_name, @@ -830,6 +1072,19 @@ object_in_construction_list (GObject *object) return in_construction; } +/** + * g_object_newv: + * @object_type: the type id of the #GObject subtype to instantiate + * @n_parameters: the length of the @parameters array + * @parameters: an array of #GParameter + * + * 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. + * + * Returns: a new instance of @object_type + */ gpointer g_object_newv (GType object_type, guint n_parameters, @@ -969,6 +1224,20 @@ g_object_newv (GType object_type, return object; } +/** + * g_object_new_valist: + * @object_type: the type id of the #GObject subtype to instantiate + * @first_property_name: the name of the first property + * @var_args: the value of the first property, followed optionally by more + * name/value pairs, followed by %NULL + * + * 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. + * + * Returns: a new instance of @object_type + */ GObject* g_object_new_valist (GType object_type, const gchar *first_property_name, @@ -1069,6 +1338,15 @@ g_object_constructor (GType type, return object; } +/** + * g_object_set_valist: + * @object: a #GObject + * @first_property_name: name of the first property to set + * @var_args: value for the first property, followed optionally by more + * name/value pairs, followed by %NULL + * + * Sets properties on an object. + */ void g_object_set_valist (GObject *object, const gchar *first_property_name, @@ -1137,6 +1415,21 @@ g_object_set_valist (GObject *object, g_object_unref (object); } +/** + * g_object_get_valist: + * @object: a #GObject + * @first_property_name: name of the first property to get + * @var_args: return location for the first property, followed optionally by more + * name/return location pairs, followed by %NULL + * + * 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 g_free() or g_object_unref(). + * + * See g_object_get(). + */ void g_object_get_valist (GObject *object, const gchar *first_property_name, @@ -1198,6 +1491,15 @@ g_object_get_valist (GObject *object, g_object_unref (object); } +/** + * g_object_set: + * @object: a #GObject + * @first_property_name: name of the first property to set + * @...: value for the first property, followed optionally by more + * name/value pairs, followed by %NULL + * + * Sets properties on an object. + */ void g_object_set (gpointer _object, const gchar *first_property_name, @@ -1213,6 +1515,42 @@ g_object_set (gpointer _object, va_end (var_args); } +/** + * g_object_get: + * @object: a #GObject + * @first_property_name: name of the first property to get + * @...: return location for the first property, followed optionally by more + * name/return location pairs, followed by %NULL + * + * 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 g_free() or g_object_unref(). + * + * + * 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 #G_TYPE_OBJECT: + * + * 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); + * + * + */ void g_object_get (gpointer _object, const gchar *first_property_name, @@ -1228,6 +1566,14 @@ g_object_get (gpointer _object, va_end (var_args); } +/** + * g_object_set_property: + * @object: a #GObject + * @property_name: the name of the property to set + * @value: the value + * + * Sets a property on an object. + */ void g_object_set_property (GObject *object, const gchar *property_name, @@ -1267,6 +1613,20 @@ g_object_set_property (GObject *object, g_object_unref (object); } +/** + * g_object_get_property: + * @object: a #GObject + * @property_name: the name of the property to get + * @value: return location for the property 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 g_value_unset(). + * + * Note that g_object_get_property() is really intended for language + * bindings, g_object_get() is much more convenient for C programming. + */ void g_object_get_property (GObject *object, const gchar *property_name, @@ -1330,6 +1690,89 @@ g_object_get_property (GObject *object, g_object_unref (object); } +/** + * g_object_connect: + * @object: a #GObject + * @signal_spec: the spec for the first signal + * @...: #GCallback for the first signal, followed by data for the first signal, + * followed optionally by more signal spec/callback/data triples, + * followed by %NULL + * + * 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: + * + * + * signal + * + * equivalent to g_signal_connect_data (..., NULL, 0) + * + * + * + * object_signal + * object-signal + * + * equivalent to g_signal_connect_object (..., 0) + * + * + * + * swapped_signal + * swapped-signal + * + * equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) + * + * + * + * swapped_object_signal + * swapped-object-signal + * + * equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) + * + * + * + * signal_after + * signal-after + * + * equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) + * + * + * + * object_signal_after + * object-signal-after + * + * equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) + * + * + * + * swapped_signal_after + * swapped-signal-after + * + * equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) + * + * + * + * swapped_object_signal_after + * swapped-object-signal-after + * + * equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) + * + * + * + * + * |[ + * 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); + * ]| + * + * Returns: @object + */ gpointer g_object_connect (gpointer _object, const gchar *signal_spec, @@ -1399,6 +1842,20 @@ g_object_connect (gpointer _object, return object; } +/** + * g_object_disconnect: + * @object: a #GObject + * @signal_spec: the spec for the first signal + * @...: #GCallback for the first signal, followed by data for the first signal, + * followed optionally by more signal spec/callback/data triples, + * followed by %NULL + * + * 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". + */ void g_object_disconnect (gpointer _object, const gchar *signal_spec, @@ -1467,6 +1924,18 @@ weak_refs_notify (gpointer data) g_free (wstack); } +/** + * g_object_weak_ref: + * @object: #GObject to reference weakly + * @notify: callback to invoke before the object is freed + * @data: extra data to pass to notify + * + * 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). + */ void g_object_weak_ref (GObject *object, GWeakNotify notify, @@ -1497,6 +1966,14 @@ g_object_weak_ref (GObject *object, g_datalist_id_set_data_full (&object->qdata, quark_weak_refs, wstack, weak_refs_notify); } +/** + * g_object_weak_unref: + * @object: #GObject to remove a weak reference from + * @notify: callback to search for + * @data: data to search for + * + * Removes a weak reference callback to an object. + */ void g_object_weak_unref (GObject *object, GWeakNotify notify, @@ -1529,6 +2006,16 @@ g_object_weak_unref (GObject *object, g_warning ("%s: couldn't find weak ref %p(%p)", G_STRFUNC, notify, data); } +/** + * g_object_add_weak_pointer: + * @object: The object that should be weak referenced. + * @weak_pointer_location: The memory address of a pointer. + * + * Adds a weak reference from weak_pointer to @object to indicate that + * the pointer located at @weak_pointer_location is only valid during the + * lifetime of @object. When the @object is finalized, @weak_pointer will + * be set to %NULL. + */ void g_object_add_weak_pointer (GObject *object, gpointer *weak_pointer_location) @@ -1541,6 +2028,15 @@ g_object_add_weak_pointer (GObject *object, weak_pointer_location); } +/** + * g_object_remove_weak_pointer: + * @object: The object that is weak referenced. + * @weak_pointer_location: The memory address of a pointer. + * + * Removes a weak reference from @object that was previously added + * using g_object_add_weak_pointer(). The @weak_pointer_location has + * to match the one used with g_object_add_weak_pointer(). + */ void g_object_remove_weak_pointer (GObject *object, gpointer *weak_pointer_location) @@ -1577,6 +2073,16 @@ object_floating_flag_handler (GObject *object, } } +/** + * g_object_is_floating: + * @object: a #GObject + * + * Checks wether @object has a floating + * reference. + * + * Since: 2.10 + * Returns: %TRUE if @object has a floating reference + */ gboolean g_object_is_floating (gpointer _object) { @@ -1585,6 +2091,23 @@ g_object_is_floating (gpointer _object) return floating_flag_handler (object, 0); } +/** + * g_object_ref_sink: + * @object: a #GObject + * + * Increase the reference count of @object, and possibly remove the + * floating reference, if @object + * has a floating reference. + * + * 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 + * Returns: @object + */ gpointer g_object_ref_sink (gpointer _object) { @@ -1599,6 +2122,18 @@ g_object_ref_sink (gpointer _object) return object; } +/** + * g_object_force_floating: + * @object: a #GObject + * + * 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 g_object_ref_sink(). + * + * Since: 2.10 + */ void g_object_force_floating (GObject *object) { @@ -1631,6 +2166,45 @@ toggle_refs_notify (GObject *object, tstack->toggle_refs[0].notify (tstack->toggle_refs[0].data, tstack->object, is_last_ref); } +/** + * g_object_add_toggle_ref: + * @object: a #GObject + * @notify: a function to call when this reference is the + * last reference to the object, or is no longer + * the last reference. + * @data: data to pass to @notify + * + * 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 @object to a proxy + * object managed by another memory manager. This is done with two + * paired references: the strong reference added by + * g_object_add_toggle_ref() and a reverse reference to the proxy + * object which is either a strong reference or weak reference. + * + * The setup is that when there are no other references to @object, + * only a weak reference is held in the reverse direction from @object + * to the proxy object, but when there are other references held to + * @object, a strong reference is held. The @notify callback is called + * when the reference from @object to the proxy object should be + * toggled from strong to weak (@is_last_ref + * true) or weak to strong (@is_last_ref false). + * + * Since a (normal) reference must be held to the object before + * calling g_object_toggle_ref(), the initial state of the reverse + * link is always strong. + * + * 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 + */ void g_object_add_toggle_ref (GObject *object, GToggleNotify notify, @@ -1671,6 +2245,19 @@ g_object_add_toggle_ref (GObject *object, (GDestroyNotify)g_free); } +/** + * g_object_remove_toggle_ref: + * @object: a #GObject + * @notify: a function to call when this reference is the + * last reference to the object, or is no longer + * the last reference. + * @data: data to pass to @notify + * + * Removes a reference added with g_object_add_toggle_ref(). The + * reference count of the object is decreased by one. + * + * Since: 2.8 + */ void g_object_remove_toggle_ref (GObject *object, GToggleNotify notify, @@ -1709,6 +2296,14 @@ g_object_remove_toggle_ref (GObject *object, g_warning ("%s: couldn't find toggle ref %p(%p)", G_STRFUNC, notify, data); } +/** + * g_object_ref: + * @object: a #GObject + * + * Increases the reference count of @object. + * + * Returns: the same @object + */ gpointer g_object_ref (gpointer _object) { @@ -1732,6 +2327,14 @@ g_object_ref (gpointer _object) return object; } +/** + * g_object_unref: + * @object: a #GObject + * + * Decreases the reference count of @object. + * When its reference count drops to 0, the object is finalized + * (i.e. its memory is freed). + */ void g_object_unref (gpointer _object) { @@ -1805,6 +2408,16 @@ g_object_unref (gpointer _object) } } +/** + * g_object_get_qdata: + * @object: The GObject to get a stored user data pointer from + * @quark: A #GQuark, naming the user data pointer + * + * This function gets back user data pointers stored via + * g_object_set_qdata(). + * + * Returns: The user data pointer set, or %NULL + */ gpointer g_object_get_qdata (GObject *object, GQuark quark) @@ -1814,6 +2427,21 @@ g_object_get_qdata (GObject *object, return quark ? g_datalist_id_get_data (&object->qdata, quark) : NULL; } +/** + * g_object_set_qdata: + * @object: The GObject to set store a user data pointer + * @quark: A #GQuark, naming the user data pointer + * @data: An opaque user data pointer + * + * This sets an opaque, named pointer on an object. + * The name is specified through a #GQuark (retrived e.g. via + * g_quark_from_static_string()), and the pointer + * can be gotten back from the @object with g_object_get_qdata() + * until the @object is finalized. + * Setting a previously set user data pointer, overrides (frees) + * the old pointer set, using #NULL as pointer essentially + * removes the data stored. + */ void g_object_set_qdata (GObject *object, GQuark quark, @@ -1825,6 +2453,19 @@ g_object_set_qdata (GObject *object, g_datalist_id_set_data (&object->qdata, quark, data); } +/** + * g_object_set_qdata_full: + * @object: The GObject to set store a user data pointer + * @quark: A #GQuark, naming the user data pointer + * @data: An opaque user data pointer + * @destroy: Function to invoke with @data as argument, when @data needs to be freed + * + * This function works like g_object_set_qdata(), but in addition, + * a void (*destroy) (gpointer) function may be specified which is + * called with @data as argument when the @object is finalized, or + * the data is being overwritten by a call to g_object_set_qdata() + * with the same @quark. + */ void g_object_set_qdata_full (GObject *object, GQuark quark, @@ -1838,6 +2479,48 @@ g_object_set_qdata_full (GObject *object, data ? destroy : (GDestroyNotify) NULL); } +/** + * g_object_steal_qdata: + * @object: The GObject to get a stored user data pointer from + * @quark: A #GQuark, naming the user data pointer + * + * This function gets back user data pointers stored via + * g_object_set_qdata() and removes the @data from object + * without invoking it's destroy() function (if any was + * set). + * Usually, calling this function is only required to update + * user data pointers with a destroy notifier, for example: + * |[ + * 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_get_qdata() in the above example, instead of g_object_steal_qdata() + * would have left the destroy function set, and thus the partial string list would + * have been freed upon g_object_set_qdata_full(). + * + * Returns: The user data pointer set, or %NULL + */ gpointer g_object_steal_qdata (GObject *object, GQuark quark) @@ -1848,6 +2531,15 @@ g_object_steal_qdata (GObject *object, return g_datalist_id_remove_no_notify (&object->qdata, quark); } +/** + * g_object_get_data: + * @object: #GObject containing the associations + * @key: name of the key for that association + * + * Gets a named field from the objects table of associations (see g_object_set_data()). + * + * Returns: the data if found, or %NULL if no such data exists. + */ gpointer g_object_get_data (GObject *object, const gchar *key) @@ -1862,6 +2554,18 @@ g_object_get_data (GObject *object, return quark ? g_datalist_id_get_data (&object->qdata, quark) : NULL; } +/** + * g_object_set_data: + * @object: #GObject containing the associations. + * @key: name of the key + * @data: data to associate with that key + * + * 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. + */ void g_object_set_data (GObject *object, const gchar *key, @@ -1873,6 +2577,19 @@ g_object_set_data (GObject *object, g_datalist_id_set_data (&object->qdata, g_quark_from_string (key), data); } +/** + * g_object_set_data_full: + * @object: #GObject containing the associations + * @key: name of the key + * @data: data to associate with that key + * @destroy: function to call when the association is destroyed + * + * Like g_object_set_data() except it adds notification + * for when the association is destroyed, either by setting it + * to a different value or when the object is destroyed. + * + * Note that the @destroy callback is not called if @data is %NULL. + */ void g_object_set_data_full (GObject *object, const gchar *key, @@ -1886,6 +2603,16 @@ g_object_set_data_full (GObject *object, data ? destroy : (GDestroyNotify) NULL); } +/** + * g_object_steal_data: + * @object: #GObject containing the associations + * @key: name of the key + * + * Remove a specified datum from the object's data associations, + * without invoking the association's destroy handler. + * + * Returns: the data if found, or %NULL if no such data exists. + */ gpointer g_object_steal_data (GObject *object, const gchar *key) @@ -2148,6 +2875,21 @@ destroy_closure_array (gpointer data) g_free (carray); } +/** + * g_object_watch_closure: + * @object: GObject restricting lifetime of @closure + * @closure: GClosure to watch + * + * This function essentially limits the life time of the @closure + * to the life time of the object. That is, when the object is finalized, + * the @closure is invalidated by calling g_closure_invalidate() on it, + * in order to prevent invocations of the closure with a finalized + * (nonexisting) object. Also, g_object_ref() and g_object_unref() are added + * as marshal guards to the @closure, to ensure that an extra reference + * count is held on @object during invocation of the @closure. + * Usually, this function will be called on closures that use this @object + * as closure data. + */ void g_object_watch_closure (GObject *object, GClosure *closure) diff --git a/gobject/gobject.h b/gobject/gobject.h index 4f7ef570a..b352c958e 100644 --- a/gobject/gobject.h +++ b/gobject/gobject.h @@ -32,19 +32,101 @@ G_BEGIN_DECLS /* --- type macros --- */ +/** + * G_TYPE_IS_OBJECT: + * @type: Type id to check + * + * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. + * + * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. + */ #define G_TYPE_IS_OBJECT(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_OBJECT) +/** + * G_OBJECT: + * @object: Object which is subject to casting. + * + * 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. + */ #define G_OBJECT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject)) +/** + * G_OBJECT_CLASS: + * @class: a valid #GObjectClass + * + * Casts a derived #GObjectClass structure into a #GObjectClass structure. + */ #define G_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass)) +/** + * G_IS_OBJECT: + * @object: Instance to check for being a %G_TYPE_OBJECT. + * + * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. + */ #define G_IS_OBJECT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_OBJECT)) +/** + * G_IS_OBJECT_CLASS: + * @class: a #GObjectClass + * + * Checks whether @class "is a" valid #GObjectClass structure of type + * %G_TYPE_OBJECT or derived. + */ #define G_IS_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_OBJECT)) +/** + * G_OBJECT_GET_CLASS: + * @object: a #GObject instance. + * + * Get the class structure associated to a #GObject instance. + * + * Returns: pointer to object class structure. + */ #define G_OBJECT_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_OBJECT, GObjectClass)) +/** + * G_OBJECT_TYPE: + * @object: Object to return the type id for. + * + * Get the type id of an object. + * + * Returns: Type id of @object. + */ #define G_OBJECT_TYPE(object) (G_TYPE_FROM_INSTANCE (object)) +/** + * G_OBJECT_TYPE_NAME: + * @object: Object to return the type name for. + * + * Get the name of an object's type. + * + * Returns: Type name of @object. The string is owned by the type system and + * should not be freed. + */ #define G_OBJECT_TYPE_NAME(object) (g_type_name (G_OBJECT_TYPE (object))) +/** + * G_OBJECT_CLASS_TYPE: + * @class: a valid #GObjectClass + * + * Get the type id of a class structure. + * + * Returns: Type id of @class. + */ #define G_OBJECT_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class)) +/** + * G_OBJECT_CLASS_NAME: + * @class: a valid #GObjectClass + * + * Return the name of a class structure's type. + * + * Returns: Type name of @class. The string is owned by the type system and + * should not be freed. + */ #define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class))) #define G_VALUE_HOLDS_OBJECT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_OBJECT)) /* --- type macros --- */ +/** + * G_TYPE_INITIALLY_UNOWNED: + * + * The type for #GInitiallyUnowned. + */ #define G_TYPE_INITIALLY_UNOWNED (g_initially_unowned_get_type()) #define G_INITIALLY_UNOWNED(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnowned)) #define G_INITIALLY_UNOWNED_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnownedClass)) @@ -60,17 +142,59 @@ typedef struct _GObjectClass GObjectClass; typedef struct _GObject GInitiallyUnowned; typedef struct _GObjectClass GInitiallyUnownedClass; typedef struct _GObjectConstructParam GObjectConstructParam; +/** + * GObjectGetPropertyFunc: + * @object: a #GObject + * @property_id: the numeric id under which the property was registered with + * g_object_class_install_property(). + * @value: a #GValue to return the property value in + * @pspec: the #GParamSpec describing the property + * + * The type of the @get_property function of #GObjectClass. + */ typedef void (*GObjectGetPropertyFunc) (GObject *object, guint property_id, GValue *value, GParamSpec *pspec); +/** + * GObjectSetPropertyFunc: + * @object: a #GObject + * @property_id: the numeric id under which the property was registered with + * g_object_class_install_property(). + * @value: the new value for the property + * @pspec: the #GParamSpec describing the property + * + * The type of the @set_property function of #GObjectClass. + */ typedef void (*GObjectSetPropertyFunc) (GObject *object, guint property_id, const GValue *value, GParamSpec *pspec); +/** + * GObjectFinalizeFunc: + * @object: the #GObject being finalized + * + * The type of the @finalize function of #GObjectClass. + */ typedef void (*GObjectFinalizeFunc) (GObject *object); +/** + * GWeakNotify: + * @data: data that was provided when the weak reference was established + * @where_the_object_was: the object being finalized + * + * 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. + */ typedef void (*GWeakNotify) (gpointer data, GObject *where_the_object_was); +/** + * GObject: + * + * All the fields in the GObject structure are private + * to the #GObject implementation and should never be accessed directly. + */ struct _GObject { GTypeInstance g_type_instance; @@ -79,6 +203,68 @@ struct _GObject volatile guint ref_count; GData *qdata; }; +/** + * GObjectClass: + * @g_type_class: the parent class + * @constructor: the @constructor function is called by g_object_new () to + * complete the object initialization after all the construction properties are + * set. The first thing a @constructor implementation must do is chain up to the + * @constructor of the parent class. Overriding @constructor should be rarely + * needed, e.g. to handle construct properties, or to implement singletons. + * @set_property: the generic setter for all properties of this type. Should be + * overridden for every type with properties. Implementations of @set_property + * don't need to emit property change notification explicitly, this is handled + * by the type system. + * @get_property: the generic getter for all properties of this type. Should be + * overridden for every type with properties. + * @dispose: the @dispose function is supposed to drop all references to other + * objects, but keep the instance otherwise intact, so that client method + * invocations still work. It may be run multiple times (due to reference + * loops). Before returning, @dispose should chain up to the @dispose method + * of the parent class. + * @finalize: instance finalization function, should finish the finalization of + * the instance begun in @dispose and chain up to the @finalize method of the + * parent class. + * @dispatch_properties_changed: emits property change notification for a bunch + * of properties. Overriding @dispatch_properties_changed should be rarely + * needed. + * @notify: the class closure for the notify signal + * @constructed: the @constructed function is called by g_object_new() as the + * final step of the object creation process. At the point of the call, all + * construction properties have been set on the object. The purpose of this + * call is to allow for object initialisation steps that can only be performed + * after construction properties have been set. @constructed implementors + * should chain up to the @constructed call of their parent class to allow it + * to complete its initialisation. + * + * The class structure for the GObject type. + * + * + * 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; + * } + * + */ struct _GObjectClass { GTypeClass g_type_class; @@ -117,12 +303,34 @@ struct _GObjectClass /* padding */ gpointer pdummy[7]; }; +/** + * GObjectConstructParam: + * @pspec: the #GParamSpec of the construct parameter + * @value: the value to set the parameter to + * + * The GObjectConstructParam struct is an auxiliary + * structure used to hand #GParamSpec/#GValue pairs to the @constructor of + * a #GObjectClass. + */ struct _GObjectConstructParam { GParamSpec *pspec; GValue *value; }; +/** + * GInitiallyUnowned: + * + * All the fields in the GInitiallyUnowned structure + * are private to the #GInitiallyUnowned implementation and should never be + * accessed directly. + */ +/** + * GInitiallyUnownedClass: + * + * The class structure for the GInitiallyUnowned type. + */ + /* --- prototypes --- */ GType g_initially_unowned_get_type (void); @@ -196,6 +404,18 @@ void g_object_add_weak_pointer (GObject *object, void g_object_remove_weak_pointer (GObject *object, gpointer *weak_pointer_location); +/** + * GToggleNotify: + * @data: Callback data passed to g_object_add_toggle_ref() + * @object: The object on which g_object_add_toggle_ref() was called. + * @is_last_ref: %TRUE if the toggle reference is now the + * last reference to the object. %FALSE if the toggle + * reference was the last reference and there are now other + * references. + * + * A callback function used for notification when the state + * of a toggle reference changes. See g_object_add_toggle_ref(). + */ typedef void (*GToggleNotify) (gpointer data, GObject *object, gboolean is_last_ref); @@ -278,6 +498,15 @@ G_STMT_START { \ g_type_name (G_PARAM_SPEC_TYPE (_pspec)), \ G_OBJECT_TYPE_NAME (_object)); \ } G_STMT_END +/** + * G_OBJECT_WARN_INVALID_PROPERTY_ID: + * @object: the #GObject on which set_property() or get_property() was called + * @property_id: the numeric id of the property + * @pspec: the #GParamSpec of the property + * + * This macro should be used to emit a standard warning about unexpected + * properties in set_property() and get_property() implementations. + */ #define G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec) \ G_OBJECT_WARN_INVALID_PSPEC ((object), "property", (property_id), (pspec)) diff --git a/gobject/gparam.h b/gobject/gparam.h index 41091d50d..ede8cb300 100644 --- a/gobject/gparam.h +++ b/gobject/gparam.h @@ -242,6 +242,14 @@ struct _GParamSpecClass /*< private >*/ gpointer dummy[4]; }; +/** + * GParameter: + * @name: the parameter name + * @value: the parameter value + * + * The GParameter struct is an auxiliary structure used + * to hand parameter name/value pairs to g_object_newv(). + */ struct _GParameter /* auxillary structure for _setv() variants */ { const gchar *name;