From 2c12a016653cadffc660665bb4d8e78181ddb402 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 18 Oct 2003 22:55:00 +0000 Subject: [PATCH] Additions. Sun Oct 19 00:33:28 2003 Matthias Clasen * gobject/tmpl/gtype.sgml: * gobject/tmpl/generic_values.sgml: * gobject/tmpl/objects.sgml: * gobject/tmpl/signals.sgml: Additions. --- docs/reference/ChangeLog | 7 ++ .../gobject/tmpl/generic_values.sgml | 18 +++-- docs/reference/gobject/tmpl/gtype.sgml | 70 ++++++++++++------- docs/reference/gobject/tmpl/objects.sgml | 51 +++++++++----- docs/reference/gobject/tmpl/signals.sgml | 11 +-- 5 files changed, 104 insertions(+), 53 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 0e6a60cac..bb504c96a 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,10 @@ +Sun Oct 19 00:33:28 2003 Matthias Clasen + + * gobject/tmpl/gtype.sgml: + * gobject/tmpl/generic_values.sgml: + * gobject/tmpl/objects.sgml: + * gobject/tmpl/signals.sgml: Additions. + Sat Oct 18 01:30:47 2003 Matthias Clasen * gobject/tmpl/gboxed.sgml: diff --git a/docs/reference/gobject/tmpl/generic_values.sgml b/docs/reference/gobject/tmpl/generic_values.sgml index a27fb58d1..6a9067702 100644 --- a/docs/reference/gobject/tmpl/generic_values.sgml +++ b/docs/reference/gobject/tmpl/generic_values.sgml @@ -213,21 +213,25 @@ as rcfile value or object property serialization). - +The type of value transformation functions which can be registered with +g_value_register_transform_func(). -@src_value: -@dest_value: +@src_value: Source value. +@dest_value: Target value. - +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. -@src_type: -@dest_type: -@transform_func: +@src_type: Source type. +@dest_type: Target type. +@transform_func: a function which transforms values of type @src_type + into value of type @dest_type diff --git a/docs/reference/gobject/tmpl/gtype.sgml b/docs/reference/gobject/tmpl/gtype.sgml index f34c83301..5864ee16a 100644 --- a/docs/reference/gobject/tmpl/gtype.sgml +++ b/docs/reference/gobject/tmpl/gtype.sgml @@ -546,11 +546,10 @@ class_init function with g_type_class_add_private(). - +A bit in the type number that's supposed to be left untouched. - Prior to any use of the type system, g_type_init() has to be called to initialize @@ -802,16 +801,18 @@ have been installed. g_type_default_interface_unref() when you are done using the interface. + If the interface type @g_type is currently in use, returns its default interface vtable. -@g_type: an interface type +@g_type: an interface type @Returns: the default vtable for the interface; or %NULL if the type is not currently in use. + Decrements the reference count for the type corresponding to the @@ -825,6 +826,7 @@ vtable (the class_finalize member of @g_iface: the default vtable structure for a interface, as returned by g_type_default_interface_ref() + Return a newly allocated and 0-terminated array of type IDs, listing the @@ -1093,12 +1095,22 @@ allocated by the corresponding GInterfaceInitFunc() function. - +A callback function which is called when the reference count of a class +drops to zero. It may use g_type_class_ref() to prevent the class from +being freed. You should not call g_type_class_unref() from a +#GTypeClassCacheFunc function to prevent infinite recursion, use +g_type_class_unref_uncached() instead. + + +The functions have to check the class id passed in to figure +whether they actually want to cache the class of this type, since all +classes are routed through the same #GTypeClassCacheFunc chain. -@cache_data: -@g_class: -@Returns: +@cache_data: data that was given to the g_type_add_class_cache_func() call +@g_class: The #GTypeClass structure which is unreferenced +@Returns: %TRUE to stop further #GTypeClassCacheFuncs from being +called, %FALSE to continue. @@ -1286,9 +1298,7 @@ Frees an instance of a type, returning it to the instance pool for the type, if there is one. -Like g_type_create_i * gobject/tmpl/gtype.sgml: - * gobject/tmpl/enumerations_flags.sgml: Add docs. -nstance(), this function is reserved for implementors of +Like g_type_create_instance(), this function is reserved for implementors of fundamental types. @@ -1297,28 +1307,38 @@ fundamental types. - +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 until one of them +returns %TRUE. The functions have to check the class id passed in to figure +whether they actually want to cache the class of this type, since all classes +are routed through the same #GTypeClassCacheFunc chain. -@cache_data: -@cache_func: +@cache_data: data to be passed to @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. -@cache_data: -@cache_func: +@cache_data: data that was given when adding @cache_func +@cache_func: a #GTypeClassCacheFunc - +A variant of g_type_class_unref() for use in #GTypeClassCacheFunc +implementations. It unreferences a class without consulting the chain +of #GTypeClassCacheFuncs, avoiding the recursion which would occur +otherwise. -@g_class: +@g_class: The #GTypeClass structure to unreference. @@ -1521,38 +1541,40 @@ The fundamental type for #GObject. - - +First fundamental type number to create a new fundamental type id with +G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. - +Last fundamental type number reserved for GLib. - +First fundamental type number to create a new fundamental type id with +G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. - +Last fundamental type number reserved for BSE. - +First available fundamental type number to create new fundamental +type id with G_TYPE_MAKE_FUNDAMENTAL(). + +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. + + +@gobject: the object which received the signal. +@pspec: the #GParamSpec of the property which changed @@ -31,32 +41,34 @@ to the #GObject implementation and should never be accessed directly. - +The type of the @get_property function of #GObjectClass. -@object: -@property_id: -@value: -@pspec: +@object: a #GObject +@property_id: the numeric id under which the property was registered with + g_object_class_install_property(). +@value: a #GValue to return the property value in +@pspec: the #GParamSpec describing the property - +The type of the @set_property function of #GObjectClass. -@object: -@property_id: -@value: -@pspec: +@object: a #GObject +@property_id: the numeric id under which the property was registered with + g_object_class_install_property(). +@value: the new value for the property +@pspec: the #GParamSpec describing the property - +The type of the @finalize function of #GObjectClass. -@object: +@object: the #GObject being finalized @@ -241,11 +253,14 @@ When its reference count drops to 0, the object is finalized (i.e. its memory is - +A #GWeakNotify function can be added to an object as a callback that gets +triggered when the object is finalized. Since the object is already being +finalized when the #GWeakNotify is called, there's not much you could do +with the object, apart from e.g. using its adress as hash-index or the like. -@data: -@where_the_object_was: +@data: data that was provided when the weak reference was established +@where_the_object_was: the object being finalized @@ -687,8 +702,8 @@ See g_object_get(). 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 (non -existing) object. Also, g_object_ref() and g_object_unref() are added +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 diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml index 9053f4c2b..2103f5fbb 100644 --- a/docs/reference/gobject/tmpl/signals.sgml +++ b/docs/reference/gobject/tmpl/signals.sgml @@ -862,12 +862,15 @@ Returns the invocation hint of the innermost signal emission of instance. - +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. -@itype: -@struct_offset: -@Returns: +@itype: the #GType identifier of an interface or classed type +@struct_offset: the offset of the member function of @itype's class + structure which is to be invoked by the new closure +@Returns: a new #GCClosure