2008-06-21 Stefan Kost <ensonic@users.sf.net>
+ * docs/reference/gobject/tmpl/objects.sgml:
+ * gobject/gobject.c:
+ * gobject/gobject.h:
+ * gobject/gparam.h:
+ Migrating docs.
+
+2008-06-21 Stefan Kost <ensonic@users.sf.net>
+
* docs/reference/gobject/tmpl/gtypeplugin.sgml:
* gobject/gtypeplugin.c:
* gobject/gtypeplugin.h:
+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-GObject
-
-<!-- ##### SECTION Short_Description ##### -->
-The base object type
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-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 <xref linkend="gobject-Signals"/>.
-</para>
-<para id="floating-ref">
-#GInitiallyUnowned is derived from #GObject. The only difference between
-the two is that the initial reference of a #GInitiallyUnowned is flagged
-as a <firstterm>floating</firstterm> 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:
-<example><programlisting>
- container = create_container();
- container_add_child (container, create_child());
-</programlisting></example>
-If <function>container_add_child()</function> will g_object_ref_sink() the
-passed in child, no reference of the newly created child is leaked.
-Without floating references, <function>container_add_child()</function>
-can only g_object_ref() the new child, so to implement this code without
-reference leaks, it would have to be written as:
-<example><programlisting>
- Child *child;
- container = create_container();
- child = create_child();
- container_add_child (container, child);
- g_object_unref (child);
-</programlisting></example>
-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.
-</para>
-<para>
-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:
-</para>
-
-<example><programlisting>
- /* 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 */
-</programlisting></example>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GParamSpecObject, g_param_spec_object()
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GObject ##### -->
-<para>
-All the fields in the <structname>GObject</structname> structure are private
-to the #GObject implementation and should never be accessed directly.
-</para>
-
-
-<!-- ##### SIGNAL GObject::notify ##### -->
-<para>
-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.
-</para>
-<para>
-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:
-<informalexample><programlisting>
-g_signal_connect (text_view->buffer, "notify::paste-target-list",
- G_CALLBACK (gtk_text_view_target_list_notify),
- text_view)
-</programlisting></informalexample>
-It is important to note that you must use
-<link linkend="canonical-parameter-name">canonical</link> parameter names as
-detail strings for the notify signal.
-</para>
-
-@pspec: the #GParamSpec of the property which changed
-@gobject: the object which received the signal.
-
-<!-- ##### STRUCT GObjectClass ##### -->
-<para>
-The class structure for the <structname>GObject</structname> type.
-</para>
-<example>
-<title>Implementing singletons using a constructor</title>
-<programlisting>
-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;
-}
-</programlisting></example>
-
-@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.
-
-<!-- ##### STRUCT GObjectConstructParam ##### -->
-<para>
-The <structname>GObjectConstructParam</structname> struct is an auxiliary
-structure used to hand #GParamSpec/#GValue pairs to the @constructor of
-a #GObjectClass.
-</para>
-
-@pspec: the #GParamSpec of the construct parameter
-@value: the value to set the parameter to
-
-<!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
-<para>
-The type of the @get_property function of #GObjectClass.
-</para>
-
-@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
-
-
-<!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
-<para>
-The type of the @set_property function of #GObjectClass.
-</para>
-
-@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
-
-
-<!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
-<para>
-The type of the @finalize function of #GObjectClass.
-</para>
-
-@object: the #GObject being finalized
-
-
-<!-- ##### MACRO G_TYPE_IS_OBJECT ##### -->
-<para>
-Returns a boolean value of %FALSE or %TRUE indicating whether
-the passed in type id is a %G_TYPE_OBJECT or derived from it.
-</para>
-
-@type: Type id to check for is a %G_TYPE_OBJECT relationship.
-@Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
-
-
-<!-- ##### MACRO G_OBJECT ##### -->
-<para>
-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.
-</para>
-
-@object: Object which is subject to casting.
-
-
-<!-- ##### MACRO G_IS_OBJECT ##### -->
-<para>
-Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
-</para>
-
-@object: Instance to check for being a %G_TYPE_OBJECT.
-
-
-<!-- ##### MACRO G_OBJECT_CLASS ##### -->
-<para>
-Casts a derived #GObjectClass structure into a #GObjectClass structure.
-</para>
-
-@class: a valid #GObjectClass
-
-
-<!-- ##### MACRO G_IS_OBJECT_CLASS ##### -->
-<para>
-Checks whether @class "is a" valid #GObjectClass structure of type
-%G_TYPE_OBJECT or derived.
-</para>
-
-@class: a #GObjectClass
-
-
-<!-- ##### MACRO G_OBJECT_GET_CLASS ##### -->
-<para>
-Returns the class structure associated to a #GObject instance.
-</para>
-
-@object: a #GObject instance.
-
-
-<!-- ##### MACRO G_OBJECT_TYPE ##### -->
-<para>
-Return the type id of an object.
-</para>
-
-@object: Object to return the type id for.
-@Returns: Type id of @object.
-
-
-<!-- ##### MACRO G_OBJECT_TYPE_NAME ##### -->
-<para>
-Returns the name of an object's type.
-</para>
-
-@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.
-
-
-<!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### -->
-<para>
-Return the type id of a class structure.
-</para>
-
-@class: a valid #GObjectClass
-@Returns: Type id of @class.
-
-
-<!-- ##### MACRO G_OBJECT_CLASS_NAME ##### -->
-<para>
-Return the name of a class structure's type.
-</para>
-
-@class: a valid #GObjectClass
-@Returns: Type name of @class. The string is owned by the type system and
-should not be freed.
-
-
-<!-- ##### FUNCTION g_object_class_install_property ##### -->
-<para>
-Installs a new property. This is usually done in the class initializer.
-</para>
-
-@oclass: a #GObjectClass
-@property_id: the id for the new property
-@pspec: the #GParamSpec for the new property
-
-
-<!-- ##### FUNCTION g_object_class_find_property ##### -->
-<para>
-Looks up the #GParamSpec for a property of a class.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_class_list_properties ##### -->
-<para>
-Returns an array of #GParamSpec* for all properties of a class.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_class_override_property ##### -->
-<para>
-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 <firstterm>override</firstterm>
-a property implementation in a parent class or to provide
-the implementation of a property from an interface.
-</para>
-<note>
-<para>
-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().
-</para>
-</note>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_interface_install_property ##### -->
-<para>
-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.
-</para>
-<para>
-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.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_interface_find_property ##### -->
-<para>
-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().
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_interface_list_properties ##### -->
-<para>
-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().
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_new ##### -->
-<para>
-Creates a new instance of a #GObject subtype and sets its properties.
-</para>
-<para>
-Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
-which are not explicitly specified are set to their default values.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_newv ##### -->
-<para>
-Creates a new instance of a #GObject subtype and sets its properties.
-</para>
-<para>
-Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
-which are not explicitly specified are set to their default values.
-</para>
-
-@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
-
-
-<!-- ##### STRUCT GParameter ##### -->
-<para>
-The <structname>GParameter</structname> struct is an auxiliary structure used
-to hand parameter name/value pairs to g_object_newv().
-</para>
-
-@name: the parameter name
-@value: the parameter value
-
-<!-- ##### FUNCTION g_object_ref ##### -->
-<para>
-Increases the reference count of @object.
-</para>
-
-@object: a #GObject
-@Returns: the same @object
-
-
-<!-- ##### FUNCTION g_object_unref ##### -->
-<para>
-Decreases the reference count of @object.
-When its reference count drops to 0, the object is finalized
-(i.e. its memory is freed).
-</para>
-
-@object: a #GObject
-
-
-<!-- ##### FUNCTION g_object_ref_sink ##### -->
-<para>
-Increase the reference count of @object, and possibly remove the
-<link linkend="floating-ref">floating</link> reference, if @object
-has a floating reference.
-</para>
-<para>
-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.
-</para>
-
-@object: a #GObject
-@Returns: @object
-@Since: 2.10
-
-
-<!-- ##### TYPEDEF GInitiallyUnowned ##### -->
-<para>
-All the fields in the <structname>GInitiallyUnowned</structname> structure
-are private to the #GInitiallyUnowned implementation and should never be
-accessed directly.
-</para>
-
-
-<!-- ##### TYPEDEF GInitiallyUnownedClass ##### -->
-<para>
-The class structure for the <structname>GInitiallyUnowned</structname> type.
-</para>
-
-
-<!-- ##### MACRO G_TYPE_INITIALLY_UNOWNED ##### -->
-<para>
-The type for #GInitiallyUnowned.
-</para>
-
-
-
-<!-- ##### FUNCTION g_object_is_floating ##### -->
-<para>
-Checks wether @object has a <link linkend="floating-ref">floating</link>
-reference.
-</para>
-
-@object: a #GObject
-@Returns: %TRUE if @object has a floating reference
-@Since: 2.10
-
-
-<!-- ##### FUNCTION g_object_force_floating ##### -->
-<para>
-This function is intended for #GObject implementations to re-enforce a
-<link linkend="floating-ref">floating</link> object reference.
-Doing this is seldomly required, all
-#GInitiallyUnowned<!-- -->s are created with a floating reference which
-usually just needs to be sunken by calling g_object_ref_sink().
-</para>
-
-@object: a #GObject
-@Since: 2.10
-
-
-<!-- ##### USER_FUNCTION GWeakNotify ##### -->
-<para>
-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.
-</para>
-
-@data: data that was provided when the weak reference was established
-@where_the_object_was: the object being finalized
-
-
-<!-- ##### FUNCTION g_object_weak_ref ##### -->
-<para>
-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).
-</para>
-
-@object: #GObject to reference weakly
-@notify: callback to invoke before the object is freed
-@data: extra data to pass to notify
-
-
-<!-- ##### FUNCTION g_object_weak_unref ##### -->
-<para>
-Removes a weak reference callback to an object.
-</para>
-
-@object: #GObject to remove a weak reference from
-@notify: callback to search for
-@data: data to search for
-
-
-<!-- ##### FUNCTION g_object_add_weak_pointer ##### -->
-<para>
-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.
-</para>
-
-@object: The object that should be weak referenced.
-@weak_pointer_location: The memory address of a pointer.
-
-
-<!-- ##### FUNCTION g_object_remove_weak_pointer ##### -->
-<para>
-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().
-</para>
-
-@object: The object that is weak referenced.
-@weak_pointer_location: The memory address of a pointer.
-
-
-<!-- ##### USER_FUNCTION GToggleNotify ##### -->
-<para>
-A callback function used for notification when the state
-of a toggle reference changes. See g_object_add_toggle_ref().
-</para>
-
-@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.
-
-
-<!-- ##### FUNCTION g_object_add_toggle_ref ##### -->
-<para>
-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.
-</para>
-<para>
-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.
-</para>
-<para>
-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
-<firstterm>toggled</firstterm> from strong to weak (@is_last_ref
-true) or weak to strong (@is_last_ref false).
-</para>
-<para>
-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.
-</para>
-<para>
-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.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_remove_toggle_ref ##### -->
-<para>
-Removes a reference added with g_object_add_toggle_ref(). The
-reference count of the object is decreased by one.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_connect ##### -->
-<para>
-A convenience function to connect multiple signals at once.
-</para>
-<para>
-The signal specs expected by this function have the form
-"modifier::signal_name", where modifier can be one of the following:
-<variablelist>
-<varlistentry>
-<term>signal</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_data (..., NULL, 0)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>object_signal</term>
-<term>object-signal</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_object (..., 0)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>swapped_signal</term>
-<term>swapped-signal</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>swapped_object_signal</term>
-<term>swapped-object-signal</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>signal_after</term>
-<term>signal-after</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_AFTER)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>object_signal_after</term>
-<term>object-signal-after</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>swapped_signal_after</term>
-<term>swapped-signal-after</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>swapped_object_signal_after</term>
-<term>swapped-object-signal-after</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
-</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
-<informalexample>
-<programlisting>
- 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);
-</programlisting>
-</informalexample>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_disconnect ##### -->
-<para>
-A convenience function to disconnect multiple signals at once.
-</para>
-<para>
-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".
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_set ##### -->
-<para>
-Sets properties on an object.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_get ##### -->
-<para>
-Gets properties of an object.
-</para>
-<para>
-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().
-</para>
-<example>
-<title>Using g_object_get(<!-- -->)</title>
-<para>
-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:
-</para>
-<programlisting>
- 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);
-</programlisting>
-</example>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_notify ##### -->
-<para>
-Emits a "notify" signal for the property @property_name on @object.
-</para>
-
-@object: a #GObject
-@property_name: the name of a property installed on the class of @object.
-
-
-<!-- ##### FUNCTION g_object_freeze_notify ##### -->
-<para>
-Stops emission of "notify" signals on @object. The signals are
-queued until g_object_thaw_notify() is called on @object.
-</para>
-<para>
-This is necessary for accessors that modify multiple properties to prevent
-premature notification while the object is still being modified.
-</para>
-
-@object: a #GObject
-
-
-<!-- ##### FUNCTION g_object_thaw_notify ##### -->
-<para>
-Reverts the effect of a previous call to g_object_freeze_notify().
-This causes all queued "notify" signals on @object to be emitted.
-</para>
-
-@object: a #GObject
-
-
-<!-- ##### FUNCTION g_object_get_data ##### -->
-<para>
-Gets a named field from the objects table of associations (see g_object_set_data()).
-</para>
-
-@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.
-
-
-<!-- ##### FUNCTION g_object_set_data ##### -->
-<para>
-Each object carries around a table of associations from
-strings to pointers. This function lets you set an association.
-</para>
-<para>
-If the object already had an association with that name,
-the old association will be destroyed.
-</para>
-
-@object: #GObject containing the associations.
-@key: name of the key
-@data: data to associate with that key
-
-
-<!-- ##### FUNCTION g_object_set_data_full ##### -->
-<para>
-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.
-</para>
-<para>
-Note that the @destroy callback is not called if @data is %NULL.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_steal_data ##### -->
-<para>
-Remove a specified datum from the object's data associations,
-without invoking the association's destroy handler.
-</para>
-
-@object: #GObject containing the associations
-@key: name of the key
-@Returns: the data if found, or %NULL if no such data exists.
-
-
-<!-- ##### FUNCTION g_object_get_qdata ##### -->
-<para>
-This function gets back user data pointers stored via
-g_object_set_qdata().
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_set_qdata ##### -->
-<para>
-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.
-</para>
-
-@object: The GObject to set store a user data pointer
-@quark: A #GQuark, naming the user data pointer
-@data: An opaque user data pointer
-
-
-<!-- ##### FUNCTION g_object_set_qdata_full ##### -->
-<para>
-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.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_steal_qdata ##### -->
-<para>
-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:
-<programlisting>
-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);
-}
-</programlisting>
-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().
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_set_property ##### -->
-<para>
-Sets a property on an object.
-</para>
-
-@object: a #GObject
-@property_name: the name of the property to set
-@value: the value
-
-
-<!-- ##### FUNCTION g_object_get_property ##### -->
-<para>
-Gets a property of an object.
-</para>
-<para>
-In general, a copy is made of the property contents and the caller is
-responsible for freeing the memory by calling g_value_unset().
-</para>
-<para>
-Note that g_object_get_property() is really intended for language
-bindings, g_object_get() is much more convenient for C programming.
-</para>
-
-@object: a #GObject
-@property_name: the name of the property to get
-@value: return location for the property value
-
-
-<!-- ##### FUNCTION g_object_new_valist ##### -->
-<para>
-Creates a new instance of a #GObject subtype and sets its properties.
-</para>
-<para>
-Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
-which are not explicitly specified are set to their default values.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_set_valist ##### -->
-<para>
-Sets properties on an object.
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_get_valist ##### -->
-<para>
-Gets properties of an object.
-</para>
-<para>
-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().
-</para>
-<para>
-See g_object_get().
-</para>
-
-@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
-
-
-<!-- ##### FUNCTION g_object_watch_closure ##### -->
-<para>
-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.
-</para>
-
-@object: GObject restricting lifetime of @closure
-@closure: GClosure to watch
-
-
-<!-- ##### FUNCTION g_object_run_dispose ##### -->
-<para>
-Releases all references to other objects. This can be used to break
-reference cycles.
-</para>
-<note><para>
-This functions should only be called from object system implementations.
-</para></note>
-
-@object: a #GObject
-
-
-<!-- ##### MACRO G_OBJECT_WARN_INVALID_PROPERTY_ID ##### -->
-<para>
-This macro should be used to emit a standard warning about unexpected
-properties in set_property() and get_property() implementations.
-</para>
-
-@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
-
-
* 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 <xref linkend="gobject-Signals"/>.
+ *
+ * <para id="floating-ref">
+ * #GInitiallyUnowned is derived from #GObject. The only difference between
+ * the two is that the initial reference of a #GInitiallyUnowned is flagged
+ * as a <firstterm>floating</firstterm> 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 <function>container_add_child()</function> will g_object_ref_sink() the
+ * passed in child, no reference of the newly created child is leaked.
+ * Without floating references, <function>container_add_child()</function>
+ * 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.
+ * </para>
+ *
+ * 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 <glib/gdatasetprivate.h>
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
+ * <link linkend="canonical-parameter-name">canonical</link> 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),
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,
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)
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)
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)
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 <firstterm>override</firstterm>
+ * a property implementation in a parent class or to provide
+ * the implementation of a property from an interface.
+ *
+ * <note>
+ * 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().
+ * </note>
+ *
+ * Since: 2.4
+ */
void
g_object_class_override_property (GObjectClass *oclass,
guint property_id,
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)
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)
{
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)
{
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)
{
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)
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)
{
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,
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,
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,
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,
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,
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,
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().
+ *
+ * <example>
+ * <title>Using g_object_get(<!-- -->)</title>
+ * 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:
+ * <programlisting>
+ * 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);
+ * </programlisting>
+ * </example>
+ */
void
g_object_get (gpointer _object,
const gchar *first_property_name,
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,
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,
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:
+ * <variablelist>
+ * <varlistentry>
+ * <term>signal</term>
+ * <listitem><para>
+ * equivalent to <literal>g_signal_connect_data (..., NULL, 0)</literal>
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>object_signal</term>
+ * <term>object-signal</term>
+ * <listitem><para>
+ * equivalent to <literal>g_signal_connect_object (..., 0)</literal>
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>swapped_signal</term>
+ * <term>swapped-signal</term>
+ * <listitem><para>
+ * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)</literal>
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>swapped_object_signal</term>
+ * <term>swapped-object-signal</term>
+ * <listitem><para>
+ * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal>
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>signal_after</term>
+ * <term>signal-after</term>
+ * <listitem><para>
+ * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_AFTER)</literal>
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>object_signal_after</term>
+ * <term>object-signal-after</term>
+ * <listitem><para>
+ * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal>
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>swapped_signal_after</term>
+ * <term>swapped-signal-after</term>
+ * <listitem><para>
+ * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>swapped_object_signal_after</term>
+ * <term>swapped-object-signal-after</term>
+ * <listitem><para>
+ * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
+ * </para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * |[
+ * 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,
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,
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,
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,
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)
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)
}
}
+/**
+ * g_object_is_floating:
+ * @object: a #GObject
+ *
+ * Checks wether @object has a <link linkend="floating-ref">floating</link>
+ * reference.
+ *
+ * Since: 2.10
+ * Returns: %TRUE if @object has a floating reference
+ */
gboolean
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
+ * <link linkend="floating-ref">floating</link> 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)
{
return object;
}
+/**
+ * g_object_force_floating:
+ * @object: a #GObject
+ *
+ * This function is intended for #GObject implementations to re-enforce a
+ * <link linkend="floating-ref">floating</link> object reference.
+ * Doing this is seldomly required, all
+ * #GInitiallyUnowned<!-- -->s 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)
{
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
+ * <firstterm>toggled</firstterm> 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,
(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,
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)
{
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)
{
}
}
+/**
+ * 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)
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,
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,
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)
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)
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,
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,
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)
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)
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))
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 <structname>GObject</structname> structure are private
+ * to the #GObject implementation and should never be accessed directly.
+ */
struct _GObject
{
GTypeInstance g_type_instance;
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 <structname>GObject</structname> type.
+ *
+ * <example>
+ * <title>Implementing singletons using a constructor</title>
+ * <programlisting>
+ * 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;
+ * }
+ * </programlisting></example>
+ */
struct _GObjectClass
{
GTypeClass g_type_class;
/* padding */
gpointer pdummy[7];
};
+/**
+ * GObjectConstructParam:
+ * @pspec: the #GParamSpec of the construct parameter
+ * @value: the value to set the parameter to
+ *
+ * The <structname>GObjectConstructParam</structname> 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 <structname>GInitiallyUnowned</structname> structure
+ * are private to the #GInitiallyUnowned implementation and should never be
+ * accessed directly.
+ */
+/**
+ * GInitiallyUnownedClass:
+ *
+ * The class structure for the <structname>GInitiallyUnowned</structname> type.
+ */
+
/* --- prototypes --- */
GType g_initially_unowned_get_type (void);
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);
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))
/*< private >*/
gpointer dummy[4];
};
+/**
+ * GParameter:
+ * @name: the parameter name
+ * @value: the parameter value
+ *
+ * The <structname>GParameter</structname> 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;