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

remove trailing whitespace from newly added gtk-doc comments and

Browse Source 
2008-06-22  Michael Natterer  <mitch@imendio.com>

	* *.c: remove trailing whitespace from newly added gtk-doc
	comments and reformatted some where they contained overly long or
	ill-formatted lines.


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

6
gobject/ChangeLog
View File

@ -1,3 +1,9 @@
2008-06-22 Michael Natterer <mitch@imendio.com>
* *.c: remove trailing whitespace from newly added gtk-doc
comments and reformatted some where they contained overly long or
ill-formatted lines.
2008-06-22 Michael Natterer <mitch@imendio.com>
* *.c: moved includes back to the top of the files (before gtk-doc

44
gobject/gboxed.c
View File

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

274
gobject/gclosure.c
View File

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

112
gobject/genums.c
View File

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

447
gobject/gobject.c
View File

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

247
gobject/gparam.c
View File

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

175
gobject/gparamspecs.c
View File

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

293
gobject/gsignal.c
View File

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

4
gobject/gsourceclosure.c
View File

@ -162,9 +162,9 @@ static GSourceCallbackFuncs closure_callback_funcs = {
* g_source_set_closure:
* @source: the source
* @closure: a #GClosure
*
*
* Set the callback for a source as a #GClosure.
*
*
* If the source is not one of the standard GLib types, the @closure_callback
* and @closure_marshal fields of the #GSourceFuncs structure must have been
* filled in with pointers to appropriate functions.

386
gobject/gtype.c
View File

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

53
gobject/gtypemodule.c
View File

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

27
gobject/gtypeplugin.c
View File

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

82
gobject/gvalue.c
View File

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

50
gobject/gvaluearray.c
View File

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

1
gobject/gvaluetransform.c
View File

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

122
gobject/gvaluetypes.c
View File

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