diff options
| -rw-r--r-- | gobject/ChangeLog | 6 | ||||
| -rw-r--r-- | gobject/gboxed.c | 44 | ||||
| -rw-r--r-- | gobject/gclosure.c | 274 | ||||
| -rw-r--r-- | gobject/genums.c | 112 | ||||
| -rw-r--r-- | gobject/gobject.c | 447 | ||||
| -rw-r--r-- | gobject/gparam.c | 247 | ||||
| -rw-r--r-- | gobject/gparamspecs.c | 175 | ||||
| -rw-r--r-- | gobject/gsignal.c | 293 | ||||
| -rw-r--r-- | gobject/gsourceclosure.c | 4 | ||||
| -rw-r--r-- | gobject/gtype.c | 386 | ||||
| -rw-r--r-- | gobject/gtypemodule.c | 53 | ||||
| -rw-r--r-- | gobject/gtypeplugin.c | 27 | ||||
| -rw-r--r-- | gobject/gvalue.c | 82 | ||||
| -rw-r--r-- | gobject/gvaluearray.c | 50 | ||||
| -rw-r--r-- | gobject/gvaluetransform.c | 1 | ||||
| -rw-r--r-- | gobject/gvaluetypes.c | 122 |
16 files changed, 1225 insertions, 1098 deletions
diff --git a/gobject/ChangeLog b/gobject/ChangeLog index c263bbd38..370f7a611 100644 --- a/gobject/ChangeLog +++ b/gobject/ChangeLog @@ -1,5 +1,11 @@ 2008-06-22 Michael Natterer <mitch@imendio.com> + * *.c: remove trailing whitespace from newly added gtk-doc + comments and reformatted some where they contained overly long or + ill-formatted lines. + +2008-06-22 Michael Natterer <mitch@imendio.com> + * *.c: moved includes back to the top of the files (before gtk-doc SECTION comments). Add "config.h" in all files and move system included before glib includes. Remove trailing whitespace from diff --git a/gobject/gboxed.c b/gobject/gboxed.c index 9383ab89b..940ad843e 100644 --- a/gobject/gboxed.c +++ b/gobject/gboxed.c @@ -32,8 +32,9 @@ /** * SECTION:gboxed + * * @Short_description: A mechanism to wrap opaque C structures registered - * by the type system + * by the type system * * @See_also: #GParamSpecBoxed, g_param_spec_boxed() * @@ -114,7 +115,7 @@ value_free (gpointer boxed) } void -g_boxed_type_init (void) +g_boxed_type_init (void) { static const GTypeInfo info = { 0, /* class_size */ @@ -372,11 +373,11 @@ boxed_proxy_lcopy_value (const GValue *value, * @name: Name of the new boxed type. * @boxed_copy: Boxed structure copy function. * @boxed_free: Boxed structure free function. - * + * * This function creates a new %G_TYPE_BOXED derived type id for a new * boxed type with name @name. Boxed type handling functions have to be * provided to copy and free opaque boxed structures of this type. - * + * * Returns: New %G_TYPE_BOXED derived type id for @name. */ GType @@ -465,7 +466,7 @@ g_boxed_copy (GType boxed_type, else { GValue src_value, dest_value; - + /* we heavily rely on third-party boxed type value vtable * implementations to follow normal boxed value storage * (data[0].v_pointer is the boxed struct, and @@ -500,7 +501,7 @@ g_boxed_copy (GType boxed_type, * g_boxed_free: * @boxed_type: The type of @boxed. * @boxed: The boxed structure to be freed. - * + * * Free the boxed structure @boxed which is of type @boxed_type. */ void @@ -540,9 +541,9 @@ g_boxed_free (GType boxed_type, /** * g_value_get_boxed: * @value: a valid #GValue of %G_TYPE_BOXED derived type - * + * * Get the contents of a %G_TYPE_BOXED derived #GValue. - * + * * Returns: boxed contents of @value */ gpointer @@ -557,11 +558,12 @@ g_value_get_boxed (const GValue *value) /** * g_value_dup_boxed: * @value: a valid #GValue of %G_TYPE_BOXED derived type - * - * Get the contents of a %G_TYPE_BOXED derived #GValue. - * Upon getting, the boxed value is duplicated and needs to be - * later freed with g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), return_value); - * + * + * Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, + * the boxed value is duplicated and needs to be later freed with + * g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), + * return_value); + * * Returns: boxed contents of @value */ gpointer @@ -620,7 +622,7 @@ value_set_boxed_internal (GValue *value, * g_value_set_boxed: * @value: a valid #GValue of %G_TYPE_BOXED derived type * @v_boxed: boxed value to be set - * + * * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. */ void @@ -637,7 +639,7 @@ g_value_set_boxed (GValue *value, * g_value_set_static_boxed: * @value: a valid #GValue of %G_TYPE_BOXED derived type * @v_boxed: static boxed value to be set - * + * * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. * The boxed value is assumed to be static, and is thus not duplicated * when setting the #GValue. @@ -656,9 +658,9 @@ g_value_set_static_boxed (GValue *value, * g_value_set_boxed_take_ownership: * @value: a valid #GValue of %G_TYPE_BOXED derived type * @v_boxed: duplicated unowned boxed value to be set - * + * * This is an internal function introduced mainly for C marshallers. - * + * * Deprecated: 2.4: Use g_value_take_boxed() instead. */ void @@ -672,11 +674,11 @@ g_value_set_boxed_take_ownership (GValue *value, * g_value_take_boxed: * @value: a valid #GValue of %G_TYPE_BOXED derived type * @v_boxed: duplicated unowned boxed value to be set - * - * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and - * takes over the ownership of the callers reference to @v_boxed; + * + * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed + * and takes over the ownership of the callers reference to @v_boxed; * the caller doesn't have to unref it any more. - * + * * Since: 2.4 */ void diff --git a/gobject/gclosure.c b/gobject/gclosure.c index 1fd456c61..389807276 100644 --- a/gobject/gclosure.c +++ b/gobject/gclosure.c @@ -30,9 +30,12 @@ #include "gvalue.h" #include "gobjectalias.h" + /** * SECTION:gclosure + * * @Short_description: Functions as first-class objects + * * @Title: Closures * * A #GClosure represents a callback supplied by the programmer. It @@ -84,6 +87,7 @@ * </itemizedlist> */ + #define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1) #define CLOSURE_MAX_N_GUARDS ((1 << 1) - 1) #define CLOSURE_MAX_N_FNOTIFIERS ((1 << 2) - 1) @@ -144,47 +148,47 @@ enum { /* --- functions --- */ /** * g_closure_new_simple: - * @sizeof_closure: the size of the structure to allocate, must be at least - * <literal>sizeof (GClosure)</literal> + * @sizeof_closure: the size of the structure to allocate, must be at least + * <literal>sizeof (GClosure)</literal> * @data: data to store in the @data field of the newly allocated #GClosure - * - * Allocates a struct of the given size and initializes the initial part - * as a #GClosure. This function is mainly useful when implementing new types - * of closures. - * + * + * Allocates a struct of the given size and initializes the initial + * part as a #GClosure. This function is mainly useful when + * implementing new types of closures. + * * |[ * typedef struct _MyClosure MyClosure; - * struct _MyClosure + * struct _MyClosure * { * GClosure closure; * // extra data goes here - * }; - * + * }; + * * static void - * my_closure_finalize (gpointer notify_data, + * my_closure_finalize (gpointer notify_data, * GClosure *closure) * { * MyClosure *my_closure = (MyClosure *)closure; - * + * * // free extra data here * } - * + * * MyClosure *my_closure_new (gpointer data) * { * GClosure *closure; * MyClosure *my_closure; - * + * * closure = g_closure_new_simple (sizeof (MyClosure), data); * my_closure = (MyClosure *) closure; - * + * * // initialize extra data here - * + * * g_closure_add_finalize_notifier (closure, notify_data, * my_closure_finalize); * return my_closure; * } * ]| - * + * * Returns: a newly allocated #GClosure */ GClosure* @@ -296,20 +300,22 @@ closure_invoke_notifiers (GClosure *closure, * @closure: a #GClosure * @marshal_data: context-dependent data to pass to @meta_marshal * @meta_marshal: a #GClosureMarshal function - * - * Sets the meta marshaller of @closure. - * A meta marshaller wraps @closure->marshal and modifies the way it is called - * in some fashion. The most common use of this facility is for C callbacks. - * The same marshallers (generated by - * <link linkend="glib-genmarshal">glib-genmarshal</link>) are used everywhere, - * but the way that we get the callback function differs. In most cases we want - * to use @closure->callback, but in other cases we want to use some - * different technique to retrieve the callback function. - * - * For example, class closures for signals (see g_signal_type_cclosure_new()) - * retrieve the callback function from a fixed offset in the class structure. - * The meta marshaller retrieves the right callback and passes it to the - * marshaller as the @marshal_data argument. + * + * Sets the meta marshaller of @closure. A meta marshaller wraps + * @closure->marshal and modifies the way it is called in some + * fashion. The most common use of this facility is for C callbacks. + * The same marshallers (generated by <link + * linkend="glib-genmarshal">glib-genmarshal</link>) are used + * everywhere, but the way that we get the callback function + * differs. In most cases we want to use @closure->callback, but in + * other cases we want to use some different technique to retrieve the + * callback function. + * + * For example, class closures for signals (see + * g_signal_type_cclosure_new()) retrieve the callback function from a + * fixed offset in the class structure. The meta marshaller retrieves + * the right callback and passes it to the marshaller as the + * @marshal_data argument. */ void g_closure_set_meta_marshal (GClosure *closure, @@ -346,11 +352,11 @@ g_closure_set_meta_marshal (GClosure *closure, * @pre_marshal_notify: a function to call before the closure callback * @post_marshal_data: data to pass to @post_marshal_notify * @post_marshal_notify: a function to call after the closure callback - * - * Adds a pair of notifiers which get invoked before and after the closure - * callback, respectively. This is typically used to protect the extra arguments - * for the duration of the callback. See g_object_watch_closure() for an - * example of marshal guards. + * + * Adds a pair of notifiers which get invoked before and after the + * closure callback, respectively. This is typically used to protect + * the extra arguments for the duration of the callback. See + * g_object_watch_closure() for an example of marshal guards. */ void g_closure_add_marshal_guards (GClosure *closure, @@ -402,13 +408,13 @@ g_closure_add_marshal_guards (GClosure *closure, * @closure: a #GClosure * @notify_data: data to pass to @notify_func * @notify_func: the callback function to register - * - * Registers a finalization notifier which will be called when the reference - * count of @closure goes down to 0. Multiple finalization notifiers on a - * single closure are invoked in unspecified order. If a single call to - * g_closure_unref() results in the closure being both invalidated and - * finalized, then the invalidate notifiers will be run before the finalize - * notifiers. + * + * Registers a finalization notifier which will be called when the + * reference count of @closure goes down to 0. Multiple finalization + * notifiers on a single closure are invoked in unspecified order. If + * a single call to g_closure_unref() results in the closure being + * both invalidated and finalized, then the invalidate notifiers will + * be run before the finalize notifiers. */ void g_closure_add_finalize_notifier (GClosure *closure, @@ -438,10 +444,11 @@ g_closure_add_finalize_notifier (GClosure *closure, * @closure: a #GClosure * @notify_data: data to pass to @notify_func * @notify_func: the callback function to register - * - * Registers an invalidation notifier which will be called when the @closure - * is invalidated with g_closure_invalidate(). Invalidation notifiers are - * invoked before finalization notifiers, in an unspecified order. + * + * Registers an invalidation notifier which will be called when the + * @closure is invalidated with g_closure_invalidate(). Invalidation + * notifiers are invoked before finalization notifiers, in an + * unspecified order. */ void g_closure_add_invalidate_notifier (GClosure *closure, @@ -509,10 +516,10 @@ closure_try_remove_fnotify (GClosure *closure, /** * g_closure_ref: * @closure: #GClosure to increment the reference count on - * + * * Increments the reference count on a closure to force it staying * alive while the caller holds a pointer to it. - * + * * Returns: The @closure passed in, for convenience */ GClosure* @@ -532,18 +539,20 @@ g_closure_ref (GClosure *closure) /** * g_closure_invalidate: * @closure: GClosure to invalidate - * - * Sets a flag on the closure to indicate that it's calling environment has - * become invalid, and thus causes any future invocations of g_closure_invoke() - * on this @closure to be ignored. Also, invalidation notifiers installed on - * the closure will be called at this point. Note that unless you are holding - * a reference to the closure yourself, the invalidation notifiers may unref - * the closure and cause it to be destroyed, so if you need to access the - * closure after calling g_closure_invalidate(), make sure that you've - * previously called g_closure_ref(). - * - * Note that g_closure_invalidate() will also be called when the reference count - * of a closure drops to zero (unless it has already been invalidated before). + * + * Sets a flag on the closure to indicate that it's calling + * environment has become invalid, and thus causes any future + * invocations of g_closure_invoke() on this @closure to be + * ignored. Also, invalidation notifiers installed on the closure will + * be called at this point. Note that unless you are holding a + * reference to the closure yourself, the invalidation notifiers may + * unref the closure and cause it to be destroyed, so if you need to + * access the closure after calling g_closure_invalidate(), make sure + * that you've previously called g_closure_ref(). + * + * Note that g_closure_invalidate() will also be called when the + * reference count of a closure drops to zero (unless it has already + * been invalidated before). */ void g_closure_invalidate (GClosure *closure) @@ -565,10 +574,10 @@ g_closure_invalidate (GClosure *closure) /** * g_closure_unref: * @closure: #GClosure to decrement the reference count on - * - * Decrements the reference count of a closure after it was previously - * incremented by the same caller. If no other callers are using the closure, - * then the closure will be destroyed and freed. + * + * Decrements the reference count of a closure after it was previously + * incremented by the same caller. If no other callers are using the + * closure, then the closure will be destroyed and freed. */ void g_closure_unref (GClosure *closure) @@ -594,27 +603,28 @@ g_closure_unref (GClosure *closure) /** * g_closure_sink: * @closure: #GClosure to decrement the initial reference count on, if it's - * still being held - * - * Takes over the initial ownership of a closure. - * Each closure is initially created in a <firstterm>floating</firstterm> state, - * which means that the initial reference count is not owned by any caller. - * g_closure_sink() checks to see if the object is still floating, and if so, - * unsets the floating state and decreases the reference count. If the closure - * is not floating, g_closure_sink() does nothing. The reason for the existance - * of the floating state is to prevent cumbersome code sequences like: + * still being held + * + * Takes over the initial ownership of a closure. Each closure is + * initially created in a <firstterm>floating</firstterm> state, which + * means that the initial reference count is not owned by any caller. + * g_closure_sink() checks to see if the object is still floating, and + * if so, unsets the floating state and decreases the reference + * count. If the closure is not floating, g_closure_sink() does + * nothing. The reason for the existance of the floating state is to + * prevent cumbersome code sequences like: * |[ - * closure = g_cclosure_new (cb_func, cb_data); - * g_source_set_closure (source, closure); + * closure = g_cclosure_new (cb_func, cb_data); + * g_source_set_closure (source, closure); * g_closure_unref (closure); // XXX GObject doesn't really need this * ]| - * Because g_source_set_closure() (and similar functions) take ownership of the - * initial reference count, if it is unowned, we instead can write: + * Because g_source_set_closure() (and similar functions) take ownership of the + * initial reference count, if it is unowned, we instead can write: * |[ * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); * ]| - * - * Generally, this function is used together with g_closure_ref(). Ane example + * + * Generally, this function is used together with g_closure_ref(). Ane example * of storing a closure for later notification looks like: * |[ * static GClosure *notify_closure = NULL; @@ -631,7 +641,7 @@ g_closure_unref (GClosure *closure) * } * } * ]| - * + * * Because g_closure_sink() may decrement the reference count of a closure * (if it hasn't been called on @closure yet) just like g_closure_unref(), * g_closure_ref() should be called prior to this function. @@ -661,12 +671,11 @@ g_closure_sink (GClosure *closure) * g_closure_remove_invalidate_notifier: * @closure: a #GClosure * @notify_data: data which was passed to g_closure_add_invalidate_notifier() - * when registering @notify_func + * when registering @notify_func * @notify_func: the callback function to remove - * + * * Removes an invalidation notifier. - * - * + * * Notice that notifiers are automatically removed after they are run. */ void @@ -692,9 +701,9 @@ g_closure_remove_invalidate_notifier (GClosure *closure, * @notify_data: data which was passed to g_closure_add_finalize_notifier() * when registering @notify_func * @notify_func: the callback function to remove - * + * * Removes a finalization notifier. - * + * * Notice that notifiers are automatically removed after they are run. */ void @@ -718,12 +727,12 @@ g_closure_remove_finalize_notifier (GClosure *closure, * g_closure_invoke: * @closure: a #GClosure * @return_value: a #GValue to store the return value. May be %NULL if the - * callback of @closure doesn't return a value. + * callback of @closure doesn't return a value. * @n_param_values: the length of the @param_values array * @param_values: an array of #GValue<!-- -->s holding the arguments on - * which to invoke the callback of @closure + * which to invoke the callback of @closure * @invocation_hint: a context-dependent invocation hint - * + * * Invokes the closure, i.e. executes the callback represented by the @closure. */ void @@ -773,7 +782,7 @@ g_closure_invoke (GClosure *closure, * g_closure_set_marshal: * @closure: a #GClosure * @marshal: a #GClosureMarshal function - * + * * Sets the marshaller of @closure. The <literal>marshal_data</literal> * of @marshal provides a way for a meta marshaller to provide additional * information to the marshaller. (See g_closure_set_meta_marshal().) For @@ -800,10 +809,10 @@ g_closure_set_marshal (GClosure *closure, * @callback_func: the function to invoke * @user_data: user data to pass to @callback_func * @destroy_data: destroy notify to be called when @user_data is no longer used - * - * Creates a new closure which invokes @callback_func with @user_data as - * the last parameter. - * + * + * Creates a new closure which invokes @callback_func with @user_data as + * the last parameter. + * * Returns: a new #GCClosure */ GClosure* @@ -828,10 +837,10 @@ g_cclosure_new (GCallback callback_func, * @callback_func: the function to invoke * @user_data: user data to pass to @callback_func * @destroy_data: destroy notify to be called when @user_data is no longer used - * - * Creates a new closure which invokes @callback_func with @user_data as - * the first parameter. - * + * + * Creates a new closure which invokes @callback_func with @user_data as + * the first parameter. + * * Returns: a new #GCClosure */ GClosure* @@ -901,13 +910,13 @@ g_type_iface_meta_marshal (GClosure *closure, /** * g_signal_type_cclosure_new: * @itype: the #GType identifier of an interface or classed type - * @struct_offset: the offset of the member function of @itype's class + * @struct_offset: the offset of the member function of @itype's class * structure which is to be invoked by the new closure - * + * * Creates a new closure which invokes the function found at the offset * @struct_offset in the class structure of the interface or classed type * identified by @itype. - * + * * Returns: a new #GCClosure */ GClosure* @@ -938,10 +947,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__BOOLEAN: * @closure: the #GClosure to which the marshaller belongs @@ -951,10 +961,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__CHAR: * @closure: the #GClosure to which the marshaller belongs @@ -964,10 +975,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__UCHAR: * @closure: the #GClosure to which the marshaller belongs @@ -977,10 +989,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__INT: * @closure: the #GClosure to which the marshaller belongs @@ -990,10 +1003,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__UINT: * @closure: the #GClosure to which the marshaller belongs @@ -1003,10 +1017,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__LONG: * @closure: the #GClosure to which the marshaller belongs @@ -1016,10 +1031,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__ULONG: * @closure: the #GClosure to which the marshaller belongs @@ -1029,10 +1045,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__ENUM: * @closure: the #GClosure to which the marshaller belongs @@ -1042,10 +1059,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type.. */ + /** * g_cclosure_marshal_VOID__FLAGS: * @closure: the #GClosure to which the marshaller belongs @@ -1055,10 +1073,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type. */ + /** * g_cclosure_marshal_VOID__FLOAT: * @closure: the #GClosure to which the marshaller belongs @@ -1068,10 +1087,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__DOUBLE: * @closure: the #GClosure to which the marshaller belongs @@ -1081,10 +1101,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__STRING: * @closure: the #GClosure to which the marshaller belongs @@ -1094,10 +1115,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__PARAM: * @closure: the #GClosure to which the marshaller belongs @@ -1107,10 +1129,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__BOXED: * @closure: the #GClosure to which the marshaller belongs @@ -1120,10 +1143,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__POINTER: * @closure: the #GClosure to which the marshaller belongs @@ -1133,10 +1157,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__OBJECT: * @closure: the #GClosure to which the marshaller belongs @@ -1146,10 +1171,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_VOID__UINT_POINTER: * @closure: the #GClosure to which the marshaller belongs @@ -1159,10 +1185,11 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>. */ + /** * g_cclosure_marshal_BOOLEAN__FLAGS: * @closure: the #GClosure to which the marshaller belongs @@ -1172,14 +1199,15 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter * denotes a flags type. */ + /** * g_cclosure_marshal_BOOL__FLAGS: - * + * * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). */ /** @@ -1191,7 +1219,7 @@ g_signal_type_cclosure_new (GType itype, * @invocation_hint: the invocation hint given as the last argument * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller - * + * * A marshaller for a #GCClosure with a callback of type * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>. */ diff --git a/gobject/genums.c b/gobject/genums.c index f90cc7b4b..bf8e3eb14 100644 --- a/gobject/genums.c +++ b/gobject/genums.c @@ -171,16 +171,17 @@ value_flags_enum_lcopy_value (const GValue *value, * g_enum_register_static: * @name: A nul-terminated string used as the name of the new type. * @const_static_values: An array of #GEnumValue structs for the possible - * enumeration values. The array is terminated by a struct with all + * enumeration values. The array is terminated by a struct with all * members being 0. GObject keeps a reference to the data, so it cannot * be stack-allocated. - * - * Registers a new static enumeration type with the name @name. - * - * It is normally more convenient to let <link linkend="glib-mkenums">glib-mkenums</link> - * generate a my_enum_get_type() function from a usual C enumeration definition + * + * Registers a new static enumeration type with the name @name. + * + * It is normally more convenient to let <link + * linkend="glib-mkenums">glib-mkenums</link> generate a + * my_enum_get_type() function from a usual C enumeration definition * than to write one yourself using g_enum_register_static(). - * + * * Returns: The new type identifier. */ GType @@ -217,13 +218,14 @@ g_enum_register_static (const gchar *name, * @const_static_values: An array of #GFlagsValue structs for the possible * flags values. The array is terminated by a struct with all members being 0. * GObject keeps a reference to the data, so it cannot be stack-allocated. - * - * Registers a new static flags type with the name @name. - * - * It is normally more convenient to let <link linkend="glib-mkenums">glib-mkenums</link> - * generate a my_flags_get_type() function from a usual C enumeration definition + * + * Registers a new static flags type with the name @name. + * + * It is normally more convenient to let <link + * linkend="glib-mkenums">glib-mkenums</link> generate a + * my_flags_get_type() function from a usual C enumeration definition * than to write one yourself using g_flags_register_static(). - * + * * Returns: The new type identifier. */ GType @@ -259,12 +261,13 @@ g_flags_register_static (const gchar *name, * @g_enum_type: the type identifier of the type being completed * @info: the #GTypeInfo struct to be filled in * @const_values: An array of #GEnumValue structs for the possible - * enumeration values. The array is terminated by a struct with all + * enumeration values. The array is terminated by a struct with all * members being 0. - * - * This function is meant to be called from the complete_type_info() function - * of a #GTypePlugin implementation, as in the following example: - * + * + * This function is meant to be called from the complete_type_info() + * function of a #GTypePlugin implementation, as in the following + * example: + * * |[ * static void * my_enum_complete_type_info (GTypePlugin *plugin, @@ -276,9 +279,9 @@ g_flags_register_static (const gchar *name, * { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, * { 0, NULL, NULL } - * }; - * - * g_enum_complete_type_info (type, info, values); + * }; + * + * g_enum_complete_type_info (type, info, values); * } * ]| */ @@ -304,11 +307,11 @@ g_enum_complete_type_info (GType g_enum_type, * @g_flags_type: the type identifier of the type being completed * @info: the #GTypeInfo struct to be filled in * @const_values: An array of #GFlagsValue structs for the possible - * enumeration values. The array is terminated by a struct with all + * enumeration values. The array is terminated by a struct with all * members being 0. - * - * This function is meant to be called from the complete_type_info() function - * of a #GTypePlugin implementation, see the example for + * + * This function is meant to be called from the complete_type_info() + * function of a #GTypePlugin implementation, see the example for * g_enum_complete_type_info() above. */ void @@ -380,11 +383,11 @@ g_flags_class_init (GFlagsClass *class, * g_enum_get_value_by_name: * @enum_class: a #GEnumClass * @name: the name to look up - * + * * Looks up a #GEnumValue by name. - * - * Returns: the #GEnumValue with name @name, or %NULL if the enumeration doesn' - * t have a member with that name + * + * Returns: the #GEnumValue with name @name, or %NULL if the + * enumeration doesn't have a member with that name */ GEnumValue* g_enum_get_value_by_name (GEnumClass *enum_class, @@ -409,11 +412,11 @@ g_enum_get_value_by_name (GEnumClass *enum_class, * g_flags_get_value_by_name: * @flags_class: a #GFlagsClass * @name: the name to look up - * + * * Looks up a #GFlagsValue by name. - * - * Returns: the #GFlagsValue with name @name, or %NULL if there is no flag with - * that name + * + * Returns: the #GFlagsValue with name @name, or %NULL if there is no + * flag with that name */ GFlagsValue* g_flags_get_value_by_name (GFlagsClass *flags_class, @@ -438,11 +441,11 @@ g_flags_get_value_by_name (GFlagsClass *flags_class, * g_enum_get_value_by_nick: * @enum_class: a #GEnumClass * @nick: the nickname to look up - * + * * Looks up a #GEnumValue by nickname. - * - * Returns: the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn' - * t have a member with that nickname + * + * Returns: the #GEnumValue with nickname @nick, or %NULL if the + * enumeration doesn't have a member with that nickname */ GEnumValue* g_enum_get_value_by_nick (GEnumClass *enum_class, @@ -467,11 +470,11 @@ g_enum_get_value_by_nick (GEnumClass *enum_class, * g_flags_get_value_by_nick: * @flags_class: a #GFlagsClass * @nick: the nickname to look up - * + * * Looks up a #GFlagsValue by nickname. - * - * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is no flag - * with that nickname + * + * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is + * no flag with that nickname */ GFlagsValue* g_flags_get_value_by_nick (GFlagsClass *flags_class, @@ -496,11 +499,11 @@ g_flags_get_value_by_nick (GFlagsClass *flags_class, * g_enum_get_value: * @enum_class: a #GEnumClass * @value: the value to look up - * + * * Returns the #GEnumValue for a value. - * - * Returns: the #GEnumValue for @value, or %NULL if @value is not - * a member of the enumeration + * + * Returns: the #GEnumValue for @value, or %NULL if @value is not a + * member of the enumeration */ GEnumValue* g_enum_get_value (GEnumClass *enum_class, @@ -524,10 +527,11 @@ g_enum_get_value (GEnumClass *enum_class, * g_flags_get_first_value: * @flags_class: a #GFlagsClass * @value: the value - * + * * Returns the first #GFlagsValue which is set in @value. - * - * Returns: the first #GFlagsValue which is set in @value, or %NULL if none is set + * + * Returns: the first #GFlagsValue which is set in @value, or %NULL if + * none is set */ GFlagsValue* g_flags_get_first_value (GFlagsClass *flags_class, @@ -560,7 +564,7 @@ g_flags_get_first_value (GFlagsClass *flags_class, * g_value_set_enum: * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM * @v_enum: enum value to be set - * + * * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. */ void @@ -575,9 +579,9 @@ g_value_set_enum (GValue *value, /** * g_value_get_enum: * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM - * + * * Get the contents of a %G_TYPE_ENUM #GValue. - * + * * Returns: enum contents of @value */ gint @@ -592,7 +596,7 @@ g_value_get_enum (const GValue *value) * g_value_set_flags: * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS * @v_flags: flags value to be set - * + * * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. */ void @@ -607,9 +611,9 @@ g_value_set_flags (GValue *value, /** * g_value_get_flags: * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS - * + * * Get the contents of a %G_TYPE_FLAGS #GValue. - * + * * Returns: flags contents of @value */ guint diff --git a/gobject/gobject.c b/gobject/gobject.c index bb2e36b3e..86d7f7191 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -41,8 +41,11 @@ /** * 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 @@ -198,6 +201,7 @@ G_LOCK_DEFINE_STATIC (debug_objects); static volatile GObject *g_trap_object_ref = NULL; static guint debug_objects_count = 0; static GHashTable *debug_objects_ht = NULL; + static void debug_objects_foreach (gpointer key, gpointer value, @@ -210,6 +214,7 @@ debug_objects_foreach (gpointer key, G_OBJECT_TYPE_NAME (object), object->ref_count); } + static void debug_objects_atexit (void) { @@ -337,13 +342,14 @@ g_object_do_class_init (GObjectClass *class) * 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 + * + * 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: * |[ @@ -351,7 +357,7 @@ g_object_do_class_init (GObjectClass *class) * G_CALLBACK (gtk_text_view_target_list_notify), * text_view) * ]| - * It is important to note that you must use + * 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. */ @@ -395,7 +401,7 @@ install_property_internal (GType g_type, * @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 @@ -434,7 +440,7 @@ g_object_class_install_property (GObjectClass *class, * @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 @@ -444,12 +450,12 @@ g_object_class_install_property (GObjectClass *class, * 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 @@ -470,11 +476,11 @@ g_object_interface_install_property (gpointer g_iface, * 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 + * + * 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, @@ -507,17 +513,17 @@ g_object_class_find_property (GObjectClass *class, * @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. + * + * 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, @@ -540,13 +546,13 @@ g_object_interface_find_property (gpointer g_iface, * @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 @@ -559,7 +565,7 @@ g_object_interface_find_property (gpointer g_iface, * need to get the overridden property, you can call * g_param_spec_get_redirect_target(). * </note> - * + * * Since: 2.4 */ void @@ -617,9 +623,9 @@ g_object_class_override_property (GObjectClass *oclass, * 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 */ @@ -645,16 +651,18 @@ g_object_class_list_properties (GObjectClass *class, * @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. + * + * 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, @@ -767,10 +775,10 @@ g_object_dispatch_properties_changed (GObject *object, /** * g_object_run_dispose: * @object: a #GObject - * - * Releases all references to other objects. This can be used to break + * + * 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 @@ -787,10 +795,10 @@ g_object_run_dispose (GObject *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. - * + * 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. */ @@ -811,8 +819,8 @@ g_object_freeze_notify (GObject *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. + * + * Emits a "notify" signal for the property @property_name on @object. */ void g_object_notify (GObject *object, @@ -854,7 +862,7 @@ g_object_notify (GObject *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. */ @@ -1021,12 +1029,12 @@ object_interface_check_properties (gpointer func_data, * @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) + * + * 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 @@ -1083,12 +1091,12 @@ object_in_construction_list (GObject *object) * @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) + * + * 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 @@ -1236,12 +1244,12 @@ g_object_newv (GType object_type, * @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) + * + * 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* @@ -1350,7 +1358,7 @@ g_object_constructor (GType type, * @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 @@ -1427,13 +1435,13 @@ g_object_set_valist (GObject *object, * @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(). - * + * + * 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 @@ -1503,7 +1511,7 @@ g_object_get_valist (GObject *object, * @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 @@ -1527,13 +1535,13 @@ g_object_set (gpointer _object, * @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(). - * + * + * 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 @@ -1542,16 +1550,16 @@ g_object_set (gpointer _object, * <programlisting> * gint intval; * gchar *strval; - * GObject *objval; - * + * 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> @@ -1577,7 +1585,7 @@ g_object_get (gpointer _object, * @object: a #GObject * @property_name: the name of the property to set * @value: the value - * + * * Sets a property on an object. */ void @@ -1624,12 +1632,12 @@ g_object_set_property (GObject *object, * @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. */ @@ -1700,12 +1708,12 @@ g_object_get_property (GObject *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 - * + * @...: #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> @@ -1765,7 +1773,7 @@ g_object_get_property (GObject *object, * </para></listitem> * </varlistentry> * </variablelist> - * + * * |[ * menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, * "type", GTK_WINDOW_POPUP, @@ -1776,7 +1784,7 @@ g_object_get_property (GObject *object, * "signal::destroy", gtk_widget_destroyed, &menu->toplevel, * NULL); * ]| - * + * * Returns: @object */ gpointer @@ -1852,15 +1860,16 @@ g_object_connect (gpointer _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, + * @...: #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". + * + * 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, @@ -1935,12 +1944,12 @@ weak_refs_notify (gpointer data) * @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). + * + * 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, @@ -1977,7 +1986,7 @@ g_object_weak_ref (GObject *object, * @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 @@ -2016,11 +2025,11 @@ g_object_weak_unref (GObject *object, * 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. + * 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, @@ -2038,7 +2047,7 @@ g_object_add_weak_pointer (GObject *object, * 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(). @@ -2082,11 +2091,12 @@ object_floating_flag_handler (GObject *object, /** * 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 @@ -2100,18 +2110,19 @@ g_object_is_floating (gpointer _object) /** * g_object_ref_sink: * @object: a #GObject - * - * Increase the reference count of @object, and possibly remove the + * + * 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. - * + * + * 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 @@ -2131,13 +2142,13 @@ g_object_ref_sink (gpointer _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 + * #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 @@ -2179,18 +2190,18 @@ toggle_refs_notify (GObject *object, * 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 @@ -2198,17 +2209,17 @@ toggle_refs_notify (GObject *object, * 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 @@ -2250,7 +2261,7 @@ g_object_add_toggle_ref (GObject *object, g_datalist_id_set_data_full (&object->qdata, quark_toggle_refs, tstack, (GDestroyNotify)g_free); } - + /** * g_object_remove_toggle_ref: * @object: a #GObject @@ -2258,10 +2269,10 @@ g_object_add_toggle_ref (GObject *object, * 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 @@ -2305,9 +2316,9 @@ g_object_remove_toggle_ref (GObject *object, /** * g_object_ref: * @object: a #GObject - * + * * Increases the reference count of @object. - * + * * Returns: the same @object */ gpointer @@ -2336,10 +2347,9 @@ g_object_ref (gpointer _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). + * + * 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) @@ -2438,7 +2448,7 @@ g_object_get_qdata (GObject *object, * @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 @@ -2464,8 +2474,9 @@ g_object_set_qdata (GObject *object, * @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 - * + * @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 @@ -2489,7 +2500,7 @@ g_object_set_qdata_full (GObject *object, * 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 @@ -2505,7 +2516,7 @@ g_object_set_qdata_full (GObject *object, * 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 @@ -2515,16 +2526,17 @@ g_object_set_qdata_full (GObject *object, * 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(). - * + * 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 @@ -2565,10 +2577,10 @@ g_object_get_data (GObject *object, * @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. */ @@ -2589,11 +2601,11 @@ g_object_set_data (GObject *object, * @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 + * 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 @@ -2613,10 +2625,10 @@ g_object_set_data_full (GObject *object, * 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 @@ -2728,16 +2740,15 @@ g_value_object_lcopy_value (const GValue *value, * g_value_set_object: * @value: a valid #GValue of %G_TYPE_OBJECT derived type * @v_object: object value to be set - * + * * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. - * + * * g_value_set_object() increases the reference count of @v_object - * (the #GValue holds a reference to @v_object). - * If you do not wish to increase the reference count of the object - * (i.e. you wish to pass your current reference to the #GValue because you no - * longer need it), - * use g_value_take_object() instead. - * + * (the #GValue holds a reference to @v_object). If you do not wish + * to increase the reference count of the object (i.e. you wish to + * pass your current reference to the #GValue because you no longer + * need it), use g_value_take_object() instead. + * * It is important that your #GValue holds a reference to @v_object (either its * own, or one it has taken) to ensure that the object won't be destroyed while * the #GValue still exists). @@ -2771,9 +2782,9 @@ g_value_set_object (GValue *value, * g_value_set_object_take_ownership: * @value: a valid #GValue of %G_TYPE_OBJECT derived type * @v_object: object value to be set - * + * * This is an internal function introduced mainly for C marshallers. - * + * * Deprecated: 2.4: Use g_value_take_object() instead. */ void @@ -2787,15 +2798,15 @@ g_value_set_object_take_ownership (GValue *value, * g_value_take_object: * @value: a valid #GValue of %G_TYPE_OBJECT derived type * @v_object: object value to be set - * - * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object - * and takes over the ownership of the callers reference to @v_object; + * + * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object + * and takes over the ownership of the callers reference to @v_object; * the caller doesn't have to unref it any more (i.e. the reference * count of the object is not increased). - * + * * If you want the #GValue to hold its own reference to @v_object, use * g_value_set_object() instead. - * + * * Since: 2.4 */ void @@ -2838,10 +2849,12 @@ g_value_get_object (const GValue *value) /** * g_value_dup_object: * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT - * - * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing its reference count. - * - * Returns: object content of @value, should be unreferenced when no longer needed. + * + * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing + * its reference count. + * + * Returns: object content of @value, should be unreferenced when no + * longer needed. */ gpointer g_value_dup_object (const GValue *value) @@ -2858,30 +2871,30 @@ g_value_dup_object (const GValue *value) * @c_handler: the #GCallback to connect. * @gobject: the object to pass as data to @c_handler. * @connect_flags: a combination of #GConnnectFlags. - * - * This is similar to g_signal_connect_data(), but uses a closure which - * ensures that the @gobject stays alive during the call to @c_handler - * by temporarily adding a reference count to @gobject. - * - * Note that there is a bug in GObject that makes this function - * much less useful than it might seem otherwise. Once @gobject is - * disposed, the callback will no longer be called, but, the signal - * handler is <emphasis>not</emphasis> currently disconnected. If the - * @instance is itself being freed at the same time than this doesn't - * matter, since the signal will automatically be removed, but - * if @instance persists, then the signal handler will leak. You - * should not remove the signal yourself because in a future versions of - * GObject, the handler <emphasis>will</emphasis> automatically - * be disconnected. - * - * It's possible to work around this problem in a way that will - * continue to work with future versions of GObject by checking - * that the signal handler is still connected before disconnected it: + * + * This is similar to g_signal_connect_data(), but uses a closure which + * ensures that the @gobject stays alive during the call to @c_handler + * by temporarily adding a reference count to @gobject. + * + * Note that there is a bug in GObject that makes this function + * much less useful than it might seem otherwise. Once @gobject is + * disposed, the callback will no longer be called, but, the signal + * handler is <emphasis>not</emphasis> currently disconnected. If the + * @instance is itself being freed at the same time than this doesn't + * matter, since the signal will automatically be removed, but + * if @instance persists, then the signal handler will leak. You + * should not remove the signal yourself because in a future versions of + * GObject, the handler <emphasis>will</emphasis> automatically + * be disconnected. + * + * It's possible to work around this problem in a way that will + * continue to work with future versions of GObject by checking + * that the signal handler is still connected before disconnected it: * <informalexample><programlisting> * if (g_signal_handler_is_connected (instance, id)) * g_signal_handler_disconnect (instance, id); * </programlisting></informalexample> - * + * * Returns: the handler id. */ gulong @@ -2976,16 +2989,16 @@ destroy_closure_array (gpointer data) * 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. + * + * 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, @@ -3023,16 +3036,16 @@ g_object_watch_closure (GObject *object, /** * g_closure_new_object: - * @sizeof_closure: the size of the structure to allocate, must be at least + * @sizeof_closure: the size of the structure to allocate, must be at least * <literal>sizeof (GClosure)</literal> - * @object: a #GObject pointer to store in the @data field of the newly + * @object: a #GObject pointer to store in the @data field of the newly * allocated #GClosure - * - * A variant of g_closure_new_simple() which stores @object in the @data - * field of the closure and calls g_object_watch_closure() on @object and the - * created closure. This function is mainly useful when implementing new types - * of closures. - * + * + * A variant of g_closure_new_simple() which stores @object in the + * @data field of the closure and calls g_object_watch_closure() on + * @object and the created closure. This function is mainly useful + * when implementing new types of closures. + * * Returns: a newly allocated #GClosure */ GClosure* @@ -3054,12 +3067,13 @@ g_closure_new_object (guint sizeof_closure, * g_cclosure_new_object: * @callback_func: the function to invoke * @object: a #GObject pointer to pass to @callback_func - * - * A variant of g_cclosure_new() which uses @object as @user_data and calls - * g_object_watch_closure() on @object and the created closure. This function - * is useful when you have a callback closely associated with a #GObject, - * and want the callback to no longer run after the object is is freed. - * + * + * A variant of g_cclosure_new() which uses @object as @user_data and + * calls g_object_watch_closure() on @object and the created + * closure. This function is useful when you have a callback closely + * associated with a #GObject, and want the callback to no longer run + * after the object is is freed. + * * Returns: a new #GCClosure */ GClosure* @@ -3082,12 +3096,13 @@ g_cclosure_new_object (GCallback callback_func, * g_cclosure_new_object_swap: * @callback_func: the function to invoke * @object: a #GObject pointer to pass to @callback_func - * - * A variant of g_cclosure_new_swap() which uses @object as @user_data and calls - * g_object_watch_closure() on @object and the created closure. This function - * is useful when you have a callback closely associated with a #GObject, - * and want the callback to no longer run after the object is is freed. - * + * + * A variant of g_cclosure_new_swap() which uses @object as @user_data + * and calls g_object_watch_closure() on @object and the created + * closure. This function is useful when you have a callback closely + * associated with a #GObject, and want the callback to no longer run + * after the object is is freed. + * * Returns: a new #GCClosure */ GClosure* diff --git a/gobject/gparam.c b/gobject/gparam.c index e9b12926d..0f5a52aaf 100644 --- a/gobject/gparam.c +++ b/gobject/gparam.c @@ -33,9 +33,13 @@ /** * SECTION:gparamspec + * * @Short_description: Metadata for parameter specifications - * @See_also:g_object_class_install_property(), g_object_set(), g_object_get(), - * g_object_set_property(), g_object_get_property(), g_value_register_transform_func() + * + * @See_also:g_object_class_install_property(), g_object_set(), + * g_object_get(), g_object_set_property(), g_object_get_property(), + * g_value_register_transform_func() + * * @Title: GParamSpec * * #GParamSpec is an object structure that encapsulates the metadata @@ -184,9 +188,9 @@ g_param_spec_finalize (GParamSpec *pspec) /** * g_param_spec_ref: * @pspec: a valid #GParamSpec - * + * * Increments the reference count of @pspec. - * + * * Returns: the #GParamSpec that was passed into this function */ GParamSpec* @@ -203,7 +207,7 @@ g_param_spec_ref (GParamSpec *pspec) /** * g_param_spec_unref: * @pspec: a valid #GParamSpec - * + * * Decrements the reference count of a @pspec. */ void @@ -225,14 +229,14 @@ g_param_spec_unref (GParamSpec *pspec) /** * g_param_spec_sink: * @pspec: a valid #GParamSpec - * - * The initial reference count of a newly created #GParamSpec is 1, even - * though no one has explicitly called g_param_spec_ref() on it yet. So the - * initial reference count is flagged as "floating", until someone calls - * <literal>g_param_spec_ref (pspec); g_param_spec_sink (pspec);</literal> - * in sequence on it, taking over the initial reference count (thus - * ending up with a @pspec that has a reference count of 1 still, but is - * not flagged "floating" anymore). + * + * The initial reference count of a newly created #GParamSpec is 1, + * even though no one has explicitly called g_param_spec_ref() on it + * yet. So the initial reference count is flagged as "floating", until + * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink + * (pspec);</literal> in sequence on it, taking over the initial + * reference count (thus ending up with a @pspec that has a reference + * count of 1 still, but is not flagged "floating" anymore). */ void g_param_spec_sink (GParamSpec *pspec) @@ -252,9 +256,9 @@ g_param_spec_sink (GParamSpec *pspec) /** * g_param_spec_ref_sink: * @pspec: a valid #GParamSpec - * + * * Convenience function to ref and sink a #GParamSpec. - * + * * Since: 2.10 * Returns: the #GParamSpec that was passed into this function */ @@ -272,9 +276,9 @@ g_param_spec_ref_sink (GParamSpec *pspec) /** * g_param_spec_get_name: * @pspec: a valid #GParamSpec - * + * * Get the name of a #GParamSpec. - * + * * Returns: the name of @pspec. */ G_CONST_RETURN gchar* @@ -288,9 +292,9 @@ g_param_spec_get_name (GParamSpec *pspec) /** * g_param_spec_get_nick: * @pspec: a valid #GParamSpec - * + * * Get the nickname of a #GParamSpec. - * + * * Returns: the nickname of @pspec. */ G_CONST_RETURN gchar* @@ -315,9 +319,9 @@ g_param_spec_get_nick (GParamSpec *pspec) /** * g_param_spec_get_blurb: * @pspec: a valid #GParamSpec - * + * * Get the short description of a #GParamSpec. - * + * * Returns: the short description of @pspec. */ G_CONST_RETURN gchar* @@ -382,24 +386,25 @@ is_canonical (const gchar *key) * @nick: the nickname of the property * @blurb: a short description of the property * @flags: a combination of #GParamFlags - * + * * Creates a new #GParamSpec instance. - * + * * A property name consists of segments consisting of ASCII letters and * digits, separated by either the '-' or '_' character. The first * character of a property name must be a letter. Names which violate these - * rules lead to undefined behaviour. - * - * When creating and looking up a #GParamSpec, either separator can be used, - * but they cannot be mixed. Using '-' is considerably more efficient and in - * fact required when using property names as detail strings for signals. - * - * Beyond the name, #GParamSpec<!-- -->s have two more descriptive strings - * associated with them, the @nick, which should be suitable for use as - * a label for the property in a property editor, and the @blurb, which should - * be a somewhat longer description, suitable for e.g. a tooltip. The @nick - * and @blurb should ideally be localized. - * + * rules lead to undefined behaviour. + * + * When creating and looking up a #GParamSpec, either separator can be + * used, but they cannot be mixed. Using '-' is considerably more + * efficient and in fact required when using property names as detail + * strings for signals. + * + * Beyond the name, #GParamSpec<!-- -->s have two more descriptive + * strings associated with them, the @nick, which should be suitable + * for use as a label for the property in a property editor, and the + * @blurb, which should be a somewhat longer description, suitable for + * e.g. a tooltip. The @nick and @blurb should ideally be localized. + * * Returns: a newly allocated #GParamSpec instance */ gpointer @@ -450,9 +455,9 @@ g_param_spec_internal (GType param_type, * g_param_spec_get_qdata: * @pspec: a valid #GParamSpec * @quark: a #GQuark, naming the user data pointer - * + * * Gets back user data pointers stored via g_param_spec_set_qdata(). - * + * * Returns: the user data pointer set, or %NULL */ gpointer @@ -469,13 +474,13 @@ g_param_spec_get_qdata (GParamSpec *pspec, * @pspec: the #GParamSpec to set store a user data pointer * @quark: a #GQuark, naming the user data pointer * @data: an opaque user data pointer - * - * Sets an opaque, named pointer on a #GParamSpec. The name is specified - * through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and - * the pointer can be gotten back from the @pspec with g_param_spec_get_qdata(). - * Setting a previously set user data pointer, overrides (frees) - * the old pointer set, using %NULL as pointer essentially - * removes the data stored. + * + * Sets an opaque, named pointer on a #GParamSpec. The name is + * specified through a #GQuark (retrieved e.g. via + * g_quark_from_static_string()), and the pointer can be gotten back + * from the @pspec with g_param_spec_get_qdata(). Setting a + * previously set user data pointer, overrides (frees) the old pointer + * set, using %NULL as pointer essentially removes the data stored. */ void g_param_spec_set_qdata (GParamSpec *pspec, @@ -495,11 +500,11 @@ g_param_spec_set_qdata (GParamSpec *pspec, * @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_param_spec_set_qdata(), but in addition, - * a <literal>void (*destroy) (gpointer)</literal> function may be - * specified which is called with @data as argument when the @pspec is - * finalized, or the data is being overwritten by a call to + * + * This function works like g_param_spec_set_qdata(), but in addition, + * a <literal>void (*destroy) (gpointer)</literal> function may be + * specified which is called with @data as argument when the @pspec is + * finalized, or the data is being overwritten by a call to * g_param_spec_set_qdata() with the same @quark. */ void @@ -518,13 +523,12 @@ g_param_spec_set_qdata_full (GParamSpec *pspec, * g_param_spec_steal_qdata: * @pspec: the #GParamSpec to get a stored user data pointer from * @quark: a #GQuark, naming the user data pointer - * - * Gets back user data pointers stored via g_param_spec_set_qdata() and - * removes the @data from @pspec 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. - * + * + * Gets back user data pointers stored via g_param_spec_set_qdata() + * and removes the @data from @pspec 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. + * * Returns: the user data pointer set, or %NULL */ gpointer @@ -540,7 +544,7 @@ g_param_spec_steal_qdata (GParamSpec *pspec, /** * g_param_spec_get_redirect_target: * @pspec: a #GParamSpec - * + * * If the paramspec redirects operations to another paramspec, * returns that paramspec. Redirect is used typically for * providing a new implementation of a property in a derived @@ -548,10 +552,11 @@ g_param_spec_steal_qdata (GParamSpec *pspec, * type. Redirection is established by creating a property * of type #GParamSpecOverride. See g_object_class_override_property() * for an example of the use of this capability. - * + * * Since: 2.4 + * * Returns: paramspec to which requests on this paramspec should - * be redirected, or %NULL if none. + * be redirected, or %NULL if none. */ GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec) @@ -572,7 +577,7 @@ g_param_spec_get_redirect_target (GParamSpec *pspec) * g_param_value_set_default: * @pspec: a valid #GParamSpec * @value: a #GValue of correct type for @pspec - * + * * Sets @value to its default value as specified in @pspec. */ void @@ -591,9 +596,9 @@ g_param_value_set_default (GParamSpec *pspec, * g_param_value_defaults: * @pspec: a valid #GParamSpec * @value: a #GValue of correct type for @pspec - * + * * Checks whether @value contains the default value as specified in @pspec. - * + * * Returns: whether @value contains the canonical default for this @pspec */ gboolean @@ -619,14 +624,14 @@ g_param_value_defaults (GParamSpec *pspec, * g_param_value_validate: * @pspec: a valid #GParamSpec * @value: a #GValue of correct type for @pspec - * + * * Ensures that the contents of @value comply with the specifications * set out by @pspec. For example, a #GParamSpecInt might require * that integers stored in @value may not be smaller than -42 and not be * greater than +42. If @value contains an integer outside of this range, * it is modified accordingly, so the resulting value will fit into the * range -42 .. +42. - * + * * Returns: whether modifying @value was necessary to ensure validity */ gboolean @@ -654,16 +659,17 @@ g_param_value_validate (GParamSpec *pspec, * @pspec: a valid #GParamSpec * @src_value: souce #GValue * @dest_value: destination #GValue of correct type for @pspec - * @strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications - * - * Transforms @src_value into @dest_value if possible, and then validates - * @dest_value, in order for it to conform to @pspec. - * If @strict_validation is %TRUE this function will only succeed if - * the transformed @dest_value complied to @pspec without modifications. - * + * @strict_validation: %TRUE requires @dest_value to conform to @pspec + * without modifications + * + * Transforms @src_value into @dest_value if possible, and then + * validates @dest_value, in order for it to conform to @pspec. If + * @strict_validation is %TRUE this function will only succeed if the + * transformed @dest_value complied to @pspec without modifications. + * * See also g_value_type_transformable(), g_value_transform() and * g_param_value_validate(). - * + * * Returns: %TRUE if transformation and validation were successful, * %FALSE otherwise and @dest_value is left untouched. */ @@ -706,11 +712,11 @@ g_param_value_convert (GParamSpec *pspec, * @pspec: a valid #GParamSpec * @value1: a #GValue of correct type for @pspec * @value2: a #GValue of correct type for @pspec - * + * * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, - * if @value1 is found to be less than, equal to or greater than @value2, + * if @value1 is found to be less than, equal to or greater than @value2, * respectively. - * + * * Returns: -1, 0 or +1, for a less than, equal to or greater than result */ gint @@ -832,11 +838,11 @@ value_param_lcopy_value (const GValue *value, /* --- param spec pool --- */ /** * GParamSpecPool: - * + * * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be * quickly accessed by owner and name. The implementation of the #GObject property * system uses such a pool to store the #GParamSpecs of the properties all object - * types. + * types. */ struct _GParamSpecPool { @@ -872,14 +878,14 @@ param_spec_pool_equals (gconstpointer key_spec_1, /** * g_param_spec_pool_new: * @type_prefixing: Whether the pool will support type-prefixed property names. - * + * * Creates a new #GParamSpecPool. - * + * * If @type_prefixing is %TRUE, lookups in the newly created pool will - * allow to specify the owner as a colon-separated prefix of the property name, - * like "GtkContainer:border-width". This feature is deprecated, so you should - * always set @type_prefixing to %FALSE. - * + * allow to specify the owner as a colon-separated prefix of the + * property name, like "GtkContainer:border-width". This feature is + * deprecated, so you should always set @type_prefixing to %FALSE. + * * Returns: a newly allocated #GParamSpecPool. */ GParamSpecPool* @@ -900,9 +906,10 @@ g_param_spec_pool_new (gboolean type_prefixing) * @pool: a #GParamSpecPool. * @pspec: the #GParamSpec to insert * @owner_type: a #GType identifying the owner of @pspec - * + * * Inserts a #GParamSpec in the pool. - */void + */ +void g_param_spec_pool_insert (GParamSpecPool *pool, GParamSpec *pspec, GType owner_type) @@ -940,7 +947,7 @@ g_param_spec_pool_insert (GParamSpecPool *pool, * g_param_spec_pool_remove: * @pool: a #GParamSpecPool * @pspec: the #GParamSpec to remove - * + * * Removes a #GParamSpec from the pool. */ void @@ -1017,11 +1024,11 @@ param_spec_ht_lookup (GHashTable *hash_table, * @pool: a #GParamSpecPool * @param_name: the name to look for * @owner_type: the owner to look for - * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name + * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name * owned by an ancestor of @owner_type. - * + * * Looks up a #GParamSpec in the pool. - * + * * Returns: The found #GParamSpec, or %NULL if no matching #GParamSpec was found. */ GParamSpec* @@ -1105,11 +1112,12 @@ pool_list (gpointer key, * g_param_spec_pool_list_owned: * @pool: a #GParamSpecPool * @owner_type: the owner to look for - * - * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in the pool. - * - * Returns: a #GList of all #GParamSpec<!-- -->s owned by @owner_type in - * the pool#GParamSpec<!-- -->s. + * + * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool. + * + * Returns: a #GList of all #GParamSpec<!-- -->s owned by @owner_type + * in the pool#GParamSpec<!-- -->s. */ GList* g_param_spec_pool_list_owned (GParamSpecPool *pool, @@ -1239,11 +1247,12 @@ pool_depth_list_for_interface (gpointer key, * @pool: a #GParamSpecPool * @owner_type: the owner to look for * @n_pspecs_p: return location for the length of the returned array - * - * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in the pool. - * - * Returns: a newly allocated array containing pointers to all - * #GParamSpec<!-- -->s owned by @owner_type in the pool + * + * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool. + * + * Returns: a newly allocated array containing pointers to all + * #GParamSpec<!-- -->s owned by @owner_type in the pool */ GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool, @@ -1342,12 +1351,12 @@ default_values_cmp (GParamSpec *pspec, * g_param_type_register_static: * @name: 0-terminated string used as the name of the new #GParamSpec type. * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. - * + * * Registers @name as the name of a new static type derived from - * #G_TYPE_PARAM. The type system uses the information contained in the - * #GParamSpecTypeInfo structure pointed to by @info to manage the #GParamSpec - * type and its instances. - * + * #G_TYPE_PARAM. The type system uses the information contained in + * the #GParamSpecTypeInfo structure pointed to by @info to manage the + * #GParamSpec type and its instances. + * * Returns: The new type identifier. */ GType @@ -1394,7 +1403,7 @@ g_param_type_register_static (const gchar *name, * g_value_set_param: * @value: a valid #GValue of type %G_TYPE_PARAM * @param: the #GParamSpec to be set - * + * * Set the contents of a %G_TYPE_PARAM #GValue to @param. */ void @@ -1416,9 +1425,9 @@ g_value_set_param (GValue *value, * g_value_set_param_take_ownership: * @value: a valid #GValue of type %G_TYPE_PARAM * @param: the #GParamSpec to be set - * + * * This is an internal function introduced mainly for C marshallers. - * + * * Deprecated: 2.4: Use g_value_take_param() instead. */ void @@ -1432,11 +1441,11 @@ g_value_set_param_take_ownership (GValue *value, * g_value_take_param: * @value: a valid #GValue of type %G_TYPE_PARAM * @param: the #GParamSpec to be set - * - * Sets the contents of a %G_TYPE_PARAM #GValue to @param and - * takes over the ownership of the callers reference to @param; - * the caller doesn't have to unref it any more. - * + * + * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes + * over the ownership of the callers reference to @param; the caller + * doesn't have to unref it any more. + * * Since: 2.4 */ void @@ -1455,9 +1464,9 @@ g_value_take_param (GValue *value, /** * g_value_get_param: * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM - * + * * Get the contents of a %G_TYPE_PARAM #GValue. - * + * * Returns: #GParamSpec content of @value */ GParamSpec* @@ -1471,10 +1480,12 @@ g_value_get_param (const GValue *value) /** * g_value_dup_param: * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM - * - * Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count. - * - * Returns: #GParamSpec content of @value, should be unreferenced when no longer needed. + * + * Get the contents of a %G_TYPE_PARAM #GValue, increasing its + * reference count. + * + * Returns: #GParamSpec content of @value, should be unreferenced when + * no longer needed. */ GParamSpec* g_value_dup_param (const GValue *value) diff --git a/gobject/gparamspecs.c b/gobject/gparamspecs.c index 6aba4df6f..ef961d49e 100644 --- a/gobject/gparamspecs.c +++ b/gobject/gparamspecs.c @@ -33,15 +33,19 @@ /** * SECTION:param_value_types + * * @Short_description: Standard Parameter and Value Types - * @See_also:#GParamSpec, #GValue, g_object_class_install_property(). + * + * @See_also: #GParamSpec, #GValue, g_object_class_install_property(). + * * @Title: Parameters and Values * - * #GValue provides an abstract container structure which can be copied, - * transformed and compared while holding a value of any (derived) type, which - * is registered as a #GType with a #GTypeValueTable in its #GTypeInfo structure. - * Parameter specifications for most value types can be created as - * #GParamSpec derived instances, to implement e.g. #GObject properties which + * #GValue provides an abstract container structure which can be + * copied, transformed and compared while holding a value of any + * (derived) type, which is registered as a #GType with a + * #GTypeValueTable in its #GTypeInfo structure. Parameter + * specifications for most value types can be created as #GParamSpec + * derived instances, to implement e.g. #GObject properties which * operate on #GValue containers. * * Parameter names need to start with a letter (a-z or A-Z). Subsequent @@ -1522,9 +1526,9 @@ g_param_spec_types_init (void) * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1562,9 +1566,9 @@ g_param_spec_char (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1600,12 +1604,12 @@ g_param_spec_uchar (const gchar *name, * @blurb: description of the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN + * + * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN * property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1639,11 +1643,11 @@ g_param_spec_boolean (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1681,11 +1685,11 @@ g_param_spec_int (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1723,11 +1727,11 @@ g_param_spec_uint (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1765,11 +1769,12 @@ g_param_spec_long (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * - * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. - * + * + * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG + * property. + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1807,11 +1812,11 @@ g_param_spec_ulong (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1849,12 +1854,12 @@ g_param_spec_int64 (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * - * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 + * + * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 * property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1890,13 +1895,13 @@ g_param_spec_uint64 (const gchar *name, * @blurb: description of the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * - * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT - * property. #GValue structures for this property can be accessed with + * + * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT + * property. #GValue structures for this property can be accessed with * g_value_set_uint() and g_value_get_uint(). - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1927,12 +1932,12 @@ g_param_spec_unichar (const gchar *name, * @enum_type: a #GType derived from %G_TYPE_ENUM * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM * property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -1973,12 +1978,12 @@ g_param_spec_enum (const gchar *name, * @flags_type: a #GType derived from %G_TYPE_FLAGS * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS * property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2020,11 +2025,11 @@ g_param_spec_flags (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2062,12 +2067,12 @@ g_param_spec_float (const gchar *name, * @maximum: maximum value for the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * - * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE + * + * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE * property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2103,11 +2108,11 @@ g_param_spec_double (const gchar *name, * @blurb: description of the property specified * @default_value: default value for the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecString instance. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2135,12 +2140,12 @@ g_param_spec_string (const gchar *name, * @blurb: description of the property specified * @param_type: a #GType derived from %G_TYPE_PARAM * @flags: flags for the property specified - * + * * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM * property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2171,12 +2176,12 @@ g_param_spec_param (const gchar *name, * @blurb: description of the property specified * @boxed_type: %G_TYPE_BOXED derived type of this property * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED + * + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED * derived property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2207,11 +2212,11 @@ g_param_spec_boxed (const gchar *name, * @nick: nick name for the property specified * @blurb: description of the property specified * @flags: flags for the property specified - * + * * Creates a new #GParamSpecPoiner instance specifying a pointer property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2238,13 +2243,14 @@ g_param_spec_pointer (const gchar *name, * @is_a_type: a #GType whose subtypes are allowed as values * of the property (use %G_TYPE_NONE for any type) * @flags: flags for the property specified - * - * Creates a new #GParamSpecGType instance specifying a - * %G_TYPE_GTYPE property. - * + * + * Creates a new #GParamSpecGType instance specifying a + * %G_TYPE_GTYPE property. + * * See g_param_spec_internal() for details on property names. - * + * * Since: 2.10 + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2272,17 +2278,17 @@ g_param_spec_gtype (const gchar *name, * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified - * @element_spec: a #GParamSpec describing the elements contained in + * @element_spec: a #GParamSpec describing the elements contained in * arrays of this property, may be %NULL * @flags: flags for the property specified - * - * Creates a new #GParamSpecValueArray instance specifying a - * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a %G_TYPE_BOXED - * type, as such, #GValue structures for this property can be accessed - * with g_value_set_boxed() and g_value_get_boxed(). - * + * + * Creates a new #GParamSpecValueArray instance specifying a + * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a + * %G_TYPE_BOXED type, as such, #GValue structures for this property + * can be accessed with g_value_set_boxed() and g_value_get_boxed(). + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2318,12 +2324,12 @@ g_param_spec_value_array (const gchar *name, * @blurb: description of the property specified * @object_type: %G_TYPE_OBJECT derived type of this property * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT + * + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT * derived property. - * + * * See g_param_spec_internal() for details on property names. - * + * * Returns: a newly created parameter specification */ GParamSpec* @@ -2351,12 +2357,13 @@ g_param_spec_object (const gchar *name, * g_param_spec_override: * @name: the name of the property. * @overridden: The property that is being overridden - * + * * Creates a new property of type #GParamSpecOverride. This is used * to direct operations to another paramspec, and will not be directly * useful unless you are implementing a new base type similar to GObject. - * + * * Since: 2.4 + * * Returns: the newly created #GParamSpec */ GParamSpec* diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 3ede9e82b..f9115091e 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -41,7 +41,10 @@ /** * SECTION:signals - * @Short_description: A means for customization of object behaviour and a general purpose notification mechanism + * + * @Short_description: A means for customization of object behaviour + * and a general purpose notification mechanism + * * @Title: Signals * * The basic concept of the signal system is that of the @@ -812,13 +815,13 @@ _g_signals_destroy (GType itype) * @instance: the object whose signal handlers you wish to stop. * @signal_id: the signal identifier, as returned by g_signal_lookup(). * @detail: the detail which the signal was emitted with. - * + * * Stops a signal's current emission. - * + * * This will prevent the default method from running, if the signal was - * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" + * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" * flag). - * + * * Prints a warning if used on a signal which isn't being emitted. */ void @@ -883,11 +886,11 @@ signal_finalize_hook (GHookList *hook_list, * @hook_func: a #GSignalEmissionHook function. * @hook_data: user data for @hook_func. * @data_destroy: a #GDestroyNotify for @hook_data. - * + * * Adds an emission hook for a signal, which will get called for any emission * of that signal, independent of the instance. This is possible only * for signals which don't have #G_SIGNAL_NO_HOOKS flag set. - * + * * Returns: the hook id, for later use with g_signal_remove_emission_hook(). */ gulong @@ -948,9 +951,9 @@ g_signal_add_emission_hook (guint signal_id, /** * g_signal_remove_emission_hook: * @signal_id: the id of the signal - * @hook_id: the id of the emission hook, as returned by + * @hook_id: the id of the emission hook, as returned by * g_signal_add_emission_hook() - * + * * Deletes an emission hook. */ void @@ -1022,10 +1025,10 @@ signal_parse_name (const gchar *name, * @signal_id_p: Location to store the signal id. * @detail_p: Location to store the detail quark. * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. - * + * * Internal function to parse a signal name into its @signal_id * and @detail quark. - * + * * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. */ gboolean @@ -1063,10 +1066,10 @@ g_signal_parse_name (const gchar *detailed_signal, * g_signal_stop_emission_by_name: * @instance: the object whose signal handlers you wish to stop. * @detailed_signal: a string of the form "signal-name::detail". - * + * * Stops a signal's current emission. - * - * This is just like g_signal_stop_emission() except it will look up the + * + * This is just like g_signal_stop_emission() except it will look up the * signal id for you. */ void @@ -1118,15 +1121,15 @@ g_signal_stop_emission_by_name (gpointer instance, * g_signal_lookup: * @name: the signal's name. * @itype: the type that the signal operates on. - * - * Given the name of the signal and the type of object it connects to, gets - * the signal's identifying integer. Emitting the signal by number is + * + * Given the name of the signal and the type of object it connects to, gets + * the signal's identifying integer. Emitting the signal by number is * somewhat faster than using the name each time. - * + * * Also tries the ancestors of the given type. - * + * * See g_signal_new() for details on allowed signal names. - * + * * Returns: the signal's identifying number, or 0 if no signal was found. */ guint @@ -1161,11 +1164,11 @@ g_signal_lookup (const gchar *name, * g_signal_list_ids: * @itype: Instance or interface type. * @n_ids: Location to store the number of signal ids for @itype. - * + * * Lists the signals by id that a certain instance or interface type * created. Further information about the signals can be acquired through * g_signal_query(). - * + * * Returns: Newly allocated array of signal IDs. */ guint* @@ -1218,11 +1221,11 @@ g_signal_list_ids (GType itype, /** * g_signal_name: * @signal_id: the signal's identifying number. - * + * * Given the signal's identifier, finds its name. - * + * * Two different signals may have the same name, if they have differing types. - * + * * Returns: the signal name, or %NULL if the signal number was invalid. */ G_CONST_RETURN gchar* @@ -1244,7 +1247,7 @@ g_signal_name (guint signal_id) * @signal_id: The signal id of the signal to query information for. * @query: A user provided structure that is filled in with constant * values upon success. - * + * * Queries the signal system for in-depth information about a * specific signal. This function will fill in a user-provided * structure to hold signal-specific information. If an invalid @@ -1280,33 +1283,33 @@ g_signal_query (guint signal_id, /** * g_signal_new: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to + * @itype: the type this signal pertains to. It will also pertain to * types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when - * the default handler is to be invoked. You should at least specify + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_offset: The offset of the function pointer in the class structure + * @class_offset: The offset of the function pointer in the class structure * for this type. Used to invoke a class method generically. Pass 0 to * not associate a class method with this signal. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to + * @c_marshaller: the function to translate arrays of parameter values to * signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * @return_type: the type of return value, or #G_TYPE_NONE for a signal * without a return value. * @n_params: the number of parameter types to follow. * @...: a list of types, one for each parameter. - * + * * Creates a new signal. (This is usually done in the class initializer.) - * + * * A signal name consists of segments consisting of ASCII letters and * digits, separated by either the '-' or '_' character. The first * character of a signal name must be a letter. Names which violate these - * rules lead to undefined behaviour of the GSignal system. - * + * rules lead to undefined behaviour of the GSignal system. + * * When registering a signal and looking up a signal, either separator can - * be used, but they cannot be mixed. - * + * be used, but they cannot be mixed. + * * Returns: the signal id */ guint @@ -1414,25 +1417,25 @@ signal_add_class_closure (SignalNode *node, /** * g_signal_newv: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to + * @itype: the type this signal pertains to. It will also pertain to * types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when - * the default handler is to be invoked. You should at least specify + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. * @class_closure: The closure to invoke on signal emission; may be %NULL. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to + * @c_marshaller: the function to translate arrays of parameter values to * signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * @return_type: the type of return value, or #G_TYPE_NONE for a signal * without a return value. * @n_params: the length of @param_types. * @param_types: an array types, one for each parameter. - * + * * Creates a new signal. (This is usually done in the class initializer.) - * + * * See g_signal_new() for details on allowed signal names. - * + * * Returns: the signal id */ guint @@ -1572,25 +1575,25 @@ g_signal_newv (const gchar *signal_name, /** * g_signal_new_valist: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to + * @itype: the type this signal pertains to. It will also pertain to * types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when - * the default handler is to be invoked. You should at least specify + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. * @class_closure: The closure to invoke on signal emission; may be %NULL. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to + * @c_marshaller: the function to translate arrays of parameter values to * signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * @return_type: the type of return value, or #G_TYPE_NONE for a signal * without a return value. * @n_params: the number of parameter types in @args. * @args: va_list of #GType, one for each parameter. - * + * * Creates a new signal. (This is usually done in the class initializer.) - * + * * See g_signal_new() for details on allowed signal names. - * + * * Returns: the signal id */ guint @@ -1685,10 +1688,10 @@ signal_destroy_R (SignalNode *signal_node) /** * g_signal_override_class_closure: * @signal_id: the signal id - * @instance_type: the instance type on which to override the class closure + * @instance_type: the instance type on which to override the class closure * for the signal. * @class_closure: the closure. - * + * * Overrides the class closure (i.e. the default handler) for the given signal * for emissions on instances of @instance_type. @instance_type must be derived * from the type to which the signal belongs. @@ -1721,13 +1724,13 @@ g_signal_override_class_closure (guint signal_id, /** * g_signal_chain_from_overridden: - * @instance_and_params: the argument list of the signal emission. The first - * element in the array is a #GValue for the instance the signal is being + * @instance_and_params: the argument list of the signal emission. The first + * element in the array is a #GValue for the instance the signal is being * emitted on. The rest are any arguments to be passed to the signal. * @return_value: Location for the return value. - * + * * Calls the original class closure of a signal. This function should only - * be called from an overridden class closure; see + * be called from an overridden class closure; see * g_signal_override_class_closure(). */ void @@ -1792,9 +1795,9 @@ g_signal_chain_from_overridden (const GValue *instance_and_params, /** * g_signal_get_invocation_hint: * @instance: the instance to query - * - * Returns the invocation hint of the innermost signal emission of instance. - * + * + * Returns the invocation hint of the innermost signal emission of instance. + * * Returns: the invocation hint of the innermost signal emission. */ GSignalInvocationHint* @@ -1817,11 +1820,11 @@ g_signal_get_invocation_hint (gpointer instance) * @signal_id: the id of the signal. * @detail: the detail. * @closure: the closure to connect. - * @after: whether the handler should be called before or after the + * @after: whether the handler should be called before or after the * default handler of the signal. - * + * * Connects a closure to a signal for a particular object. - * + * * Returns: the handler id */ gulong @@ -1871,11 +1874,11 @@ g_signal_connect_closure_by_id (gpointer instance, * @instance: the instance to connect to. * @detailed_signal: a string of the form "signal-name::detail". * @closure: the closure to connect. - * @after: whether the handler should be called before or after the + * @after: whether the handler should be called before or after the * default handler of the signal. - * + * * Connects a closure to a signal for a particular object. - * + * * Returns: the handler id */ gulong @@ -1932,13 +1935,13 @@ g_signal_connect_closure (gpointer instance, * @data: data to pass to @c_handler calls. * @destroy_data: a #GClosureNotify for @data. * @connect_flags: a combination of #GConnectFlags. - * + * * Connects a #GCallback function to a signal for a particular object. Similar * to g_signal_connect(), but allows to provide a #GClosureNotify for the data * which will be called when the signal handler is disconnected and no longer * used. Specify @connect_flags if you need <literal>..._after()</literal> or * <literal>..._swapped()</literal> variants of this function. - * + * * Returns: the handler id */ gulong @@ -1997,14 +2000,14 @@ g_signal_connect_data (gpointer instance, * g_signal_handler_block: * @instance: The instance to block the signal handler of. * @handler_id: Handler id of the handler to be blocked. - * - * Blocks a handler of an instance so it will not be called during - * any signal emissions unless it is unblocked again. Thus "blocking" - * a signal handler means to temporarily deactive it, a signal handler - * has to be unblocked exactly the same amount of times it has been + * + * Blocks a handler of an instance so it will not be called during any + * signal emissions unless it is unblocked again. Thus "blocking" a + * signal handler means to temporarily deactive it, a signal handler + * has to be unblocked exactly the same amount of times it has been * blocked before to become active again. - * - * The @handler_id has to be a valid signal handler id, connected to a + * + * The @handler_id has to be a valid signal handler id, connected to a * signal of @instance. */ void @@ -2035,19 +2038,19 @@ g_signal_handler_block (gpointer instance, * g_signal_handler_unblock: * @instance: The instance to unblock the signal handler of. * @handler_id: Handler id of the handler to be unblocked. - * - * Undoes the effect of a previous g_signal_handler_block() call. - * A blocked handler is skipped during signal emissions and will not be - * invoked, unblocking it (for exactly the amount of times it has been - * blocked before) reverts its "blocked" state, so the handler will be - * recognized by the signal system and is called upon future or currently - * ongoing signal emissions (since the order in which handlers are - * called during signal emissions is deterministic, whether the - * unblocked handler in question is called as part of a currently - * ongoing emission depends on how far that emission has proceeded - * yet). - * - * The @handler_id has to be a valid id of a signal handler that is + * + * Undoes the effect of a previous g_signal_handler_block() call. A + * blocked handler is skipped during signal emissions and will not be + * invoked, unblocking it (for exactly the amount of times it has been + * blocked before) reverts its "blocked" state, so the handler will be + * recognized by the signal system and is called upon future or + * currently ongoing signal emissions (since the order in which + * handlers are called during signal emissions is deterministic, + * whether the unblocked handler in question is called as part of a + * currently ongoing emission depends on how far that emission has + * proceeded yet). + * + * The @handler_id has to be a valid id of a signal handler that is * connected to a signal of @instance and is currently blocked. */ void @@ -2077,12 +2080,12 @@ g_signal_handler_unblock (gpointer instance, * g_signal_handler_disconnect: * @instance: The instance to remove the signal handler from. * @handler_id: Handler id of the handler to be disconnected. - * - * Disconnects a handler from an instance so it will not be called during - * any future or currently ongoing emissions of the signal it has been + * + * Disconnects a handler from an instance so it will not be called during + * any future or currently ongoing emissions of the signal it has been * connected to. The @handler_id becomes invalid and may be reused. - * - * The @handler_id has to be a valid signal handler id, connected to a + * + * The @handler_id has to be a valid signal handler id, connected to a * signal of @instance. */ void @@ -2112,9 +2115,9 @@ g_signal_handler_disconnect (gpointer instance, * g_signal_handler_is_connected: * @instance: The instance where a signal handler is sought. * @handler_id: the handler id. - * + * * Returns whether @handler_id is the id of a handler connected to @instance. - * + * * Returns: whether @handler_id identifies a handler connected to @instance. */ gboolean @@ -2179,20 +2182,20 @@ g_signal_handlers_destroy (gpointer instance) /** * g_signal_handler_find: * @instance: The instance owning the signal handler to be found. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func * and/or @data the handler has to match. * @signal_id: Signal the handler has to be connected to. * @detail: Signal detail the handler has to be connected to. * @closure: The closure the handler will invoke. * @func: The C closure callback of the handler (useless for non-C closures). * @data: The closure data of the handler's closure. - * + * * Finds the first signal handler that matches certain selection criteria. * The criteria mask is passed as an OR-ed combination of #GSignalMatchType * flags, and the criteria values are passed as arguments. * The match @mask has to be non-0 for successful matches. * If no handler was found, 0 is returned. - * + * * Returns: A valid non-0 signal handler id for a successful match. */ gulong @@ -2259,22 +2262,22 @@ signal_handlers_foreach_matched_R (gpointer instance, /** * g_signal_handlers_block_matched: * @instance: The instance to block handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). * @data: The closure data of the handlers' closures. - * + * * Blocks all handlers on an instance that match a certain selection criteria. - * The criteria mask is passed as an OR-ed combination of #GSignalMatchType + * The criteria mask is passed as an OR-ed combination of #GSignalMatchType * flags, and the criteria values are passed as arguments. * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. * If no handlers were found, 0 is returned, the number of blocked handlers * otherwise. - * + * * Returns: The number of handlers that matched. */ guint @@ -2306,14 +2309,14 @@ g_signal_handlers_block_matched (gpointer instance, /** * g_signal_handlers_unblock_matched: * @instance: The instance to unblock handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). * @data: The closure data of the handlers' closures. - * + * * Unblocks all handlers on an instance that match a certain selection * criteria. The criteria mask is passed as an OR-ed combination of * #GSignalMatchType flags, and the criteria values are passed as arguments. @@ -2322,7 +2325,7 @@ g_signal_handlers_block_matched (gpointer instance, * If no handlers were found, 0 is returned, the number of unblocked handlers * otherwise. The match criteria should not apply to any handlers that are * not currently blocked. - * + * * Returns: The number of handlers that matched. */ guint @@ -2354,22 +2357,23 @@ g_signal_handlers_unblock_matched (gpointer instance, /** * g_signal_handlers_disconnect_matched: * @instance: The instance to remove handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). * @data: The closure data of the handlers' closures. - * - * Disconnects all handlers on an instance that match a certain selection - * criteria. The criteria mask is passed as an OR-ed combination of - * #GSignalMatchType flags, and the criteria values are passed as arguments. - * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC - * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. - * If no handlers were found, 0 is returned, the number of disconnected - * handlers otherwise. - * + * + * Disconnects all handlers on an instance that match a certain + * selection criteria. The criteria mask is passed as an OR-ed + * combination of #GSignalMatchType flags, and the criteria values are + * passed as arguments. Passing at least one of the + * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or + * %G_SIGNAL_MATCH_DATA match flags is required for successful + * matches. If no handlers were found, 0 is returned, the number of + * disconnected handlers otherwise. + * * Returns: The number of handlers that matched. */ guint @@ -2404,17 +2408,17 @@ g_signal_handlers_disconnect_matched (gpointer instance, * @signal_id: the signal id. * @detail: the detail. * @may_be_blocked: whether blocked handlers should count as match. - * + * * Returns whether there are any handlers connected to @instance for the * given signal id and detail. - * - * One example of when you might use this is when the arguments to the - * signal are difficult to compute. A class implementor may opt to not emit - * the signal if no one is attached anyway, thus saving the cost of building - * the arguments. - * - * Returns: %TRUE if a handler is connected to the signal, - * %FALSE otherwise. + * + * One example of when you might use this is when the arguments to the + * signal are difficult to compute. A class implementor may opt to not + * emit the signal if no one is attached anyway, thus saving the cost + * of building the arguments. + * + * Returns: %TRUE if a handler is connected to the signal, %FALSE + * otherwise. */ gboolean g_signal_has_handler_pending (gpointer instance, @@ -2501,16 +2505,16 @@ signal_check_skip_emission (SignalNode *node, /** * g_signal_emitv: - * @instance_and_params: argument list for the signal emission. The first - * element in the array is a #GValue for the instance the signal is - * being emitted on. The rest are any arguments to be passed to the + * @instance_and_params: argument list for the signal emission. The first + * element in the array is a #GValue for the instance the signal is + * being emitted on. The rest are any arguments to be passed to the * signal. * @signal_id: the signal id * @detail: the detail * @return_value: Location to store the return value of the signal emission. - * - * Emits a signal. - * + * + * Emits a signal. + * * Note that g_signal_emitv() doesn't change @return_value if no handlers are * connected, in contrast to g_signal_emit() and g_signal_emit_valist(). */ @@ -2610,9 +2614,9 @@ g_signal_emitv (const GValue *instance_and_params, * @var_args: a list of parameters to be passed to the signal, followed by a * location for the return value. If the return type of the signal * is #G_TYPE_NONE, the return value location can be omitted. - * - * Emits a signal. - * + * + * Emits a signal. + * * Note that g_signal_emit_valist() resets the return value to the default * if no handlers are connected, in contrast to g_signal_emitv(). */ @@ -2744,9 +2748,9 @@ g_signal_emit_valist (gpointer instance, * @...: parameters to be passed to the signal, followed by a * location for the return value. If the return type of the signal * is #G_TYPE_NONE, the return value location can be omitted. - * - * Emits a signal. - * + * + * Emits a signal. + * * Note that g_signal_emit() resets the return value to the default * if no handlers are connected, in contrast to g_signal_emitv(). */ @@ -2770,9 +2774,9 @@ g_signal_emit (gpointer instance, * @...: parameters to be passed to the signal, followed by a * location for the return value. If the return type of the signal * is #G_TYPE_NONE, the return value location can be omitted. - * - * Emits a signal. - * + * + * Emits a signal. + * * Note that g_signal_emit_by_name() resets the return value to the default * if no handlers are connected, in contrast to g_signal_emitv(). */ @@ -3128,7 +3132,7 @@ type_debug_name (GType type) * @return_accu: standard #GSignalAccumulator parameter * @handler_return: standard #GSignalAccumulator parameter * @dummy: standard #GSignalAccumulator parameter - * + * * A predefined #GSignalAccumulator for signals that return a * boolean values. The behavior that this accumulator gives is * that a return of %TRUE stops the signal emission: no further @@ -3136,8 +3140,9 @@ type_debug_name (GType type) * the emission to coninue. The idea here is that a %TRUE return * indicates that the callback <emphasis>handled</emphasis> the signal, * and no further handling is needed. - * + * * Since: 2.4 + * * Returns: standard #GSignalAccumulator result */ gboolean diff --git a/gobject/gsourceclosure.c b/gobject/gsourceclosure.c index 345c32289..508961c5c 100644 --- a/gobject/gsourceclosure.c +++ b/gobject/gsourceclosure.c @@ -162,9 +162,9 @@ static GSourceCallbackFuncs closure_callback_funcs = { * g_source_set_closure: * @source: the source * @closure: a #GClosure - * + * * Set the callback for a source as a #GClosure. - * + * * If the source is not one of the standard GLib types, the @closure_callback * and @closure_marshal fields of the #GSourceFuncs structure must have been * filled in with pointers to appropriate functions. diff --git a/gobject/gtype.c b/gobject/gtype.c index bcb6a0d9d..3c08569df 100644 --- a/gobject/gtype.c +++ b/gobject/gtype.c @@ -34,7 +34,10 @@ /** * SECTION:gtype - * @Short_description: The GLib Runtime type identification and management system + * + * @Short_description: The GLib Runtime type identification and + * management system + * * @Title:Type Information * * The GType API is the foundation of the GObject system. It provides the @@ -238,6 +241,7 @@ struct _TypeNode } _prot; GType supers[1]; /* flexible array */ }; + #define SIZEOF_BASE_TYPE_NODE() (G_STRUCT_OFFSET (TypeNode, supers)) #define MAX_N_SUPERS (255) #define MAX_N_CHILDREN (4095) @@ -270,17 +274,20 @@ struct _IFaceHolder GTypePlugin *plugin; IFaceHolder *next; }; + struct _IFaceEntry { GType iface_type; GTypeInterface *vtable; InitState init_state; }; + struct _CommonData { guint ref_count; GTypeValueTable *value_table; }; + struct _IFaceData { CommonData common; @@ -292,6 +299,7 @@ struct _IFaceData gconstpointer dflt_data; gpointer dflt_vtable; }; + struct _ClassData { CommonData common; @@ -304,6 +312,7 @@ struct _ClassData gconstpointer class_data; gpointer class; }; + struct _InstanceData { CommonData common; @@ -320,6 +329,7 @@ struct _InstanceData guint16 n_preallocs; GInstanceInitFunc instance_init; }; + union _TypeData { CommonData common; @@ -327,10 +337,12 @@ union _TypeData ClassData class; InstanceData instance; }; + typedef struct { gpointer cache_data; GTypeClassCacheFunc cache_func; } ClassCacheFunc; + typedef struct { gpointer check_data; GTypeInterfaceCheckFunc check_func; @@ -1299,7 +1311,7 @@ type_iface_add_prerequisite_W (TypeNode *iface, * g_type_interface_add_prerequisite: * @interface_type: #GType value of an interface type. * @prerequisite_type: #GType value of an interface or instantiatable type. - * + * * Adds @prerequisite_type to the list of prerequisites of @interface_type. * This means that any type implementing @interface_type must also implement * @prerequisite_type. Prerequisites can be thought of as an alternative to @@ -1385,11 +1397,12 @@ g_type_interface_add_prerequisite (GType interface_type, * g_type_interface_prerequisites: * @interface_type: an interface type * @n_prerequisites: location to return the number of prerequisites, or %NULL - * + * * Returns the prerequisites of an interfaces type. - * + * * Since: 2.2 - * Returns: a newly-allocated zero-terminated array of #GType containing + * + * Returns: a newly-allocated zero-terminated array of #GType containing * the prerequisites of @interface_type */ GType* @@ -1528,6 +1541,7 @@ typedef struct { gpointer instance; gpointer class; } InstanceRealClass; + static gint instance_real_class_cmp (gconstpointer p1, gconstpointer p2) @@ -1538,6 +1552,7 @@ instance_real_class_cmp (gconstpointer p1, guint8 *i2 = irc2->instance; return G_BSEARCH_ARRAY_CMP (i1, i2); } + G_LOCK_DEFINE_STATIC (instance_real_class); static GBSearchArray *instance_real_class_bsa = NULL; static GBSearchConfig instance_real_class_bconfig = { @@ -1545,6 +1560,7 @@ static GBSearchConfig instance_real_class_bconfig = { instance_real_class_cmp, 0, }; + static inline void instance_real_class_set (gpointer instance, GTypeClass *class) @@ -1558,6 +1574,7 @@ instance_real_class_set (gpointer instance, instance_real_class_bsa = g_bsearch_array_replace (instance_real_class_bsa, &instance_real_class_bconfig, &key); G_UNLOCK (instance_real_class); } + static inline void instance_real_class_remove (gpointer instance) { @@ -1575,6 +1592,7 @@ instance_real_class_remove (gpointer instance) } G_UNLOCK (instance_real_class); } + static inline GTypeClass* instance_real_class_get (gpointer instance) { @@ -1591,20 +1609,21 @@ instance_real_class_get (gpointer instance) /** * g_type_create_instance: * @type: An instantiatable type to create an instance for. - * - * Creates and initializes an instance of @type if @type is valid and can - * be instantiated. The type system only performs basic allocation and - * structure setups for instances: actual instance creation should happen - * through functions supplied by the type's fundamental type implementation. - * So use of g_type_create_instance() is reserved for implementators of - * fundamental types only. E.g. instances of the #GObject hierarchy - * should be created via g_object_new() and <emphasis>never</emphasis> - * directly through g_type_create_instance() which doesn't handle - * things like singleton objects or object construction. - * Note: Do <emphasis>not</emphasis> use this function, unless you're - * implementing a fundamental type. Also language bindings should <emphasis>not</emphasis> - * use this function but g_object_new() instead. - * + * + * Creates and initializes an instance of @type if @type is valid and + * can be instantiated. The type system only performs basic allocation + * and structure setups for instances: actual instance creation should + * happen through functions supplied by the type's fundamental type + * implementation. So use of g_type_create_instance() is reserved for + * implementators of fundamental types only. E.g. instances of the + * #GObject hierarchy should be created via g_object_new() and + * <emphasis>never</emphasis> directly through + * g_type_create_instance() which doesn't handle things like singleton + * objects or object construction. Note: Do <emphasis>not</emphasis> + * use this function, unless you're implementing a fundamental + * type. Also language bindings should <emphasis>not</emphasis> use + * this function but g_object_new() instead. + * * Returns: An allocated and initialized instance, subject to further * treatment by the fundamental type implementation. */ @@ -1662,12 +1681,12 @@ g_type_create_instance (GType type) /** * g_type_free_instance: * @instance: an instance of a type. - * - * Frees an instance of a type, returning it to the instance pool for the type, - * if there is one. - * - * Like g_type_create_instance(), this function is reserved for implementors of - * fundamental types. + * + * Frees an instance of a type, returning it to the instance pool for + * the type, if there is one. + * + * Like g_type_create_instance(), this function is reserved for + * implementors of fundamental types. */ void g_type_free_instance (GTypeInstance *instance) @@ -2163,7 +2182,7 @@ type_data_last_unref_Wm (GType type, * g_type_add_class_cache_func: * @cache_data: data to be passed to @cache_func * @cache_func: a #GTypeClassCacheFunc - * + * * Adds a #GTypeClassCacheFunc to be called before the reference count of a * class goes from one to zero. This can be used to prevent premature class * destruction. All installed #GTypeClassCacheFunc functions will be chained @@ -2192,10 +2211,10 @@ g_type_add_class_cache_func (gpointer cache_data, * g_type_remove_class_cache_func: * @cache_data: data that was given when adding @cache_func * @cache_func: a #GTypeClassCacheFunc - * - * Removes a previously installed #GTypeClassCacheFunc. The cache maintained - * by @cache_func has to be empty when calling g_type_remove_class_cache_func() - * to avoid leaks. + * + * Removes a previously installed #GTypeClassCacheFunc. The cache + * maintained by @cache_func has to be empty when calling + * g_type_remove_class_cache_func() to avoid leaks. */ void g_type_remove_class_cache_func (gpointer cache_data, @@ -2231,18 +2250,18 @@ g_type_remove_class_cache_func (gpointer cache_data, * g_type_add_interface_check: * @check_data: data to pass to @check_func * @check_func: function to be called after each interface - * is initialized. - * + * is initialized. + * * Adds a function to be called after an interface vtable is - * initialized for any class (i.e. after the @interface_init - * member of #GInterfaceInfo has been called). - * - * This function is useful when you want to check an invariant - * that depends on the interfaces of a class. For instance, - * the implementation of #GObject uses this facility to check - * that an object implements all of the properties that are - * defined on its interfaces. - * + * initialized for any class (i.e. after the @interface_init member of + * #GInterfaceInfo has been called). + * + * This function is useful when you want to check an invariant that + * depends on the interfaces of a class. For instance, the + * implementation of #GObject uses this facility to check that an + * object implements all of the properties that are defined on its + * interfaces. + * * Since: 2.4 */ void @@ -2265,10 +2284,10 @@ g_type_add_interface_check (gpointer check_data, * g_type_remove_interface_check: * @check_data: callback data passed to g_type_add_interface_check() * @check_func: callback function passed to g_type_add_interface_check() - * + * * Removes an interface check function added with * g_type_add_interface_check(). - * + * * Since: 2.4 */ void @@ -2308,14 +2327,14 @@ g_type_remove_interface_check (gpointer check_data, * @info: The #GTypeInfo structure for this type. * @finfo: The #GTypeFundamentalInfo structure for this type. * @flags: Bitwise combination of #GTypeFlags values. - * + * * Registers @type_id as the predefined identifier and @type_name as the * name of a fundamental type. The type system uses the information - * contained in the #GTypeInfo structure pointed to by @info and the + * contained in the #GTypeInfo structure pointed to by @info and the * #GTypeFundamentalInfo structure pointed to by @finfo to manage the * type and its instances. The value of @flags determines additional * characteristics of the fundamental type. - * + * * Returns: The predefined type identifier. */ GType @@ -2379,13 +2398,14 @@ g_type_register_fundamental (GType type_id, * @instance_size: Size of the instance structure (see #GTypeInfo) * @instance_init: Location of the instance initialization function (see #GTypeInfo) * @flags: Bitwise combination of #GTypeFlags values. - * + * * Registers @type_name as the name of a new static type derived from - * @parent_type. The value of @flags determines the nature (e.g. - * abstract or not) of the type. It works by filling a #GTypeInfo + * @parent_type. The value of @flags determines the nature (e.g. + * abstract or not) of the type. It works by filling a #GTypeInfo * struct and calling g_type_register_static(). - * - * Since: 2.12 + * + * Since: 2.12 + * * Returns: The new type identifier. */ GType @@ -2419,13 +2439,13 @@ g_type_register_static_simple (GType parent_type, * @type_name: 0-terminated string used as the name of the new type. * @info: The #GTypeInfo structure for this type. * @flags: Bitwise combination of #GTypeFlags values. - * + * * Registers @type_name as the name of a new static type derived from * @parent_type. The type system uses the information contained in the * #GTypeInfo structure pointed to by @info to manage the type and its * instances (if not abstract). The value of @flags determines the nature * (e.g. abstract or not) of the type. - * + * * Returns: The new type identifier. */ GType @@ -2474,13 +2494,13 @@ g_type_register_static (GType parent_type, * @type_name: 0-terminated string used as the name of the new type. * @plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from. * @flags: Bitwise combination of #GTypeFlags values. - * + * * Registers @type_name as the name of a new dynamic type derived from * @parent_type. The type system uses the information contained in the * #GTypePlugin structure pointed to by @plugin to manage the type and its * instances (if not abstract). The value of @flags determines the nature * (e.g. abstract or not) of the type. - * + * * Returns: The new type identifier or #G_TYPE_INVALID if registration failed. */ GType @@ -2517,8 +2537,8 @@ g_type_register_dynamic (GType parent_type, * @instance_type: #GType value of an instantiable type. * @interface_type: #GType value of an interface type. * @info: The #GInterfaceInfo structure for this - * (@instance_type, @interface_type) combination. - * + * (@instance_type, @interface_type) combination. + * * Adds the static @interface_type to @instantiable_type. The information * contained in the #GTypeInterfaceInfo structure pointed to by @info * is used to manage the relationship. @@ -2554,7 +2574,7 @@ g_type_add_interface_static (GType instance_type, * @instance_type: the #GType value of an instantiable type. * @interface_type: the #GType value of an interface type. * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. - * + * * Adds the dynamic @interface_type to @instantiable_type. The information * contained in the #GTypePlugin structure pointed to by @plugin * is used to manage the relationship. @@ -2590,11 +2610,11 @@ g_type_add_interface_dynamic (GType instance_type, /** * g_type_class_ref: * @type: Type ID of a classed type. - * + * * Increments the reference count of the class structure belonging to * @type. This function will demand-create the class if it doesn't * exist already. - * + * * Returns: The #GTypeClass structure for the given type ID. */ gpointer @@ -2650,7 +2670,7 @@ g_type_class_ref (GType type) /** * g_type_class_unref: * @g_class: The #GTypeClass structure to unreference. - * + * * Decrements the reference count of the class structure being passed in. * Once the last reference count of a class has been released, classes * may be finalized by the type system, so further dereferencing of a @@ -2678,7 +2698,7 @@ g_type_class_unref (gpointer g_class) /** * g_type_class_unref_uncached: * @g_class: The #GTypeClass structure to unreference. - * + * * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc * implementations. It unreferences a class without consulting the chain * of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur @@ -2706,12 +2726,12 @@ g_type_class_unref_uncached (gpointer g_class) /** * g_type_class_peek: * @type: Type ID of a classed type. - * + * * This function is essentially the same as g_type_class_ref(), except that * the classes reference count isn't incremented. As a consequence, this function * may return %NULL if the class of the type passed in does not currently * exist (hasn't been referenced before). - * + * * Returns: The #GTypeClass structure for the given type ID or %NULL * if the class does not currently exist. */ @@ -2735,7 +2755,7 @@ g_type_class_peek (GType type) /** * g_type_class_peek_static: * @type: Type ID of a classed type. - * + * * A more efficient version of g_type_class_peek() which works only for * static types. * @@ -2765,18 +2785,18 @@ g_type_class_peek_static (GType type) /** * g_type_class_peek_parent: * @g_class: The #GTypeClass structure to retrieve the parent class for. - * + * * This is a convenience function often needed in class initializers. - * It returns the class structure of the immediate parent type of the class passed in. - * Since derived classes hold - * a reference count on their parent classes as long as they are instantiated, - * the returned class will always exist. This function is essentially - * equivalent to: - * + * It returns the class structure of the immediate parent type of the + * class passed in. Since derived classes hold a reference count on + * their parent classes as long as they are instantiated, the returned + * class will always exist. This function is essentially equivalent + * to: + * * <programlisting> * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); * </programlisting> - * + * * Returns: The parent class of @g_class. */ gpointer @@ -2807,12 +2827,12 @@ g_type_class_peek_parent (gpointer g_class) * g_type_interface_peek: * @instance_class: A #GTypeClass structure. * @iface_type: An interface ID which this class conforms to. - * - * Returns the #GTypeInterface structure of an interface to which the passed in - * class conforms. - * - * Returns: The GTypeInterface structure of iface_type if implemented - * by @instance_class, %NULL otherwise + * + * Returns the #GTypeInterface structure of an interface to which the + * passed in class conforms. + * + * Returns: The GTypeInterface structure of iface_type if implemented + * by @instance_class, %NULL otherwise */ gpointer g_type_interface_peek (gpointer instance_class, @@ -2848,15 +2868,15 @@ g_type_interface_peek (gpointer instance_class, /** * g_type_interface_peek_parent: * @g_iface: A #GTypeInterface structure. - * + * * Returns the corresponding #GTypeInterface structure of the parent type - * of the instance type to which @g_iface belongs. This is useful when - * deriving the implementation of an interface from the parent type and - * then possibly overriding some methods. - * - * Returns: The corresponding #GTypeInterface structure of the parent type - * of the instance type to which @g_iface belongs, or %NULL if the parent type - * doesn't conform to the interface. + * of the instance type to which @g_iface belongs. This is useful when + * deriving the implementation of an interface from the parent type and + * then possibly overriding some methods. + * + * Returns: The corresponding #GTypeInterface structure of the parent + * type of the instance type to which @g_iface belongs, or + * %NULL if the parent type doesn't conform to the interface. */ gpointer g_type_interface_peek_parent (gpointer g_iface) @@ -2893,10 +2913,10 @@ g_type_interface_peek_parent (gpointer g_iface) /** * g_type_default_interface_ref: * @g_type: an interface type - * + * * Increments the reference count for the interface type @g_type, * and returns the default interface vtable for the type. - * + * * If the type is not currently in use, then the default vtable * for the type will be created and initalized by calling * the base interface init and default vtable init functions for @@ -2905,11 +2925,12 @@ g_type_interface_peek_parent (gpointer g_iface) * Calling g_type_default_interface_ref() is useful when you * want to make sure that signals and properties for an interface * have been installed. - * + * * Since: 2.4 - * Returns: the default vtable for the interface; call - * g_type_default_interface_unref() when you are done using - * the interface. + * + * Returns: the default vtable for the interface; call + * g_type_default_interface_unref() when you are done using + * the interface. */ gpointer g_type_default_interface_ref (GType g_type) @@ -2951,13 +2972,14 @@ g_type_default_interface_ref (GType g_type) /** * g_type_default_interface_peek: * @g_type: an interface type - * - * If the interface type @g_type is currently in use, returns - * its default interface vtable. - * + * + * If the interface type @g_type is currently in use, returns its + * default interface vtable. + * * Since: 2.4 + * * Returns: the default vtable for the interface, or %NULL - * if the type is not currently in use. + * if the type is not currently in use. */ gpointer g_type_default_interface_peek (GType g_type) @@ -2979,15 +3001,15 @@ g_type_default_interface_peek (GType g_type) /** * g_type_default_interface_unref: * @g_iface: the default vtable structure for a interface, as - * returned by g_type_default_interface_ref() - * + * returned by g_type_default_interface_ref() + * * Decrements the reference count for the type corresponding to the * interface default vtable @g_iface. If the type is dynamic, then * when no one is using the interface and all references have * been released, the finalize function for the interface's default * vtable (the <structfield>class_finalize</structfield> member of * #GTypeInfo) will be called. - * + * * Since: 2.4 */ void @@ -3013,13 +3035,13 @@ g_type_default_interface_unref (gpointer g_iface) /** * g_type_name: * @type: Type to return name for. - * - * Get the unique name that is assigned to a type ID. - * Note that this function (like all other GType API) cannot cope with invalid - * type IDs. %G_TYPE_INVALID may be passed to this function, as may be any other - * validly registered type ID, but randomized type IDs should not be passed in and - * will most likely lead to a crash. - * + * + * Get the unique name that is assigned to a type ID. Note that this + * function (like all other GType API) cannot cope with invalid type + * IDs. %G_TYPE_INVALID may be passed to this function, as may be any + * other validly registered type ID, but randomized type IDs should + * not be passed in and will most likely lead to a crash. + * * Returns: Static type name or %NULL. */ G_CONST_RETURN gchar* @@ -3037,9 +3059,9 @@ g_type_name (GType type) /** * g_type_qname: * @type: Type to return quark of type name for. - * + * * Get the corresponding quark of the type IDs name. - * + * * Returns: The type names quark or 0. */ GQuark @@ -3055,10 +3077,12 @@ g_type_qname (GType type) /** * g_type_from_name: * @name: Type name to lookup. - * - * Lookup the type ID from a given type name, returning 0 if no type has been registered under this name - * (this is the preferred method to find out by name whether a specific type has been registered yet). - * + * + * Lookup the type ID from a given type name, returning 0 if no type + * has been registered under this name (this is the preferred method + * to find out by name whether a specific type has been registered + * yet). + * * Returns: Corresponding type ID or 0. */ GType @@ -3083,10 +3107,10 @@ g_type_from_name (const gchar *name) /** * g_type_parent: * @type: The derived type. - * - * Return the direct parent type of the passed in type. - * If the passed in type has no parent, i.e. is a fundamental type, 0 is returned. - * + * + * Return the direct parent type of the passed in type. If the passed + * in type has no parent, i.e. is a fundamental type, 0 is returned. + * * Returns: The parent type. */ GType @@ -3102,10 +3126,10 @@ g_type_parent (GType type) /** * g_type_depth: * @type: A #GType value. - * - * Returns the length of the ancestry of the passed in type. This includes the - * type itself, so that e.g. a fundamental type has depth 1. - * + * + * Returns the length of the ancestry of the passed in type. This + * includes the type itself, so that e.g. a fundamental type has depth 1. + * * Returns: The depth of @type. */ guint @@ -3122,14 +3146,15 @@ g_type_depth (GType type) * g_type_next_base: * @leaf_type: Descendant of @root_type and the type to be returned. * @root_type: Immediate parent of the returned type. - * - * Given a @leaf_type and a @root_type which is contained in its anchestry, return - * the type that @root_type is the immediate parent of. - * In other words, this function determines the type that is derived directly from - * @root_type which is also a base class of @leaf_type. Given a root type and a - * leaf type, this function can be used to determine the types and order in which - * the leaf type is descended from the root type. - * + * + * Given a @leaf_type and a @root_type which is contained in its + * anchestry, return the type that @root_type is the immediate parent + * of. In other words, this function determines the type that is + * derived directly from @root_type which is also a base class of + * @leaf_type. Given a root type and a leaf type, this function can + * be used to determine the types and order in which the leaf type is + * descended from the root type. + * * Returns: Immediate child of @root_type and anchestor of @leaf_type. */ GType @@ -3207,10 +3232,11 @@ type_node_conforms_to_U (TypeNode *node, * g_type_is_a: * @type: Type to check anchestry for. * @is_a_type: Possible anchestor of @type or interface @type could conform to. - * - * If @is_a_type is a derivable type, check whether @type is a descendant of @is_a_type. - * If @is_a_type is an interface, check whether @type conforms to it. - * + * + * If @is_a_type is a derivable type, check whether @type is a + * descendant of @is_a_type. If @is_a_type is an interface, check + * whether @type conforms to it. + * * Returns: %TRUE if @type is_a @is_a_type holds true. */ gboolean @@ -3231,10 +3257,10 @@ g_type_is_a (GType type, * g_type_children: * @type: The parent type. * @n_children: Optional #guint pointer to contain the number of child types. - * + * * Return a newly allocated and 0-terminated array of type IDs, listing the * child types of @type. The return value has to be g_free()ed after use. - * + * * Returns: Newly allocated and 0-terminated array of child types. */ GType* @@ -3271,12 +3297,13 @@ g_type_children (GType type, /** * g_type_interfaces: * @type: The type to list interface types for. - * @n_interfaces: Optional #guint pointer to contain the number of interface types. - * + * @n_interfaces: Optional #guint pointer to contain the number of + * interface types. + * * Return a newly allocated and 0-terminated array of type IDs, listing the * interface types that @type conforms to. The return value has to be * g_free()ed after use. - * + * * Returns: Newly allocated and 0-terminated array of interface types. */ GType* @@ -3361,10 +3388,10 @@ type_get_qdata_L (TypeNode *node, * g_type_get_qdata: * @type: a #GType * @quark: a #GQuark id to identify the data - * + * * Obtains data which has previously been attached to @type * with g_type_set_qdata(). - * + * * Returns: the data, or %NULL if no data was found */ gpointer @@ -3429,7 +3456,7 @@ type_set_qdata_W (TypeNode *node, * @type: a #GType * @quark: a #GQuark id to identify the data * @data: the data - * + * * Attaches arbitrary data to a type. */ void @@ -3471,14 +3498,15 @@ type_add_flags_W (TypeNode *node, /** * g_type_query: * @type: the #GType value of a static, classed type. - * @query: A user provided structure that is filled in with constant values + * @query: A user provided structure that is filled in with constant values * upon success. - * - * Queries the type system for information about a specific type. - * This function will fill in a user-provided structure to hold type-specific - * information. If an invalid #GType is passed in, the @type member of the - * #GTypeQuery is 0. All members filled into the #GTypeQuery structure should - * be considered constant and have to be left untouched. + * + * Queries the type system for information about a specific type. + * This function will fill in a user-provided structure to hold + * type-specific information. If an invalid #GType is passed in, the + * @type member of the #GTypeQuery is 0. All members filled into the + * #GTypeQuery structure should be considered constant and have to be + * left untouched. */ void g_type_query (GType type, @@ -3548,10 +3576,10 @@ g_type_test_flags (GType type, /** * g_type_get_plugin: * @type: The #GType to retrieve the plugin for. - * + * * Returns the #GTypePlugin structure for @type or * %NULL if @type does not have a #GTypePlugin structure. - * + * * Returns: The corresponding plugin if @type is a dynamic type, * %NULL otherwise. */ @@ -3569,12 +3597,12 @@ g_type_get_plugin (GType type) * g_type_interface_get_plugin: * @instance_type: the #GType value of an instantiatable type. * @interface_type: the #GType value of an interface type. - * - * Returns the #GTypePlugin structure for the dynamic interface - * @interface_type which has been added to @instance_type, or - * %NULL if @interface_type has not been added to @instance_type or does - * not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). - * + * + * Returns the #GTypePlugin structure for the dynamic interface + * @interface_type which has been added to @instance_type, or %NULL if + * @interface_type has not been added to @instance_type or does not + * have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + * * Returns: the #GTypePlugin for the dynamic interface @interface_type * of @instance_type. */ @@ -3616,14 +3644,14 @@ g_type_interface_get_plugin (GType instance_type, /** * g_type_fundamental_next: - * + * * Returns the next free fundamental type id which can be used to * register a new fundamental type with g_type_register_fundamental(). * The returned type ID represents the highest currently registered * fundamental type identifier. - * + * * Returns: The nextmost fundamental type ID to be registered, - * or 0 if the type system ran out of fundamental type IDs. + * or 0 if the type system ran out of fundamental type IDs. */ GType g_type_fundamental_next (void) @@ -3754,7 +3782,7 @@ g_type_check_class_cast (GTypeClass *type_class, return type_class; } -/* +/** * g_type_check_instance: * @instance: A valid #GTypeInstance structure. * @@ -3853,12 +3881,12 @@ g_type_check_value_holds (GValue *value, /** * g_type_value_table_peek: * @type: A #GType value. - * + * * Returns the location of the #GTypeValueTable associated with @type. * <emphasis>Note that this function should only be used from source code * that implements or has internal knowledge of the implementation of * @type.</emphasis> - * + * * Returns: Location of the #GTypeValueTable associated with @type or * %NULL if there is no #GTypeValueTable associated with @type. */ @@ -3941,8 +3969,9 @@ g_type_name_from_class (GTypeClass *g_class) /* --- initialization --- */ /** * g_type_init_with_debug_flags: - * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. - * + * @debug_flags: Bitwise combination of #GTypeDebugFlags values for + * debugging purposes. + * * Similar to g_type_init(), but additionally sets debug flags. */ void @@ -4052,12 +4081,13 @@ g_type_init_with_debug_flags (GTypeDebugFlags debug_flags) /** * g_type_init: - * - * Prior to any use of the type system, g_type_init() has to be called to initialize - * the type system and assorted other code portions (such as the various fundamental - * type implementations or the signal system). + * + * Prior to any use of the type system, g_type_init() has to be called + * to initialize the type system and assorted other code portions + * (such as the various fundamental type implementations or the signal + * system). */ -void +void g_type_init (void) { g_type_init_with_debug_flags (0); @@ -4067,7 +4097,7 @@ g_type_init (void) * g_type_class_add_private: * @g_class: class structure for an instantiatable type * @private_size: size of private structure. - * + * * Registers a private structure for an instantiatable type; * when an object is allocated, the private structures for * the type and all of its parent types are allocated @@ -4079,32 +4109,32 @@ g_type_init (void) * <structname>MyObjectPrivate</structname> to an object * <structname>MyObject</structname> defined in the standard GObject * fashion. - * + * * |[ * typedef struct _MyObjectPrivate MyObjectPrivate; - * + * * struct _MyObjectPrivate { * int some_field; * }; - * + * * #define MY_OBJECT_GET_PRIVATE(o) \ * (G_TYPE_INSTANCE_GET_PRIVATE ((o), MY_TYPE_OBJECT, MyObjectPrivate)) - * + * * static void * my_object_class_init (MyObjectClass *klass) * { * g_type_class_add_private (klass, sizeof (MyObjectPrivate)); * } - * + * * static int * my_object_get_some_field (MyObject *my_object) * { * MyObjectPrivate *priv = MY_OBJECT_GET_PRIVATE (my_object); - * + * * return priv->some_field; * } * ]| - * + * * Since: 2.4 */ void diff --git a/gobject/gtypemodule.c b/gobject/gtypemodule.c index c4fc30d2a..8749c1efb 100644 --- a/gobject/gtypemodule.c +++ b/gobject/gtypemodule.c @@ -28,7 +28,9 @@ /** * SECTION:gtypemodule + * * @Short_description: Type loading modules + * * @See_also:<variablelist> * <varlistentry> * <term>#GTypePlugin</term> @@ -39,6 +41,7 @@ * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> * </varlistentry> * </variablelist> + * * @Title: GTypeModule * * #GTypeModule provides a simple implementation of the #GTypePlugin @@ -280,11 +283,11 @@ g_type_module_use (GTypeModule *module) /** * g_type_module_unuse: * @module: a #GTypeModule - * + * * Decreases the use count of a #GTypeModule by one. If the * result is zero, the module will be unloaded. (However, the * #GTypeModule will not be freed, and types associated with the - * #GTypeModule are not unregistered. Once a #GTypeModule is + * #GTypeModule are not unregistered. Once a #GTypeModule is * initialized, it must exist forever.) */ void @@ -359,19 +362,19 @@ g_type_module_complete_interface_info (GTypePlugin *plugin, * @type_name: name for the type * @type_info: type information structure * @flags: flags field providing details about the type - * + * * Looks up or registers a type that is implemented with a particular * type plugin. If a type with name @type_name was previously registered, * the #GType identifier for the type is returned, otherwise the type * is newly registered, and the resulting #GType identifier returned. - * + * * When reregistering a type (typically because a module is unloaded * then reloaded, and reinitialized), @module and @parent_type must * be the same as they were previously. - * + * * As long as any instances of the type exist, the type plugin will * not be unloaded. - * + * * Returns: the new or existing type ID */ GType @@ -443,11 +446,11 @@ g_type_module_register_type (GTypeModule *module, * @instance_type: type to which to add the interface. * @interface_type: interface type to add * @interface_info: type information structure - * - * Registers an additional interface for a type, whose interface - * lives in the given type plugin. If the interface was already registered - * for the type in this plugin, nothing will be done. - * + * + * Registers an additional interface for a type, whose interface lives + * in the given type plugin. If the interface was already registered + * for the type in this plugin, nothing will be done. + * * As long as any instances of the type exist, the type plugin will * not be unloaded. */ @@ -504,19 +507,21 @@ g_type_module_add_interface (GTypeModule *module, * g_type_module_register_enum: * @module: a #GTypeModule * @name: name for the type - * @const_static_values: an array of #GEnumValue structs for the possible - * enumeration values. The array is terminated by a struct with all - * members being 0. - * + * @const_static_values: an array of #GEnumValue structs for the + * possible enumeration values. The array is + * terminated by a struct with all members being + * 0. + * * Looks up or registers an enumeration that is implemented with a particular * type plugin. If a type with name @type_name was previously registered, * the #GType identifier for the type is returned, otherwise the type * is newly registered, and the resulting #GType identifier returned. - * + * * As long as any instances of the type exist, the type plugin will * not be unloaded. - * + * * Since: 2.6 + * * Returns: the new or existing type ID */ GType @@ -541,19 +546,21 @@ g_type_module_register_enum (GTypeModule *module, * g_type_module_register_flags: * @module: a #GTypeModule * @name: name for the type - * @const_static_values: an array of #GFlagsValue structs for the possible - * flags values. The array is terminated by a struct with all - * members being 0. - * + * @const_static_values: an array of #GFlagsValue structs for the + * possible flags values. The array is + * terminated by a struct with all members being + * 0. + * * Looks up or registers a flags type that is implemented with a particular * type plugin. If a type with name @type_name was previously registered, * the #GType identifier for the type is returned, otherwise the type * is newly registered, and the resulting #GType identifier returned. - * + * * As long as any instances of the type exist, the type plugin will * not be unloaded. - * + * * Since: 2.6 + * * Returns: the new or existing type ID */ GType diff --git a/gobject/gtypeplugin.c b/gobject/gtypeplugin.c index 12698b01c..f8588fe9a 100644 --- a/gobject/gtypeplugin.c +++ b/gobject/gtypeplugin.c @@ -25,8 +25,11 @@ /** * SECTION:gtypeplugin + * * @Short_description: An interface for dynamically loadable types + * * @See_also:#GTypeModule and g_type_register_dynamic(). + * * @Titile: GTypePlugin * * The GObject type system supports dynamic loading of types. The @@ -111,10 +114,10 @@ g_type_plugin_get_type (void) /** * g_type_plugin_use: * @plugin: a #GTypePlugin - * - * Calls the @use_plugin function from the #GTypePluginClass of @plugin. - * There should be no need to use this function outside of the GObject - * type system itself. + * + * Calls the @use_plugin function from the #GTypePluginClass of + * @plugin. There should be no need to use this function outside of + * the GObject type system itself. */ void g_type_plugin_use (GTypePlugin *plugin) @@ -130,10 +133,10 @@ g_type_plugin_use (GTypePlugin *plugin) /** * g_type_plugin_unuse: * @plugin: a #GTypePlugin - * - * Calls the @unuse_plugin function from the #GTypePluginClass of @plugin. - * There should be no need to use this function outside of the GObject - * type system itself. + * + * Calls the @unuse_plugin function from the #GTypePluginClass of + * @plugin. There should be no need to use this function outside of + * the GObject type system itself. */ void g_type_plugin_unuse (GTypePlugin *plugin) @@ -183,10 +186,10 @@ g_type_plugin_complete_type_info (GTypePlugin *plugin, * is added * @interface_type: the #GType of the interface whose info is completed * @info: the #GInterfaceInfo to fill in - * - * Calls the @complete_interface_info function from the #GTypePluginClass - * of @plugin. There should be no need to use this function outside of the - * GObject type system itself. + * + * Calls the @complete_interface_info function from the + * #GTypePluginClass of @plugin. There should be no need to use this + * function outside of the GObject type system itself. */ void g_type_plugin_complete_interface_info (GTypePlugin *plugin, diff --git a/gobject/gvalue.c b/gobject/gvalue.c index 4ebbbbc08..b14d28c5f 100644 --- a/gobject/gvalue.c +++ b/gobject/gvalue.c @@ -16,16 +16,35 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ + +/* + * FIXME: MT-safety + */ + +#include "config.h" + +#include <string.h> + +#include "gvalue.h" +#include "gvaluecollector.h" +#include "gbsearcharray.h" +#include "gobjectalias.h" + + /** * SECTION:generic_values - * @Short_description: A polymorphic type that can hold values of any other type - * @See_also: The fundamental types which all support #GValue operations and - * thus can be used as a type initializer for g_value_init() are defined by - * a separate interface. See the <link - * linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values - * API</link> for details. + * + * @Short_description: A polymorphic type that can hold values of any + * other type + * + * @See_also: The fundamental types which all support #GValue + * operations and thus can be used as a type initializer for + * g_value_init() are defined by a separate interface. See the <link + * linkend="gobject-Standard-Parameter-and-Value-Types">Standard + * Values API</link> for details. + * * @Title: Generic values - * + * * The #GValue structure is basically a variable container that consists * of a type identifier and a specific value of that type. * The type identifier within a #GValue structure always determines the @@ -39,17 +58,6 @@ * provided by this interface. */ -/* - * FIXME: MT-safety - */ - -#include <string.h> - -#include "gvalue.h" -#include "gvaluecollector.h" -#include "gbsearcharray.h" -#include "gobjectalias.h" - /* --- typedefs & structures --- */ typedef struct { @@ -92,9 +100,9 @@ value_meminit (GValue *value, * g_value_init: * @value: A zero-filled (uninitialized) #GValue structure. * @g_type: Type the #GValue should hold values of. - * + * * Initializes @value with the default value of @type. - * + * * Returns: the #GValue structure that has been passed in */ GValue* @@ -132,7 +140,7 @@ g_value_init (GValue *value, * g_value_copy: * @src_value: An initialized #GValue structure. * @dest_value: An initialized #GValue structure of the same type as @src_value. - * + * * Copies the value of @src_value into @dest_value. */ void @@ -161,10 +169,10 @@ g_value_copy (const GValue *src_value, /** * g_value_reset: * @value: An initialized #GValue structure. - * + * * Clears the current value in @value and resets it to the default value * (as if the value had just been initialized). - * + * * Returns: the #GValue structure that has been passed in */ GValue* @@ -192,7 +200,7 @@ g_value_reset (GValue *value) /** * g_value_unset: * @value: An initialized #GValue structure. - * + * * Clears the current value in @value and "unsets" the type, * this releases all resources associated with this GValue. * An unset value is the same as an uninitialized (zero-filled) @@ -215,10 +223,10 @@ g_value_unset (GValue *value) /** * g_value_fits_pointer: * @value: An initialized #GValue structure. - * + * * Determines if @value will fit inside the size of a pointer value. * This is an internal function introduced mainly for C marshallers. - * + * * Returns: %TRUE if @value will fit inside a pointer value. */ gboolean @@ -236,11 +244,11 @@ g_value_fits_pointer (const GValue *value) /** * g_value_peek_pointer: * @value: An initialized #GValue structure. - * + * * Return the value contents as pointer. This function asserts that * g_value_fits_pointer() returned %TRUE for the passed in value. * This is an internal function introduced mainly for C marshallers. - * + * * Returns: %TRUE if @value will fit inside a pointer value. */ gpointer @@ -264,8 +272,8 @@ g_value_peek_pointer (const GValue *value) * g_value_set_instance: * @value: An initialized #GValue structure. * @instance: the instance - * - * Sets @value from an instantiatable type via the + * + * Sets @value from an instantiatable type via the * value_table's collect_value() function. */ void @@ -365,7 +373,7 @@ transform_entries_cmp (gconstpointer bsearch_node1, * @dest_type: Target type. * @transform_func: a function which transforms values of type @src_type * into value of type @dest_type - * + * * Registers a value transformation function for use in g_value_transform(). * A previously registered transformation function for @src_type and @dest_type * will be replaced. @@ -402,10 +410,10 @@ g_value_register_transform_func (GType src_type, * g_value_type_transformable: * @src_type: Source type. * @dest_type: Target type. - * + * * Check whether g_value_transform() is able to transform values * of type @src_type into values of type @dest_type. - * + * * Returns: %TRUE if the transformation is possible, %FALSE otherwise. */ gboolean @@ -423,10 +431,10 @@ g_value_type_transformable (GType src_type, * g_value_type_compatible: * @src_type: source type to be copied. * @dest_type: destination type for copying. - * + * * Returns whether a #GValue of type @src_type can be copied into * a #GValue of type @dest_type. - * + * * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. */ gboolean @@ -444,7 +452,7 @@ g_value_type_compatible (GType src_type, * g_value_transform: * @src_value: Source value. * @dest_value: Target value. - * + * * Tries to cast the contents of @src_value into a type appropriate * to store in @dest_value, e.g. to transform a %G_TYPE_INT value * into a %G_TYPE_FLOAT value. Performing transformations between @@ -452,7 +460,7 @@ g_value_type_compatible (GType src_type, * transformations into strings might reveal seemingly arbitrary * results and shouldn't be relied upon for production code (such * as rcfile value or object property serialization). - * + * * Returns: Whether a transformation rule was found and could be applied. * Upon failing transformations, @dest_value is left untouched. */ diff --git a/gobject/gvaluearray.c b/gobject/gvaluearray.c index ff1249f20..2137e357a 100644 --- a/gobject/gvaluearray.c +++ b/gobject/gvaluearray.c @@ -27,14 +27,17 @@ #include <stdlib.h> /* qsort() */ #include "gvaluearray.h" - #include "gobjectalias.h" /** * SECTION:value_arrays - * @Short_description: A container structure to maintain an array of generic values + * + * @Short_description: A container structure to maintain an array of + * generic values + * * @See_also:#GValue, #GParamSpecValueArray, g_param_spec_value_array() + * * @Title: Value arrays * * The prime purpose of a #GValueArray is for it to be used as an @@ -56,9 +59,9 @@ * g_value_array_get_nth: * @value_array: #GValueArray to get a value from * @index_: index of the value of interest - * + * * Return a pointer to the value at @index_ containd in @value_array. - * + * * Returns: pointer to a value at @index_ in @value_array */ GValue* @@ -107,11 +110,11 @@ value_array_shrink (GValueArray *value_array) /** * g_value_array_new: * @n_prealloced: number of values to preallocate space for - * + * * Allocate and initialize a new #GValueArray, optionally preserve space * for @n_prealloced elements. New arrays always contain 0 elements, * regardless of the value of @n_prealloced. - * + * * Returns: a newly allocated #GValueArray with 0 values */ GValueArray* @@ -131,7 +134,7 @@ g_value_array_new (guint n_prealloced) /** * g_value_array_free: * @value_array: #GValueArray to free - * + * * Free a #GValueArray including its contents. */ void @@ -155,10 +158,10 @@ g_value_array_free (GValueArray *value_array) /** * g_value_array_copy: * @value_array: #GValueArray to copy - * + * * Construct an exact copy of a #GValueArray by duplicating all its * contents. - * + * * Returns: Newly allocated copy of #GValueArray */ GValueArray* @@ -189,9 +192,9 @@ g_value_array_copy (const GValueArray *value_array) * g_value_array_prepend: * @value_array: #GValueArray to add an element to * @value: #GValue to copy into #GValueArray - * + * * Insert a copy of @value as first element of @value_array. - * + * * Returns: the #GValueArray passed in as @value_array */ GValueArray* @@ -207,9 +210,9 @@ g_value_array_prepend (GValueArray *value_array, * g_value_array_append: * @value_array: #GValueArray to add an element to * @value: #GValue to copy into #GValueArray - * + * * Insert a copy of @value as last element of @value_array. - * + * * Returns: the #GValueArray passed in as @value_array */ GValueArray* @@ -226,9 +229,9 @@ g_value_array_append (GValueArray *value_array, * @value_array: #GValueArray to add an element to * @index_: insertion position, must be <= value_array->n_values * @value: #GValue to copy into #GValueArray - * + * * Insert a copy of @value at specified position into @value_array. - * + * * Returns: the #GValueArray passed in as @value_array */ GValueArray* @@ -261,9 +264,9 @@ g_value_array_insert (GValueArray *value_array, * g_value_array_remove: * @value_array: #GValueArray to remove an element from * @index_: position of value to remove, must be < value_array->n_values - * + * * Remove the value at position @index_ from @value_array. - * + * * Returns: the #GValueArray passed in as @value_array */ GValueArray* @@ -290,12 +293,12 @@ g_value_array_remove (GValueArray *value_array, * g_value_array_sort: * @value_array: #GValueArray to sort * @compare_func: function to compare elements - * + * * Sort @value_array using @compare_func to compare the elements accoring to * the semantics of #GCompareFunc. - * + * * The current implementation uses Quick-Sort as sorting algorithm. - * + * * Returns: the #GValueArray passed in as @value_array */ GValueArray* @@ -317,13 +320,12 @@ g_value_array_sort (GValueArray *value_array, * @value_array: #GValueArray to sort * @compare_func: function to compare elements * @user_data: extra data argument provided for @compare_func - * + * * Sort @value_array using @compare_func to compare the elements accoring * to the semantics of #GCompareDataFunc. - * - * + * * The current implementation uses Quick-Sort as sorting algorithm. - * + * * Returns: the #GValueArray passed in as @value_array */ GValueArray* diff --git a/gobject/gvaluetransform.c b/gobject/gvaluetransform.c index ca091606f..e1c3bba10 100644 --- a/gobject/gvaluetransform.c +++ b/gobject/gvaluetransform.c @@ -23,7 +23,6 @@ #include "gvalue.h" #include "genums.h" - #include "gobjectalias.h" diff --git a/gobject/gvaluetypes.c b/gobject/gvaluetypes.c index 765a8d6ec..0cd485289 100644 --- a/gobject/gvaluetypes.c +++ b/gobject/gvaluetypes.c @@ -32,7 +32,6 @@ #include "gparam.h" #include "gboxed.h" #include "genums.h" - #include "gobjectalias.h" @@ -559,7 +558,7 @@ g_value_types_init (void) * g_value_set_char: * @value: a valid #GValue of type %G_TYPE_CHAR * @v_char: character value to be set - * + * * Set the contents of a %G_TYPE_CHAR #GValue to @v_char. */ void @@ -574,7 +573,7 @@ g_value_set_char (GValue *value, /** * g_value_get_char: * @value: a valid #GValue of type %G_TYPE_CHAR - * + * * Get the contents of a %G_TYPE_CHAR #GValue. * * Returns: character contents of @value @@ -591,7 +590,7 @@ g_value_get_char (const GValue *value) * g_value_set_uchar: * @value: a valid #GValue of type %G_TYPE_UCHAR * @v_uchar: unsigned character value to be set - * + * * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. */ void @@ -606,9 +605,9 @@ g_value_set_uchar (GValue *value, /** * g_value_get_uchar: * @value: a valid #GValue of type %G_TYPE_UCHAR - * + * * Get the contents of a %G_TYPE_UCHAR #GValue. - * + * * Returns: unsigned character contents of @value */ guchar @@ -623,7 +622,7 @@ g_value_get_uchar (const GValue *value) * g_value_set_boolean: * @value: a valid #GValue of type %G_TYPE_BOOLEAN * @v_boolean: boolean value to be set - * + * * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. */ void @@ -638,9 +637,9 @@ g_value_set_boolean (GValue *value, /** * g_value_get_boolean: * @value: a valid #GValue of type %G_TYPE_BOOLEAN - * + * * Get the contents of a %G_TYPE_BOOLEAN #GValue. - * + * * Returns: boolean contents of @value */ gboolean @@ -655,7 +654,7 @@ g_value_get_boolean (const GValue *value) * g_value_set_int: * @value: a valid #GValue of type %G_TYPE_INT * @v_int: integer value to be set - * + * * Set the contents of a %G_TYPE_INT #GValue to @v_int. */ void @@ -670,9 +669,9 @@ g_value_set_int (GValue *value, /** * g_value_get_int: * @value: a valid #GValue of type %G_TYPE_INT - * + * * Get the contents of a %G_TYPE_INT #GValue. - * + * * Returns: integer contents of @value */ gint @@ -687,7 +686,7 @@ g_value_get_int (const GValue *value) * g_value_set_uint: * @value: a valid #GValue of type %G_TYPE_UINT * @v_uint: unsigned integer value to be set - * + * * Set the contents of a %G_TYPE_UINT #GValue to @v_uint. */ void @@ -702,9 +701,9 @@ g_value_set_uint (GValue *value, /** * g_value_get_uint: * @value: a valid #GValue of type %G_TYPE_UINT - * + * * Get the contents of a %G_TYPE_UINT #GValue. - * + * * Returns: unsigned integer contents of @value */ guint @@ -719,7 +718,7 @@ g_value_get_uint (const GValue *value) * g_value_set_long: * @value: a valid #GValue of type %G_TYPE_LONG * @v_long: long integer value to be set - * + * * Set the contents of a %G_TYPE_LONG #GValue to @v_long. */ void @@ -734,9 +733,9 @@ g_value_set_long (GValue *value, /** * g_value_get_long: * @value: a valid #GValue of type %G_TYPE_LONG - * + * * Get the contents of a %G_TYPE_LONG #GValue. - * + * * Returns: long integer contents of @value */ glong @@ -751,7 +750,7 @@ g_value_get_long (const GValue *value) * g_value_set_ulong: * @value: a valid #GValue of type %G_TYPE_ULONG * @v_ulong: unsigned long integer value to be set - * + * * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. */ void @@ -766,9 +765,9 @@ g_value_set_ulong (GValue *value, /** * g_value_get_ulong: * @value: a valid #GValue of type %G_TYPE_ULONG - * + * * Get the contents of a %G_TYPE_ULONG #GValue. - * + * * Returns: unsigned long integer contents of @value */ gulong @@ -782,9 +781,9 @@ g_value_get_ulong (const GValue *value) /** * g_value_get_int64: * @value: a valid #GValue of type %G_TYPE_INT64 - * + * * Get the contents of a %G_TYPE_INT64 #GValue. - * + * * Returns: 64bit integer contents of @value */ void @@ -800,7 +799,7 @@ g_value_set_int64 (GValue *value, * g_value_set_int64: * @value: a valid #GValue of type %G_TYPE_INT64 * @v_int64: 64bit integer value to be set - * + * * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. */ gint64 @@ -815,7 +814,7 @@ g_value_get_int64 (const GValue *value) * g_value_set_uint64: * @value: a valid #GValue of type %G_TYPE_UINT64 * @v_uint64: unsigned 64bit integer value to be set - * + * * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. */ void @@ -830,9 +829,9 @@ g_value_set_uint64 (GValue *value, /** * g_value_get_uint64: * @value: a valid #GValue of type %G_TYPE_UINT64 - * + * * Get the contents of a %G_TYPE_UINT64 #GValue. - * + * * Returns: unsigned 64bit integer contents of @value */ guint64 @@ -847,7 +846,7 @@ g_value_get_uint64 (const GValue *value) * g_value_set_float: * @value: a valid #GValue of type %G_TYPE_FLOAT * @v_float: float value to be set - * + * * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. */ void @@ -862,9 +861,9 @@ g_value_set_float (GValue *value, /** * g_value_get_float: * @value: a valid #GValue of type %G_TYPE_FLOAT - * + * * Get the contents of a %G_TYPE_FLOAT #GValue. - * + * * Returns: float contents of @value */ gfloat @@ -879,7 +878,7 @@ g_value_get_float (const GValue *value) * g_value_set_double: * @value: a valid #GValue of type %G_TYPE_DOUBLE * @v_double: double value to be set - * + * * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. */ void @@ -894,9 +893,9 @@ g_value_set_double (GValue *value, /** * g_value_get_double: * @value: a valid #GValue of type %G_TYPE_DOUBLE - * + * * Get the contents of a %G_TYPE_DOUBLE #GValue. - * + * * Returns: double contents of @value */ gdouble @@ -911,7 +910,7 @@ g_value_get_double (const GValue *value) * g_value_set_string: * @value: a valid #GValue of type %G_TYPE_STRING * @v_string: string to be set - * + * * Set the contents of a %G_TYPE_STRING #GValue to @v_string. */ void @@ -936,7 +935,7 @@ g_value_set_string (GValue *value, * g_value_set_static_string: * @value: a valid #GValue of type %G_TYPE_STRING * @v_string: static string to be set - * + * * Set the contents of a %G_TYPE_STRING #GValue to @v_string. * The string is assumed to be static, and is thus not duplicated * when setting the #GValue. @@ -957,9 +956,9 @@ g_value_set_static_string (GValue *value, * g_value_set_string_take_ownership: * @value: a valid #GValue of type %G_TYPE_STRING * @v_string: duplicated unowned string to be set - * + * * This is an internal function introduced mainly for C marshallers. - * + * * Deprecated: 2.4: Use g_value_take_string() instead. */ void @@ -973,9 +972,9 @@ g_value_set_string_take_ownership (GValue *value, * g_value_take_string: * @value: a valid #GValue of type %G_TYPE_STRING * @v_string: duplicated unowned string to be set - * + * * Sets the contents of a %G_TYPE_STRING #GValue to @v_string. - * + * * Since: 2.4 */ void @@ -994,9 +993,9 @@ g_value_take_string (GValue *value, /** * g_value_get_string: * @value: a valid #GValue of type %G_TYPE_STRING - * + * * Get the contents of a %G_TYPE_STRING #GValue. - * + * * Returns: string content of @value */ G_CONST_RETURN gchar* @@ -1010,9 +1009,9 @@ g_value_get_string (const GValue *value) /** * g_value_dup_string: * @value: a valid #GValue of type %G_TYPE_STRING - * + * * Get a copy the contents of a %G_TYPE_STRING #GValue. - * + * * Returns: a newly allocated copy of the string content of @value */ gchar* @@ -1027,7 +1026,7 @@ g_value_dup_string (const GValue *value) * g_value_set_pointer: * @value: a valid #GValue of %G_TYPE_POINTER * @v_pointer: pointer value to be set - * + * * Set the contents of a pointer #GValue to @v_pointer. */ void @@ -1042,9 +1041,9 @@ g_value_set_pointer (GValue *value, /** * g_value_get_pointer: * @value: a valid #GValue of %G_TYPE_POINTER - * + * * Get the contents of a pointer #GValue. - * + * * Returns: pointer contents of @value */ gpointer @@ -1069,12 +1068,12 @@ g_gtype_get_type (void) * g_value_set_gtype: * @value: a valid #GValue of type %G_TYPE_GTYPE * @v_gtype: #GType to be set - * + * * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. - * + * * Since: 2.12 */ -void +void g_value_set_gtype (GValue *value, GType v_gtype) { @@ -1087,13 +1086,14 @@ g_value_set_gtype (GValue *value, /** * g_value_get_gtype: * @value: a valid #GValue of type %G_TYPE_GTYPE - * + * * Get the contents of a %G_TYPE_GTYPE #GValue. - * + * * Since: 2.12 + * * Returns: the #GType stored in @value */ -GType +GType g_value_get_gtype (const GValue *value) { g_return_val_if_fail (G_VALUE_HOLDS_GTYPE (value), 0); @@ -1104,12 +1104,12 @@ g_value_get_gtype (const GValue *value) /** * g_strdup_value_contents: * @value: #GValue which contents are to be described. - * - * Return a newly allocated string, which describes the contents of a #GValue. - * The main purpose of this function is to describe #GValue contents for - * debugging output, the way in which the contents are described may change - * between different GLib versions. - * + * + * Return a newly allocated string, which describes the contents of a + * #GValue. The main purpose of this function is to describe #GValue + * contents for debugging output, the way in which the contents are + * described may change between different GLib versions. + * * Returns: Newly allocated string. */ gchar* @@ -1177,10 +1177,10 @@ g_strdup_value_contents (const GValue *value) /** * g_pointer_type_register_static: * @name: the name of the new pointer type. - * + * * Creates a new %G_TYPE_POINTER derived type id for a new - * pointer type with name @name. - * + * pointer type with name @name. + * * Returns: a new %G_TYPE_POINTER derived type id for @name. */ GType |