| <!-- ##### SECTION Title ##### --> |
| GObject |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| The base object type |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### 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> |
| |
| @gobject: the object which received the signal. |
| @pspec: the #GParamSpec of the property which changed |
| |
| <!-- ##### STRUCT GObjectClass ##### --> |
| <para> |
| The class structure for the <structname>GObject</structname> type. |
| </para> |
| |
| @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. |
| @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 |
| |
| <!-- ##### 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. |
| |
| |
| <!-- ##### 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: @object |
| |
| |
| <!-- ##### FUNCTION g_object_unref ##### --> |
| <para> |
| Decreases the reference count if @object. |
| When its reference count drops to 0, the object is finalized (i.e. its memory is freed). |
| </para> |
| |
| @object: a #GObject |
| |
| |
| <!-- ##### 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. |
| |
| |
| <!-- ##### 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 (...)</literal> |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>object_signal</term> |
| <term>object-signal</term> |
| <listitem><para> |
| equivalent to <literal>g_signal_connect_object (...)</literal> |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>swapped_signal</term> |
| <term>swapped-signal</term> |
| <listitem><para> |
| equivalent to <literal>g_signal_connect_data (..., 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 (..., 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 (..., 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> |
| |
| @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 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 |
| @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 macros 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 |
| |
| |