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> 2008-06-22 Michael Natterer <mitch@imendio.com>
* *.c: moved includes back to the top of the files (before gtk-doc * *.c: moved includes back to the top of the files (before gtk-doc

44
gobject/gboxed.c
View File

@ -32,8 +32,9 @@
/** /**
* SECTION:gboxed * SECTION:gboxed
*
* @Short_description: A mechanism to wrap opaque C structures registered * @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() * @See_also: #GParamSpecBoxed, g_param_spec_boxed()
* *
@ -114,7 +115,7 @@ value_free (gpointer boxed)
} }
void void
g_boxed_type_init (void) g_boxed_type_init (void)
{ {
static const GTypeInfo info = { static const GTypeInfo info = {
0, /* class_size */ 0, /* class_size */
@ -372,11 +373,11 @@ boxed_proxy_lcopy_value (const GValue *value,
* @name: Name of the new boxed type. * @name: Name of the new boxed type.
* @boxed_copy: Boxed structure copy function. * @boxed_copy: Boxed structure copy function.
* @boxed_free: Boxed structure free function. * @boxed_free: Boxed structure free function.
* *
* This function creates a new %G_TYPE_BOXED derived type id for a new * 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 * boxed type with name @name. Boxed type handling functions have to be
* provided to copy and free opaque boxed structures of this type. * provided to copy and free opaque boxed structures of this type.
* *
* Returns: New %G_TYPE_BOXED derived type id for @name. * Returns: New %G_TYPE_BOXED derived type id for @name.
*/ */
GType GType
@ -465,7 +466,7 @@ g_boxed_copy (GType boxed_type,
else else
{ {
GValue src_value, dest_value; GValue src_value, dest_value;
/* we heavily rely on third-party boxed type value vtable /* we heavily rely on third-party boxed type value vtable
* implementations to follow normal boxed value storage * implementations to follow normal boxed value storage
* (data[0].v_pointer is the boxed struct, and * (data[0].v_pointer is the boxed struct, and
@ -500,7 +501,7 @@ g_boxed_copy (GType boxed_type,
* g_boxed_free: * g_boxed_free:
* @boxed_type: The type of @boxed. * @boxed_type: The type of @boxed.
* @boxed: The boxed structure to be freed. * @boxed: The boxed structure to be freed.
* *
* Free the boxed structure @boxed which is of type @boxed_type. * Free the boxed structure @boxed which is of type @boxed_type.
*/ */
void void
@ -540,9 +541,9 @@ g_boxed_free (GType boxed_type,
/** /**
* g_value_get_boxed: * g_value_get_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type * @value: a valid #GValue of %G_TYPE_BOXED derived type
* *
* Get the contents of a %G_TYPE_BOXED derived #GValue. * Get the contents of a %G_TYPE_BOXED derived #GValue.
* *
* Returns: boxed contents of @value * Returns: boxed contents of @value
*/ */
gpointer gpointer
@ -557,11 +558,12 @@ g_value_get_boxed (const GValue *value)
/** /**
* g_value_dup_boxed: * g_value_dup_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type * @value: a valid #GValue of %G_TYPE_BOXED derived type
* *
* Get the contents of a %G_TYPE_BOXED derived #GValue. * Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting,
* Upon getting, the boxed value is duplicated and needs to be * the boxed value is duplicated and needs to be later freed with
* later freed with g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), return_value); * g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value),
* * return_value);
*
* Returns: boxed contents of @value * Returns: boxed contents of @value
*/ */
gpointer gpointer
@ -620,7 +622,7 @@ value_set_boxed_internal (GValue *value,
* g_value_set_boxed: * g_value_set_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type * @value: a valid #GValue of %G_TYPE_BOXED derived type
* @v_boxed: boxed value to be set * @v_boxed: boxed value to be set
* *
* Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
*/ */
void void
@ -637,7 +639,7 @@ g_value_set_boxed (GValue *value,
* g_value_set_static_boxed: * g_value_set_static_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type * @value: a valid #GValue of %G_TYPE_BOXED derived type
* @v_boxed: static boxed value to be set * @v_boxed: static boxed value to be set
* *
* Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. * 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 * The boxed value is assumed to be static, and is thus not duplicated
* when setting the #GValue. * when setting the #GValue.
@ -656,9 +658,9 @@ g_value_set_static_boxed (GValue *value,
* g_value_set_boxed_take_ownership: * g_value_set_boxed_take_ownership:
* @value: a valid #GValue of %G_TYPE_BOXED derived type * @value: a valid #GValue of %G_TYPE_BOXED derived type
* @v_boxed: duplicated unowned boxed value to be set * @v_boxed: duplicated unowned boxed value to be set
* *
* This is an internal function introduced mainly for C marshallers. * This is an internal function introduced mainly for C marshallers.
* *
* Deprecated: 2.4: Use g_value_take_boxed() instead. * Deprecated: 2.4: Use g_value_take_boxed() instead.
*/ */
void void
@ -672,11 +674,11 @@ g_value_set_boxed_take_ownership (GValue *value,
* g_value_take_boxed: * g_value_take_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type * @value: a valid #GValue of %G_TYPE_BOXED derived type
* @v_boxed: duplicated unowned boxed value to be set * @v_boxed: duplicated unowned boxed value to be set
* *
* Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed
* takes over the ownership of the callers reference 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. * the caller doesn't have to unref it any more.
* *
* Since: 2.4 * Since: 2.4
*/ */
void void

274
gobject/gclosure.c
View File

@ -30,9 +30,12 @@
#include "gvalue.h" #include "gvalue.h"
#include "gobjectalias.h" #include "gobjectalias.h"
/** /**
* SECTION:gclosure * SECTION:gclosure
*
* @Short_description: Functions as first-class objects * @Short_description: Functions as first-class objects
*
* @Title: Closures * @Title: Closures
* *
* A #GClosure represents a callback supplied by the programmer. It * A #GClosure represents a callback supplied by the programmer. It
@ -84,6 +87,7 @@
* </itemizedlist> * </itemizedlist>
*/ */
#define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1) #define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1)
#define CLOSURE_MAX_N_GUARDS ((1 << 1) - 1) #define CLOSURE_MAX_N_GUARDS ((1 << 1) - 1)
#define CLOSURE_MAX_N_FNOTIFIERS ((1 << 2) - 1) #define CLOSURE_MAX_N_FNOTIFIERS ((1 << 2) - 1)
@ -144,47 +148,47 @@ enum {
/* --- functions --- */ /* --- functions --- */
/** /**
* g_closure_new_simple: * g_closure_new_simple:
* @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> * <literal>sizeof (GClosure)</literal>
* @data: data to store in the @data field of the newly allocated #GClosure * @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 * Allocates a struct of the given size and initializes the initial
* as a #GClosure. This function is mainly useful when implementing new types * part as a #GClosure. This function is mainly useful when
* of closures. * implementing new types of closures.
* *
* |[ * |[
* typedef struct _MyClosure MyClosure; * typedef struct _MyClosure MyClosure;
* struct _MyClosure * struct _MyClosure
* { * {
* GClosure closure; * GClosure closure;
* // extra data goes here * // extra data goes here
* }; * };
* *
* static void * static void
* my_closure_finalize (gpointer notify_data, * my_closure_finalize (gpointer notify_data,
* GClosure *closure) * GClosure *closure)
* { * {
* MyClosure *my_closure = (MyClosure *)closure; * MyClosure *my_closure = (MyClosure *)closure;
* *
* // free extra data here * // free extra data here
* } * }
* *
* MyClosure *my_closure_new (gpointer data) * MyClosure *my_closure_new (gpointer data)
* { * {
* GClosure *closure; * GClosure *closure;
* MyClosure *my_closure; * MyClosure *my_closure;
* *
* closure = g_closure_new_simple (sizeof (MyClosure), data); * closure = g_closure_new_simple (sizeof (MyClosure), data);
* my_closure = (MyClosure *) closure; * my_closure = (MyClosure *) closure;
* *
* // initialize extra data here * // initialize extra data here
* *
* g_closure_add_finalize_notifier (closure, notify_data, * g_closure_add_finalize_notifier (closure, notify_data,
* my_closure_finalize); * my_closure_finalize);
* return my_closure; * return my_closure;
* } * }
* ]| * ]|
* *
* Returns: a newly allocated #GClosure * Returns: a newly allocated #GClosure
*/ */
GClosure* GClosure*
@ -296,20 +300,22 @@ closure_invoke_notifiers (GClosure *closure,
* @closure: a #GClosure * @closure: a #GClosure
* @marshal_data: context-dependent data to pass to @meta_marshal * @marshal_data: context-dependent data to pass to @meta_marshal
* @meta_marshal: a #GClosureMarshal function * @meta_marshal: a #GClosureMarshal function
* *
* Sets the meta marshaller of @closure. * Sets the meta marshaller of @closure. A meta marshaller wraps
* A meta marshaller wraps @closure->marshal and modifies the way it is called * @closure->marshal and modifies the way it is called in some
* in some fashion. The most common use of this facility is for C callbacks. * fashion. The most common use of this facility is for C callbacks.
* The same marshallers (generated by * The same marshallers (generated by <link
* <link linkend="glib-genmarshal">glib-genmarshal</link>) are used everywhere, * linkend="glib-genmarshal">glib-genmarshal</link>) are used
* but the way that we get the callback function differs. In most cases we want * everywhere, but the way that we get the callback function
* to use @closure->callback, but in other cases we want to use some * differs. In most cases we want to use @closure->callback, but in
* different technique to retrieve the callback function. * 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. * For example, class closures for signals (see
* The meta marshaller retrieves the right callback and passes it to the * g_signal_type_cclosure_new()) retrieve the callback function from a
* marshaller as the @marshal_data argument. * 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 void
g_closure_set_meta_marshal (GClosure *closure, 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 * @pre_marshal_notify: a function to call before the closure callback
* @post_marshal_data: data to pass to @post_marshal_notify * @post_marshal_data: data to pass to @post_marshal_notify
* @post_marshal_notify: a function to call after the closure callback * @post_marshal_notify: a function to call after the closure callback
* *
* Adds a pair of notifiers which get invoked before and after the closure * Adds a pair of notifiers which get invoked before and after the
* callback, respectively. This is typically used to protect the extra arguments * closure callback, respectively. This is typically used to protect
* for the duration of the callback. See g_object_watch_closure() for an * the extra arguments for the duration of the callback. See
* example of marshal guards. * g_object_watch_closure() for an example of marshal guards.
*/ */
void void
g_closure_add_marshal_guards (GClosure *closure, g_closure_add_marshal_guards (GClosure *closure,
@ -402,13 +408,13 @@ g_closure_add_marshal_guards (GClosure *closure,
* @closure: a #GClosure * @closure: a #GClosure
* @notify_data: data to pass to @notify_func * @notify_data: data to pass to @notify_func
* @notify_func: the callback function to register * @notify_func: the callback function to register
* *
* Registers a finalization notifier which will be called when the reference * Registers a finalization notifier which will be called when the
* count of @closure goes down to 0. Multiple finalization notifiers on a * reference count of @closure goes down to 0. Multiple finalization
* single closure are invoked in unspecified order. If a single call to * notifiers on a single closure are invoked in unspecified order. If
* g_closure_unref() results in the closure being both invalidated and * a single call to g_closure_unref() results in the closure being
* finalized, then the invalidate notifiers will be run before the finalize * both invalidated and finalized, then the invalidate notifiers will
* notifiers. * be run before the finalize notifiers.
*/ */
void void
g_closure_add_finalize_notifier (GClosure *closure, g_closure_add_finalize_notifier (GClosure *closure,
@ -438,10 +444,11 @@ g_closure_add_finalize_notifier (GClosure *closure,
* @closure: a #GClosure * @closure: a #GClosure
* @notify_data: data to pass to @notify_func * @notify_data: data to pass to @notify_func
* @notify_func: the callback function to register * @notify_func: the callback function to register
* *
* Registers an invalidation notifier which will be called when the @closure * Registers an invalidation notifier which will be called when the
* is invalidated with g_closure_invalidate(). Invalidation notifiers are * @closure is invalidated with g_closure_invalidate(). Invalidation
* invoked before finalization notifiers, in an unspecified order. * notifiers are invoked before finalization notifiers, in an
* unspecified order.
*/ */
void void
g_closure_add_invalidate_notifier (GClosure *closure, g_closure_add_invalidate_notifier (GClosure *closure,
@ -509,10 +516,10 @@ closure_try_remove_fnotify (GClosure *closure,
/** /**
* g_closure_ref: * g_closure_ref:
* @closure: #GClosure to increment the reference count on * @closure: #GClosure to increment the reference count on
* *
* Increments the reference count on a closure to force it staying * Increments the reference count on a closure to force it staying
* alive while the caller holds a pointer to it. * alive while the caller holds a pointer to it.
* *
* Returns: The @closure passed in, for convenience * Returns: The @closure passed in, for convenience
*/ */
GClosure* GClosure*
@ -532,18 +539,20 @@ g_closure_ref (GClosure *closure)
/** /**
* g_closure_invalidate: * g_closure_invalidate:
* @closure: GClosure to invalidate * @closure: GClosure to invalidate
* *
* Sets a flag on the closure to indicate that it's calling environment has * Sets a flag on the closure to indicate that it's calling
* become invalid, and thus causes any future invocations of g_closure_invoke() * environment has become invalid, and thus causes any future
* on this @closure to be ignored. Also, invalidation notifiers installed on * invocations of g_closure_invoke() on this @closure to be
* the closure will be called at this point. Note that unless you are holding * ignored. Also, invalidation notifiers installed on the closure will
* a reference to the closure yourself, the invalidation notifiers may unref * be called at this point. Note that unless you are holding a
* the closure and cause it to be destroyed, so if you need to access the * reference to the closure yourself, the invalidation notifiers may
* closure after calling g_closure_invalidate(), make sure that you've * unref the closure and cause it to be destroyed, so if you need to
* previously called g_closure_ref(). * 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 void
g_closure_invalidate (GClosure *closure) g_closure_invalidate (GClosure *closure)
@ -565,10 +574,10 @@ g_closure_invalidate (GClosure *closure)
/** /**
* g_closure_unref: * g_closure_unref:
* @closure: #GClosure to decrement the reference count on * @closure: #GClosure to decrement the reference count on
* *
* Decrements the reference count of a closure after it was previously * Decrements the reference count of a closure after it was previously
* incremented by the same caller. If no other callers are using the closure, * incremented by the same caller. If no other callers are using the
* then the closure will be destroyed and freed. * closure, then the closure will be destroyed and freed.
*/ */
void void
g_closure_unref (GClosure *closure) g_closure_unref (GClosure *closure)
@ -594,27 +603,28 @@ g_closure_unref (GClosure *closure)
/** /**
* g_closure_sink: * g_closure_sink:
* @closure: #GClosure to decrement the initial reference count on, if it's * @closure: #GClosure to decrement the initial reference count on, if it's
* still being held * still being held
* *
* Takes over the initial ownership of a closure. * Takes over the initial ownership of a closure. Each closure is
* Each closure is initially created in a <firstterm>floating</firstterm> state, * initially created in a <firstterm>floating</firstterm> state, which
* which means that the initial reference count is not owned by any caller. * 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, * g_closure_sink() checks to see if the object is still floating, and
* unsets the floating state and decreases the reference count. If the closure * if so, unsets the floating state and decreases the reference
* is not floating, g_closure_sink() does nothing. The reason for the existance * count. If the closure is not floating, g_closure_sink() does
* of the floating state is to prevent cumbersome code sequences like: * 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); * closure = g_cclosure_new (cb_func, cb_data);
* g_source_set_closure (source, closure); * g_source_set_closure (source, closure);
* g_closure_unref (closure); // XXX GObject doesn't really need this * g_closure_unref (closure); // XXX GObject doesn't really need this
* ]| * ]|
* Because g_source_set_closure() (and similar functions) take ownership of the * Because g_source_set_closure() (and similar functions) take ownership of the
* initial reference count, if it is unowned, we instead can write: * initial reference count, if it is unowned, we instead can write:
* |[ * |[
* g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); * 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: * of storing a closure for later notification looks like:
* |[ * |[
* static GClosure *notify_closure = NULL; * 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 * 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(), * (if it hasn't been called on @closure yet) just like g_closure_unref(),
* g_closure_ref() should be called prior to this function. * g_closure_ref() should be called prior to this function.
@ -661,12 +671,11 @@ g_closure_sink (GClosure *closure)
* g_closure_remove_invalidate_notifier: * g_closure_remove_invalidate_notifier:
* @closure: a #GClosure * @closure: a #GClosure
* @notify_data: data which was passed to g_closure_add_invalidate_notifier() * @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 * @notify_func: the callback function to remove
* *
* Removes an invalidation notifier. * Removes an invalidation notifier.
* *
*
* Notice that notifiers are automatically removed after they are run. * Notice that notifiers are automatically removed after they are run.
*/ */
void void
@ -692,9 +701,9 @@ g_closure_remove_invalidate_notifier (GClosure *closure,
* @notify_data: data which was passed to g_closure_add_finalize_notifier() * @notify_data: data which was passed to g_closure_add_finalize_notifier()
* when registering @notify_func * when registering @notify_func
* @notify_func: the callback function to remove * @notify_func: the callback function to remove
* *
* Removes a finalization notifier. * Removes a finalization notifier.
* *
* Notice that notifiers are automatically removed after they are run. * Notice that notifiers are automatically removed after they are run.
*/ */
void void
@ -718,12 +727,12 @@ g_closure_remove_finalize_notifier (GClosure *closure,
* g_closure_invoke: * g_closure_invoke:
* @closure: a #GClosure * @closure: a #GClosure
* @return_value: a #GValue to store the return value. May be %NULL if the * @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 * @n_param_values: the length of the @param_values array
* @param_values: an array of #GValue<!-- -->s holding the arguments on * @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 * @invocation_hint: a context-dependent invocation hint
* *
* Invokes the closure, i.e. executes the callback represented by the @closure. * Invokes the closure, i.e. executes the callback represented by the @closure.
*/ */
void void
@ -773,7 +782,7 @@ g_closure_invoke (GClosure *closure,
* g_closure_set_marshal: * g_closure_set_marshal:
* @closure: a #GClosure * @closure: a #GClosure
* @marshal: a #GClosureMarshal function * @marshal: a #GClosureMarshal function
* *
* Sets the marshaller of @closure. The <literal>marshal_data</literal> * Sets the marshaller of @closure. The <literal>marshal_data</literal>
* of @marshal provides a way for a meta marshaller to provide additional * of @marshal provides a way for a meta marshaller to provide additional
* information to the marshaller. (See g_closure_set_meta_marshal().) For * 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 * @callback_func: the function to invoke
* @user_data: user data to pass to @callback_func * @user_data: user data to pass to @callback_func
* @destroy_data: destroy notify to be called when @user_data is no longer used * @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 * Creates a new closure which invokes @callback_func with @user_data as
* the last parameter. * the last parameter.
* *
* Returns: a new #GCClosure * Returns: a new #GCClosure
*/ */
GClosure* GClosure*
@ -828,10 +837,10 @@ g_cclosure_new (GCallback callback_func,
* @callback_func: the function to invoke * @callback_func: the function to invoke
* @user_data: user data to pass to @callback_func * @user_data: user data to pass to @callback_func
* @destroy_data: destroy notify to be called when @user_data is no longer used * @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 * Creates a new closure which invokes @callback_func with @user_data as
* the first parameter. * the first parameter.
* *
* Returns: a new #GCClosure * Returns: a new #GCClosure
*/ */
GClosure* GClosure*
@ -901,13 +910,13 @@ g_type_iface_meta_marshal (GClosure *closure,
/** /**
* g_signal_type_cclosure_new: * g_signal_type_cclosure_new:
* @itype: the #GType identifier of an interface or classed type * @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 * structure which is to be invoked by the new closure
* *
* Creates a new closure which invokes the function found at the offset * Creates a new closure which invokes the function found at the offset
* @struct_offset in the class structure of the interface or classed type * @struct_offset in the class structure of the interface or classed type
* identified by @itype. * identified by @itype.
* *
* Returns: a new #GCClosure * Returns: a new #GCClosure
*/ */
GClosure* GClosure*
@ -938,10 +947,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__BOOLEAN: * g_cclosure_marshal_VOID__BOOLEAN:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__CHAR: * g_cclosure_marshal_VOID__CHAR:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__UCHAR: * g_cclosure_marshal_VOID__UCHAR:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__INT: * g_cclosure_marshal_VOID__INT:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__UINT: * g_cclosure_marshal_VOID__UINT:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__LONG: * g_cclosure_marshal_VOID__LONG:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__ULONG: * g_cclosure_marshal_VOID__ULONG:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__ENUM: * g_cclosure_marshal_VOID__ENUM:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * 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.. * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type..
*/ */
/** /**
* g_cclosure_marshal_VOID__FLAGS: * g_cclosure_marshal_VOID__FLAGS:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * 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. * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type.
*/ */
/** /**
* g_cclosure_marshal_VOID__FLOAT: * g_cclosure_marshal_VOID__FLOAT:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__DOUBLE: * g_cclosure_marshal_VOID__DOUBLE:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__STRING: * g_cclosure_marshal_VOID__STRING:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__PARAM: * g_cclosure_marshal_VOID__PARAM:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__BOXED: * g_cclosure_marshal_VOID__BOXED:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__POINTER: * g_cclosure_marshal_VOID__POINTER:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__OBJECT: * g_cclosure_marshal_VOID__OBJECT:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_VOID__UINT_POINTER: * g_cclosure_marshal_VOID__UINT_POINTER:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>. * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>.
*/ */
/** /**
* g_cclosure_marshal_BOOLEAN__FLAGS: * g_cclosure_marshal_BOOLEAN__FLAGS:
* @closure: the #GClosure to which the marshaller belongs * @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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * 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 * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
* denotes a flags type. * denotes a flags type.
*/ */
/** /**
* g_cclosure_marshal_BOOL__FLAGS: * g_cclosure_marshal_BOOL__FLAGS:
* *
* Another name for g_cclosure_marshal_BOOLEAN__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 * @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke() * to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller * @marshal_data: additional data specified when registering the marshaller
* *
* A marshaller for a #GCClosure with a callback of type * A marshaller for a #GCClosure with a callback of type
* <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>. * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>.
*/ */

112
gobject/genums.c
View File

@ -171,16 +171,17 @@ value_flags_enum_lcopy_value (const GValue *value,
* g_enum_register_static: * g_enum_register_static:
* @name: A nul-terminated string used as the name of the new type. * @name: A nul-terminated string used as the name of the new type.
* @const_static_values: An array of #GEnumValue structs for the possible * @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 * members being 0. GObject keeps a reference to the data, so it cannot
* be stack-allocated. * be stack-allocated.
* *
* Registers a new static enumeration type with the name @name. * Registers a new static enumeration type with the name @name.
* *
* It is normally more convenient to let <link linkend="glib-mkenums">glib-mkenums</link> * It is normally more convenient to let <link
* generate a my_enum_get_type() function from a usual C enumeration definition * 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(). * than to write one yourself using g_enum_register_static().
* *
* Returns: The new type identifier. * Returns: The new type identifier.
*/ */
GType GType
@ -217,13 +218,14 @@ g_enum_register_static (const gchar *name,
* @const_static_values: An array of #GFlagsValue structs for the possible * @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. * 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. * GObject keeps a reference to the data, so it cannot be stack-allocated.
* *
* Registers a new static flags type with the name @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> * It is normally more convenient to let <link
* generate a my_flags_get_type() function from a usual C enumeration definition * 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(). * than to write one yourself using g_flags_register_static().
* *
* Returns: The new type identifier. * Returns: The new type identifier.
*/ */
GType GType
@ -259,12 +261,13 @@ g_flags_register_static (const gchar *name,
* @g_enum_type: the type identifier of the type being completed * @g_enum_type: the type identifier of the type being completed
* @info: the #GTypeInfo struct to be filled in * @info: the #GTypeInfo struct to be filled in
* @const_values: An array of #GEnumValue structs for the possible * @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. * members being 0.
* *
* This function is meant to be called from the complete_type_info() function * This function is meant to be called from the complete_type_info()
* of a #GTypePlugin implementation, as in the following example: * function of a #GTypePlugin implementation, as in the following
* * example:
*
* |[ * |[
* static void * static void
* my_enum_complete_type_info (GTypePlugin *plugin, * 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_FOO, "MY_ENUM_FOO", "foo" },
* { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
* { 0, NULL, NULL } * { 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 * @g_flags_type: the type identifier of the type being completed
* @info: the #GTypeInfo struct to be filled in * @info: the #GTypeInfo struct to be filled in
* @const_values: An array of #GFlagsValue structs for the possible * @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. * members being 0.
* *
* This function is meant to be called from the complete_type_info() function * This function is meant to be called from the complete_type_info()
* of a #GTypePlugin implementation, see the example for * function of a #GTypePlugin implementation, see the example for
* g_enum_complete_type_info() above. * g_enum_complete_type_info() above.
*/ */
void void
@ -380,11 +383,11 @@ g_flags_class_init (GFlagsClass *class,
* g_enum_get_value_by_name: * g_enum_get_value_by_name:
* @enum_class: a #GEnumClass * @enum_class: a #GEnumClass
* @name: the name to look up * @name: the name to look up
* *
* Looks up a #GEnumValue by name. * Looks up a #GEnumValue by name.
* *
* Returns: the #GEnumValue with name @name, or %NULL if the enumeration doesn' * Returns: the #GEnumValue with name @name, or %NULL if the
* t have a member with that name * enumeration doesn't have a member with that name
*/ */
GEnumValue* GEnumValue*
g_enum_get_value_by_name (GEnumClass *enum_class, 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: * g_flags_get_value_by_name:
* @flags_class: a #GFlagsClass * @flags_class: a #GFlagsClass
* @name: the name to look up * @name: the name to look up
* *
* Looks up a #GFlagsValue by name. * Looks up a #GFlagsValue by name.
* *
* Returns: the #GFlagsValue with name @name, or %NULL if there is no flag with * Returns: the #GFlagsValue with name @name, or %NULL if there is no
* that name * flag with that name
*/ */
GFlagsValue* GFlagsValue*
g_flags_get_value_by_name (GFlagsClass *flags_class, 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: * g_enum_get_value_by_nick:
* @enum_class: a #GEnumClass * @enum_class: a #GEnumClass
* @nick: the nickname to look up * @nick: the nickname to look up
* *
* Looks up a #GEnumValue by nickname. * Looks up a #GEnumValue by nickname.
* *
* Returns: the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn' * Returns: the #GEnumValue with nickname @nick, or %NULL if the
* t have a member with that nickname * enumeration doesn't have a member with that nickname
*/ */
GEnumValue* GEnumValue*
g_enum_get_value_by_nick (GEnumClass *enum_class, 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: * g_flags_get_value_by_nick:
* @flags_class: a #GFlagsClass * @flags_class: a #GFlagsClass
* @nick: the nickname to look up * @nick: the nickname to look up
* *
* Looks up a #GFlagsValue by nickname. * Looks up a #GFlagsValue by nickname.
* *
* Returns: the #GFlagsValue with nickname @nick, or %NULL if there is no flag * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is
* with that nickname * no flag with that nickname
*/ */
GFlagsValue* GFlagsValue*
g_flags_get_value_by_nick (GFlagsClass *flags_class, 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: * g_enum_get_value:
* @enum_class: a #GEnumClass * @enum_class: a #GEnumClass
* @value: the value to look up * @value: the value to look up
* *
* Returns the #GEnumValue for a value. * Returns the #GEnumValue for a value.
* *
* Returns: the #GEnumValue for @value, or %NULL if @value is not * Returns: the #GEnumValue for @value, or %NULL if @value is not a
* a member of the enumeration * member of the enumeration
*/ */
GEnumValue* GEnumValue*
g_enum_get_value (GEnumClass *enum_class, g_enum_get_value (GEnumClass *enum_class,
@ -524,10 +527,11 @@ g_enum_get_value (GEnumClass *enum_class,
* g_flags_get_first_value: * g_flags_get_first_value:
* @flags_class: a #GFlagsClass * @flags_class: a #GFlagsClass
* @value: the value * @value: the value
* *
* Returns the first #GFlagsValue which is set in @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* GFlagsValue*
g_flags_get_first_value (GFlagsClass *flags_class, g_flags_get_first_value (GFlagsClass *flags_class,
@ -560,7 +564,7 @@ g_flags_get_first_value (GFlagsClass *flags_class,
* g_value_set_enum: * g_value_set_enum:
* @value: a valid #GValue whose type is derived from %G_TYPE_ENUM * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM
* @v_enum: enum value to be set * @v_enum: enum value to be set
* *
* Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum.
*/ */
void void
@ -575,9 +579,9 @@ g_value_set_enum (GValue *value,
/** /**
* g_value_get_enum: * g_value_get_enum:
* @value: a valid #GValue whose type is derived from %G_TYPE_ENUM * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM
* *
* Get the contents of a %G_TYPE_ENUM #GValue. * Get the contents of a %G_TYPE_ENUM #GValue.
* *
* Returns: enum contents of @value * Returns: enum contents of @value
*/ */
gint gint
@ -592,7 +596,7 @@ g_value_get_enum (const GValue *value)
* g_value_set_flags: * g_value_set_flags:
* @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS
* @v_flags: flags value to be set * @v_flags: flags value to be set
* *
* Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags.
*/ */
void void
@ -607,9 +611,9 @@ g_value_set_flags (GValue *value,
/** /**
* g_value_get_flags: * g_value_get_flags:
* @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS
* *
* Get the contents of a %G_TYPE_FLAGS #GValue. * Get the contents of a %G_TYPE_FLAGS #GValue.
* *
* Returns: flags contents of @value * Returns: flags contents of @value
*/ */
guint guint

447
gobject/gobject.c
View File

@ -41,8 +41,11 @@
/** /**
* SECTION:objects * SECTION:objects
*
* @Short_description: The base object type * @Short_description: The base object type
*
* @See_also:#GParamSpecObject, g_param_spec_object() * @See_also:#GParamSpecObject, g_param_spec_object()
*
* @Title: The Base Object Type * @Title: The Base Object Type
* *
* GObject is the fundamental type providing the common attributes and * 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 volatile GObject *g_trap_object_ref = NULL;
static guint debug_objects_count = 0; static guint debug_objects_count = 0;
static GHashTable *debug_objects_ht = NULL; static GHashTable *debug_objects_ht = NULL;
static void static void
debug_objects_foreach (gpointer key, debug_objects_foreach (gpointer key,
gpointer value, gpointer value,
@ -210,6 +214,7 @@ debug_objects_foreach (gpointer key,
G_OBJECT_TYPE_NAME (object), G_OBJECT_TYPE_NAME (object),
object->ref_count); object->ref_count);
} }
static void static void
debug_objects_atexit (void) debug_objects_atexit (void)
{ {
@ -337,13 +342,14 @@ g_object_do_class_init (GObjectClass *class)
* GObject::notify: * GObject::notify:
* @pspec: the #GParamSpec of the property which changed * @pspec: the #GParamSpec of the property which changed
* @gobject: the object which received the signal. * @gobject: the object which received the signal.
* *
* The notify signal is emitted on an object when one of its properties * The notify signal is emitted on an object when one of its
* has been changed. Note that getting this signal doesn't guarantee that the * properties has been changed. Note that getting this signal
* value of the property has actually changed, it may also be emitted when * doesn't guarantee that the value of the property has actually
* the setter for the property is called to reinstate the previous value. * 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 *
* This signal is typically used to obtain change notification for a
* single property, by specifying the property name as a detail in the * single property, by specifying the property name as a detail in the
* g_signal_connect() call, like this: * 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), * G_CALLBACK (gtk_text_view_target_list_notify),
* text_view) * 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 * <link linkend="canonical-parameter-name">canonical</link> parameter names as
* detail strings for the notify signal. * detail strings for the notify signal.
*/ */
@ -395,7 +401,7 @@ install_property_internal (GType g_type,
* @oclass: a #GObjectClass * @oclass: a #GObjectClass
* @property_id: the id for the new property * @property_id: the id for the new property
* @pspec: the #GParamSpec for the new property * @pspec: the #GParamSpec for the new property
* *
* Installs a new property. This is usually done in the class initializer. * Installs a new property. This is usually done in the class initializer.
*/ */
void void
@ -434,7 +440,7 @@ g_object_class_install_property (GObjectClass *class,
* @g_iface: any interface vtable for the interface, or the default * @g_iface: any interface vtable for the interface, or the default
* vtable for the interface. * vtable for the interface.
* @pspec: the #GParamSpec for the new property * @pspec: the #GParamSpec for the new property
* *
* Add a property to an interface; this is only useful for interfaces * Add a property to an interface; this is only useful for interfaces
* that are added to GObject-derived types. Adding a property to an * that are added to GObject-derived types. Adding a property to an
* interface forces all objects classes with that interface to have a * 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 * class only needs to provide an implementation and inherits the
* property description, default value, bounds, and so forth from the * property description, default value, bounds, and so forth from the
* interface property. * interface property.
* *
* This function is meant to be called from the interface's default * This function is meant to be called from the interface's default
* vtable initialization function (the @class_init member of * vtable initialization function (the @class_init member of
* #GTypeInfo.) It must not be called after after @class_init has * #GTypeInfo.) It must not be called after after @class_init has
* been called for any object types implementing this interface. * been called for any object types implementing this interface.
* *
* Since: 2.4 * Since: 2.4
*/ */
void void
@ -470,11 +476,11 @@ g_object_interface_install_property (gpointer g_iface,
* g_object_class_find_property: * g_object_class_find_property:
* @oclass: a #GObjectClass * @oclass: a #GObjectClass
* @property_name: the name of the property to look up * @property_name: the name of the property to look up
* *
* Looks up the #GParamSpec for a property of a class. * Looks up the #GParamSpec for a property of a class.
* *
* Returns: the #GParamSpec for the property, or %NULL if the class doesn't have * Returns: the #GParamSpec for the property, or %NULL if the class
* a property of that name * doesn't have a property of that name
*/ */
GParamSpec* GParamSpec*
g_object_class_find_property (GObjectClass *class, 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 * @g_iface: any interface vtable for the interface, or the default
* vtable for the interface * vtable for the interface
* @property_name: name of a property to lookup. * @property_name: name of a property to lookup.
* *
* Find the #GParamSpec with the given name for an * Find the #GParamSpec with the given name for an
* interface. Generally, the interface vtable passed in as @g_iface * interface. Generally, the interface vtable passed in as @g_iface
* will be the default vtable from g_type_default_interface_ref(), or, * will be the default vtable from g_type_default_interface_ref(), or,
* if you know the interface has already been loaded, * if you know the interface has already been loaded,
* g_type_default_interface_peek(). * g_type_default_interface_peek().
* *
* Since: 2.4 * Since: 2.4
* Returns: the #GParamSpec for the property of the *
* interface with the name @property_name, or %NULL * Returns: the #GParamSpec for the property of the interface with the
* if no such property exists. * name @property_name, or %NULL if no such property exists.
*/ */
GParamSpec* GParamSpec*
g_object_interface_find_property (gpointer g_iface, 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 * @property_id: the new property ID
* @name: the name of a property registered in a parent class or * @name: the name of a property registered in a parent class or
* in an interface of this class. * in an interface of this class.
* *
* Registers @property_id as referring to a property with the * Registers @property_id as referring to a property with the
* name @name in a parent class or in an interface implemented * name @name in a parent class or in an interface implemented
* by @oclass. This allows this class to <firstterm>override</firstterm> * by @oclass. This allows this class to <firstterm>override</firstterm>
* a property implementation in a parent class or to provide * a property implementation in a parent class or to provide
* the implementation of a property from an interface. * the implementation of a property from an interface.
* *
* <note> * <note>
* Internally, overriding is implemented by creating a property of type * Internally, overriding is implemented by creating a property of type
* #GParamSpecOverride; generally operations that query the properties of * #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 * need to get the overridden property, you can call
* g_param_spec_get_redirect_target(). * g_param_spec_get_redirect_target().
* </note> * </note>
* *
* Since: 2.4 * Since: 2.4
*/ */
void void
@ -617,9 +623,9 @@ g_object_class_override_property (GObjectClass *oclass,
* g_object_class_list_properties: * g_object_class_list_properties:
* @oclass: a #GObjectClass * @oclass: a #GObjectClass
* @n_properties: return location for the length of the returned array * @n_properties: return location for the length of the returned array
* *
* Get an array of #GParamSpec* for all properties of a class. * Get an array of #GParamSpec* for all properties of a class.
* *
* Returns: an array of #GParamSpec* which should be freed after use * Returns: an array of #GParamSpec* which should be freed after use
*/ */
GParamSpec** /* free result */ 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 * @g_iface: any interface vtable for the interface, or the default
* vtable for the interface * vtable for the interface
* @n_properties_p: location to store number of properties returned. * @n_properties_p: location to store number of properties returned.
* *
* Lists the properties of an interface.Generally, the interface * Lists the properties of an interface.Generally, the interface
* vtable passed in as @g_iface will be the default vtable from * vtable passed in as @g_iface will be the default vtable from
* g_type_default_interface_ref(), or, if you know the interface has * g_type_default_interface_ref(), or, if you know the interface has
* already been loaded, g_type_default_interface_peek(). * already been loaded, g_type_default_interface_peek().
* *
* Since: 2.4 * Since: 2.4
* Returns: a pointer to an array of pointers to #GParamSpec structures. *
* The paramspecs are owned by GLib, but the array should * Returns: a pointer to an array of pointers to #GParamSpec
* be freed with g_free() when you are done with it. * structures. The paramspecs are owned by GLib, but the
* array should be freed with g_free() when you are done with
* it.
*/ */
GParamSpec** GParamSpec**
g_object_interface_list_properties (gpointer g_iface, g_object_interface_list_properties (gpointer g_iface,
@ -767,10 +775,10 @@ g_object_dispatch_properties_changed (GObject *object,
/** /**
* g_object_run_dispose: * g_object_run_dispose:
* @object: a #GObject * @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. * reference cycles.
* *
* This functions should only be called from object system implementations. * This functions should only be called from object system implementations.
*/ */
void void
@ -787,10 +795,10 @@ g_object_run_dispose (GObject *object)
/** /**
* g_object_freeze_notify: * g_object_freeze_notify:
* @object: a #GObject * @object: a #GObject
* *
* Stops emission of "notify" signals on @object. The signals are * 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 * This is necessary for accessors that modify multiple properties to prevent
* premature notification while the object is still being modified. * premature notification while the object is still being modified.
*/ */
@ -811,8 +819,8 @@ g_object_freeze_notify (GObject *object)
* g_object_notify: * g_object_notify:
* @object: a #GObject * @object: a #GObject
* @property_name: the name of a property installed on the class of @object. * @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 void
g_object_notify (GObject *object, g_object_notify (GObject *object,
@ -854,7 +862,7 @@ g_object_notify (GObject *object,
/** /**
* g_object_thaw_notify: * g_object_thaw_notify:
* @object: a #GObject * @object: a #GObject
* *
* Reverts the effect of a previous call to g_object_freeze_notify(). * Reverts the effect of a previous call to g_object_freeze_notify().
* This causes all queued "notify" signals on @object to be emitted. * 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 * @first_property_name: the name of the first property
* @...: the value of the first property, followed optionally by more * @...: the value of the first property, followed optionally by more
* name/value pairs, followed by %NULL * name/value pairs, followed by %NULL
* *
* Creates a new instance of a #GObject subtype and sets its properties. * 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. * which are not explicitly specified are set to their default values.
* *
* Returns: a new instance of @object_type * Returns: a new instance of @object_type
*/ */
gpointer gpointer
@ -1083,12 +1091,12 @@ object_in_construction_list (GObject *object)
* @object_type: the type id of the #GObject subtype to instantiate * @object_type: the type id of the #GObject subtype to instantiate
* @n_parameters: the length of the @parameters array * @n_parameters: the length of the @parameters array
* @parameters: an array of #GParameter * @parameters: an array of #GParameter
* *
* Creates a new instance of a #GObject subtype and sets its properties. * 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. * which are not explicitly specified are set to their default values.
* *
* Returns: a new instance of @object_type * Returns: a new instance of @object_type
*/ */
gpointer gpointer
@ -1236,12 +1244,12 @@ g_object_newv (GType object_type,
* @first_property_name: the name of the first property * @first_property_name: the name of the first property
* @var_args: the value of the first property, followed optionally by more * @var_args: the value of the first property, followed optionally by more
* name/value pairs, followed by %NULL * name/value pairs, followed by %NULL
* *
* Creates a new instance of a #GObject subtype and sets its properties. * 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. * which are not explicitly specified are set to their default values.
* *
* Returns: a new instance of @object_type * Returns: a new instance of @object_type
*/ */
GObject* GObject*
@ -1350,7 +1358,7 @@ g_object_constructor (GType type,
* @first_property_name: name of the first property to set * @first_property_name: name of the first property to set
* @var_args: value for the first property, followed optionally by more * @var_args: value for the first property, followed optionally by more
* name/value pairs, followed by %NULL * name/value pairs, followed by %NULL
* *
* Sets properties on an object. * Sets properties on an object.
*/ */
void void
@ -1427,13 +1435,13 @@ g_object_set_valist (GObject *object,
* @first_property_name: name of the first property to get * @first_property_name: name of the first property to get
* @var_args: return location for the first property, followed optionally by more * @var_args: return location for the first property, followed optionally by more
* name/return location pairs, followed by %NULL * name/return location pairs, followed by %NULL
* *
* Gets properties of an object. * Gets properties of an object.
* *
* In general, a copy is made of the property contents and the caller is * In general, a copy is made of the property contents and the caller
* responsible for freeing the memory in the appropriate manner for the type, * is responsible for freeing the memory in the appropriate manner for
* for instance by calling g_free() or g_object_unref(). * the type, for instance by calling g_free() or g_object_unref().
* *
* See g_object_get(). * See g_object_get().
*/ */
void void
@ -1503,7 +1511,7 @@ g_object_get_valist (GObject *object,
* @first_property_name: name of the first property to set * @first_property_name: name of the first property to set
* @...: value for the first property, followed optionally by more * @...: value for the first property, followed optionally by more
* name/value pairs, followed by %NULL * name/value pairs, followed by %NULL
* *
* Sets properties on an object. * Sets properties on an object.
*/ */
void void
@ -1527,13 +1535,13 @@ g_object_set (gpointer _object,
* @first_property_name: name of the first property to get * @first_property_name: name of the first property to get
* @...: return location for the first property, followed optionally by more * @...: return location for the first property, followed optionally by more
* name/return location pairs, followed by %NULL * name/return location pairs, followed by %NULL
* *
* Gets properties of an object. * Gets properties of an object.
* *
* In general, a copy is made of the property contents and the caller is * In general, a copy is made of the property contents and the caller
* responsible for freeing the memory in the appropriate manner for the type, * is responsible for freeing the memory in the appropriate manner for
* for instance by calling g_free() or g_object_unref(). * the type, for instance by calling g_free() or g_object_unref().
* *
* <example> * <example>
* <title>Using g_object_get(<!-- -->)</title> * <title>Using g_object_get(<!-- -->)</title>
* An example of using g_object_get() to get the contents * An example of using g_object_get() to get the contents
@ -1542,16 +1550,16 @@ g_object_set (gpointer _object,
* <programlisting> * <programlisting>
* gint intval; * gint intval;
* gchar *strval; * gchar *strval;
* GObject *objval; * GObject *objval;
* *
* g_object_get (my_object, * g_object_get (my_object,
* "int-property", &intval, * "int-property", &intval,
* "str-property", &strval, * "str-property", &strval,
* "obj-property", &objval, * "obj-property", &objval,
* NULL); * NULL);
* *
* // Do something with intval, strval, objval * // Do something with intval, strval, objval
* *
* g_free (strval); * g_free (strval);
* g_object_unref (objval); * g_object_unref (objval);
* </programlisting> * </programlisting>
@ -1577,7 +1585,7 @@ g_object_get (gpointer _object,
* @object: a #GObject * @object: a #GObject
* @property_name: the name of the property to set * @property_name: the name of the property to set
* @value: the value * @value: the value
* *
* Sets a property on an object. * Sets a property on an object.
*/ */
void void
@ -1624,12 +1632,12 @@ g_object_set_property (GObject *object,
* @object: a #GObject * @object: a #GObject
* @property_name: the name of the property to get * @property_name: the name of the property to get
* @value: return location for the property value * @value: return location for the property value
* *
* Gets a property of an object. * Gets a property of an object.
* *
* In general, a copy is made of the property contents and the caller is * In general, a copy is made of the property contents and the caller is
* responsible for freeing the memory by calling g_value_unset(). * responsible for freeing the memory by calling g_value_unset().
* *
* Note that g_object_get_property() is really intended for language * Note that g_object_get_property() is really intended for language
* bindings, g_object_get() is much more convenient for C programming. * bindings, g_object_get() is much more convenient for C programming.
*/ */
@ -1700,12 +1708,12 @@ g_object_get_property (GObject *object,
* g_object_connect: * g_object_connect:
* @object: a #GObject * @object: a #GObject
* @signal_spec: the spec for the first signal * @signal_spec: the spec for the first signal
* @...: #GCallback for the first signal, followed by data for the first signal, * @...: #GCallback for the first signal, followed by data for the
* followed optionally by more signal spec/callback/data triples, * first signal, followed optionally by more signal
* followed by %NULL * spec/callback/data triples, followed by %NULL
* *
* A convenience function to connect multiple signals at once. * A convenience function to connect multiple signals at once.
* *
* The signal specs expected by this function have the form * The signal specs expected by this function have the form
* "modifier::signal_name", where modifier can be one of the following: * "modifier::signal_name", where modifier can be one of the following:
* <variablelist> * <variablelist>
@ -1765,7 +1773,7 @@ g_object_get_property (GObject *object,
* </para></listitem> * </para></listitem>
* </varlistentry> * </varlistentry>
* </variablelist> * </variablelist>
* *
* |[ * |[
* menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, * menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
* "type", GTK_WINDOW_POPUP, * "type", GTK_WINDOW_POPUP,
@ -1776,7 +1784,7 @@ g_object_get_property (GObject *object,
* "signal::destroy", gtk_widget_destroyed, &amp;menu-&gt;toplevel, * "signal::destroy", gtk_widget_destroyed, &amp;menu-&gt;toplevel,
* NULL); * NULL);
* ]| * ]|
* *
* Returns: @object * Returns: @object
*/ */
gpointer gpointer
@ -1852,15 +1860,16 @@ g_object_connect (gpointer _object,
* g_object_disconnect: * g_object_disconnect:
* @object: a #GObject * @object: a #GObject
* @signal_spec: the spec for the first signal * @signal_spec: the spec for the first signal
* @...: #GCallback for the first signal, followed by data 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 optionally by more signal spec/callback/data triples,
* followed by %NULL * followed by %NULL
* *
* A convenience function to disconnect multiple signals at once. * A convenience function to disconnect multiple signals at once.
* *
* The signal specs expected by this function have the form "any_signal", which * The signal specs expected by this function have the form
* means to disconnect any signal with matching callback and data, or * "any_signal", which means to disconnect any signal with matching
* "any_signal::signal_name", which only disconnects the signal named "signal_name". * callback and data, or "any_signal::signal_name", which only
* disconnects the signal named "signal_name".
*/ */
void void
g_object_disconnect (gpointer _object, g_object_disconnect (gpointer _object,
@ -1935,12 +1944,12 @@ weak_refs_notify (gpointer data)
* @object: #GObject to reference weakly * @object: #GObject to reference weakly
* @notify: callback to invoke before the object is freed * @notify: callback to invoke before the object is freed
* @data: extra data to pass to notify * @data: extra data to pass to notify
* *
* Adds a weak reference callback to an object. Weak references are used for * Adds a weak reference callback to an object. Weak references are
* notification when an object is finalized. They are called "weak references" * used for notification when an object is finalized. They are called
* because they allow you to safely hold a pointer to an object without calling * "weak references" because they allow you to safely hold a pointer
* g_object_ref() (g_object_ref() adds a strong reference, that is, forces the * to an object without calling g_object_ref() (g_object_ref() adds a
* object to stay alive). * strong reference, that is, forces the object to stay alive).
*/ */
void void
g_object_weak_ref (GObject *object, g_object_weak_ref (GObject *object,
@ -1977,7 +1986,7 @@ g_object_weak_ref (GObject *object,
* @object: #GObject to remove a weak reference from * @object: #GObject to remove a weak reference from
* @notify: callback to search for * @notify: callback to search for
* @data: data to search for * @data: data to search for
* *
* Removes a weak reference callback to an object. * Removes a weak reference callback to an object.
*/ */
void void
@ -2016,11 +2025,11 @@ g_object_weak_unref (GObject *object,
* g_object_add_weak_pointer: * g_object_add_weak_pointer:
* @object: The object that should be weak referenced. * @object: The object that should be weak referenced.
* @weak_pointer_location: The memory address of a pointer. * @weak_pointer_location: The memory address of a pointer.
* *
* Adds a weak reference from weak_pointer to @object to indicate that * Adds a weak reference from weak_pointer to @object to indicate that
* the pointer located at @weak_pointer_location is only valid during the * the pointer located at @weak_pointer_location is only valid during
* lifetime of @object. When the @object is finalized, @weak_pointer will * the lifetime of @object. When the @object is finalized,
* be set to %NULL. * @weak_pointer will be set to %NULL.
*/ */
void void
g_object_add_weak_pointer (GObject *object, g_object_add_weak_pointer (GObject *object,
@ -2038,7 +2047,7 @@ g_object_add_weak_pointer (GObject *object,
* g_object_remove_weak_pointer: * g_object_remove_weak_pointer:
* @object: The object that is weak referenced. * @object: The object that is weak referenced.
* @weak_pointer_location: The memory address of a pointer. * @weak_pointer_location: The memory address of a pointer.
* *
* Removes a weak reference from @object that was previously added * Removes a weak reference from @object that was previously added
* using g_object_add_weak_pointer(). The @weak_pointer_location has * using g_object_add_weak_pointer(). The @weak_pointer_location has
* to match the one used with g_object_add_weak_pointer(). * 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: * g_object_is_floating:
* @object: a #GObject * @object: a #GObject
* *
* Checks wether @object has a <link linkend="floating-ref">floating</link> * Checks wether @object has a <link linkend="floating-ref">floating</link>
* reference. * reference.
* *
* Since: 2.10 * Since: 2.10
*
* Returns: %TRUE if @object has a floating reference * Returns: %TRUE if @object has a floating reference
*/ */
gboolean gboolean
@ -2100,18 +2110,19 @@ g_object_is_floating (gpointer _object)
/** /**
* g_object_ref_sink: * g_object_ref_sink:
* @object: a #GObject * @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 * <link linkend="floating-ref">floating</link> reference, if @object
* has a floating reference. * has a floating reference.
* *
* In other words, if the object is floating, then this call "assumes * In other words, if the object is floating, then this call "assumes
* ownership" of the floating reference, converting it to a normal reference * ownership" of the floating reference, converting it to a normal
* by clearing the floating flag while leaving the reference count unchanged. * reference by clearing the floating flag while leaving the reference
* If the object is not floating, then this call adds a new normal reference * count unchanged. If the object is not floating, then this call
* increasing the reference count by one. * adds a new normal reference increasing the reference count by one.
* *
* Since: 2.10 * Since: 2.10
*
* Returns: @object * Returns: @object
*/ */
gpointer gpointer
@ -2131,13 +2142,13 @@ g_object_ref_sink (gpointer _object)
/** /**
* g_object_force_floating: * g_object_force_floating:
* @object: a #GObject * @object: a #GObject
* *
* This function is intended for #GObject implementations to re-enforce a * This function is intended for #GObject implementations to re-enforce a
* <link linkend="floating-ref">floating</link> object reference. * <link linkend="floating-ref">floating</link> object reference.
* Doing this is seldomly required, all * 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(). * usually just needs to be sunken by calling g_object_ref_sink().
* *
* Since: 2.10 * Since: 2.10
*/ */
void void
@ -2179,18 +2190,18 @@ toggle_refs_notify (GObject *object,
* last reference to the object, or is no longer * last reference to the object, or is no longer
* the last reference. * the last reference.
* @data: data to pass to @notify * @data: data to pass to @notify
* *
* Increases the reference count of the object by one and sets a * Increases the reference count of the object by one and sets a
* callback to be called when all other references to the object are * callback to be called when all other references to the object are
* dropped, or when this is already the last reference to the object * dropped, or when this is already the last reference to the object
* and another reference is established. * and another reference is established.
* *
* This functionality is intended for binding @object to a proxy * This functionality is intended for binding @object to a proxy
* object managed by another memory manager. This is done with two * object managed by another memory manager. This is done with two
* paired references: the strong reference added by * paired references: the strong reference added by
* g_object_add_toggle_ref() and a reverse reference to the proxy * g_object_add_toggle_ref() and a reverse reference to the proxy
* object which is either a strong reference or weak reference. * object which is either a strong reference or weak reference.
* *
* The setup is that when there are no other references to @object, * The setup is that when there are no other references to @object,
* only a weak reference is held in the reverse direction from @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 * 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 * when the reference from @object to the proxy object should be
* <firstterm>toggled</firstterm> from strong to weak (@is_last_ref * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref
* true) or weak to strong (@is_last_ref false). * true) or weak to strong (@is_last_ref false).
* *
* Since a (normal) reference must be held to the object before * Since a (normal) reference must be held to the object before
* calling g_object_toggle_ref(), the initial state of the reverse * calling g_object_toggle_ref(), the initial state of the reverse
* link is always strong. * link is always strong.
* *
* Multiple toggle references may be added to the same gobject, * Multiple toggle references may be added to the same gobject,
* however if there are multiple toggle references to an object, none * however if there are multiple toggle references to an object, none
* of them will ever be notified until all but one are removed. For * 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 * this reason, you should only ever use a toggle reference if there
* is important state in the proxy object. * is important state in the proxy object.
* *
* Since: 2.8 * Since: 2.8
*/ */
void void
@ -2250,7 +2261,7 @@ g_object_add_toggle_ref (GObject *object,
g_datalist_id_set_data_full (&object->qdata, quark_toggle_refs, tstack, g_datalist_id_set_data_full (&object->qdata, quark_toggle_refs, tstack,
(GDestroyNotify)g_free); (GDestroyNotify)g_free);
} }
/** /**
* g_object_remove_toggle_ref: * g_object_remove_toggle_ref:
* @object: a #GObject * @object: a #GObject
@ -2258,10 +2269,10 @@ g_object_add_toggle_ref (GObject *object,
* last reference to the object, or is no longer * last reference to the object, or is no longer
* the last reference. * the last reference.
* @data: data to pass to @notify * @data: data to pass to @notify
* *
* Removes a reference added with g_object_add_toggle_ref(). The * Removes a reference added with g_object_add_toggle_ref(). The
* reference count of the object is decreased by one. * reference count of the object is decreased by one.
* *
* Since: 2.8 * Since: 2.8
*/ */
void void
@ -2305,9 +2316,9 @@ g_object_remove_toggle_ref (GObject *object,
/** /**
* g_object_ref: * g_object_ref:
* @object: a #GObject * @object: a #GObject
* *
* Increases the reference count of @object. * Increases the reference count of @object.
* *
* Returns: the same @object * Returns: the same @object
*/ */
gpointer gpointer
@ -2336,10 +2347,9 @@ g_object_ref (gpointer _object)
/** /**
* g_object_unref: * g_object_unref:
* @object: a #GObject * @object: a #GObject
* *
* Decreases the reference count of @object. * Decreases the reference count of @object. When its reference count
* When its reference count drops to 0, the object is finalized * drops to 0, the object is finalized (i.e. its memory is freed).
* (i.e. its memory is freed).
*/ */
void void
g_object_unref (gpointer _object) 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 * @object: The GObject to set store a user data pointer
* @quark: A #GQuark, naming the user data pointer * @quark: A #GQuark, naming the user data pointer
* @data: An opaque user data pointer * @data: An opaque user data pointer
* *
* This sets an opaque, named pointer on an object. * This sets an opaque, named pointer on an object.
* The name is specified through a #GQuark (retrived e.g. via * The name is specified through a #GQuark (retrived e.g. via
* g_quark_from_static_string()), and the pointer * 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 * @object: The GObject to set store a user data pointer
* @quark: A #GQuark, naming the user data pointer * @quark: A #GQuark, naming the user data pointer
* @data: An opaque 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, * This function works like g_object_set_qdata(), but in addition,
* a void (*destroy) (gpointer) function may be specified which is * a void (*destroy) (gpointer) function may be specified which is
* called with @data as argument when the @object is finalized, or * 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: * g_object_steal_qdata:
* @object: The GObject to get a stored user data pointer from * @object: The GObject to get a stored user data pointer from
* @quark: A #GQuark, naming the user data pointer * @quark: A #GQuark, naming the user data pointer
* *
* This function gets back user data pointers stored via * This function gets back user data pointers stored via
* g_object_set_qdata() and removes the @data from object * g_object_set_qdata() and removes the @data from object
* without invoking it's destroy() function (if any was * 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"); * GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
* // retrive the old string list * // retrive the old string list
* GList *list = g_object_steal_qdata (object, quark_string_list); * GList *list = g_object_steal_qdata (object, quark_string_list);
* *
* // prepend new string * // prepend new string
* list = g_list_prepend (list, g_strdup (new_string)); * list = g_list_prepend (list, g_strdup (new_string));
* // this changed 'list', so we need to set it again * // 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) * free_string_list (gpointer data)
* { * {
* GList *node, *list = data; * GList *node, *list = data;
* *
* for (node = list; node; node = node->next) * for (node = list; node; node = node->next)
* g_free (node->data); * g_free (node->data);
* g_list_free (list); * g_list_free (list);
* } * }
* ]| * ]|
* Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() * Using g_object_get_qdata() in the above example, instead of
* would have left the destroy function set, and thus the partial string list would * g_object_steal_qdata() would have left the destroy function set,
* have been freed upon g_object_set_qdata_full(). * and thus the partial string list would have been freed upon
* * g_object_set_qdata_full().
*
* Returns: The user data pointer set, or %NULL * Returns: The user data pointer set, or %NULL
*/ */
gpointer gpointer
@ -2565,10 +2577,10 @@ g_object_get_data (GObject *object,
* @object: #GObject containing the associations. * @object: #GObject containing the associations.
* @key: name of the key * @key: name of the key
* @data: data to associate with that key * @data: data to associate with that key
* *
* Each object carries around a table of associations from * Each object carries around a table of associations from
* strings to pointers. This function lets you set an association. * strings to pointers. This function lets you set an association.
* *
* If the object already had an association with that name, * If the object already had an association with that name,
* the old association will be destroyed. * the old association will be destroyed.
*/ */
@ -2589,11 +2601,11 @@ g_object_set_data (GObject *object,
* @key: name of the key * @key: name of the key
* @data: data to associate with that key * @data: data to associate with that key
* @destroy: function to call when the association is destroyed * @destroy: function to call when the association is destroyed
* *
* Like g_object_set_data() except it adds notification * 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. * to a different value or when the object is destroyed.
* *
* Note that the @destroy callback is not called if @data is %NULL. * Note that the @destroy callback is not called if @data is %NULL.
*/ */
void void
@ -2613,10 +2625,10 @@ g_object_set_data_full (GObject *object,
* g_object_steal_data: * g_object_steal_data:
* @object: #GObject containing the associations * @object: #GObject containing the associations
* @key: name of the key * @key: name of the key
* *
* Remove a specified datum from the object's data associations, * Remove a specified datum from the object's data associations,
* without invoking the association's destroy handler. * without invoking the association's destroy handler.
* *
* Returns: the data if found, or %NULL if no such data exists. * Returns: the data if found, or %NULL if no such data exists.
*/ */
gpointer gpointer
@ -2728,16 +2740,15 @@ g_value_object_lcopy_value (const GValue *value,
* g_value_set_object: * g_value_set_object:
* @value: a valid #GValue of %G_TYPE_OBJECT derived type * @value: a valid #GValue of %G_TYPE_OBJECT derived type
* @v_object: object value to be set * @v_object: object value to be set
* *
* Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
* *
* g_value_set_object() increases the reference count of @v_object * g_value_set_object() increases the reference count of @v_object
* (the #GValue holds a reference to @v_object). * (the #GValue holds a reference to @v_object). If you do not wish
* If you do not wish to increase the reference count of the object * to increase the reference count of the object (i.e. you wish to
* (i.e. you wish to pass your current reference to the #GValue because you no * pass your current reference to the #GValue because you no longer
* longer need it), * need it), use g_value_take_object() instead.
* use g_value_take_object() instead. *
*
* It is important that your #GValue holds a reference to @v_object (either its * 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 * own, or one it has taken) to ensure that the object won't be destroyed while
* the #GValue still exists). * the #GValue still exists).
@ -2771,9 +2782,9 @@ g_value_set_object (GValue *value,
* g_value_set_object_take_ownership: * g_value_set_object_take_ownership:
* @value: a valid #GValue of %G_TYPE_OBJECT derived type * @value: a valid #GValue of %G_TYPE_OBJECT derived type
* @v_object: object value to be set * @v_object: object value to be set
* *
* This is an internal function introduced mainly for C marshallers. * This is an internal function introduced mainly for C marshallers.
* *
* Deprecated: 2.4: Use g_value_take_object() instead. * Deprecated: 2.4: Use g_value_take_object() instead.
*/ */
void void
@ -2787,15 +2798,15 @@ g_value_set_object_take_ownership (GValue *value,
* g_value_take_object: * g_value_take_object:
* @value: a valid #GValue of %G_TYPE_OBJECT derived type * @value: a valid #GValue of %G_TYPE_OBJECT derived type
* @v_object: object value to be set * @v_object: object value to be set
* *
* Sets the contents of a %G_TYPE_OBJECT derived #GValue 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; * 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 * the caller doesn't have to unref it any more (i.e. the reference
* count of the object is not increased). * count of the object is not increased).
* *
* If you want the #GValue to hold its own reference to @v_object, use * If you want the #GValue to hold its own reference to @v_object, use
* g_value_set_object() instead. * g_value_set_object() instead.
* *
* Since: 2.4 * Since: 2.4
*/ */
void void
@ -2838,10 +2849,12 @@ g_value_get_object (const GValue *value)
/** /**
* g_value_dup_object: * g_value_dup_object:
* @value: a valid #GValue whose type is derived from %G_TYPE_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 gpointer
g_value_dup_object (const GValue *value) g_value_dup_object (const GValue *value)
@ -2858,30 +2871,30 @@ g_value_dup_object (const GValue *value)
* @c_handler: the #GCallback to connect. * @c_handler: the #GCallback to connect.
* @gobject: the object to pass as data to @c_handler. * @gobject: the object to pass as data to @c_handler.
* @connect_flags: a combination of #GConnnectFlags. * @connect_flags: a combination of #GConnnectFlags.
* *
* This is similar to g_signal_connect_data(), but uses a closure which * 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 * ensures that the @gobject stays alive during the call to @c_handler
* by temporarily adding a reference count to @gobject. * by temporarily adding a reference count to @gobject.
* *
* Note that there is a bug in GObject that makes this function * Note that there is a bug in GObject that makes this function
* much less useful than it might seem otherwise. Once @gobject is * much less useful than it might seem otherwise. Once @gobject is
* disposed, the callback will no longer be called, but, the signal * disposed, the callback will no longer be called, but, the signal
* handler is <emphasis>not</emphasis> currently disconnected. If the * handler is <emphasis>not</emphasis> currently disconnected. If the
* @instance is itself being freed at the same time than this doesn't * @instance is itself being freed at the same time than this doesn't
* matter, since the signal will automatically be removed, but * matter, since the signal will automatically be removed, but
* if @instance persists, then the signal handler will leak. You * if @instance persists, then the signal handler will leak. You
* should not remove the signal yourself because in a future versions of * should not remove the signal yourself because in a future versions of
* GObject, the handler <emphasis>will</emphasis> automatically * GObject, the handler <emphasis>will</emphasis> automatically
* be disconnected. * be disconnected.
* *
* It's possible to work around this problem in a way that will * It's possible to work around this problem in a way that will
* continue to work with future versions of GObject by checking * continue to work with future versions of GObject by checking
* that the signal handler is still connected before disconnected it: * that the signal handler is still connected before disconnected it:
* <informalexample><programlisting> * <informalexample><programlisting>
* if (g_signal_handler_is_connected (instance, id)) * if (g_signal_handler_is_connected (instance, id))
* g_signal_handler_disconnect (instance, id); * g_signal_handler_disconnect (instance, id);
* </programlisting></informalexample> * </programlisting></informalexample>
* *
* Returns: the handler id. * Returns: the handler id.
*/ */
gulong gulong
@ -2976,16 +2989,16 @@ destroy_closure_array (gpointer data)
* g_object_watch_closure: * g_object_watch_closure:
* @object: GObject restricting lifetime of @closure * @object: GObject restricting lifetime of @closure
* @closure: GClosure to watch * @closure: GClosure to watch
* *
* This function essentially limits the life time of the @closure * This function essentially limits the life time of the @closure to
* to the life time of the object. That is, when the object is finalized, * the life time of the object. That is, when the object is finalized,
* the @closure is invalidated by calling g_closure_invalidate() on it, * the @closure is invalidated by calling g_closure_invalidate() on
* in order to prevent invocations of the closure with a finalized * it, in order to prevent invocations of the closure with a finalized
* (nonexisting) object. Also, g_object_ref() and g_object_unref() are added * (nonexisting) object. Also, g_object_ref() and g_object_unref() are
* as marshal guards to the @closure, to ensure that an extra reference * added as marshal guards to the @closure, to ensure that an extra
* count is held on @object during invocation of the @closure. * reference count is held on @object during invocation of the
* Usually, this function will be called on closures that use this @object * @closure. Usually, this function will be called on closures that
* as closure data. * use this @object as closure data.
*/ */
void void
g_object_watch_closure (GObject *object, g_object_watch_closure (GObject *object,
@ -3023,16 +3036,16 @@ g_object_watch_closure (GObject *object,
/** /**
* g_closure_new_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> * <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 * allocated #GClosure
* *
* A variant of g_closure_new_simple() which stores @object in the @data * A variant of g_closure_new_simple() which stores @object in the
* field of the closure and calls g_object_watch_closure() on @object and the * @data field of the closure and calls g_object_watch_closure() on
* created closure. This function is mainly useful when implementing new types * @object and the created closure. This function is mainly useful
* of closures. * when implementing new types of closures.
* *
* Returns: a newly allocated #GClosure * Returns: a newly allocated #GClosure
*/ */
GClosure* GClosure*
@ -3054,12 +3067,13 @@ g_closure_new_object (guint sizeof_closure,
* g_cclosure_new_object: * g_cclosure_new_object:
* @callback_func: the function to invoke * @callback_func: the function to invoke
* @object: a #GObject pointer to pass to @callback_func * @object: a #GObject pointer to pass to @callback_func
* *
* A variant of g_cclosure_new() which uses @object as @user_data and calls * A variant of g_cclosure_new() which uses @object as @user_data and
* g_object_watch_closure() on @object and the created closure. This function * calls g_object_watch_closure() on @object and the created
* is useful when you have a callback closely associated with a #GObject, * closure. This function is useful when you have a callback closely
* and want the callback to no longer run after the object is is freed. * associated with a #GObject, and want the callback to no longer run
* * after the object is is freed.
*
* Returns: a new #GCClosure * Returns: a new #GCClosure
*/ */
GClosure* GClosure*
@ -3082,12 +3096,13 @@ g_cclosure_new_object (GCallback callback_func,
* g_cclosure_new_object_swap: * g_cclosure_new_object_swap:
* @callback_func: the function to invoke * @callback_func: the function to invoke
* @object: a #GObject pointer to pass to @callback_func * @object: a #GObject pointer to pass to @callback_func
* *
* A variant of g_cclosure_new_swap() which uses @object as @user_data and calls * A variant of g_cclosure_new_swap() which uses @object as @user_data
* g_object_watch_closure() on @object and the created closure. This function * and calls g_object_watch_closure() on @object and the created
* is useful when you have a callback closely associated with a #GObject, * closure. This function is useful when you have a callback closely
* and want the callback to no longer run after the object is is freed. * associated with a #GObject, and want the callback to no longer run
* * after the object is is freed.
*
* Returns: a new #GCClosure * Returns: a new #GCClosure
*/ */
GClosure* GClosure*

247
gobject/gparam.c
View File

@ -33,9 +33,13 @@
/** /**
* SECTION:gparamspec * SECTION:gparamspec
*
* @Short_description: Metadata for parameter specifications * @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 * @Title: GParamSpec
* *
* #GParamSpec is an object structure that encapsulates the metadata * #GParamSpec is an object structure that encapsulates the metadata
@ -184,9 +188,9 @@ g_param_spec_finalize (GParamSpec *pspec)
/** /**
* g_param_spec_ref: * g_param_spec_ref:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* *
* Increments the reference count of @pspec. * Increments the reference count of @pspec.
* *
* Returns: the #GParamSpec that was passed into this function * Returns: the #GParamSpec that was passed into this function
*/ */
GParamSpec* GParamSpec*
@ -203,7 +207,7 @@ g_param_spec_ref (GParamSpec *pspec)
/** /**
* g_param_spec_unref: * g_param_spec_unref:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* *
* Decrements the reference count of a @pspec. * Decrements the reference count of a @pspec.
*/ */
void void
@ -225,14 +229,14 @@ g_param_spec_unref (GParamSpec *pspec)
/** /**
* g_param_spec_sink: * g_param_spec_sink:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* *
* The initial reference count of a newly created #GParamSpec is 1, even * The initial reference count of a newly created #GParamSpec is 1,
* though no one has explicitly called g_param_spec_ref() on it yet. So the * even though no one has explicitly called g_param_spec_ref() on it
* initial reference count is flagged as "floating", until someone calls * yet. So the initial reference count is flagged as "floating", until
* <literal>g_param_spec_ref (pspec); g_param_spec_sink (pspec);</literal> * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink
* in sequence on it, taking over the initial reference count (thus * (pspec);</literal> in sequence on it, taking over the initial
* ending up with a @pspec that has a reference count of 1 still, but is * reference count (thus ending up with a @pspec that has a reference
* not flagged "floating" anymore). * count of 1 still, but is not flagged "floating" anymore).
*/ */
void void
g_param_spec_sink (GParamSpec *pspec) g_param_spec_sink (GParamSpec *pspec)
@ -252,9 +256,9 @@ g_param_spec_sink (GParamSpec *pspec)
/** /**
* g_param_spec_ref_sink: * g_param_spec_ref_sink:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* *
* Convenience function to ref and sink a #GParamSpec. * Convenience function to ref and sink a #GParamSpec.
* *
* Since: 2.10 * Since: 2.10
* Returns: the #GParamSpec that was passed into this function * 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: * g_param_spec_get_name:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* *
* Get the name of a #GParamSpec. * Get the name of a #GParamSpec.
* *
* Returns: the name of @pspec. * Returns: the name of @pspec.
*/ */
G_CONST_RETURN gchar* G_CONST_RETURN gchar*
@ -288,9 +292,9 @@ g_param_spec_get_name (GParamSpec *pspec)
/** /**
* g_param_spec_get_nick: * g_param_spec_get_nick:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* *
* Get the nickname of a #GParamSpec. * Get the nickname of a #GParamSpec.
* *
* Returns: the nickname of @pspec. * Returns: the nickname of @pspec.
*/ */
G_CONST_RETURN gchar* G_CONST_RETURN gchar*
@ -315,9 +319,9 @@ g_param_spec_get_nick (GParamSpec *pspec)
/** /**
* g_param_spec_get_blurb: * g_param_spec_get_blurb:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* *
* Get the short description of a #GParamSpec. * Get the short description of a #GParamSpec.
* *
* Returns: the short description of @pspec. * Returns: the short description of @pspec.
*/ */
G_CONST_RETURN gchar* G_CONST_RETURN gchar*
@ -382,24 +386,25 @@ is_canonical (const gchar *key)
* @nick: the nickname of the property * @nick: the nickname of the property
* @blurb: a short description of the property * @blurb: a short description of the property
* @flags: a combination of #GParamFlags * @flags: a combination of #GParamFlags
* *
* Creates a new #GParamSpec instance. * Creates a new #GParamSpec instance.
* *
* A property name consists of segments consisting of ASCII letters and * A property name consists of segments consisting of ASCII letters and
* digits, separated by either the '-' or '_' character. The first * digits, separated by either the '-' or '_' character. The first
* character of a property name must be a letter. Names which violate these * character of a property name must be a letter. Names which violate these
* rules lead to undefined behaviour. * rules lead to undefined behaviour.
* *
* When creating and looking up a #GParamSpec, either separator can be used, * When creating and looking up a #GParamSpec, either separator can be
* but they cannot be mixed. Using '-' is considerably more efficient and in * used, but they cannot be mixed. Using '-' is considerably more
* fact required when using property names as detail strings for signals. * 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 * Beyond the name, #GParamSpec<!-- -->s have two more descriptive
* a label for the property in a property editor, and the @blurb, which should * strings associated with them, the @nick, which should be suitable
* be a somewhat longer description, suitable for e.g. a tooltip. The @nick * for use as a label for the property in a property editor, and the
* and @blurb should ideally be localized. * @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 * Returns: a newly allocated #GParamSpec instance
*/ */
gpointer gpointer
@ -450,9 +455,9 @@ g_param_spec_internal (GType param_type,
* g_param_spec_get_qdata: * g_param_spec_get_qdata:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* @quark: a #GQuark, naming the user data pointer * @quark: a #GQuark, naming the user data pointer
* *
* Gets back user data pointers stored via g_param_spec_set_qdata(). * Gets back user data pointers stored via g_param_spec_set_qdata().
* *
* Returns: the user data pointer set, or %NULL * Returns: the user data pointer set, or %NULL
*/ */
gpointer gpointer
@ -469,13 +474,13 @@ g_param_spec_get_qdata (GParamSpec *pspec,
* @pspec: the #GParamSpec to set store a user data pointer * @pspec: the #GParamSpec to set store a user data pointer
* @quark: a #GQuark, naming the user data pointer * @quark: a #GQuark, naming the user data pointer
* @data: an opaque user data pointer * @data: an opaque user data pointer
* *
* Sets an opaque, named pointer on a #GParamSpec. The name is specified * Sets an opaque, named pointer on a #GParamSpec. The name is
* through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and * specified through a #GQuark (retrieved e.g. via
* the pointer can be gotten back from the @pspec with g_param_spec_get_qdata(). * g_quark_from_static_string()), and the pointer can be gotten back
* Setting a previously set user data pointer, overrides (frees) * from the @pspec with g_param_spec_get_qdata(). Setting a
* the old pointer set, using %NULL as pointer essentially * previously set user data pointer, overrides (frees) the old pointer
* removes the data stored. * set, using %NULL as pointer essentially removes the data stored.
*/ */
void void
g_param_spec_set_qdata (GParamSpec *pspec, g_param_spec_set_qdata (GParamSpec *pspec,
@ -495,11 +500,11 @@ g_param_spec_set_qdata (GParamSpec *pspec,
* @data: an opaque user data pointer * @data: an opaque user data pointer
* @destroy: function to invoke with @data as argument, when @data needs to * @destroy: function to invoke with @data as argument, when @data needs to
* be freed * be freed
* *
* This function works like g_param_spec_set_qdata(), but in addition, * This function works like g_param_spec_set_qdata(), but in addition,
* a <literal>void (*destroy) (gpointer)</literal> function may be * a <literal>void (*destroy) (gpointer)</literal> function may be
* specified which is called with @data as argument when the @pspec is * specified which is called with @data as argument when the @pspec is
* finalized, or the data is being overwritten by a call to * finalized, or the data is being overwritten by a call to
* g_param_spec_set_qdata() with the same @quark. * g_param_spec_set_qdata() with the same @quark.
*/ */
void void
@ -518,13 +523,12 @@ g_param_spec_set_qdata_full (GParamSpec *pspec,
* g_param_spec_steal_qdata: * g_param_spec_steal_qdata:
* @pspec: the #GParamSpec to get a stored user data pointer from * @pspec: the #GParamSpec to get a stored user data pointer from
* @quark: a #GQuark, naming the user data pointer * @quark: a #GQuark, naming the user data pointer
* *
* Gets back user data pointers stored via g_param_spec_set_qdata() and * Gets back user data pointers stored via g_param_spec_set_qdata()
* removes the @data from @pspec without invoking it's destroy() function * and removes the @data from @pspec without invoking it's destroy()
* (if any was set). * function (if any was set). Usually, calling this function is only
* Usually, calling this function is only required to update * required to update user data pointers with a destroy notifier.
* user data pointers with a destroy notifier. *
*
* Returns: the user data pointer set, or %NULL * Returns: the user data pointer set, or %NULL
*/ */
gpointer gpointer
@ -540,7 +544,7 @@ g_param_spec_steal_qdata (GParamSpec *pspec,
/** /**
* g_param_spec_get_redirect_target: * g_param_spec_get_redirect_target:
* @pspec: a #GParamSpec * @pspec: a #GParamSpec
* *
* If the paramspec redirects operations to another paramspec, * If the paramspec redirects operations to another paramspec,
* returns that paramspec. Redirect is used typically for * returns that paramspec. Redirect is used typically for
* providing a new implementation of a property in a derived * 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 * type. Redirection is established by creating a property
* of type #GParamSpecOverride. See g_object_class_override_property() * of type #GParamSpecOverride. See g_object_class_override_property()
* for an example of the use of this capability. * for an example of the use of this capability.
* *
* Since: 2.4 * Since: 2.4
*
* Returns: paramspec to which requests on this paramspec should * Returns: paramspec to which requests on this paramspec should
* be redirected, or %NULL if none. * be redirected, or %NULL if none.
*/ */
GParamSpec* GParamSpec*
g_param_spec_get_redirect_target (GParamSpec *pspec) 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: * g_param_value_set_default:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* @value: a #GValue of correct type for @pspec * @value: a #GValue of correct type for @pspec
* *
* Sets @value to its default value as specified in @pspec. * Sets @value to its default value as specified in @pspec.
*/ */
void void
@ -591,9 +596,9 @@ g_param_value_set_default (GParamSpec *pspec,
* g_param_value_defaults: * g_param_value_defaults:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* @value: a #GValue of correct type for @pspec * @value: a #GValue of correct type for @pspec
* *
* Checks whether @value contains the default value as specified in @pspec. * Checks whether @value contains the default value as specified in @pspec.
* *
* Returns: whether @value contains the canonical default for this @pspec * Returns: whether @value contains the canonical default for this @pspec
*/ */
gboolean gboolean
@ -619,14 +624,14 @@ g_param_value_defaults (GParamSpec *pspec,
* g_param_value_validate: * g_param_value_validate:
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* @value: a #GValue of correct type for @pspec * @value: a #GValue of correct type for @pspec
* *
* Ensures that the contents of @value comply with the specifications * Ensures that the contents of @value comply with the specifications
* set out by @pspec. For example, a #GParamSpecInt might require * set out by @pspec. For example, a #GParamSpecInt might require
* that integers stored in @value may not be smaller than -42 and not be * 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, * greater than +42. If @value contains an integer outside of this range,
* it is modified accordingly, so the resulting value will fit into the * it is modified accordingly, so the resulting value will fit into the
* range -42 .. +42. * range -42 .. +42.
* *
* Returns: whether modifying @value was necessary to ensure validity * Returns: whether modifying @value was necessary to ensure validity
*/ */
gboolean gboolean
@ -654,16 +659,17 @@ g_param_value_validate (GParamSpec *pspec,
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* @src_value: souce #GValue * @src_value: souce #GValue
* @dest_value: destination #GValue of correct type for @pspec * @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. * Transforms @src_value into @dest_value if possible, and then
* If @strict_validation is %TRUE this function will only succeed if * validates @dest_value, in order for it to conform to @pspec. If
* the transformed @dest_value complied to @pspec without modifications. * @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 * See also g_value_type_transformable(), g_value_transform() and
* g_param_value_validate(). * g_param_value_validate().
* *
* Returns: %TRUE if transformation and validation were successful, * Returns: %TRUE if transformation and validation were successful,
* %FALSE otherwise and @dest_value is left untouched. * %FALSE otherwise and @dest_value is left untouched.
*/ */
@ -706,11 +712,11 @@ g_param_value_convert (GParamSpec *pspec,
* @pspec: a valid #GParamSpec * @pspec: a valid #GParamSpec
* @value1: a #GValue of correct type for @pspec * @value1: a #GValue of correct type for @pspec
* @value2: 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, * 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. * respectively.
* *
* Returns: -1, 0 or +1, for a less than, equal to or greater than result * Returns: -1, 0 or +1, for a less than, equal to or greater than result
*/ */
gint gint
@ -832,11 +838,11 @@ value_param_lcopy_value (const GValue *value,
/* --- param spec pool --- */ /* --- param spec pool --- */
/** /**
* GParamSpecPool: * GParamSpecPool:
* *
* A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be
* quickly accessed by owner and name. The implementation of the #GObject property * 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 * system uses such a pool to store the #GParamSpecs of the properties all object
* types. * types.
*/ */
struct _GParamSpecPool struct _GParamSpecPool
{ {
@ -872,14 +878,14 @@ param_spec_pool_equals (gconstpointer key_spec_1,
/** /**
* g_param_spec_pool_new: * g_param_spec_pool_new:
* @type_prefixing: Whether the pool will support type-prefixed property names. * @type_prefixing: Whether the pool will support type-prefixed property names.
* *
* Creates a new #GParamSpecPool. * Creates a new #GParamSpecPool.
* *
* If @type_prefixing is %TRUE, lookups in the newly created pool will * 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, * allow to specify the owner as a colon-separated prefix of the
* like "GtkContainer:border-width". This feature is deprecated, so you should * property name, like "GtkContainer:border-width". This feature is
* always set @type_prefixing to %FALSE. * deprecated, so you should always set @type_prefixing to %FALSE.
* *
* Returns: a newly allocated #GParamSpecPool. * Returns: a newly allocated #GParamSpecPool.
*/ */
GParamSpecPool* GParamSpecPool*
@ -900,9 +906,10 @@ g_param_spec_pool_new (gboolean type_prefixing)
* @pool: a #GParamSpecPool. * @pool: a #GParamSpecPool.
* @pspec: the #GParamSpec to insert * @pspec: the #GParamSpec to insert
* @owner_type: a #GType identifying the owner of @pspec * @owner_type: a #GType identifying the owner of @pspec
* *
* Inserts a #GParamSpec in the pool. * Inserts a #GParamSpec in the pool.
*/void */
void
g_param_spec_pool_insert (GParamSpecPool *pool, g_param_spec_pool_insert (GParamSpecPool *pool,
GParamSpec *pspec, GParamSpec *pspec,
GType owner_type) GType owner_type)
@ -940,7 +947,7 @@ g_param_spec_pool_insert (GParamSpecPool *pool,
* g_param_spec_pool_remove: * g_param_spec_pool_remove:
* @pool: a #GParamSpecPool * @pool: a #GParamSpecPool
* @pspec: the #GParamSpec to remove * @pspec: the #GParamSpec to remove
* *
* Removes a #GParamSpec from the pool. * Removes a #GParamSpec from the pool.
*/ */
void void
@ -1017,11 +1024,11 @@ param_spec_ht_lookup (GHashTable *hash_table,
* @pool: a #GParamSpecPool * @pool: a #GParamSpecPool
* @param_name: the name to look for * @param_name: the name to look for
* @owner_type: the owner 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. * owned by an ancestor of @owner_type.
* *
* Looks up a #GParamSpec in the pool. * Looks up a #GParamSpec in the pool.
* *
* Returns: The found #GParamSpec, or %NULL if no matching #GParamSpec was found. * Returns: The found #GParamSpec, or %NULL if no matching #GParamSpec was found.
*/ */
GParamSpec* GParamSpec*
@ -1105,11 +1112,12 @@ pool_list (gpointer key,
* g_param_spec_pool_list_owned: * g_param_spec_pool_list_owned:
* @pool: a #GParamSpecPool * @pool: a #GParamSpecPool
* @owner_type: the owner to look for * @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* GList*
g_param_spec_pool_list_owned (GParamSpecPool *pool, g_param_spec_pool_list_owned (GParamSpecPool *pool,
@ -1239,11 +1247,12 @@ pool_depth_list_for_interface (gpointer key,
* @pool: a #GParamSpecPool * @pool: a #GParamSpecPool
* @owner_type: the owner to look for * @owner_type: the owner to look for
* @n_pspecs_p: return location for the length of the returned array * @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 * Returns: a newly allocated array containing pointers to all
* #GParamSpec<!-- -->s owned by @owner_type in the pool
*/ */
GParamSpec** GParamSpec**
g_param_spec_pool_list (GParamSpecPool *pool, g_param_spec_pool_list (GParamSpecPool *pool,
@ -1342,12 +1351,12 @@ default_values_cmp (GParamSpec *pspec,
* g_param_type_register_static: * g_param_type_register_static:
* @name: 0-terminated string used as the name of the new #GParamSpec type. * @name: 0-terminated string used as the name of the new #GParamSpec type.
* @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type.
* *
* Registers @name as the name of a new static type derived from * Registers @name as the name of a new static type derived from
* #G_TYPE_PARAM. The type system uses the information contained in the * #G_TYPE_PARAM. The type system uses the information contained in
* #GParamSpecTypeInfo structure pointed to by @info to manage the #GParamSpec * the #GParamSpecTypeInfo structure pointed to by @info to manage the
* type and its instances. * #GParamSpec type and its instances.
* *
* Returns: The new type identifier. * Returns: The new type identifier.
*/ */
GType GType
@ -1394,7 +1403,7 @@ g_param_type_register_static (const gchar *name,
* g_value_set_param: * g_value_set_param:
* @value: a valid #GValue of type %G_TYPE_PARAM * @value: a valid #GValue of type %G_TYPE_PARAM
* @param: the #GParamSpec to be set * @param: the #GParamSpec to be set
* *
* Set the contents of a %G_TYPE_PARAM #GValue to @param. * Set the contents of a %G_TYPE_PARAM #GValue to @param.
*/ */
void void
@ -1416,9 +1425,9 @@ g_value_set_param (GValue *value,
* g_value_set_param_take_ownership: * g_value_set_param_take_ownership:
* @value: a valid #GValue of type %G_TYPE_PARAM * @value: a valid #GValue of type %G_TYPE_PARAM
* @param: the #GParamSpec to be set * @param: the #GParamSpec to be set
* *
* This is an internal function introduced mainly for C marshallers. * This is an internal function introduced mainly for C marshallers.
* *
* Deprecated: 2.4: Use g_value_take_param() instead. * Deprecated: 2.4: Use g_value_take_param() instead.
*/ */
void void
@ -1432,11 +1441,11 @@ g_value_set_param_take_ownership (GValue *value,
* g_value_take_param: * g_value_take_param:
* @value: a valid #GValue of type %G_TYPE_PARAM * @value: a valid #GValue of type %G_TYPE_PARAM
* @param: the #GParamSpec to be set * @param: the #GParamSpec to be set
* *
* Sets the contents of a %G_TYPE_PARAM #GValue to @param and * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes
* takes over the ownership of the callers reference to @param; * over the ownership of the callers reference to @param; the caller
* the caller doesn't have to unref it any more. * doesn't have to unref it any more.
* *
* Since: 2.4 * Since: 2.4
*/ */
void void
@ -1455,9 +1464,9 @@ g_value_take_param (GValue *value,
/** /**
* g_value_get_param: * g_value_get_param:
* @value: a valid #GValue whose type is derived from %G_TYPE_PARAM * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
* *
* Get the contents of a %G_TYPE_PARAM #GValue. * Get the contents of a %G_TYPE_PARAM #GValue.
* *
* Returns: #GParamSpec content of @value * Returns: #GParamSpec content of @value
*/ */
GParamSpec* GParamSpec*
@ -1471,10 +1480,12 @@ g_value_get_param (const GValue *value)
/** /**
* g_value_dup_param: * g_value_dup_param:
* @value: a valid #GValue whose type is derived from %G_TYPE_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* GParamSpec*
g_value_dup_param (const GValue *value) g_value_dup_param (const GValue *value)

175
gobject/gparamspecs.c
View File

@ -33,15 +33,19 @@
/** /**
* SECTION:param_value_types * SECTION:param_value_types
*
* @Short_description: Standard Parameter and 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 * @Title: Parameters and Values
* *
* #GValue provides an abstract container structure which can be copied, * #GValue provides an abstract container structure which can be
* transformed and compared while holding a value of any (derived) type, which * copied, transformed and compared while holding a value of any
* is registered as a #GType with a #GTypeValueTable in its #GTypeInfo structure. * (derived) type, which is registered as a #GType with a
* Parameter specifications for most value types can be created as * #GTypeValueTable in its #GTypeInfo structure. Parameter
* #GParamSpec derived instances, to implement e.g. #GObject properties which * specifications for most value types can be created as #GParamSpec
* derived instances, to implement e.g. #GObject properties which
* operate on #GValue containers. * operate on #GValue containers.
* *
* Parameter names need to start with a letter (a-z or A-Z). Subsequent * 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 * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1562,9 +1566,9 @@ g_param_spec_char (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1600,12 +1604,12 @@ g_param_spec_uchar (const gchar *name,
* @blurb: description of the property specified * @blurb: description of the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags 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. * property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1639,11 +1643,11 @@ g_param_spec_boolean (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1681,11 +1685,11 @@ g_param_spec_int (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1723,11 +1727,11 @@ g_param_spec_uint (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1765,11 +1769,12 @@ g_param_spec_long (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags 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. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1807,11 +1812,11 @@ g_param_spec_ulong (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1849,12 +1854,12 @@ g_param_spec_int64 (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags 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. * property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1890,13 +1895,13 @@ g_param_spec_uint64 (const gchar *name,
* @blurb: description of the property specified * @blurb: description of the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT
* property. #GValue structures for this property can be accessed with * property. #GValue structures for this property can be accessed with
* g_value_set_uint() and g_value_get_uint(). * g_value_set_uint() and g_value_get_uint().
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1927,12 +1932,12 @@ g_param_spec_unichar (const gchar *name,
* @enum_type: a #GType derived from %G_TYPE_ENUM * @enum_type: a #GType derived from %G_TYPE_ENUM
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM
* property. * property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -1973,12 +1978,12 @@ g_param_spec_enum (const gchar *name,
* @flags_type: a #GType derived from %G_TYPE_FLAGS * @flags_type: a #GType derived from %G_TYPE_FLAGS
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS
* property. * property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2020,11 +2025,11 @@ g_param_spec_flags (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2062,12 +2067,12 @@ g_param_spec_float (const gchar *name,
* @maximum: maximum value for the property specified * @maximum: maximum value for the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags 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. * property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2103,11 +2108,11 @@ g_param_spec_double (const gchar *name,
* @blurb: description of the property specified * @blurb: description of the property specified
* @default_value: default value for the property specified * @default_value: default value for the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecString instance. * Creates a new #GParamSpecString instance.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2135,12 +2140,12 @@ g_param_spec_string (const gchar *name,
* @blurb: description of the property specified * @blurb: description of the property specified
* @param_type: a #GType derived from %G_TYPE_PARAM * @param_type: a #GType derived from %G_TYPE_PARAM
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM
* property. * property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2171,12 +2176,12 @@ g_param_spec_param (const gchar *name,
* @blurb: description of the property specified * @blurb: description of the property specified
* @boxed_type: %G_TYPE_BOXED derived type of this property * @boxed_type: %G_TYPE_BOXED derived type of this property
* @flags: flags for the property specified * @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. * derived property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2207,11 +2212,11 @@ g_param_spec_boxed (const gchar *name,
* @nick: nick name for the property specified * @nick: nick name for the property specified
* @blurb: description of the property specified * @blurb: description of the property specified
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecPoiner instance specifying a pointer property. * Creates a new #GParamSpecPoiner instance specifying a pointer property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2238,13 +2243,14 @@ g_param_spec_pointer (const gchar *name,
* @is_a_type: a #GType whose subtypes are allowed as values * @is_a_type: a #GType whose subtypes are allowed as values
* of the property (use %G_TYPE_NONE for any type) * of the property (use %G_TYPE_NONE for any type)
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecGType instance specifying a * Creates a new #GParamSpecGType instance specifying a
* %G_TYPE_GTYPE property. * %G_TYPE_GTYPE property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Since: 2.10 * Since: 2.10
*
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2272,17 +2278,17 @@ g_param_spec_gtype (const gchar *name,
* @name: canonical name of the property specified * @name: canonical name of the property specified
* @nick: nick name for the property specified * @nick: nick name for the property specified
* @blurb: description of 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 * arrays of this property, may be %NULL
* @flags: flags for the property specified * @flags: flags for the property specified
* *
* Creates a new #GParamSpecValueArray instance specifying a * Creates a new #GParamSpecValueArray instance specifying a
* %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a %G_TYPE_BOXED * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a
* type, as such, #GValue structures for this property can be accessed * %G_TYPE_BOXED type, as such, #GValue structures for this property
* with g_value_set_boxed() and g_value_get_boxed(). * can be accessed with g_value_set_boxed() and g_value_get_boxed().
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2318,12 +2324,12 @@ g_param_spec_value_array (const gchar *name,
* @blurb: description of the property specified * @blurb: description of the property specified
* @object_type: %G_TYPE_OBJECT derived type of this property * @object_type: %G_TYPE_OBJECT derived type of this property
* @flags: flags for the property specified * @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. * derived property.
* *
* See g_param_spec_internal() for details on property names. * See g_param_spec_internal() for details on property names.
* *
* Returns: a newly created parameter specification * Returns: a newly created parameter specification
*/ */
GParamSpec* GParamSpec*
@ -2351,12 +2357,13 @@ g_param_spec_object (const gchar *name,
* g_param_spec_override: * g_param_spec_override:
* @name: the name of the property. * @name: the name of the property.
* @overridden: The property that is being overridden * @overridden: The property that is being overridden
* *
* Creates a new property of type #GParamSpecOverride. This is used * Creates a new property of type #GParamSpecOverride. This is used
* to direct operations to another paramspec, and will not be directly * to direct operations to another paramspec, and will not be directly
* useful unless you are implementing a new base type similar to GObject. * useful unless you are implementing a new base type similar to GObject.
* *
* Since: 2.4 * Since: 2.4
*
* Returns: the newly created #GParamSpec * Returns: the newly created #GParamSpec
*/ */
GParamSpec* GParamSpec*

293
gobject/gsignal.c
View File

@ -41,7 +41,10 @@
/** /**
* SECTION:signals * 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 * @Title: Signals
* *
* The basic concept of the signal system is that of the * 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. * @instance: the object whose signal handlers you wish to stop.
* @signal_id: the signal identifier, as returned by g_signal_lookup(). * @signal_id: the signal identifier, as returned by g_signal_lookup().
* @detail: the detail which the signal was emitted with. * @detail: the detail which the signal was emitted with.
* *
* Stops a signal's current emission. * Stops a signal's current emission.
* *
* This will prevent the default method from running, if the signal was * 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). * flag).
* *
* Prints a warning if used on a signal which isn't being emitted. * Prints a warning if used on a signal which isn't being emitted.
*/ */
void void
@ -883,11 +886,11 @@ signal_finalize_hook (GHookList *hook_list,
* @hook_func: a #GSignalEmissionHook function. * @hook_func: a #GSignalEmissionHook function.
* @hook_data: user data for @hook_func. * @hook_data: user data for @hook_func.
* @data_destroy: a #GDestroyNotify for @hook_data. * @data_destroy: a #GDestroyNotify for @hook_data.
* *
* Adds an emission hook for a signal, which will get called for any emission * 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 * of that signal, independent of the instance. This is possible only
* for signals which don't have #G_SIGNAL_NO_HOOKS flag set. * 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(). * Returns: the hook id, for later use with g_signal_remove_emission_hook().
*/ */
gulong gulong
@ -948,9 +951,9 @@ g_signal_add_emission_hook (guint signal_id,
/** /**
* g_signal_remove_emission_hook: * g_signal_remove_emission_hook:
* @signal_id: the id of the signal * @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() * g_signal_add_emission_hook()
* *
* Deletes an emission hook. * Deletes an emission hook.
*/ */
void void
@ -1022,10 +1025,10 @@ signal_parse_name (const gchar *name,
* @signal_id_p: Location to store the signal id. * @signal_id_p: Location to store the signal id.
* @detail_p: Location to store the detail quark. * @detail_p: Location to store the detail quark.
* @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail.
* *
* Internal function to parse a signal name into its @signal_id * Internal function to parse a signal name into its @signal_id
* and @detail quark. * and @detail quark.
* *
* Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values.
*/ */
gboolean gboolean
@ -1063,10 +1066,10 @@ g_signal_parse_name (const gchar *detailed_signal,
* g_signal_stop_emission_by_name: * g_signal_stop_emission_by_name:
* @instance: the object whose signal handlers you wish to stop. * @instance: the object whose signal handlers you wish to stop.
* @detailed_signal: a string of the form "signal-name::detail". * @detailed_signal: a string of the form "signal-name::detail".
* *
* Stops a signal's current emission. * 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. * signal id for you.
*/ */
void void
@ -1118,15 +1121,15 @@ g_signal_stop_emission_by_name (gpointer instance,
* g_signal_lookup: * g_signal_lookup:
* @name: the signal's name. * @name: the signal's name.
* @itype: the type that the signal operates on. * @itype: the type that the signal operates on.
* *
* Given the name of the signal and the type of object it connects to, gets * 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 * the signal's identifying integer. Emitting the signal by number is
* somewhat faster than using the name each time. * somewhat faster than using the name each time.
* *
* Also tries the ancestors of the given type. * Also tries the ancestors of the given type.
* *
* See g_signal_new() for details on allowed signal names. * See g_signal_new() for details on allowed signal names.
* *
* Returns: the signal's identifying number, or 0 if no signal was found. * Returns: the signal's identifying number, or 0 if no signal was found.
*/ */
guint guint
@ -1161,11 +1164,11 @@ g_signal_lookup (const gchar *name,
* g_signal_list_ids: * g_signal_list_ids:
* @itype: Instance or interface type. * @itype: Instance or interface type.
* @n_ids: Location to store the number of signal ids for @itype. * @n_ids: Location to store the number of signal ids for @itype.
* *
* Lists the signals by id that a certain instance or interface type * Lists the signals by id that a certain instance or interface type
* created. Further information about the signals can be acquired through * created. Further information about the signals can be acquired through
* g_signal_query(). * g_signal_query().
* *
* Returns: Newly allocated array of signal IDs. * Returns: Newly allocated array of signal IDs.
*/ */
guint* guint*
@ -1218,11 +1221,11 @@ g_signal_list_ids (GType itype,
/** /**
* g_signal_name: * g_signal_name:
* @signal_id: the signal's identifying number. * @signal_id: the signal's identifying number.
* *
* Given the signal's identifier, finds its name. * Given the signal's identifier, finds its name.
* *
* Two different signals may have the same name, if they have differing types. * 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. * Returns: the signal name, or %NULL if the signal number was invalid.
*/ */
G_CONST_RETURN gchar* 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. * @signal_id: The signal id of the signal to query information for.
* @query: A user provided structure that is filled in with constant * @query: A user provided structure that is filled in with constant
* values upon success. * values upon success.
* *
* Queries the signal system for in-depth information about a * Queries the signal system for in-depth information about a
* specific signal. This function will fill in a user-provided * specific signal. This function will fill in a user-provided
* structure to hold signal-specific information. If an invalid * structure to hold signal-specific information. If an invalid
@ -1280,33 +1283,33 @@ g_signal_query (guint signal_id,
/** /**
* g_signal_new: * g_signal_new:
* @signal_name: the name for the signal * @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. * types which are derived from this type.
* @signal_flags: a combination of #GSignalFlags specifying detail of when * @signal_flags: a combination of #GSignalFlags specifying detail of when
* the default handler is to be invoked. You should at least specify * the default handler is to be invoked. You should at least specify
* %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. * %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 * for this type. Used to invoke a class method generically. Pass 0 to
* not associate a class method with this signal. * not associate a class method with this signal.
* @accumulator: the accumulator for this signal; may be %NULL. * @accumulator: the accumulator for this signal; may be %NULL.
* @accu_data: user data for the @accumulator. * @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. * 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. * without a return value.
* @n_params: the number of parameter types to follow. * @n_params: the number of parameter types to follow.
* @...: a list of types, one for each parameter. * @...: a list of types, one for each parameter.
* *
* Creates a new signal. (This is usually done in the class initializer.) * Creates a new signal. (This is usually done in the class initializer.)
* *
* A signal name consists of segments consisting of ASCII letters and * A signal name consists of segments consisting of ASCII letters and
* digits, separated by either the '-' or '_' character. The first * digits, separated by either the '-' or '_' character. The first
* character of a signal name must be a letter. Names which violate these * 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 * 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 * Returns: the signal id
*/ */
guint guint
@ -1414,25 +1417,25 @@ signal_add_class_closure (SignalNode *node,
/** /**
* g_signal_newv: * g_signal_newv:
* @signal_name: the name for the signal * @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. * types which are derived from this type.
* @signal_flags: a combination of #GSignalFlags specifying detail of when * @signal_flags: a combination of #GSignalFlags specifying detail of when
* the default handler is to be invoked. You should at least specify * the default handler is to be invoked. You should at least specify
* %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
* @class_closure: The closure to invoke on signal emission; may be %NULL. * @class_closure: The closure to invoke on signal emission; may be %NULL.
* @accumulator: the accumulator for this signal; may be %NULL. * @accumulator: the accumulator for this signal; may be %NULL.
* @accu_data: user data for the @accumulator. * @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. * 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. * without a return value.
* @n_params: the length of @param_types. * @n_params: the length of @param_types.
* @param_types: an array types, one for each parameter. * @param_types: an array types, one for each parameter.
* *
* Creates a new signal. (This is usually done in the class initializer.) * Creates a new signal. (This is usually done in the class initializer.)
* *
* See g_signal_new() for details on allowed signal names. * See g_signal_new() for details on allowed signal names.
* *
* Returns: the signal id * Returns: the signal id
*/ */
guint guint
@ -1572,25 +1575,25 @@ g_signal_newv (const gchar *signal_name,
/** /**
* g_signal_new_valist: * g_signal_new_valist:
* @signal_name: the name for the signal * @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. * types which are derived from this type.
* @signal_flags: a combination of #GSignalFlags specifying detail of when * @signal_flags: a combination of #GSignalFlags specifying detail of when
* the default handler is to be invoked. You should at least specify * the default handler is to be invoked. You should at least specify
* %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
* @class_closure: The closure to invoke on signal emission; may be %NULL. * @class_closure: The closure to invoke on signal emission; may be %NULL.
* @accumulator: the accumulator for this signal; may be %NULL. * @accumulator: the accumulator for this signal; may be %NULL.
* @accu_data: user data for the @accumulator. * @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. * 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. * without a return value.
* @n_params: the number of parameter types in @args. * @n_params: the number of parameter types in @args.
* @args: va_list of #GType, one for each parameter. * @args: va_list of #GType, one for each parameter.
* *
* Creates a new signal. (This is usually done in the class initializer.) * Creates a new signal. (This is usually done in the class initializer.)
* *
* See g_signal_new() for details on allowed signal names. * See g_signal_new() for details on allowed signal names.
* *
* Returns: the signal id * Returns: the signal id
*/ */
guint guint
@ -1685,10 +1688,10 @@ signal_destroy_R (SignalNode *signal_node)
/** /**
* g_signal_override_class_closure: * g_signal_override_class_closure:
* @signal_id: the signal id * @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. * for the signal.
* @class_closure: the closure. * @class_closure: the closure.
* *
* Overrides the class closure (i.e. the default handler) for the given signal * 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 * for emissions on instances of @instance_type. @instance_type must be derived
* from the type to which the signal belongs. * 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: * g_signal_chain_from_overridden:
* @instance_and_params: the argument list of the signal emission. The first * @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 * 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. * emitted on. The rest are any arguments to be passed to the signal.
* @return_value: Location for the return value. * @return_value: Location for the return value.
* *
* Calls the original class closure of a signal. This function should only * 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(). * g_signal_override_class_closure().
*/ */
void void
@ -1792,9 +1795,9 @@ g_signal_chain_from_overridden (const GValue *instance_and_params,
/** /**
* g_signal_get_invocation_hint: * g_signal_get_invocation_hint:
* @instance: the instance to query * @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. * Returns: the invocation hint of the innermost signal emission.
*/ */
GSignalInvocationHint* GSignalInvocationHint*
@ -1817,11 +1820,11 @@ g_signal_get_invocation_hint (gpointer instance)
* @signal_id: the id of the signal. * @signal_id: the id of the signal.
* @detail: the detail. * @detail: the detail.
* @closure: the closure to connect. * @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. * default handler of the signal.
* *
* Connects a closure to a signal for a particular object. * Connects a closure to a signal for a particular object.
* *
* Returns: the handler id * Returns: the handler id
*/ */
gulong gulong
@ -1871,11 +1874,11 @@ g_signal_connect_closure_by_id (gpointer instance,
* @instance: the instance to connect to. * @instance: the instance to connect to.
* @detailed_signal: a string of the form "signal-name::detail". * @detailed_signal: a string of the form "signal-name::detail".
* @closure: the closure to connect. * @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. * default handler of the signal.
* *
* Connects a closure to a signal for a particular object. * Connects a closure to a signal for a particular object.
* *
* Returns: the handler id * Returns: the handler id
*/ */
gulong gulong
@ -1932,13 +1935,13 @@ g_signal_connect_closure (gpointer instance,
* @data: data to pass to @c_handler calls. * @data: data to pass to @c_handler calls.
* @destroy_data: a #GClosureNotify for @data. * @destroy_data: a #GClosureNotify for @data.
* @connect_flags: a combination of #GConnectFlags. * @connect_flags: a combination of #GConnectFlags.
* *
* Connects a #GCallback function to a signal for a particular object. Similar * 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 * 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 * which will be called when the signal handler is disconnected and no longer
* used. Specify @connect_flags if you need <literal>..._after()</literal> or * used. Specify @connect_flags if you need <literal>..._after()</literal> or
* <literal>..._swapped()</literal> variants of this function. * <literal>..._swapped()</literal> variants of this function.
* *
* Returns: the handler id * Returns: the handler id
*/ */
gulong gulong
@ -1997,14 +2000,14 @@ g_signal_connect_data (gpointer instance,
* g_signal_handler_block: * g_signal_handler_block:
* @instance: The instance to block the signal handler of. * @instance: The instance to block the signal handler of.
* @handler_id: Handler id of the handler to be blocked. * @handler_id: Handler id of the handler to be blocked.
* *
* Blocks a handler of an instance so it will not be called during * Blocks a handler of an instance so it will not be called during any
* any signal emissions unless it is unblocked again. Thus "blocking" * signal emissions unless it is unblocked again. Thus "blocking" a
* a signal handler means to temporarily deactive it, a signal handler * signal handler means to temporarily deactive it, a signal handler
* has to be unblocked exactly the same amount of times it has been * has to be unblocked exactly the same amount of times it has been
* blocked before to become active again. * 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. * signal of @instance.
*/ */
void void
@ -2035,19 +2038,19 @@ g_signal_handler_block (gpointer instance,
* g_signal_handler_unblock: * g_signal_handler_unblock:
* @instance: The instance to unblock the signal handler of. * @instance: The instance to unblock the signal handler of.
* @handler_id: Handler id of the handler to be unblocked. * @handler_id: Handler id of the handler to be unblocked.
* *
* Undoes the effect of a previous g_signal_handler_block() call. * Undoes the effect of a previous g_signal_handler_block() call. A
* A blocked handler is skipped during signal emissions and will not be * blocked handler is skipped during signal emissions and will not be
* invoked, unblocking it (for exactly the amount of times it has been * invoked, unblocking it (for exactly the amount of times it has been
* blocked before) reverts its "blocked" state, so the handler will be * blocked before) reverts its "blocked" state, so the handler will be
* recognized by the signal system and is called upon future or currently * recognized by the signal system and is called upon future or
* ongoing signal emissions (since the order in which handlers are * currently ongoing signal emissions (since the order in which
* called during signal emissions is deterministic, whether the * handlers are called during signal emissions is deterministic,
* unblocked handler in question is called as part of a currently * whether the unblocked handler in question is called as part of a
* ongoing emission depends on how far that emission has proceeded * currently ongoing emission depends on how far that emission has
* yet). * proceeded yet).
* *
* The @handler_id has to be a valid id of a signal handler that is * 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. * connected to a signal of @instance and is currently blocked.
*/ */
void void
@ -2077,12 +2080,12 @@ g_signal_handler_unblock (gpointer instance,
* g_signal_handler_disconnect: * g_signal_handler_disconnect:
* @instance: The instance to remove the signal handler from. * @instance: The instance to remove the signal handler from.
* @handler_id: Handler id of the handler to be disconnected. * @handler_id: Handler id of the handler to be disconnected.
* *
* Disconnects a handler from an instance so it will not be called during * 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 * any future or currently ongoing emissions of the signal it has been
* connected to. The @handler_id becomes invalid and may be reused. * 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. * signal of @instance.
*/ */
void void
@ -2112,9 +2115,9 @@ g_signal_handler_disconnect (gpointer instance,
* g_signal_handler_is_connected: * g_signal_handler_is_connected:
* @instance: The instance where a signal handler is sought. * @instance: The instance where a signal handler is sought.
* @handler_id: the handler id. * @handler_id: the handler id.
* *
* Returns whether @handler_id is the id of a handler connected to @instance. * Returns whether @handler_id is the id of a handler connected to @instance.
* *
* Returns: whether @handler_id identifies a handler connected to @instance. * Returns: whether @handler_id identifies a handler connected to @instance.
*/ */
gboolean gboolean
@ -2179,20 +2182,20 @@ g_signal_handlers_destroy (gpointer instance)
/** /**
* g_signal_handler_find: * g_signal_handler_find:
* @instance: The instance owning the signal handler to be found. * @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. * and/or @data the handler has to match.
* @signal_id: Signal the handler has to be connected to. * @signal_id: Signal the handler has to be connected to.
* @detail: Signal detail the handler has to be connected to. * @detail: Signal detail the handler has to be connected to.
* @closure: The closure the handler will invoke. * @closure: The closure the handler will invoke.
* @func: The C closure callback of the handler (useless for non-C closures). * @func: The C closure callback of the handler (useless for non-C closures).
* @data: The closure data of the handler's closure. * @data: The closure data of the handler's closure.
* *
* Finds the first signal handler that matches certain selection criteria. * Finds the first signal handler that matches 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. * flags, and the criteria values are passed as arguments.
* The match @mask has to be non-0 for successful matches. * The match @mask has to be non-0 for successful matches.
* If no handler was found, 0 is returned. * If no handler was found, 0 is returned.
* *
* Returns: A valid non-0 signal handler id for a successful match. * Returns: A valid non-0 signal handler id for a successful match.
*/ */
gulong gulong
@ -2259,22 +2262,22 @@ signal_handlers_foreach_matched_R (gpointer instance,
/** /**
* g_signal_handlers_block_matched: * g_signal_handlers_block_matched:
* @instance: The instance to block handlers from. * @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. * and/or @data the handlers have to match.
* @signal_id: Signal the handlers have to be connected to. * @signal_id: Signal the handlers have to be connected to.
* @detail: Signal detail the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to.
* @closure: The closure the handlers will invoke. * @closure: The closure the handlers will invoke.
* @func: The C closure callback of the handlers (useless for non-C closures). * @func: The C closure callback of the handlers (useless for non-C closures).
* @data: The closure data of the handlers' closures. * @data: The closure data of the handlers' closures.
* *
* Blocks all handlers on an instance that match a certain selection criteria. * 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. * flags, and the criteria values are passed as arguments.
* Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC * 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. * 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 * If no handlers were found, 0 is returned, the number of blocked handlers
* otherwise. * otherwise.
* *
* Returns: The number of handlers that matched. * Returns: The number of handlers that matched.
*/ */
guint guint
@ -2306,14 +2309,14 @@ g_signal_handlers_block_matched (gpointer instance,
/** /**
* g_signal_handlers_unblock_matched: * g_signal_handlers_unblock_matched:
* @instance: The instance to unblock handlers from. * @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. * and/or @data the handlers have to match.
* @signal_id: Signal the handlers have to be connected to. * @signal_id: Signal the handlers have to be connected to.
* @detail: Signal detail the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to.
* @closure: The closure the handlers will invoke. * @closure: The closure the handlers will invoke.
* @func: The C closure callback of the handlers (useless for non-C closures). * @func: The C closure callback of the handlers (useless for non-C closures).
* @data: The closure data of the handlers' closures. * @data: The closure data of the handlers' closures.
* *
* Unblocks all handlers on an instance that match a certain selection * Unblocks all handlers on an instance that match a certain selection
* criteria. The criteria mask is passed as an OR-ed combination of * criteria. The criteria mask is passed as an OR-ed combination of
* #GSignalMatchType flags, and the criteria values are passed as arguments. * #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 * 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 * otherwise. The match criteria should not apply to any handlers that are
* not currently blocked. * not currently blocked.
* *
* Returns: The number of handlers that matched. * Returns: The number of handlers that matched.
*/ */
guint guint
@ -2354,22 +2357,23 @@ g_signal_handlers_unblock_matched (gpointer instance,
/** /**
* g_signal_handlers_disconnect_matched: * g_signal_handlers_disconnect_matched:
* @instance: The instance to remove handlers from. * @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. * and/or @data the handlers have to match.
* @signal_id: Signal the handlers have to be connected to. * @signal_id: Signal the handlers have to be connected to.
* @detail: Signal detail the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to.
* @closure: The closure the handlers will invoke. * @closure: The closure the handlers will invoke.
* @func: The C closure callback of the handlers (useless for non-C closures). * @func: The C closure callback of the handlers (useless for non-C closures).
* @data: The closure data of the handlers' closures. * @data: The closure data of the handlers' closures.
* *
* Disconnects all handlers on an instance that match a certain selection * Disconnects all handlers on an instance that match a certain
* criteria. The criteria mask is passed as an OR-ed combination of * selection criteria. The criteria mask is passed as an OR-ed
* #GSignalMatchType flags, and the criteria values are passed as arguments. * combination of #GSignalMatchType flags, and the criteria values are
* Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC * passed as arguments. Passing at least one of the
* or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or
* If no handlers were found, 0 is returned, the number of disconnected * %G_SIGNAL_MATCH_DATA match flags is required for successful
* handlers otherwise. * matches. If no handlers were found, 0 is returned, the number of
* * disconnected handlers otherwise.
*
* Returns: The number of handlers that matched. * Returns: The number of handlers that matched.
*/ */
guint guint
@ -2404,17 +2408,17 @@ g_signal_handlers_disconnect_matched (gpointer instance,
* @signal_id: the signal id. * @signal_id: the signal id.
* @detail: the detail. * @detail: the detail.
* @may_be_blocked: whether blocked handlers should count as match. * @may_be_blocked: whether blocked handlers should count as match.
* *
* Returns whether there are any handlers connected to @instance for the * Returns whether there are any handlers connected to @instance for the
* given signal id and detail. * given signal id and detail.
* *
* One example of when you might use this is when the arguments to the * 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 * signal are difficult to compute. A class implementor may opt to not
* the signal if no one is attached anyway, thus saving the cost of building * emit the signal if no one is attached anyway, thus saving the cost
* the arguments. * of building the arguments.
* *
* Returns: %TRUE if a handler is connected to the signal, * Returns: %TRUE if a handler is connected to the signal, %FALSE
* %FALSE otherwise. * otherwise.
*/ */
gboolean gboolean
g_signal_has_handler_pending (gpointer instance, g_signal_has_handler_pending (gpointer instance,
@ -2501,16 +2505,16 @@ signal_check_skip_emission (SignalNode *node,
/** /**
* g_signal_emitv: * g_signal_emitv:
* @instance_and_params: argument list for the signal emission. The first * @instance_and_params: argument list for the signal emission. The first
* element in the array is a #GValue for the instance the signal is * 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 * being emitted on. The rest are any arguments to be passed to the
* signal. * signal.
* @signal_id: the signal id * @signal_id: the signal id
* @detail: the detail * @detail: the detail
* @return_value: Location to store the return value of the signal emission. * @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 * 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(). * 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 * @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 * location for the return value. If the return type of the signal
* is #G_TYPE_NONE, the return value location can be omitted. * 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 * Note that g_signal_emit_valist() resets the return value to the default
* if no handlers are connected, in contrast to g_signal_emitv(). * 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 * @...: parameters to be passed to the signal, followed by a
* location for the return value. If the return type of the signal * location for the return value. If the return type of the signal
* is #G_TYPE_NONE, the return value location can be omitted. * 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 * Note that g_signal_emit() resets the return value to the default
* if no handlers are connected, in contrast to g_signal_emitv(). * 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 * @...: parameters to be passed to the signal, followed by a
* location for the return value. If the return type of the signal * location for the return value. If the return type of the signal
* is #G_TYPE_NONE, the return value location can be omitted. * 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 * 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(). * 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 * @return_accu: standard #GSignalAccumulator parameter
* @handler_return: standard #GSignalAccumulator parameter * @handler_return: standard #GSignalAccumulator parameter
* @dummy: standard #GSignalAccumulator parameter * @dummy: standard #GSignalAccumulator parameter
* *
* A predefined #GSignalAccumulator for signals that return a * A predefined #GSignalAccumulator for signals that return a
* boolean values. The behavior that this accumulator gives is * boolean values. The behavior that this accumulator gives is
* that a return of %TRUE stops the signal emission: no further * 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 * the emission to coninue. The idea here is that a %TRUE return
* indicates that the callback <emphasis>handled</emphasis> the signal, * indicates that the callback <emphasis>handled</emphasis> the signal,
* and no further handling is needed. * and no further handling is needed.
* *
* Since: 2.4 * Since: 2.4
*
* Returns: standard #GSignalAccumulator result * Returns: standard #GSignalAccumulator result
*/ */
gboolean gboolean

4
gobject/gsourceclosure.c
View File

@ -162,9 +162,9 @@ static GSourceCallbackFuncs closure_callback_funcs = {
* g_source_set_closure: * g_source_set_closure:
* @source: the source * @source: the source
* @closure: a #GClosure * @closure: a #GClosure
* *
* Set the callback for a source as 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 * 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 * and @closure_marshal fields of the #GSourceFuncs structure must have been
* filled in with pointers to appropriate functions. * filled in with pointers to appropriate functions.

386
gobject/gtype.c
View File

@ -34,7 +34,10 @@
/** /**
* SECTION:gtype * 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 * @Title:Type Information
* *
* The GType API is the foundation of the GObject system. It provides the * The GType API is the foundation of the GObject system. It provides the
@ -238,6 +241,7 @@ struct _TypeNode
} _prot; } _prot;
GType supers[1]; /* flexible array */ GType supers[1]; /* flexible array */
}; };
#define SIZEOF_BASE_TYPE_NODE() (G_STRUCT_OFFSET (TypeNode, supers)) #define SIZEOF_BASE_TYPE_NODE() (G_STRUCT_OFFSET (TypeNode, supers))
#define MAX_N_SUPERS (255) #define MAX_N_SUPERS (255)
#define MAX_N_CHILDREN (4095) #define MAX_N_CHILDREN (4095)
@ -270,17 +274,20 @@ struct _IFaceHolder
GTypePlugin *plugin; GTypePlugin *plugin;
IFaceHolder *next; IFaceHolder *next;
}; };
struct _IFaceEntry struct _IFaceEntry
{ {
GType iface_type; GType iface_type;
GTypeInterface *vtable; GTypeInterface *vtable;
InitState init_state; InitState init_state;
}; };
struct _CommonData struct _CommonData
{ {
guint ref_count; guint ref_count;
GTypeValueTable *value_table; GTypeValueTable *value_table;
}; };
struct _IFaceData struct _IFaceData
{ {
CommonData common; CommonData common;
@ -292,6 +299,7 @@ struct _IFaceData
gconstpointer dflt_data; gconstpointer dflt_data;
gpointer dflt_vtable; gpointer dflt_vtable;
}; };
struct _ClassData struct _ClassData
{ {
CommonData common; CommonData common;
@ -304,6 +312,7 @@ struct _ClassData
gconstpointer class_data; gconstpointer class_data;
gpointer class; gpointer class;
}; };
struct _InstanceData struct _InstanceData
{ {
CommonData common; CommonData common;
@ -320,6 +329,7 @@ struct _InstanceData
guint16 n_preallocs; guint16 n_preallocs;
GInstanceInitFunc instance_init; GInstanceInitFunc instance_init;
}; };
union _TypeData union _TypeData
{ {
CommonData common; CommonData common;
@ -327,10 +337,12 @@ union _TypeData
ClassData class; ClassData class;
InstanceData instance; InstanceData instance;
}; };
typedef struct { typedef struct {
gpointer cache_data; gpointer cache_data;
GTypeClassCacheFunc cache_func; GTypeClassCacheFunc cache_func;
} ClassCacheFunc; } ClassCacheFunc;
typedef struct { typedef struct {
gpointer check_data; gpointer check_data;
GTypeInterfaceCheckFunc check_func; GTypeInterfaceCheckFunc check_func;
@ -1299,7 +1311,7 @@ type_iface_add_prerequisite_W (TypeNode *iface,
* g_type_interface_add_prerequisite: * g_type_interface_add_prerequisite:
* @interface_type: #GType value of an interface type. * @interface_type: #GType value of an interface type.
* @prerequisite_type: #GType value of an interface or instantiatable type. * @prerequisite_type: #GType value of an interface or instantiatable type.
* *
* Adds @prerequisite_type to the list of prerequisites of @interface_type. * Adds @prerequisite_type to the list of prerequisites of @interface_type.
* This means that any type implementing @interface_type must also implement * This means that any type implementing @interface_type must also implement
* @prerequisite_type. Prerequisites can be thought of as an alternative to * @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: * g_type_interface_prerequisites:
* @interface_type: an interface type * @interface_type: an interface type
* @n_prerequisites: location to return the number of prerequisites, or %NULL * @n_prerequisites: location to return the number of prerequisites, or %NULL
* *
* Returns the prerequisites of an interfaces type. * Returns the prerequisites of an interfaces type.
* *
* Since: 2.2 * 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 * the prerequisites of @interface_type
*/ */
GType* GType*
@ -1528,6 +1541,7 @@ typedef struct {
gpointer instance; gpointer instance;
gpointer class; gpointer class;
} InstanceRealClass; } InstanceRealClass;
static gint static gint
instance_real_class_cmp (gconstpointer p1, instance_real_class_cmp (gconstpointer p1,
gconstpointer p2) gconstpointer p2)
@ -1538,6 +1552,7 @@ instance_real_class_cmp (gconstpointer p1,
guint8 *i2 = irc2->instance; guint8 *i2 = irc2->instance;
return G_BSEARCH_ARRAY_CMP (i1, i2); return G_BSEARCH_ARRAY_CMP (i1, i2);
} }
G_LOCK_DEFINE_STATIC (instance_real_class); G_LOCK_DEFINE_STATIC (instance_real_class);
static GBSearchArray *instance_real_class_bsa = NULL; static GBSearchArray *instance_real_class_bsa = NULL;
static GBSearchConfig instance_real_class_bconfig = { static GBSearchConfig instance_real_class_bconfig = {
@ -1545,6 +1560,7 @@ static GBSearchConfig instance_real_class_bconfig = {
instance_real_class_cmp, instance_real_class_cmp,
0, 0,
}; };
static inline void static inline void
instance_real_class_set (gpointer instance, instance_real_class_set (gpointer instance,
GTypeClass *class) 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); instance_real_class_bsa = g_bsearch_array_replace (instance_real_class_bsa, &instance_real_class_bconfig, &key);
G_UNLOCK (instance_real_class); G_UNLOCK (instance_real_class);
} }
static inline void static inline void
instance_real_class_remove (gpointer instance) instance_real_class_remove (gpointer instance)
{ {
@ -1575,6 +1592,7 @@ instance_real_class_remove (gpointer instance)
} }
G_UNLOCK (instance_real_class); G_UNLOCK (instance_real_class);
} }
static inline GTypeClass* static inline GTypeClass*
instance_real_class_get (gpointer instance) instance_real_class_get (gpointer instance)
{ {
@ -1591,20 +1609,21 @@ instance_real_class_get (gpointer instance)
/** /**
* g_type_create_instance: * g_type_create_instance:
* @type: An instantiatable type to create an instance for. * @type: An instantiatable type to create an instance for.
* *
* Creates and initializes an instance of @type if @type is valid and can * Creates and initializes an instance of @type if @type is valid and
* be instantiated. The type system only performs basic allocation and * can be instantiated. The type system only performs basic allocation
* structure setups for instances: actual instance creation should happen * and structure setups for instances: actual instance creation should
* through functions supplied by the type's fundamental type implementation. * happen through functions supplied by the type's fundamental type
* So use of g_type_create_instance() is reserved for implementators of * implementation. So use of g_type_create_instance() is reserved for
* fundamental types only. E.g. instances of the #GObject hierarchy * implementators of fundamental types only. E.g. instances of the
* should be created via g_object_new() and <emphasis>never</emphasis> * #GObject hierarchy should be created via g_object_new() and
* directly through g_type_create_instance() which doesn't handle * <emphasis>never</emphasis> directly through
* things like singleton objects or object construction. * g_type_create_instance() which doesn't handle things like singleton
* Note: Do <emphasis>not</emphasis> use this function, unless you're * objects or object construction. Note: Do <emphasis>not</emphasis>
* implementing a fundamental type. Also language bindings should <emphasis>not</emphasis> * use this function, unless you're implementing a fundamental
* use this function but g_object_new() instead. * 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 * Returns: An allocated and initialized instance, subject to further
* treatment by the fundamental type implementation. * treatment by the fundamental type implementation.
*/ */
@ -1662,12 +1681,12 @@ g_type_create_instance (GType type)
/** /**
* g_type_free_instance: * g_type_free_instance:
* @instance: an instance of a type. * @instance: an instance of a type.
* *
* Frees an instance of a type, returning it to the instance pool for the type, * Frees an instance of a type, returning it to the instance pool for
* if there is one. * the type, if there is one.
* *
* Like g_type_create_instance(), this function is reserved for implementors of * Like g_type_create_instance(), this function is reserved for
* fundamental types. * implementors of fundamental types.
*/ */
void void
g_type_free_instance (GTypeInstance *instance) g_type_free_instance (GTypeInstance *instance)
@ -2163,7 +2182,7 @@ type_data_last_unref_Wm (GType type,
* g_type_add_class_cache_func: * g_type_add_class_cache_func:
* @cache_data: data to be passed to @cache_func * @cache_data: data to be passed to @cache_func
* @cache_func: a #GTypeClassCacheFunc * @cache_func: a #GTypeClassCacheFunc
* *
* Adds a #GTypeClassCacheFunc to be called before the reference count of a * 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 * class goes from one to zero. This can be used to prevent premature class
* destruction. All installed #GTypeClassCacheFunc functions will be chained * 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: * g_type_remove_class_cache_func:
* @cache_data: data that was given when adding @cache_func * @cache_data: data that was given when adding @cache_func
* @cache_func: a #GTypeClassCacheFunc * @cache_func: a #GTypeClassCacheFunc
* *
* Removes a previously installed #GTypeClassCacheFunc. The cache maintained * Removes a previously installed #GTypeClassCacheFunc. The cache
* by @cache_func has to be empty when calling g_type_remove_class_cache_func() * maintained by @cache_func has to be empty when calling
* to avoid leaks. * g_type_remove_class_cache_func() to avoid leaks.
*/ */
void void
g_type_remove_class_cache_func (gpointer cache_data, 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: * g_type_add_interface_check:
* @check_data: data to pass to @check_func * @check_data: data to pass to @check_func
* @check_func: function to be called after each interface * @check_func: function to be called after each interface
* is initialized. * is initialized.
* *
* Adds a function to be called after an interface vtable is * Adds a function to be called after an interface vtable is
* initialized for any class (i.e. after the @interface_init * initialized for any class (i.e. after the @interface_init member of
* member of #GInterfaceInfo has been called). * #GInterfaceInfo has been called).
* *
* This function is useful when you want to check an invariant * This function is useful when you want to check an invariant that
* that depends on the interfaces of a class. For instance, * depends on the interfaces of a class. For instance, the
* the implementation of #GObject uses this facility to check * implementation of #GObject uses this facility to check that an
* that an object implements all of the properties that are * object implements all of the properties that are defined on its
* defined on its interfaces. * interfaces.
* *
* Since: 2.4 * Since: 2.4
*/ */
void void
@ -2265,10 +2284,10 @@ g_type_add_interface_check (gpointer check_data,
* g_type_remove_interface_check: * g_type_remove_interface_check:
* @check_data: callback data passed to g_type_add_interface_check() * @check_data: callback data passed to g_type_add_interface_check()
* @check_func: callback function 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 * Removes an interface check function added with
* g_type_add_interface_check(). * g_type_add_interface_check().
* *
* Since: 2.4 * Since: 2.4
*/ */
void void
@ -2308,14 +2327,14 @@ g_type_remove_interface_check (gpointer check_data,
* @info: The #GTypeInfo structure for this type. * @info: The #GTypeInfo structure for this type.
* @finfo: The #GTypeFundamentalInfo structure for this type. * @finfo: The #GTypeFundamentalInfo structure for this type.
* @flags: Bitwise combination of #GTypeFlags values. * @flags: Bitwise combination of #GTypeFlags values.
* *
* Registers @type_id as the predefined identifier and @type_name as the * Registers @type_id as the predefined identifier and @type_name as the
* name of a fundamental type. The type system uses the information * 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 * #GTypeFundamentalInfo structure pointed to by @finfo to manage the
* type and its instances. The value of @flags determines additional * type and its instances. The value of @flags determines additional
* characteristics of the fundamental type. * characteristics of the fundamental type.
* *
* Returns: The predefined type identifier. * Returns: The predefined type identifier.
*/ */
GType GType
@ -2379,13 +2398,14 @@ g_type_register_fundamental (GType type_id,
* @instance_size: Size of the instance structure (see #GTypeInfo) * @instance_size: Size of the instance structure (see #GTypeInfo)
* @instance_init: Location of the instance initialization function (see #GTypeInfo) * @instance_init: Location of the instance initialization function (see #GTypeInfo)
* @flags: Bitwise combination of #GTypeFlags values. * @flags: Bitwise combination of #GTypeFlags values.
* *
* Registers @type_name as the name of a new static type derived from * Registers @type_name as the name of a new static type derived from
* @parent_type. The value of @flags determines the nature (e.g. * @parent_type. The value of @flags determines the nature (e.g.
* abstract or not) of the type. It works by filling a #GTypeInfo * abstract or not) of the type. It works by filling a #GTypeInfo
* struct and calling g_type_register_static(). * struct and calling g_type_register_static().
* *
* Since: 2.12 * Since: 2.12
*
* Returns: The new type identifier. * Returns: The new type identifier.
*/ */
GType 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. * @type_name: 0-terminated string used as the name of the new type.
* @info: The #GTypeInfo structure for this type. * @info: The #GTypeInfo structure for this type.
* @flags: Bitwise combination of #GTypeFlags values. * @flags: Bitwise combination of #GTypeFlags values.
* *
* Registers @type_name as the name of a new static type derived from * Registers @type_name as the name of a new static type derived from
* @parent_type. The type system uses the information contained in the * @parent_type. The type system uses the information contained in the
* #GTypeInfo structure pointed to by @info to manage the type and its * #GTypeInfo structure pointed to by @info to manage the type and its
* instances (if not abstract). The value of @flags determines the nature * instances (if not abstract). The value of @flags determines the nature
* (e.g. abstract or not) of the type. * (e.g. abstract or not) of the type.
* *
* Returns: The new type identifier. * Returns: The new type identifier.
*/ */
GType 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. * @type_name: 0-terminated string used as the name of the new type.
* @plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from. * @plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from.
* @flags: Bitwise combination of #GTypeFlags values. * @flags: Bitwise combination of #GTypeFlags values.
* *
* Registers @type_name as the name of a new dynamic type derived from * Registers @type_name as the name of a new dynamic type derived from
* @parent_type. The type system uses the information contained in the * @parent_type. The type system uses the information contained in the
* #GTypePlugin structure pointed to by @plugin to manage the type and its * #GTypePlugin structure pointed to by @plugin to manage the type and its
* instances (if not abstract). The value of @flags determines the nature * instances (if not abstract). The value of @flags determines the nature
* (e.g. abstract or not) of the type. * (e.g. abstract or not) of the type.
* *
* Returns: The new type identifier or #G_TYPE_INVALID if registration failed. * Returns: The new type identifier or #G_TYPE_INVALID if registration failed.
*/ */
GType GType
@ -2517,8 +2537,8 @@ g_type_register_dynamic (GType parent_type,
* @instance_type: #GType value of an instantiable type. * @instance_type: #GType value of an instantiable type.
* @interface_type: #GType value of an interface type. * @interface_type: #GType value of an interface type.
* @info: The #GInterfaceInfo structure for this * @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 * Adds the static @interface_type to @instantiable_type. The information
* contained in the #GTypeInterfaceInfo structure pointed to by @info * contained in the #GTypeInterfaceInfo structure pointed to by @info
* is used to manage the relationship. * 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. * @instance_type: the #GType value of an instantiable type.
* @interface_type: the #GType value of an interface type. * @interface_type: the #GType value of an interface type.
* @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from.
* *
* Adds the dynamic @interface_type to @instantiable_type. The information * Adds the dynamic @interface_type to @instantiable_type. The information
* contained in the #GTypePlugin structure pointed to by @plugin * contained in the #GTypePlugin structure pointed to by @plugin
* is used to manage the relationship. * is used to manage the relationship.
@ -2590,11 +2610,11 @@ g_type_add_interface_dynamic (GType instance_type,
/** /**
* g_type_class_ref: * g_type_class_ref:
* @type: Type ID of a classed type. * @type: Type ID of a classed type.
* *
* Increments the reference count of the class structure belonging to * Increments the reference count of the class structure belonging to
* @type. This function will demand-create the class if it doesn't * @type. This function will demand-create the class if it doesn't
* exist already. * exist already.
* *
* Returns: The #GTypeClass structure for the given type ID. * Returns: The #GTypeClass structure for the given type ID.
*/ */
gpointer gpointer
@ -2650,7 +2670,7 @@ g_type_class_ref (GType type)
/** /**
* g_type_class_unref: * g_type_class_unref:
* @g_class: The #GTypeClass structure to unreference. * @g_class: The #GTypeClass structure to unreference.
* *
* Decrements the reference count of the class structure being passed in. * Decrements the reference count of the class structure being passed in.
* Once the last reference count of a class has been released, classes * Once the last reference count of a class has been released, classes
* may be finalized by the type system, so further dereferencing of a * 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_type_class_unref_uncached:
* @g_class: The #GTypeClass structure to unreference. * @g_class: The #GTypeClass structure to unreference.
* *
* A variant of g_type_class_unref() for use in #GTypeClassCacheFunc * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc
* implementations. It unreferences a class without consulting the chain * implementations. It unreferences a class without consulting the chain
* of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur * 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: * g_type_class_peek:
* @type: Type ID of a classed type. * @type: Type ID of a classed type.
* *
* This function is essentially the same as g_type_class_ref(), except that * 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 * 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 * may return %NULL if the class of the type passed in does not currently
* exist (hasn't been referenced before). * exist (hasn't been referenced before).
* *
* Returns: The #GTypeClass structure for the given type ID or %NULL * Returns: The #GTypeClass structure for the given type ID or %NULL
* if the class does not currently exist. * if the class does not currently exist.
*/ */
@ -2735,7 +2755,7 @@ g_type_class_peek (GType type)
/** /**
* g_type_class_peek_static: * g_type_class_peek_static:
* @type: Type ID of a classed type. * @type: Type ID of a classed type.
* *
* A more efficient version of g_type_class_peek() which works only for * A more efficient version of g_type_class_peek() which works only for
* static types. * static types.
* *
@ -2765,18 +2785,18 @@ g_type_class_peek_static (GType type)
/** /**
* g_type_class_peek_parent: * g_type_class_peek_parent:
* @g_class: The #GTypeClass structure to retrieve the parent class for. * @g_class: The #GTypeClass structure to retrieve the parent class for.
* *
* This is a convenience function often needed in class initializers. * 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. * It returns the class structure of the immediate parent type of the
* Since derived classes hold * class passed in. Since derived classes hold a reference count on
* a reference count on their parent classes as long as they are instantiated, * their parent classes as long as they are instantiated, the returned
* the returned class will always exist. This function is essentially * class will always exist. This function is essentially equivalent
* equivalent to: * to:
* *
* <programlisting> * <programlisting>
* g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
* </programlisting> * </programlisting>
* *
* Returns: The parent class of @g_class. * Returns: The parent class of @g_class.
*/ */
gpointer gpointer
@ -2807,12 +2827,12 @@ g_type_class_peek_parent (gpointer g_class)
* g_type_interface_peek: * g_type_interface_peek:
* @instance_class: A #GTypeClass structure. * @instance_class: A #GTypeClass structure.
* @iface_type: An interface ID which this class conforms to. * @iface_type: An interface ID which this class conforms to.
* *
* Returns the #GTypeInterface structure of an interface to which the passed in * Returns the #GTypeInterface structure of an interface to which the
* class conforms. * passed in class conforms.
* *
* Returns: The GTypeInterface structure of iface_type if implemented * Returns: The GTypeInterface structure of iface_type if implemented
* by @instance_class, %NULL otherwise * by @instance_class, %NULL otherwise
*/ */
gpointer gpointer
g_type_interface_peek (gpointer instance_class, g_type_interface_peek (gpointer instance_class,
@ -2848,15 +2868,15 @@ g_type_interface_peek (gpointer instance_class,
/** /**
* g_type_interface_peek_parent: * g_type_interface_peek_parent:
* @g_iface: A #GTypeInterface structure. * @g_iface: A #GTypeInterface structure.
* *
* Returns the corresponding #GTypeInterface structure of the parent type * Returns the corresponding #GTypeInterface structure of the parent type
* of the instance type to which @g_iface belongs. This is useful when * of the instance type to which @g_iface belongs. This is useful when
* deriving the implementation of an interface from the parent type and * deriving the implementation of an interface from the parent type and
* then possibly overriding some methods. * then possibly overriding some methods.
* *
* Returns: The corresponding #GTypeInterface structure of the parent type * Returns: The corresponding #GTypeInterface structure of the parent
* of the instance type to which @g_iface belongs, or %NULL if the parent type * type of the instance type to which @g_iface belongs, or
* doesn't conform to the interface. * %NULL if the parent type doesn't conform to the interface.
*/ */
gpointer gpointer
g_type_interface_peek_parent (gpointer g_iface) 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_default_interface_ref:
* @g_type: an interface type * @g_type: an interface type
* *
* Increments the reference count for the interface type @g_type, * Increments the reference count for the interface type @g_type,
* and returns the default interface vtable for the type. * and returns the default interface vtable for the type.
* *
* If the type is not currently in use, then the default vtable * If the type is not currently in use, then the default vtable
* for the type will be created and initalized by calling * for the type will be created and initalized by calling
* the base interface init and default vtable init functions for * 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 * Calling g_type_default_interface_ref() is useful when you
* want to make sure that signals and properties for an interface * want to make sure that signals and properties for an interface
* have been installed. * have been installed.
* *
* Since: 2.4 * Since: 2.4
* Returns: the default vtable for the interface; call *
* g_type_default_interface_unref() when you are done using * Returns: the default vtable for the interface; call
* the interface. * g_type_default_interface_unref() when you are done using
* the interface.
*/ */
gpointer gpointer
g_type_default_interface_ref (GType g_type) 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_default_interface_peek:
* @g_type: an interface type * @g_type: an interface type
* *
* If the interface type @g_type is currently in use, returns * If the interface type @g_type is currently in use, returns its
* its default interface vtable. * default interface vtable.
* *
* Since: 2.4 * Since: 2.4
*
* Returns: the default vtable for the interface, or %NULL * 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 gpointer
g_type_default_interface_peek (GType g_type) 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_type_default_interface_unref:
* @g_iface: the default vtable structure for a interface, as * @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 * Decrements the reference count for the type corresponding to the
* interface default vtable @g_iface. If the type is dynamic, then * interface default vtable @g_iface. If the type is dynamic, then
* when no one is using the interface and all references have * when no one is using the interface and all references have
* been released, the finalize function for the interface's default * been released, the finalize function for the interface's default
* vtable (the <structfield>class_finalize</structfield> member of * vtable (the <structfield>class_finalize</structfield> member of
* #GTypeInfo) will be called. * #GTypeInfo) will be called.
* *
* Since: 2.4 * Since: 2.4
*/ */
void void
@ -3013,13 +3035,13 @@ g_type_default_interface_unref (gpointer g_iface)
/** /**
* g_type_name: * g_type_name:
* @type: Type to return name for. * @type: Type to return name for.
* *
* Get the unique name that is assigned to a type ID. * Get the unique name that is assigned to a type ID. Note that this
* Note that this function (like all other GType API) cannot cope with invalid * function (like all other GType API) cannot cope with invalid type
* type IDs. %G_TYPE_INVALID may be passed to this function, as may be any other * IDs. %G_TYPE_INVALID may be passed to this function, as may be any
* validly registered type ID, but randomized type IDs should not be passed in and * other validly registered type ID, but randomized type IDs should
* will most likely lead to a crash. * not be passed in and will most likely lead to a crash.
* *
* Returns: Static type name or %NULL. * Returns: Static type name or %NULL.
*/ */
G_CONST_RETURN gchar* G_CONST_RETURN gchar*
@ -3037,9 +3059,9 @@ g_type_name (GType type)
/** /**
* g_type_qname: * g_type_qname:
* @type: Type to return quark of type name for. * @type: Type to return quark of type name for.
* *
* Get the corresponding quark of the type IDs name. * Get the corresponding quark of the type IDs name.
* *
* Returns: The type names quark or 0. * Returns: The type names quark or 0.
*/ */
GQuark GQuark
@ -3055,10 +3077,12 @@ g_type_qname (GType type)
/** /**
* g_type_from_name: * g_type_from_name:
* @name: Type name to lookup. * @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 * Lookup the type ID from a given type name, returning 0 if no type
* (this is the preferred method to find out by name whether a specific type has been registered yet). * 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. * Returns: Corresponding type ID or 0.
*/ */
GType GType
@ -3083,10 +3107,10 @@ g_type_from_name (const gchar *name)
/** /**
* g_type_parent: * g_type_parent:
* @type: The derived type. * @type: The derived type.
* *
* Return the direct parent type of the passed in type. * Return the direct parent type of the passed in type. If the passed
* If the passed in type has no parent, i.e. is a fundamental type, 0 is returned. * in type has no parent, i.e. is a fundamental type, 0 is returned.
* *
* Returns: The parent type. * Returns: The parent type.
*/ */
GType GType
@ -3102,10 +3126,10 @@ g_type_parent (GType type)
/** /**
* g_type_depth: * g_type_depth:
* @type: A #GType value. * @type: A #GType value.
* *
* Returns the length of the ancestry of the passed in type. This includes the * Returns the length of the ancestry of the passed in type. This
* type itself, so that e.g. a fundamental type has depth 1. * includes the type itself, so that e.g. a fundamental type has depth 1.
* *
* Returns: The depth of @type. * Returns: The depth of @type.
*/ */
guint guint
@ -3122,14 +3146,15 @@ g_type_depth (GType type)
* g_type_next_base: * g_type_next_base:
* @leaf_type: Descendant of @root_type and the type to be returned. * @leaf_type: Descendant of @root_type and the type to be returned.
* @root_type: Immediate parent of the returned type. * @root_type: Immediate parent of the returned type.
* *
* Given a @leaf_type and a @root_type which is contained in its anchestry, return * Given a @leaf_type and a @root_type which is contained in its
* the type that @root_type is the immediate parent of. * anchestry, return the type that @root_type is the immediate parent
* In other words, this function determines the type that is derived directly from * of. In other words, this function determines the type that is
* @root_type which is also a base class of @leaf_type. Given a root type and a * derived directly from @root_type which is also a base class of
* leaf type, this function can be used to determine the types and order in which * @leaf_type. Given a root type and a leaf type, this function can
* the leaf type is descended from the root type. * 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. * Returns: Immediate child of @root_type and anchestor of @leaf_type.
*/ */
GType GType
@ -3207,10 +3232,11 @@ type_node_conforms_to_U (TypeNode *node,
* g_type_is_a: * g_type_is_a:
* @type: Type to check anchestry for. * @type: Type to check anchestry for.
* @is_a_type: Possible anchestor of @type or interface @type could conform to. * @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 a derivable type, check whether @type is a
* If @is_a_type is an interface, check whether @type conforms to it. * 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. * Returns: %TRUE if @type is_a @is_a_type holds true.
*/ */
gboolean gboolean
@ -3231,10 +3257,10 @@ g_type_is_a (GType type,
* g_type_children: * g_type_children:
* @type: The parent type. * @type: The parent type.
* @n_children: Optional #guint pointer to contain the number of child types. * @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 * 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. * 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. * Returns: Newly allocated and 0-terminated array of child types.
*/ */
GType* GType*
@ -3271,12 +3297,13 @@ g_type_children (GType type,
/** /**
* g_type_interfaces: * g_type_interfaces:
* @type: The type to list interface types for. * @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 * 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 * interface types that @type conforms to. The return value has to be
* g_free()ed after use. * g_free()ed after use.
* *
* Returns: Newly allocated and 0-terminated array of interface types. * Returns: Newly allocated and 0-terminated array of interface types.
*/ */
GType* GType*
@ -3361,10 +3388,10 @@ type_get_qdata_L (TypeNode *node,
* g_type_get_qdata: * g_type_get_qdata:
* @type: a #GType * @type: a #GType
* @quark: a #GQuark id to identify the data * @quark: a #GQuark id to identify the data
* *
* Obtains data which has previously been attached to @type * Obtains data which has previously been attached to @type
* with g_type_set_qdata(). * with g_type_set_qdata().
* *
* Returns: the data, or %NULL if no data was found * Returns: the data, or %NULL if no data was found
*/ */
gpointer gpointer
@ -3429,7 +3456,7 @@ type_set_qdata_W (TypeNode *node,
* @type: a #GType * @type: a #GType
* @quark: a #GQuark id to identify the data * @quark: a #GQuark id to identify the data
* @data: the data * @data: the data
* *
* Attaches arbitrary data to a type. * Attaches arbitrary data to a type.
*/ */
void void
@ -3471,14 +3498,15 @@ type_add_flags_W (TypeNode *node,
/** /**
* g_type_query: * g_type_query:
* @type: the #GType value of a static, classed type. * @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. * upon success.
* *
* Queries the type system for information about a specific type. * Queries the type system for information about a specific type.
* This function will fill in a user-provided structure to hold type-specific * This function will fill in a user-provided structure to hold
* information. If an invalid #GType is passed in, the @type member of the * type-specific information. If an invalid #GType is passed in, the
* #GTypeQuery is 0. All members filled into the #GTypeQuery structure should * @type member of the #GTypeQuery is 0. All members filled into the
* be considered constant and have to be left untouched. * #GTypeQuery structure should be considered constant and have to be
* left untouched.
*/ */
void void
g_type_query (GType type, g_type_query (GType type,
@ -3548,10 +3576,10 @@ g_type_test_flags (GType type,
/** /**
* g_type_get_plugin: * g_type_get_plugin:
* @type: The #GType to retrieve the plugin for. * @type: The #GType to retrieve the plugin for.
* *
* Returns the #GTypePlugin structure for @type or * Returns the #GTypePlugin structure for @type or
* %NULL if @type does not have a #GTypePlugin structure. * %NULL if @type does not have a #GTypePlugin structure.
* *
* Returns: The corresponding plugin if @type is a dynamic type, * Returns: The corresponding plugin if @type is a dynamic type,
* %NULL otherwise. * %NULL otherwise.
*/ */
@ -3569,12 +3597,12 @@ g_type_get_plugin (GType type)
* g_type_interface_get_plugin: * g_type_interface_get_plugin:
* @instance_type: the #GType value of an instantiatable type. * @instance_type: the #GType value of an instantiatable type.
* @interface_type: the #GType value of an interface type. * @interface_type: the #GType value of an interface type.
* *
* Returns the #GTypePlugin structure for the dynamic interface * Returns the #GTypePlugin structure for the dynamic interface
* @interface_type which has been added to @instance_type, or * @interface_type which has been added to @instance_type, or %NULL if
* %NULL if @interface_type has not been added to @instance_type or does * @interface_type has not been added to @instance_type or does not
* not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). * have a #GTypePlugin structure. See g_type_add_interface_dynamic().
* *
* Returns: the #GTypePlugin for the dynamic interface @interface_type * Returns: the #GTypePlugin for the dynamic interface @interface_type
* of @instance_type. * of @instance_type.
*/ */
@ -3616,14 +3644,14 @@ g_type_interface_get_plugin (GType instance_type,
/** /**
* g_type_fundamental_next: * g_type_fundamental_next:
* *
* Returns the next free fundamental type id which can be used to * Returns the next free fundamental type id which can be used to
* register a new fundamental type with g_type_register_fundamental(). * register a new fundamental type with g_type_register_fundamental().
* The returned type ID represents the highest currently registered * The returned type ID represents the highest currently registered
* fundamental type identifier. * fundamental type identifier.
* *
* Returns: The nextmost fundamental type ID to be registered, * 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 GType
g_type_fundamental_next (void) g_type_fundamental_next (void)
@ -3754,7 +3782,7 @@ g_type_check_class_cast (GTypeClass *type_class,
return type_class; return type_class;
} }
/* /**
* g_type_check_instance: * g_type_check_instance:
* @instance: A valid #GTypeInstance structure. * @instance: A valid #GTypeInstance structure.
* *
@ -3853,12 +3881,12 @@ g_type_check_value_holds (GValue *value,
/** /**
* g_type_value_table_peek: * g_type_value_table_peek:
* @type: A #GType value. * @type: A #GType value.
* *
* Returns the location of the #GTypeValueTable associated with @type. * Returns the location of the #GTypeValueTable associated with @type.
* <emphasis>Note that this function should only be used from source code * <emphasis>Note that this function should only be used from source code
* that implements or has internal knowledge of the implementation of * that implements or has internal knowledge of the implementation of
* @type.</emphasis> * @type.</emphasis>
* *
* Returns: Location of the #GTypeValueTable associated with @type or * Returns: Location of the #GTypeValueTable associated with @type or
* %NULL if there is no #GTypeValueTable associated with @type. * %NULL if there is no #GTypeValueTable associated with @type.
*/ */
@ -3941,8 +3969,9 @@ g_type_name_from_class (GTypeClass *g_class)
/* --- initialization --- */ /* --- initialization --- */
/** /**
* g_type_init_with_debug_flags: * 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. * Similar to g_type_init(), but additionally sets debug flags.
*/ */
void void
@ -4052,12 +4081,13 @@ g_type_init_with_debug_flags (GTypeDebugFlags debug_flags)
/** /**
* g_type_init: * g_type_init:
* *
* Prior to any use of the type system, g_type_init() has to be called to initialize * Prior to any use of the type system, g_type_init() has to be called
* the type system and assorted other code portions (such as the various fundamental * to initialize the type system and assorted other code portions
* type implementations or the signal system). * (such as the various fundamental type implementations or the signal
* system).
*/ */
void void
g_type_init (void) g_type_init (void)
{ {
g_type_init_with_debug_flags (0); g_type_init_with_debug_flags (0);
@ -4067,7 +4097,7 @@ g_type_init (void)
* g_type_class_add_private: * g_type_class_add_private:
* @g_class: class structure for an instantiatable type * @g_class: class structure for an instantiatable type
* @private_size: size of private structure. * @private_size: size of private structure.
* *
* Registers a private structure for an instantiatable type; * Registers a private structure for an instantiatable type;
* when an object is allocated, the private structures for * when an object is allocated, the private structures for
* the type and all of its parent types are allocated * 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>MyObjectPrivate</structname> to an object
* <structname>MyObject</structname> defined in the standard GObject * <structname>MyObject</structname> defined in the standard GObject
* fashion. * fashion.
* *
* |[ * |[
* typedef struct _MyObjectPrivate MyObjectPrivate; * typedef struct _MyObjectPrivate MyObjectPrivate;
* *
* struct _MyObjectPrivate { * struct _MyObjectPrivate {
* int some_field; * int some_field;
* }; * };
* *
* #define MY_OBJECT_GET_PRIVATE(o) \ * #define MY_OBJECT_GET_PRIVATE(o) \
* (G_TYPE_INSTANCE_GET_PRIVATE ((o), MY_TYPE_OBJECT, MyObjectPrivate)) * (G_TYPE_INSTANCE_GET_PRIVATE ((o), MY_TYPE_OBJECT, MyObjectPrivate))
* *
* static void * static void
* my_object_class_init (MyObjectClass *klass) * my_object_class_init (MyObjectClass *klass)
* { * {
* g_type_class_add_private (klass, sizeof (MyObjectPrivate)); * g_type_class_add_private (klass, sizeof (MyObjectPrivate));
* } * }
* *
* static int * static int
* my_object_get_some_field (MyObject *my_object) * my_object_get_some_field (MyObject *my_object)
* { * {
* MyObjectPrivate *priv = MY_OBJECT_GET_PRIVATE (my_object); * MyObjectPrivate *priv = MY_OBJECT_GET_PRIVATE (my_object);
* *
* return priv->some_field; * return priv->some_field;
* } * }
* ]| * ]|
* *
* Since: 2.4 * Since: 2.4
*/ */
void void

53
gobject/gtypemodule.c
View File

@ -28,7 +28,9 @@
/** /**
* SECTION:gtypemodule * SECTION:gtypemodule
*
* @Short_description: Type loading modules * @Short_description: Type loading modules
*
* @See_also:<variablelist> * @See_also:<variablelist>
* <varlistentry> * <varlistentry>
* <term>#GTypePlugin</term> * <term>#GTypePlugin</term>
@ -39,6 +41,7 @@
* <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
* </varlistentry> * </varlistentry>
* </variablelist> * </variablelist>
*
* @Title: GTypeModule * @Title: GTypeModule
* *
* #GTypeModule provides a simple implementation of the #GTypePlugin * #GTypeModule provides a simple implementation of the #GTypePlugin
@ -280,11 +283,11 @@ g_type_module_use (GTypeModule *module)
/** /**
* g_type_module_unuse: * g_type_module_unuse:
* @module: a #GTypeModule * @module: a #GTypeModule
* *
* Decreases the use count of a #GTypeModule by one. If the * Decreases the use count of a #GTypeModule by one. If the
* result is zero, the module will be unloaded. (However, the * result is zero, the module will be unloaded. (However, the
* #GTypeModule will not be freed, and types associated with 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.) * initialized, it must exist forever.)
*/ */
void void
@ -359,19 +362,19 @@ g_type_module_complete_interface_info (GTypePlugin *plugin,
* @type_name: name for the type * @type_name: name for the type
* @type_info: type information structure * @type_info: type information structure
* @flags: flags field providing details about the type * @flags: flags field providing details about the type
* *
* Looks up or registers a type that is implemented with a particular * Looks up or registers a type that is implemented with a particular
* type plugin. If a type with name @type_name was previously registered, * type plugin. If a type with name @type_name was previously registered,
* the #GType identifier for the type is returned, otherwise the type * the #GType identifier for the type is returned, otherwise the type
* is newly registered, and the resulting #GType identifier returned. * is newly registered, and the resulting #GType identifier returned.
* *
* When reregistering a type (typically because a module is unloaded * When reregistering a type (typically because a module is unloaded
* then reloaded, and reinitialized), @module and @parent_type must * then reloaded, and reinitialized), @module and @parent_type must
* be the same as they were previously. * be the same as they were previously.
* *
* As long as any instances of the type exist, the type plugin will * As long as any instances of the type exist, the type plugin will
* not be unloaded. * not be unloaded.
* *
* Returns: the new or existing type ID * Returns: the new or existing type ID
*/ */
GType GType
@ -443,11 +446,11 @@ g_type_module_register_type (GTypeModule *module,
* @instance_type: type to which to add the interface. * @instance_type: type to which to add the interface.
* @interface_type: interface type to add * @interface_type: interface type to add
* @interface_info: type information structure * @interface_info: type information structure
* *
* Registers an additional interface for a type, whose interface * Registers an additional interface for a type, whose interface lives
* lives in the given type plugin. If the interface was already registered * in the given type plugin. If the interface was already registered
* for the type in this plugin, nothing will be done. * for the type in this plugin, nothing will be done.
* *
* As long as any instances of the type exist, the type plugin will * As long as any instances of the type exist, the type plugin will
* not be unloaded. * not be unloaded.
*/ */
@ -504,19 +507,21 @@ g_type_module_add_interface (GTypeModule *module,
* g_type_module_register_enum: * g_type_module_register_enum:
* @module: a #GTypeModule * @module: a #GTypeModule
* @name: name for the type * @name: name for the type
* @const_static_values: an array of #GEnumValue structs for the possible * @const_static_values: an array of #GEnumValue structs for the
* enumeration values. The array is terminated by a struct with all * possible enumeration values. The array is
* members being 0. * terminated by a struct with all members being
* * 0.
*
* Looks up or registers an enumeration that is implemented with a particular * Looks up or registers an enumeration that is implemented with a particular
* type plugin. If a type with name @type_name was previously registered, * type plugin. If a type with name @type_name was previously registered,
* the #GType identifier for the type is returned, otherwise the type * the #GType identifier for the type is returned, otherwise the type
* is newly registered, and the resulting #GType identifier returned. * is newly registered, and the resulting #GType identifier returned.
* *
* As long as any instances of the type exist, the type plugin will * As long as any instances of the type exist, the type plugin will
* not be unloaded. * not be unloaded.
* *
* Since: 2.6 * Since: 2.6
*
* Returns: the new or existing type ID * Returns: the new or existing type ID
*/ */
GType GType
@ -541,19 +546,21 @@ g_type_module_register_enum (GTypeModule *module,
* g_type_module_register_flags: * g_type_module_register_flags:
* @module: a #GTypeModule * @module: a #GTypeModule
* @name: name for the type * @name: name for the type
* @const_static_values: an array of #GFlagsValue structs for the possible * @const_static_values: an array of #GFlagsValue structs for the
* flags values. The array is terminated by a struct with all * possible flags values. The array is
* members being 0. * terminated by a struct with all members being
* * 0.
*
* Looks up or registers a flags type that is implemented with a particular * 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, * type plugin. If a type with name @type_name was previously registered,
* the #GType identifier for the type is returned, otherwise the type * the #GType identifier for the type is returned, otherwise the type
* is newly registered, and the resulting #GType identifier returned. * is newly registered, and the resulting #GType identifier returned.
* *
* As long as any instances of the type exist, the type plugin will * As long as any instances of the type exist, the type plugin will
* not be unloaded. * not be unloaded.
* *
* Since: 2.6 * Since: 2.6
*
* Returns: the new or existing type ID * Returns: the new or existing type ID
*/ */
GType GType

27
gobject/gtypeplugin.c
View File

@ -25,8 +25,11 @@
/** /**
* SECTION:gtypeplugin * SECTION:gtypeplugin
*
* @Short_description: An interface for dynamically loadable types * @Short_description: An interface for dynamically loadable types
*
* @See_also:#GTypeModule and g_type_register_dynamic(). * @See_also:#GTypeModule and g_type_register_dynamic().
*
* @Titile: GTypePlugin * @Titile: GTypePlugin
* *
* The GObject type system supports dynamic loading of types. The * The GObject type system supports dynamic loading of types. The
@ -111,10 +114,10 @@ g_type_plugin_get_type (void)
/** /**
* g_type_plugin_use: * g_type_plugin_use:
* @plugin: a #GTypePlugin * @plugin: a #GTypePlugin
* *
* Calls the @use_plugin function from the #GTypePluginClass of @plugin. * Calls the @use_plugin function from the #GTypePluginClass of
* There should be no need to use this function outside of the GObject * @plugin. There should be no need to use this function outside of
* type system itself. * the GObject type system itself.
*/ */
void void
g_type_plugin_use (GTypePlugin *plugin) g_type_plugin_use (GTypePlugin *plugin)
@ -130,10 +133,10 @@ g_type_plugin_use (GTypePlugin *plugin)
/** /**
* g_type_plugin_unuse: * g_type_plugin_unuse:
* @plugin: a #GTypePlugin * @plugin: a #GTypePlugin
* *
* Calls the @unuse_plugin function from the #GTypePluginClass of @plugin. * Calls the @unuse_plugin function from the #GTypePluginClass of
* There should be no need to use this function outside of the GObject * @plugin. There should be no need to use this function outside of
* type system itself. * the GObject type system itself.
*/ */
void void
g_type_plugin_unuse (GTypePlugin *plugin) g_type_plugin_unuse (GTypePlugin *plugin)
@ -183,10 +186,10 @@ g_type_plugin_complete_type_info (GTypePlugin *plugin,
* is added * is added
* @interface_type: the #GType of the interface whose info is completed * @interface_type: the #GType of the interface whose info is completed
* @info: the #GInterfaceInfo to fill in * @info: the #GInterfaceInfo to fill in
* *
* Calls the @complete_interface_info function from the #GTypePluginClass * Calls the @complete_interface_info function from the
* of @plugin. There should be no need to use this function outside of the * #GTypePluginClass of @plugin. There should be no need to use this
* GObject type system itself. * function outside of the GObject type system itself.
*/ */
void void
g_type_plugin_complete_interface_info (GTypePlugin *plugin, g_type_plugin_complete_interface_info (GTypePlugin *plugin,

82
gobject/gvalue.c
View File

@ -16,16 +16,35 @@
* Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA. * 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 * 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 * @Short_description: A polymorphic type that can hold values of any
* thus can be used as a type initializer for g_value_init() are defined by * other type
* a separate interface. See the <link *
* linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values * @See_also: The fundamental types which all support #GValue
* API</link> for details. * 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 * @Title: Generic values
* *
* The #GValue structure is basically a variable container that consists * The #GValue structure is basically a variable container that consists
* of a type identifier and a specific value of that type. * of a type identifier and a specific value of that type.
* The type identifier within a #GValue structure always determines the * The type identifier within a #GValue structure always determines the
@ -39,17 +58,6 @@
* provided by this interface. * provided by this interface.
*/ */
/*
* FIXME: MT-safety
*/
#include <string.h>
#include "gvalue.h"
#include "gvaluecollector.h"
#include "gbsearcharray.h"
#include "gobjectalias.h"
/* --- typedefs & structures --- */ /* --- typedefs & structures --- */
typedef struct { typedef struct {
@ -92,9 +100,9 @@ value_meminit (GValue *value,
* g_value_init: * g_value_init:
* @value: A zero-filled (uninitialized) #GValue structure. * @value: A zero-filled (uninitialized) #GValue structure.
* @g_type: Type the #GValue should hold values of. * @g_type: Type the #GValue should hold values of.
* *
* Initializes @value with the default value of @type. * Initializes @value with the default value of @type.
* *
* Returns: the #GValue structure that has been passed in * Returns: the #GValue structure that has been passed in
*/ */
GValue* GValue*
@ -132,7 +140,7 @@ g_value_init (GValue *value,
* g_value_copy: * g_value_copy:
* @src_value: An initialized #GValue structure. * @src_value: An initialized #GValue structure.
* @dest_value: An initialized #GValue structure of the same type as @src_value. * @dest_value: An initialized #GValue structure of the same type as @src_value.
* *
* Copies the value of @src_value into @dest_value. * Copies the value of @src_value into @dest_value.
*/ */
void void
@ -161,10 +169,10 @@ g_value_copy (const GValue *src_value,
/** /**
* g_value_reset: * g_value_reset:
* @value: An initialized #GValue structure. * @value: An initialized #GValue structure.
* *
* Clears the current value in @value and resets it to the default value * Clears the current value in @value and resets it to the default value
* (as if the value had just been initialized). * (as if the value had just been initialized).
* *
* Returns: the #GValue structure that has been passed in * Returns: the #GValue structure that has been passed in
*/ */
GValue* GValue*
@ -192,7 +200,7 @@ g_value_reset (GValue *value)
/** /**
* g_value_unset: * g_value_unset:
* @value: An initialized #GValue structure. * @value: An initialized #GValue structure.
* *
* Clears the current value in @value and "unsets" the type, * Clears the current value in @value and "unsets" the type,
* this releases all resources associated with this GValue. * this releases all resources associated with this GValue.
* An unset value is the same as an uninitialized (zero-filled) * An unset value is the same as an uninitialized (zero-filled)
@ -215,10 +223,10 @@ g_value_unset (GValue *value)
/** /**
* g_value_fits_pointer: * g_value_fits_pointer:
* @value: An initialized #GValue structure. * @value: An initialized #GValue structure.
* *
* Determines if @value will fit inside the size of a pointer value. * Determines if @value will fit inside the size of a pointer value.
* This is an internal function introduced mainly for C marshallers. * This is an internal function introduced mainly for C marshallers.
* *
* Returns: %TRUE if @value will fit inside a pointer value. * Returns: %TRUE if @value will fit inside a pointer value.
*/ */
gboolean gboolean
@ -236,11 +244,11 @@ g_value_fits_pointer (const GValue *value)
/** /**
* g_value_peek_pointer: * g_value_peek_pointer:
* @value: An initialized #GValue structure. * @value: An initialized #GValue structure.
* *
* Return the value contents as pointer. This function asserts that * Return the value contents as pointer. This function asserts that
* g_value_fits_pointer() returned %TRUE for the passed in value. * g_value_fits_pointer() returned %TRUE for the passed in value.
* This is an internal function introduced mainly for C marshallers. * This is an internal function introduced mainly for C marshallers.
* *
* Returns: %TRUE if @value will fit inside a pointer value. * Returns: %TRUE if @value will fit inside a pointer value.
*/ */
gpointer gpointer
@ -264,8 +272,8 @@ g_value_peek_pointer (const GValue *value)
* g_value_set_instance: * g_value_set_instance:
* @value: An initialized #GValue structure. * @value: An initialized #GValue structure.
* @instance: the instance * @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. * value_table's collect_value() function.
*/ */
void void
@ -365,7 +373,7 @@ transform_entries_cmp (gconstpointer bsearch_node1,
* @dest_type: Target type. * @dest_type: Target type.
* @transform_func: a function which transforms values of type @src_type * @transform_func: a function which transforms values of type @src_type
* into value of type @dest_type * into value of type @dest_type
* *
* Registers a value transformation function for use in g_value_transform(). * Registers a value transformation function for use in g_value_transform().
* A previously registered transformation function for @src_type and @dest_type * A previously registered transformation function for @src_type and @dest_type
* will be replaced. * will be replaced.
@ -402,10 +410,10 @@ g_value_register_transform_func (GType src_type,
* g_value_type_transformable: * g_value_type_transformable:
* @src_type: Source type. * @src_type: Source type.
* @dest_type: Target type. * @dest_type: Target type.
* *
* Check whether g_value_transform() is able to transform values * Check whether g_value_transform() is able to transform values
* of type @src_type into values of type @dest_type. * of type @src_type into values of type @dest_type.
* *
* Returns: %TRUE if the transformation is possible, %FALSE otherwise. * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
*/ */
gboolean gboolean
@ -423,10 +431,10 @@ g_value_type_transformable (GType src_type,
* g_value_type_compatible: * g_value_type_compatible:
* @src_type: source type to be copied. * @src_type: source type to be copied.
* @dest_type: destination type for copying. * @dest_type: destination type for copying.
* *
* Returns whether a #GValue of type @src_type can be copied into * Returns whether a #GValue of type @src_type can be copied into
* a #GValue of type @dest_type. * a #GValue of type @dest_type.
* *
* Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
*/ */
gboolean gboolean
@ -444,7 +452,7 @@ g_value_type_compatible (GType src_type,
* g_value_transform: * g_value_transform:
* @src_value: Source value. * @src_value: Source value.
* @dest_value: Target value. * @dest_value: Target value.
* *
* Tries to cast the contents of @src_value into a type appropriate * 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 * to store in @dest_value, e.g. to transform a %G_TYPE_INT value
* into a %G_TYPE_FLOAT value. Performing transformations between * 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 * transformations into strings might reveal seemingly arbitrary
* results and shouldn't be relied upon for production code (such * results and shouldn't be relied upon for production code (such
* as rcfile value or object property serialization). * as rcfile value or object property serialization).
* *
* Returns: Whether a transformation rule was found and could be applied. * Returns: Whether a transformation rule was found and could be applied.
* Upon failing transformations, @dest_value is left untouched. * Upon failing transformations, @dest_value is left untouched.
*/ */

50
gobject/gvaluearray.c
View File

@ -27,14 +27,17 @@
#include <stdlib.h> /* qsort() */ #include <stdlib.h> /* qsort() */
#include "gvaluearray.h" #include "gvaluearray.h"
#include "gobjectalias.h" #include "gobjectalias.h"
/** /**
* SECTION:value_arrays * 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() * @See_also:#GValue, #GParamSpecValueArray, g_param_spec_value_array()
*
* @Title: Value arrays * @Title: Value arrays
* *
* The prime purpose of a #GValueArray is for it to be used as an * The prime purpose of a #GValueArray is for it to be used as an
@ -56,9 +59,9 @@
* g_value_array_get_nth: * g_value_array_get_nth:
* @value_array: #GValueArray to get a value from * @value_array: #GValueArray to get a value from
* @index_: index of the value of interest * @index_: index of the value of interest
* *
* Return a pointer to the value at @index_ containd in @value_array. * Return a pointer to the value at @index_ containd in @value_array.
* *
* Returns: pointer to a value at @index_ in @value_array * Returns: pointer to a value at @index_ in @value_array
*/ */
GValue* GValue*
@ -107,11 +110,11 @@ value_array_shrink (GValueArray *value_array)
/** /**
* g_value_array_new: * g_value_array_new:
* @n_prealloced: number of values to preallocate space for * @n_prealloced: number of values to preallocate space for
* *
* Allocate and initialize a new #GValueArray, optionally preserve space * Allocate and initialize a new #GValueArray, optionally preserve space
* for @n_prealloced elements. New arrays always contain 0 elements, * for @n_prealloced elements. New arrays always contain 0 elements,
* regardless of the value of @n_prealloced. * regardless of the value of @n_prealloced.
* *
* Returns: a newly allocated #GValueArray with 0 values * Returns: a newly allocated #GValueArray with 0 values
*/ */
GValueArray* GValueArray*
@ -131,7 +134,7 @@ g_value_array_new (guint n_prealloced)
/** /**
* g_value_array_free: * g_value_array_free:
* @value_array: #GValueArray to free * @value_array: #GValueArray to free
* *
* Free a #GValueArray including its contents. * Free a #GValueArray including its contents.
*/ */
void void
@ -155,10 +158,10 @@ g_value_array_free (GValueArray *value_array)
/** /**
* g_value_array_copy: * g_value_array_copy:
* @value_array: #GValueArray to copy * @value_array: #GValueArray to copy
* *
* Construct an exact copy of a #GValueArray by duplicating all its * Construct an exact copy of a #GValueArray by duplicating all its
* contents. * contents.
* *
* Returns: Newly allocated copy of #GValueArray * Returns: Newly allocated copy of #GValueArray
*/ */
GValueArray* GValueArray*
@ -189,9 +192,9 @@ g_value_array_copy (const GValueArray *value_array)
* g_value_array_prepend: * g_value_array_prepend:
* @value_array: #GValueArray to add an element to * @value_array: #GValueArray to add an element to
* @value: #GValue to copy into #GValueArray * @value: #GValue to copy into #GValueArray
* *
* Insert a copy of @value as first element of @value_array. * Insert a copy of @value as first element of @value_array.
* *
* Returns: the #GValueArray passed in as @value_array * Returns: the #GValueArray passed in as @value_array
*/ */
GValueArray* GValueArray*
@ -207,9 +210,9 @@ g_value_array_prepend (GValueArray *value_array,
* g_value_array_append: * g_value_array_append:
* @value_array: #GValueArray to add an element to * @value_array: #GValueArray to add an element to
* @value: #GValue to copy into #GValueArray * @value: #GValue to copy into #GValueArray
* *
* Insert a copy of @value as last element of @value_array. * Insert a copy of @value as last element of @value_array.
* *
* Returns: the #GValueArray passed in as @value_array * Returns: the #GValueArray passed in as @value_array
*/ */
GValueArray* GValueArray*
@ -226,9 +229,9 @@ g_value_array_append (GValueArray *value_array,
* @value_array: #GValueArray to add an element to * @value_array: #GValueArray to add an element to
* @index_: insertion position, must be &lt;= value_array-&gt;n_values * @index_: insertion position, must be &lt;= value_array-&gt;n_values
* @value: #GValue to copy into #GValueArray * @value: #GValue to copy into #GValueArray
* *
* Insert a copy of @value at specified position into @value_array. * Insert a copy of @value at specified position into @value_array.
* *
* Returns: the #GValueArray passed in as @value_array * Returns: the #GValueArray passed in as @value_array
*/ */
GValueArray* GValueArray*
@ -261,9 +264,9 @@ g_value_array_insert (GValueArray *value_array,
* g_value_array_remove: * g_value_array_remove:
* @value_array: #GValueArray to remove an element from * @value_array: #GValueArray to remove an element from
* @index_: position of value to remove, must be &lt; value_array->n_values * @index_: position of value to remove, must be &lt; value_array->n_values
* *
* Remove the value at position @index_ from @value_array. * Remove the value at position @index_ from @value_array.
* *
* Returns: the #GValueArray passed in as @value_array * Returns: the #GValueArray passed in as @value_array
*/ */
GValueArray* GValueArray*
@ -290,12 +293,12 @@ g_value_array_remove (GValueArray *value_array,
* g_value_array_sort: * g_value_array_sort:
* @value_array: #GValueArray to sort * @value_array: #GValueArray to sort
* @compare_func: function to compare elements * @compare_func: function to compare elements
* *
* Sort @value_array using @compare_func to compare the elements accoring to * Sort @value_array using @compare_func to compare the elements accoring to
* the semantics of #GCompareFunc. * the semantics of #GCompareFunc.
* *
* The current implementation uses Quick-Sort as sorting algorithm. * The current implementation uses Quick-Sort as sorting algorithm.
* *
* Returns: the #GValueArray passed in as @value_array * Returns: the #GValueArray passed in as @value_array
*/ */
GValueArray* GValueArray*
@ -317,13 +320,12 @@ g_value_array_sort (GValueArray *value_array,
* @value_array: #GValueArray to sort * @value_array: #GValueArray to sort
* @compare_func: function to compare elements * @compare_func: function to compare elements
* @user_data: extra data argument provided for @compare_func * @user_data: extra data argument provided for @compare_func
* *
* Sort @value_array using @compare_func to compare the elements accoring * Sort @value_array using @compare_func to compare the elements accoring
* to the semantics of #GCompareDataFunc. * to the semantics of #GCompareDataFunc.
* *
*
* The current implementation uses Quick-Sort as sorting algorithm. * The current implementation uses Quick-Sort as sorting algorithm.
* *
* Returns: the #GValueArray passed in as @value_array * Returns: the #GValueArray passed in as @value_array
*/ */
GValueArray* GValueArray*

1
gobject/gvaluetransform.c
View File

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

122
gobject/gvaluetypes.c
View File

@ -32,7 +32,6 @@
#include "gparam.h" #include "gparam.h"
#include "gboxed.h" #include "gboxed.h"
#include "genums.h" #include "genums.h"
#include "gobjectalias.h" #include "gobjectalias.h"
@ -559,7 +558,7 @@ g_value_types_init (void)
* g_value_set_char: * g_value_set_char:
* @value: a valid #GValue of type %G_TYPE_CHAR * @value: a valid #GValue of type %G_TYPE_CHAR
* @v_char: character value to be set * @v_char: character value to be set
* *
* Set the contents of a %G_TYPE_CHAR #GValue to @v_char. * Set the contents of a %G_TYPE_CHAR #GValue to @v_char.
*/ */
void void
@ -574,7 +573,7 @@ g_value_set_char (GValue *value,
/** /**
* g_value_get_char: * g_value_get_char:
* @value: a valid #GValue of type %G_TYPE_CHAR * @value: a valid #GValue of type %G_TYPE_CHAR
* *
* Get the contents of a %G_TYPE_CHAR #GValue. * Get the contents of a %G_TYPE_CHAR #GValue.
* *
* Returns: character contents of @value * Returns: character contents of @value
@ -591,7 +590,7 @@ g_value_get_char (const GValue *value)
* g_value_set_uchar: * g_value_set_uchar:
* @value: a valid #GValue of type %G_TYPE_UCHAR * @value: a valid #GValue of type %G_TYPE_UCHAR
* @v_uchar: unsigned character value to be set * @v_uchar: unsigned character value to be set
* *
* Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar.
*/ */
void void
@ -606,9 +605,9 @@ g_value_set_uchar (GValue *value,
/** /**
* g_value_get_uchar: * g_value_get_uchar:
* @value: a valid #GValue of type %G_TYPE_UCHAR * @value: a valid #GValue of type %G_TYPE_UCHAR
* *
* Get the contents of a %G_TYPE_UCHAR #GValue. * Get the contents of a %G_TYPE_UCHAR #GValue.
* *
* Returns: unsigned character contents of @value * Returns: unsigned character contents of @value
*/ */
guchar guchar
@ -623,7 +622,7 @@ g_value_get_uchar (const GValue *value)
* g_value_set_boolean: * g_value_set_boolean:
* @value: a valid #GValue of type %G_TYPE_BOOLEAN * @value: a valid #GValue of type %G_TYPE_BOOLEAN
* @v_boolean: boolean value to be set * @v_boolean: boolean value to be set
* *
* Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean.
*/ */
void void
@ -638,9 +637,9 @@ g_value_set_boolean (GValue *value,
/** /**
* g_value_get_boolean: * g_value_get_boolean:
* @value: a valid #GValue of type %G_TYPE_BOOLEAN * @value: a valid #GValue of type %G_TYPE_BOOLEAN
* *
* Get the contents of a %G_TYPE_BOOLEAN #GValue. * Get the contents of a %G_TYPE_BOOLEAN #GValue.
* *
* Returns: boolean contents of @value * Returns: boolean contents of @value
*/ */
gboolean gboolean
@ -655,7 +654,7 @@ g_value_get_boolean (const GValue *value)
* g_value_set_int: * g_value_set_int:
* @value: a valid #GValue of type %G_TYPE_INT * @value: a valid #GValue of type %G_TYPE_INT
* @v_int: integer value to be set * @v_int: integer value to be set
* *
* Set the contents of a %G_TYPE_INT #GValue to @v_int. * Set the contents of a %G_TYPE_INT #GValue to @v_int.
*/ */
void void
@ -670,9 +669,9 @@ g_value_set_int (GValue *value,
/** /**
* g_value_get_int: * g_value_get_int:
* @value: a valid #GValue of type %G_TYPE_INT * @value: a valid #GValue of type %G_TYPE_INT
* *
* Get the contents of a %G_TYPE_INT #GValue. * Get the contents of a %G_TYPE_INT #GValue.
* *
* Returns: integer contents of @value * Returns: integer contents of @value
*/ */
gint gint
@ -687,7 +686,7 @@ g_value_get_int (const GValue *value)
* g_value_set_uint: * g_value_set_uint:
* @value: a valid #GValue of type %G_TYPE_UINT * @value: a valid #GValue of type %G_TYPE_UINT
* @v_uint: unsigned integer value to be set * @v_uint: unsigned integer value to be set
* *
* Set the contents of a %G_TYPE_UINT #GValue to @v_uint. * Set the contents of a %G_TYPE_UINT #GValue to @v_uint.
*/ */
void void
@ -702,9 +701,9 @@ g_value_set_uint (GValue *value,
/** /**
* g_value_get_uint: * g_value_get_uint:
* @value: a valid #GValue of type %G_TYPE_UINT * @value: a valid #GValue of type %G_TYPE_UINT
* *
* Get the contents of a %G_TYPE_UINT #GValue. * Get the contents of a %G_TYPE_UINT #GValue.
* *
* Returns: unsigned integer contents of @value * Returns: unsigned integer contents of @value
*/ */
guint guint
@ -719,7 +718,7 @@ g_value_get_uint (const GValue *value)
* g_value_set_long: * g_value_set_long:
* @value: a valid #GValue of type %G_TYPE_LONG * @value: a valid #GValue of type %G_TYPE_LONG
* @v_long: long integer value to be set * @v_long: long integer value to be set
* *
* Set the contents of a %G_TYPE_LONG #GValue to @v_long. * Set the contents of a %G_TYPE_LONG #GValue to @v_long.
*/ */
void void
@ -734,9 +733,9 @@ g_value_set_long (GValue *value,
/** /**
* g_value_get_long: * g_value_get_long:
* @value: a valid #GValue of type %G_TYPE_LONG * @value: a valid #GValue of type %G_TYPE_LONG
* *
* Get the contents of a %G_TYPE_LONG #GValue. * Get the contents of a %G_TYPE_LONG #GValue.
* *
* Returns: long integer contents of @value * Returns: long integer contents of @value
*/ */
glong glong
@ -751,7 +750,7 @@ g_value_get_long (const GValue *value)
* g_value_set_ulong: * g_value_set_ulong:
* @value: a valid #GValue of type %G_TYPE_ULONG * @value: a valid #GValue of type %G_TYPE_ULONG
* @v_ulong: unsigned long integer value to be set * @v_ulong: unsigned long integer value to be set
* *
* Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong.
*/ */
void void
@ -766,9 +765,9 @@ g_value_set_ulong (GValue *value,
/** /**
* g_value_get_ulong: * g_value_get_ulong:
* @value: a valid #GValue of type %G_TYPE_ULONG * @value: a valid #GValue of type %G_TYPE_ULONG
* *
* Get the contents of a %G_TYPE_ULONG #GValue. * Get the contents of a %G_TYPE_ULONG #GValue.
* *
* Returns: unsigned long integer contents of @value * Returns: unsigned long integer contents of @value
*/ */
gulong gulong
@ -782,9 +781,9 @@ g_value_get_ulong (const GValue *value)
/** /**
* g_value_get_int64: * g_value_get_int64:
* @value: a valid #GValue of type %G_TYPE_INT64 * @value: a valid #GValue of type %G_TYPE_INT64
* *
* Get the contents of a %G_TYPE_INT64 #GValue. * Get the contents of a %G_TYPE_INT64 #GValue.
* *
* Returns: 64bit integer contents of @value * Returns: 64bit integer contents of @value
*/ */
void void
@ -800,7 +799,7 @@ g_value_set_int64 (GValue *value,
* g_value_set_int64: * g_value_set_int64:
* @value: a valid #GValue of type %G_TYPE_INT64 * @value: a valid #GValue of type %G_TYPE_INT64
* @v_int64: 64bit integer value to be set * @v_int64: 64bit integer value to be set
* *
* Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64.
*/ */
gint64 gint64
@ -815,7 +814,7 @@ g_value_get_int64 (const GValue *value)
* g_value_set_uint64: * g_value_set_uint64:
* @value: a valid #GValue of type %G_TYPE_UINT64 * @value: a valid #GValue of type %G_TYPE_UINT64
* @v_uint64: unsigned 64bit integer value to be set * @v_uint64: unsigned 64bit integer value to be set
* *
* Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64.
*/ */
void void
@ -830,9 +829,9 @@ g_value_set_uint64 (GValue *value,
/** /**
* g_value_get_uint64: * g_value_get_uint64:
* @value: a valid #GValue of type %G_TYPE_UINT64 * @value: a valid #GValue of type %G_TYPE_UINT64
* *
* Get the contents of a %G_TYPE_UINT64 #GValue. * Get the contents of a %G_TYPE_UINT64 #GValue.
* *
* Returns: unsigned 64bit integer contents of @value * Returns: unsigned 64bit integer contents of @value
*/ */
guint64 guint64
@ -847,7 +846,7 @@ g_value_get_uint64 (const GValue *value)
* g_value_set_float: * g_value_set_float:
* @value: a valid #GValue of type %G_TYPE_FLOAT * @value: a valid #GValue of type %G_TYPE_FLOAT
* @v_float: float value to be set * @v_float: float value to be set
* *
* Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float.
*/ */
void void
@ -862,9 +861,9 @@ g_value_set_float (GValue *value,
/** /**
* g_value_get_float: * g_value_get_float:
* @value: a valid #GValue of type %G_TYPE_FLOAT * @value: a valid #GValue of type %G_TYPE_FLOAT
* *
* Get the contents of a %G_TYPE_FLOAT #GValue. * Get the contents of a %G_TYPE_FLOAT #GValue.
* *
* Returns: float contents of @value * Returns: float contents of @value
*/ */
gfloat gfloat
@ -879,7 +878,7 @@ g_value_get_float (const GValue *value)
* g_value_set_double: * g_value_set_double:
* @value: a valid #GValue of type %G_TYPE_DOUBLE * @value: a valid #GValue of type %G_TYPE_DOUBLE
* @v_double: double value to be set * @v_double: double value to be set
* *
* Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double.
*/ */
void void
@ -894,9 +893,9 @@ g_value_set_double (GValue *value,
/** /**
* g_value_get_double: * g_value_get_double:
* @value: a valid #GValue of type %G_TYPE_DOUBLE * @value: a valid #GValue of type %G_TYPE_DOUBLE
* *
* Get the contents of a %G_TYPE_DOUBLE #GValue. * Get the contents of a %G_TYPE_DOUBLE #GValue.
* *
* Returns: double contents of @value * Returns: double contents of @value
*/ */
gdouble gdouble
@ -911,7 +910,7 @@ g_value_get_double (const GValue *value)
* g_value_set_string: * g_value_set_string:
* @value: a valid #GValue of type %G_TYPE_STRING * @value: a valid #GValue of type %G_TYPE_STRING
* @v_string: string to be set * @v_string: string to be set
* *
* Set the contents of a %G_TYPE_STRING #GValue to @v_string. * Set the contents of a %G_TYPE_STRING #GValue to @v_string.
*/ */
void void
@ -936,7 +935,7 @@ g_value_set_string (GValue *value,
* g_value_set_static_string: * g_value_set_static_string:
* @value: a valid #GValue of type %G_TYPE_STRING * @value: a valid #GValue of type %G_TYPE_STRING
* @v_string: static string to be set * @v_string: static string to be set
* *
* Set the contents of a %G_TYPE_STRING #GValue to @v_string. * Set the contents of a %G_TYPE_STRING #GValue to @v_string.
* The string is assumed to be static, and is thus not duplicated * The string is assumed to be static, and is thus not duplicated
* when setting the #GValue. * when setting the #GValue.
@ -957,9 +956,9 @@ g_value_set_static_string (GValue *value,
* g_value_set_string_take_ownership: * g_value_set_string_take_ownership:
* @value: a valid #GValue of type %G_TYPE_STRING * @value: a valid #GValue of type %G_TYPE_STRING
* @v_string: duplicated unowned string to be set * @v_string: duplicated unowned string to be set
* *
* This is an internal function introduced mainly for C marshallers. * This is an internal function introduced mainly for C marshallers.
* *
* Deprecated: 2.4: Use g_value_take_string() instead. * Deprecated: 2.4: Use g_value_take_string() instead.
*/ */
void void
@ -973,9 +972,9 @@ g_value_set_string_take_ownership (GValue *value,
* g_value_take_string: * g_value_take_string:
* @value: a valid #GValue of type %G_TYPE_STRING * @value: a valid #GValue of type %G_TYPE_STRING
* @v_string: duplicated unowned string to be set * @v_string: duplicated unowned string to be set
* *
* Sets the contents of a %G_TYPE_STRING #GValue to @v_string. * Sets the contents of a %G_TYPE_STRING #GValue to @v_string.
* *
* Since: 2.4 * Since: 2.4
*/ */
void void
@ -994,9 +993,9 @@ g_value_take_string (GValue *value,
/** /**
* g_value_get_string: * g_value_get_string:
* @value: a valid #GValue of type %G_TYPE_STRING * @value: a valid #GValue of type %G_TYPE_STRING
* *
* Get the contents of a %G_TYPE_STRING #GValue. * Get the contents of a %G_TYPE_STRING #GValue.
* *
* Returns: string content of @value * Returns: string content of @value
*/ */
G_CONST_RETURN gchar* G_CONST_RETURN gchar*
@ -1010,9 +1009,9 @@ g_value_get_string (const GValue *value)
/** /**
* g_value_dup_string: * g_value_dup_string:
* @value: a valid #GValue of type %G_TYPE_STRING * @value: a valid #GValue of type %G_TYPE_STRING
* *
* Get a copy the contents of a %G_TYPE_STRING #GValue. * Get a copy the contents of a %G_TYPE_STRING #GValue.
* *
* Returns: a newly allocated copy of the string content of @value * Returns: a newly allocated copy of the string content of @value
*/ */
gchar* gchar*
@ -1027,7 +1026,7 @@ g_value_dup_string (const GValue *value)
* g_value_set_pointer: * g_value_set_pointer:
* @value: a valid #GValue of %G_TYPE_POINTER * @value: a valid #GValue of %G_TYPE_POINTER
* @v_pointer: pointer value to be set * @v_pointer: pointer value to be set
* *
* Set the contents of a pointer #GValue to @v_pointer. * Set the contents of a pointer #GValue to @v_pointer.
*/ */
void void
@ -1042,9 +1041,9 @@ g_value_set_pointer (GValue *value,
/** /**
* g_value_get_pointer: * g_value_get_pointer:
* @value: a valid #GValue of %G_TYPE_POINTER * @value: a valid #GValue of %G_TYPE_POINTER
* *
* Get the contents of a pointer #GValue. * Get the contents of a pointer #GValue.
* *
* Returns: pointer contents of @value * Returns: pointer contents of @value
*/ */
gpointer gpointer
@ -1069,12 +1068,12 @@ g_gtype_get_type (void)
* g_value_set_gtype: * g_value_set_gtype:
* @value: a valid #GValue of type %G_TYPE_GTYPE * @value: a valid #GValue of type %G_TYPE_GTYPE
* @v_gtype: #GType to be set * @v_gtype: #GType to be set
* *
* Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype.
* *
* Since: 2.12 * Since: 2.12
*/ */
void void
g_value_set_gtype (GValue *value, g_value_set_gtype (GValue *value,
GType v_gtype) GType v_gtype)
{ {
@ -1087,13 +1086,14 @@ g_value_set_gtype (GValue *value,
/** /**
* g_value_get_gtype: * g_value_get_gtype:
* @value: a valid #GValue of type %G_TYPE_GTYPE * @value: a valid #GValue of type %G_TYPE_GTYPE
* *
* Get the contents of a %G_TYPE_GTYPE #GValue. * Get the contents of a %G_TYPE_GTYPE #GValue.
* *
* Since: 2.12 * Since: 2.12
*
* Returns: the #GType stored in @value * Returns: the #GType stored in @value
*/ */
GType GType
g_value_get_gtype (const GValue *value) g_value_get_gtype (const GValue *value)
{ {
g_return_val_if_fail (G_VALUE_HOLDS_GTYPE (value), 0); 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: * g_strdup_value_contents:
* @value: #GValue which contents are to be described. * @value: #GValue which contents are to be described.
* *
* Return a newly allocated string, which describes the contents of a #GValue. * Return a newly allocated string, which describes the contents of a
* The main purpose of this function is to describe #GValue contents for * #GValue. The main purpose of this function is to describe #GValue
* debugging output, the way in which the contents are described may change * contents for debugging output, the way in which the contents are
* between different GLib versions. * described may change between different GLib versions.
* *
* Returns: Newly allocated string. * Returns: Newly allocated string.
*/ */
gchar* gchar*
@ -1177,10 +1177,10 @@ g_strdup_value_contents (const GValue *value)
/** /**
* g_pointer_type_register_static: * g_pointer_type_register_static:
* @name: the name of the new pointer type. * @name: the name of the new pointer type.
* *
* Creates a new %G_TYPE_POINTER derived type id for a new * 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. * Returns: a new %G_TYPE_POINTER derived type id for @name.
*/ */
GType GType