luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-24 14:36:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

remove trailing whitespace from newly added gtk-doc comments and

Browse Source 
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.


svn path=/trunk/; revision=7090
This commit is contained in:
Michael Natterer 2008-06-22 14:53:09 +00:00 committed by Michael Natterer
parent 5602b7e275
commit 6347be5fb6
16 changed files with 1225 additions and 1098 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
gobject/ChangeLog
View File

@ -1,3 +1,9 @@
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

12
gobject/gboxed.c
View File

@ -32,6 +32,7 @@
/**
* SECTION:gboxed
*
* @Short_description: A mechanism to wrap opaque C structures registered
* by the type system
*
@ -558,9 +559,10 @@ 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
*/
@ -673,8 +675,8 @@ g_value_set_boxed_take_ownership (GValue *value,
* @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

124
gobject/gclosure.c
View File

@ -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)
@ -148,9 +152,9 @@ enum {
* <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;
@ -297,19 +301,21 @@ closure_invoke_notifiers (GClosure *closure,
* @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.
* 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.
* 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,
@ -347,10 +353,10 @@ g_closure_set_meta_marshal (GClosure *closure,
* @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,
@ -403,12 +409,12 @@ g_closure_add_marshal_guards (GClosure *closure,
* @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,
@ -439,9 +445,10 @@ g_closure_add_finalize_notifier (GClosure *closure,
* @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,
@ -533,17 +540,19 @@ 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().
* 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).
* 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)
@ -567,8 +576,8 @@ g_closure_invalidate (GClosure *closure)
* @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.
* 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)
@ -596,13 +605,14 @@ g_closure_unref (GClosure *closure)
* @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:
* 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);
@ -666,7 +676,6 @@ g_closure_sink (GClosure *closure)
*
* Removes an invalidation notifier.
*
*
* Notice that notifiers are automatically removed after they are run.
*/
void
@ -942,6 +951,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -955,6 +965,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -968,6 +979,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -981,6 +993,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -994,6 +1007,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1007,6 +1021,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1020,6 +1035,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1033,6 +1049,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1046,6 +1063,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1059,6 +1077,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1072,6 +1091,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1085,6 +1105,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1098,6 +1119,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1111,6 +1133,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1124,6 +1147,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1137,6 +1161,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1150,6 +1175,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1163,6 +1189,7 @@ g_signal_type_cclosure_new (GType itype,
* 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
@ -1177,6 +1204,7 @@ g_signal_type_cclosure_new (GType itype,
* <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
* denotes a flags type.
*/
/**
* g_cclosure_marshal_BOOL__FLAGS:
*

42
gobject/genums.c
View File

@ -177,8 +177,9 @@ value_flags_enum_lcopy_value (const GValue *value,
*
* 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
* 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.
@ -220,8 +221,9 @@ g_enum_register_static (const gchar *name,
*
* 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
* 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.
@ -262,8 +264,9 @@ g_flags_register_static (const gchar *name,
* 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
@ -307,8 +310,8 @@ g_enum_complete_type_info (GType g_enum_type,
* 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
@ -383,8 +386,8 @@ g_flags_class_init (GFlagsClass *class,
*
* 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,
@ -412,8 +415,8 @@ g_enum_get_value_by_name (GEnumClass *enum_class,
*
* 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,
@ -441,8 +444,8 @@ g_flags_get_value_by_name (GFlagsClass *flags_class,
*
* 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,
@ -470,8 +473,8 @@ g_enum_get_value_by_nick (GEnumClass *enum_class,
*
* 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,
@ -499,8 +502,8 @@ g_flags_get_value_by_nick (GFlagsClass *flags_class,
*
* 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,
@ -527,7 +530,8 @@ g_enum_get_value (GEnumClass *enum_class,
*
* 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,

157
gobject/gobject.c
View File

@ -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)
{
@ -338,10 +343,11 @@ g_object_do_class_init (GObjectClass *class)
* @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.
* 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
@ -473,8 +479,8 @@ g_object_interface_install_property (gpointer g_iface,
*
* 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,
@ -515,9 +521,9 @@ g_object_class_find_property (GObjectClass *class,
* 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,
@ -652,9 +658,11 @@ g_object_class_list_properties (GObjectClass *class,
* 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,
@ -1430,9 +1438,9 @@ g_object_set_valist (GObject *object,
*
* 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().
*
* See g_object_get().
*/
@ -1530,9 +1538,9 @@ g_object_set (gpointer _object,
*
* 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>
@ -1700,9 +1708,9 @@ 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.
*
@ -1858,9 +1866,10 @@ g_object_connect (gpointer _object,
*
* A convenience function to disconnect multiple signals at once.
*
* The signal specs expected by this function have the form "any_signal", which
* means to disconnect any signal with matching callback and data, or
* "any_signal::signal_name", which only disconnects the signal named "signal_name".
* 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,
@ -1936,11 +1945,11 @@ weak_refs_notify (gpointer data)
* @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,
@ -2018,9 +2027,9 @@ g_object_weak_unref (GObject *object,
* @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,
@ -2087,6 +2096,7 @@ object_floating_flag_handler (GObject *object,
* reference.
*
* Since: 2.10
*
* Returns: %TRUE if @object has a floating reference
*/
gboolean
@ -2106,12 +2116,13 @@ g_object_is_floating (gpointer _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.
* 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
@ -2337,9 +2348,8 @@ 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)
@ -2464,7 +2474,8 @@ 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
@ -2521,9 +2532,10 @@ g_object_set_qdata_full (GObject *object,
* 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
*/
@ -2732,11 +2744,10 @@ g_value_object_lcopy_value (const GValue *value,
* 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
@ -2839,9 +2850,11 @@ 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.
* 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.
* Returns: object content of @value, should be unreferenced when no
* longer needed.
*/
gpointer
g_value_dup_object (const GValue *value)
@ -2977,15 +2990,15 @@ destroy_closure_array (gpointer data)
* @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,
@ -3028,10 +3041,10 @@ g_object_watch_closure (GObject *object,
* @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
*/
@ -3055,10 +3068,11 @@ g_closure_new_object (guint sizeof_closure,
* @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
*/
@ -3083,10 +3097,11 @@ g_cclosure_new_object (GCallback callback_func,
* @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
*/

109
gobject/gparam.c
View File

@ -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
@ -226,13 +230,13 @@ 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)
@ -390,15 +394,16 @@ is_canonical (const gchar *key)
* 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.
* 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.
* 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
*/
@ -470,12 +475,12 @@ g_param_spec_get_qdata (GParamSpec *pspec,
* @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,
@ -519,11 +524,10 @@ g_param_spec_set_qdata_full (GParamSpec *pspec,
* @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
*/
@ -550,6 +554,7 @@ g_param_spec_steal_qdata (GParamSpec *pspec,
* 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.
*/
@ -654,12 +659,13 @@ 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
* @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.
* 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().
@ -876,9 +882,9 @@ param_spec_pool_equals (gconstpointer key_spec_1,
* 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.
*/
@ -902,7 +908,8 @@ g_param_spec_pool_new (gboolean type_prefixing)
* @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)
@ -1106,10 +1113,11 @@ pool_list (gpointer key,
* @pool: a #GParamSpecPool
* @owner_type: the owner to look for
*
* Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in the pool.
* 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.
* 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,
@ -1240,7 +1248,8 @@ pool_depth_list_for_interface (gpointer key,
* @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.
* 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
@ -1344,9 +1353,9 @@ default_values_cmp (GParamSpec *pspec,
* @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.
*/
@ -1433,9 +1442,9 @@ g_value_set_param_take_ownership (GValue *value,
* @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
*/
@ -1472,9 +1481,11 @@ 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.
* 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.
* Returns: #GParamSpec content of @value, should be unreferenced when
* no longer needed.
*/
GParamSpec*
g_value_dup_param (const GValue *value)

27
gobject/gparamspecs.c
View File

@ -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
@ -1766,7 +1770,8 @@ g_param_spec_long (const gchar *name,
* @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.
*
@ -2245,6 +2250,7 @@ g_param_spec_pointer (const gchar *name,
* See g_param_spec_internal() for details on property names.
*
* Since: 2.10
*
* Returns: a newly created parameter specification
*/
GParamSpec*
@ -2277,9 +2283,9 @@ g_param_spec_gtype (const gchar *name,
* @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().
* %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.
*
@ -2357,6 +2363,7 @@ g_param_spec_object (const gchar *name,
* useful unless you are implementing a new base type similar to GObject.
*
* Since: 2.4
*
* Returns: the newly created #GParamSpec
*/
GParamSpec*

53
gobject/gsignal.c
View File

@ -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
@ -1998,9 +2001,9 @@ g_signal_connect_data (gpointer instance,
* @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
* 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.
*
@ -2036,16 +2039,16 @@ g_signal_handler_block (gpointer instance,
* @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
* 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).
* 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.
@ -2362,13 +2365,14 @@ g_signal_handlers_unblock_matched (gpointer instance,
* @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.
*/
@ -2409,12 +2413,12 @@ g_signal_handlers_disconnect_matched (gpointer instance,
* 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.
* 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.
* Returns: %TRUE if a handler is connected to the signal, %FALSE
* otherwise.
*/
gboolean
g_signal_has_handler_pending (gpointer instance,
@ -3138,6 +3142,7 @@ type_debug_name (GType type)
* and no further handling is needed.
*
* Since: 2.4
*
* Returns: standard #GSignalAccumulator result
*/
gboolean

172
gobject/gtype.c
View File

@ -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;
@ -1389,6 +1401,7 @@ g_type_interface_add_prerequisite (GType interface_type,
* Returns the prerequisites of an interfaces type.
*
* Since: 2.2
*
* Returns: a newly-allocated zero-terminated array of #GType containing
* the prerequisites of @interface_type
*/
@ -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)
{
@ -1592,18 +1610,19 @@ 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.
@ -1663,11 +1682,11 @@ 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.
* 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.
* Like g_type_create_instance(), this function is reserved for
* implementors of fundamental types.
*/
void
g_type_free_instance (GTypeInstance *instance)
@ -2193,9 +2212,9 @@ g_type_add_class_cache_func (gpointer cache_data,
* @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,
@ -2234,14 +2253,14 @@ g_type_remove_class_cache_func (gpointer cache_data,
* 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).
* 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.
* 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
*/
@ -2386,6 +2405,7 @@ g_type_register_fundamental (GType type_id,
* struct and calling g_type_register_static().
*
* Since: 2.12
*
* Returns: The new type identifier.
*/
GType
@ -2767,11 +2787,11 @@ g_type_class_peek_static (GType type)
* @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)));
@ -2808,8 +2828,8 @@ g_type_class_peek_parent (gpointer g_class)
* @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 an interface to which the
* passed in class conforms.
*
* Returns: The GTypeInterface structure of iface_type if implemented
* by @instance_class, %NULL otherwise
@ -2854,9 +2874,9 @@ g_type_interface_peek (gpointer instance_class,
* 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.
* 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)
@ -2907,6 +2927,7 @@ g_type_interface_peek_parent (gpointer g_iface)
* 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.
@ -2952,10 +2973,11 @@ 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.
*/
@ -3014,11 +3036,11 @@ 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.
*/
@ -3056,8 +3078,10 @@ 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.
*/
@ -3084,8 +3108,8 @@ 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.
*/
@ -3103,8 +3127,8 @@ 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.
*/
@ -3123,12 +3147,13 @@ g_type_depth (GType type)
* @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.
*/
@ -3208,8 +3233,9 @@ type_node_conforms_to_U (TypeNode *node,
* @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.
*/
@ -3271,7 +3297,8 @@ 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
@ -3475,10 +3502,11 @@ type_add_flags_W (TypeNode *node,
* 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.
* 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,
@ -3571,9 +3599,9 @@ g_type_get_plugin (GType 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().
* @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.
@ -3754,7 +3782,7 @@ g_type_check_class_cast (GTypeClass *type_class,
return type_class;
}
/*
/**
* g_type_check_instance:
* @instance: A valid #GTypeInstance structure.
*
@ -3941,7 +3969,8 @@ 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.
*/
@ -4053,9 +4082,10 @@ 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
g_type_init (void)

23
gobject/gtypemodule.c
View File

@ -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
@ -444,8 +447,8 @@ g_type_module_register_type (GTypeModule *module,
* @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
* 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
@ -504,9 +507,10 @@ 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,
@ -517,6 +521,7 @@ g_type_module_add_interface (GTypeModule *module,
* not be unloaded.
*
* Since: 2.6
*
* Returns: the new or existing type ID
*/
GType
@ -541,9 +546,10 @@ 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,
@ -554,6 +560,7 @@ g_type_module_register_enum (GTypeModule *module,
* not be unloaded.
*
* Since: 2.6
*
* Returns: the new or existing type ID
*/
GType

21
gobject/gtypeplugin.c
View File

@ -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
@ -112,9 +115,9 @@ 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)
@ -131,9 +134,9 @@ 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)
@ -184,9 +187,9 @@ g_type_plugin_complete_type_info (GTypePlugin *plugin,
* @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,

42
gobject/gvalue.c
View File

@ -16,14 +16,33 @@
* 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
@ -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 {

8
gobject/gvaluearray.c
View File

@ -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
@ -321,7 +324,6 @@ g_value_array_sort (GValueArray *value_array,
* 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

1
gobject/gvaluetransform.c
View File

@ -23,7 +23,6 @@
#include "gvalue.h"
#include "genums.h"
#include "gobjectalias.h"

10
gobject/gvaluetypes.c
View File

@ -32,7 +32,6 @@
#include "gparam.h"
#include "gboxed.h"
#include "genums.h"
#include "gobjectalias.h"
@ -1091,6 +1090,7 @@ g_value_set_gtype (GValue *value,
* Get the contents of a %G_TYPE_GTYPE #GValue.
*
* Since: 2.12
*
* Returns: the #GType stored in @value
*/
GType
@ -1105,10 +1105,10 @@ 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.
*/