diff options
Diffstat (limited to 'gir/gobject-2.0.c')
| -rw-r--r-- | gir/gobject-2.0.c | 222 |
1 files changed, 134 insertions, 88 deletions
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 81e65a32..941b838d 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -210,6 +210,11 @@ * either one of the #GObject instances it refers to are finalized, or when * the #GBinding instance loses its last reference. * + * <note><para>Bindings for languages with garbage collection can use + * g_binding_unbind() to explicitly release a binding between the source + * and target properties, instead of relying on the last reference on the + * binding, source, and target instances to drop.</para></note> + * * #GBinding is available since GObject 2.26 */ @@ -328,8 +333,6 @@ * GValue b = G_VALUE_INIT; * const gchar *message; * - * g_type_init (); - * * /* The GValue starts empty */ * g_assert (!G_VALUE_HOLDS_STRING (&a)); * @@ -391,9 +394,7 @@ * * The GType API is the foundation of the GObject system. It provides the * facilities for registering and managing all fundamental data types, - * user-defined object and interface types. Before using any GType - * or GObject functions, g_type_init() must be called to initialize the - * type system. + * user-defined object and interface types. * * For type creation and registration purposes, all types fall into one of * two categories: static or dynamic. Static types are never loaded or @@ -590,7 +591,8 @@ * /* restore floating state */ * if (was_floating) * g_object_force_floating (object); - * g_object_unref (object); /* release previously acquired reference */ + * else + * g_object_unref (object); /* release previously acquired reference */ * ]| */ @@ -767,6 +769,22 @@ /** + * g_binding_unbind: + * @binding: a #GBinding + * + * Explicitly releases the binding between the source and the target + * property expressed by @binding. + * + * <note>This function will release the reference that is being held on + * the @binding instance; if you want to hold on to the #GBinding instance + * after calling g_binding_unbind(), you will need to hold a reference + * to it.</note> + * + * Since: 2.38 + */ + + +/** * g_boxed_copy: * @boxed_type: The type of @src_boxed. * @src_boxed: The boxed structure to be copied. @@ -2429,7 +2447,7 @@ * * If the previous value was replaced then ownership of the * old value (@oldval) is passed to the caller, including - * the registred destroy notify for it (passed out in @old_destroy). + * the registered destroy notify for it (passed out in @old_destroy). * Its up to the caller to free this as he wishes, which may * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. @@ -2459,7 +2477,7 @@ * * If the previous value was replaced then ownership of the * old value (@oldval) is passed to the caller, including - * the registred destroy notify for it (passed out in @old_destroy). + * the registered destroy notify for it (passed out in @old_destroy). * Its up to the caller to free this as he wishes, which may * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. @@ -2701,7 +2719,20 @@ /** - * g_param_spec_boolean: (skip) + * g_param_get_default_value: + * @param: a #GParamSpec + * + * Gets the default value of @param as a pointer to a #GValue. + * + * The #GValue will remain value for the life of @param. + * + * Returns: a pointer to a #GValue which must not be modified + * Since: 2.38 + */ + + +/** + * g_param_spec_boolean: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2713,12 +2744,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_boxed: (skip) + * g_param_spec_boxed: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2730,12 +2761,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_char: (skip) + * g_param_spec_char: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2746,12 +2777,12 @@ * * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_double: (skip) + * g_param_spec_double: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2765,12 +2796,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_enum: (skip) + * g_param_spec_enum: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2783,12 +2814,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_flags: (skip) + * g_param_spec_flags: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2801,12 +2832,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_float: (skip) + * g_param_spec_float: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2819,7 +2850,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -2885,7 +2916,7 @@ /** - * g_param_spec_gtype: (skip) + * g_param_spec_gtype: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2898,12 +2929,12 @@ * See g_param_spec_internal() for details on property names. * * Since: 2.10 - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_int: (skip) + * g_param_spec_int: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2916,12 +2947,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_int64: (skip) + * g_param_spec_int64: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2934,7 +2965,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -2969,7 +3000,7 @@ /** - * g_param_spec_long: (skip) + * g_param_spec_long: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2982,12 +3013,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_object: (skip) + * g_param_spec_object: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2999,7 +3030,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -3018,7 +3049,7 @@ /** - * g_param_spec_param: (skip) + * g_param_spec_param: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3030,12 +3061,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_pointer: (skip) + * g_param_spec_pointer: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3045,7 +3076,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -3201,7 +3232,7 @@ /** - * g_param_spec_string: (skip) + * g_param_spec_string: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3212,12 +3243,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_uchar: (skip) + * g_param_spec_uchar: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3228,12 +3259,12 @@ * * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_uint: (skip) + * g_param_spec_uint: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3246,12 +3277,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_uint64: (skip) + * g_param_spec_uint64: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3265,12 +3296,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_ulong: (skip) + * g_param_spec_ulong: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3284,12 +3315,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_unichar: (skip) + * g_param_spec_unichar: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3302,7 +3333,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -3334,12 +3365,12 @@ /** - * g_param_spec_variant: (skip) + * g_param_spec_variant: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified * @type: a #GVariantType - * @default_value: (allow-none): a #GVariant of type @type to use as the default value, or %NULL + * @default_value: (allow-none) (transfer full): a #GVariant of type @type to use as the default value, or %NULL * @flags: flags for the property specified * * Creates a new #GParamSpecVariant instance specifying a #GVariant @@ -3349,7 +3380,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: the newly created #GParamSpec + * Returns: (transfer full): the newly created #GParamSpec * Since: 2.26 */ @@ -3591,24 +3622,10 @@ * 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> + * When the @gobject is destroyed the signal handler will be automatically + * disconnected. Note that this is not currently threadsafe (ie: + * emitting a signal while @gobject is being destroyed in another thread + * is not safe). * * Returns: the handler id. */ @@ -4032,7 +4049,7 @@ * * Overrides the class closure (i.e. the default handler) for the * given signal for emissions on instances of @instance_type with - * callabck @class_handler. @instance_type must be derived from the + * callback @class_handler. @instance_type must be derived from the * type to which the signal belongs. * * See g_signal_chain_from_overridden() and @@ -4277,7 +4294,7 @@ * structures. * * Note that the accumulated size of the private structures of - * a type and all its parent types cannot excced 64 KiB. + * a type and all its parent types cannot exceed 64 KiB. * * This function should be called in the type's class_init() function. * The private structure can be retrieved using the @@ -4337,6 +4354,24 @@ /** + * g_type_class_get_instance_private_offset: (skip) + * @g_class: a #GTypeClass + * + * Gets the offset of the private data for instances of @g_class. + * + * This is how many bytes you should add to the instance pointer of a + * class in order to get the private data for the type represented by + * @g_class. + * + * You can only call this function after you have registered a private + * data area for @g_class using g_type_class_add_private(). + * + * Returns: the offset, in bytes + * Since: 2.38 + */ + + +/** * g_type_class_peek: * @type: Type ID of a classed type. * @@ -4592,19 +4627,27 @@ /** - * g_type_init: + * g_type_get_type_registration_serial: * - * 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). + * Returns an opaque serial number that represents the state of the set of + * registered types. Any time a type is registered this serial changes, + * which means you can cache information based on type lookups (such as + * g_type_from_name()) and know if the cache is still valid at a later + * time by comparing the current serial with the one at the type lookup. * - * This function is idempotent: If you call it multiple times, all but - * the first calls will be silently ignored. + * Since: 2.36 + * Returns: An unsigned int, representing the state of type registrations. + */ + + +/** + * g_type_init: * - * There is no way to undo the effect of g_type_init(). + * This function used to initialise the type system. Since GLib 2.36, + * the type system is initialised automatically and this function does + * nothing. * - * Since version 2.24 this also initializes the thread system + * Deprecated: 2.36: the type system is now initialised automatically */ @@ -4612,9 +4655,14 @@ * g_type_init_with_debug_flags: * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. * - * Similar to g_type_init(), but additionally sets debug flags. + * This function used to initialise the type system with debugging + * flags. Since GLib 2.36, the type system is initialised automatically + * and this function does nothing. * - * This function is idempotent. + * If you need to enable debugging features, use the GOBJECT_DEBUG + * environment variable. + * + * Deprecated: 2.36: the type system is now initialised automatically */ @@ -5159,7 +5207,8 @@ * Sort @value_array using @compare_func to compare the elements according to * the semantics of #GCompareFunc. * - * The current implementation uses Quick-Sort as sorting algorithm. + * The current implementation uses the same sorting algorithm as standard + * C qsort() function. * * Returns: (transfer none): the #GValueArray passed in as @value_array * Deprecated: 2.32: Use #GArray and g_array_sort(). @@ -5175,7 +5224,8 @@ * Sort @value_array using @compare_func to compare the elements according * to the semantics of #GCompareDataFunc. * - * The current implementation uses Quick-Sort as sorting algorithm. + * The current implementation uses the same sorting algorithm as standard + * C qsort() function. * * Rename to: g_value_array_sort * Returns: (transfer none): the #GValueArray passed in as @value_array @@ -5492,8 +5542,6 @@ * g_value_peek_pointer: * @value: An initialized #GValue structure. * - * - * * Returns: (transfer none): 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. */ @@ -5936,8 +5984,6 @@ /** * g_variant_get_gtype: * - * - * * Since: 2.24 * Deprecated: 2.26 */ |