From 783f1b8640089f41af5862cb8e6ab092efe2b26f Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 13 Apr 2023 15:37:00 +0100 Subject: [PATCH] gtype: Improve documentation for G_TYPE_IS_CLASSED and interfaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The documentation previously implicitly said in a few places that interfaces are classed, but reading through the implementation of `GType`, I don’t think they are. If they were, the registration of the fundamental `G_TYPE_INTERFACE` in `gobject_init()` would specify `G_TYPE_FLAG_CLASSED`. It only specifies `G_TYPE_FLAG_DERIVABLE`. I think this makes sense, because you can’t subclass an interface. Subclassing is a key property of being classed. Tweak the `GType` tutorial to remove that implicit statement, and expand the documentation for `G_TYPE_IS_CLASSED`. Signed-off-by: Philip Withnall Fixes: #252 --- docs/reference/gobject/tut_gobject.xml | 2 +- docs/reference/gobject/tut_gtype.xml | 16 ++++++++-------- docs/reference/gobject/tut_howto.xml | 2 +- gobject/gtype.h | 9 +++++++++ 4 files changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/reference/gobject/tut_gobject.xml b/docs/reference/gobject/tut_gobject.xml index 7a2ecc77e..7754fec1e 100644 --- a/docs/reference/gobject/tut_gobject.xml +++ b/docs/reference/gobject/tut_gobject.xml @@ -294,7 +294,7 @@ ViewerFile *file = g_object_new (VIEWER_TYPE_FILE, NULL); memory will be freed or returned to the object pool for this type. Once the object has been freed, if it was the last instance of the type, the type's class will be destroyed as described in and - . + . diff --git a/docs/reference/gobject/tut_gtype.xml b/docs/reference/gobject/tut_gtype.xml index ee042889d..c2d51b9a5 100644 --- a/docs/reference/gobject/tut_gtype.xml +++ b/docs/reference/gobject/tut_gtype.xml @@ -599,7 +599,7 @@ B *b; interface initialization, see - + @@ -610,7 +610,7 @@ B *b; Last call to g_type_free_instance for target type interface destruction, see - + @@ -633,8 +633,8 @@ B *b; - - Non-instantiatable classed types: interfaces + + Non-instantiatable non-classed types: interfaces This section covers the theory behind interfaces. See @@ -649,7 +649,7 @@ B *b; be seen as a playback interface. Once you know what they do, you can control your CD player, MP3 player or anything that uses these symbols. To declare an interface you have to register a non-instantiatable - classed type which derives from + non-classed type which derives from GTypeInterface. The following piece of code declares such an interface. #define VIEWER_TYPE_EDITABLE viewer_editable_get_type () @@ -792,7 +792,7 @@ struct _GInterfaceInfo - + Interface Initialization @@ -937,7 +937,7 @@ viewer_editable_default_init (ViewerEditableInterface *iface) - + Interface Destruction @@ -955,7 +955,7 @@ viewer_editable_default_init (ViewerEditableInterface *iface) Again, it is important to understand, as in - , + , that both interface_finalize and base_finalize are invoked exactly once for the destruction of each implementation of an interface. Thus, if you were to use one of these functions, you would need to use a static integer variable diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml index 4ed178cec..9bff49b56 100644 --- a/docs/reference/gobject/tut_howto.xml +++ b/docs/reference/gobject/tut_howto.xml @@ -854,7 +854,7 @@ b_method_to_call (B *obj, gint some_param) The theory behind how GObject interfaces work is given in - ; this section covers how to + ; this section covers how to define and implement an interface. diff --git a/gobject/gtype.h b/gobject/gtype.h index a555a90dd..b68af22ca 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -304,6 +304,15 @@ G_BEGIN_DECLS * * Checks if @type is a classed type. * + * A classed type has an associated #GTypeClass which can be derived to store + * class-wide virtual function pointers and data for all instances of the type. + * This allows for subclassing. All #GObjects are classed; none of the scalar + * fundamental types built into GLib are classed. + * + * Interfaces are not classed: while their #GTypeInterface struct could be + * considered similar to #GTypeClass, and classes can derive interfaces, + * #GTypeInterface doesn’t allow for subclassing. + * * Returns: %TRUE if @type is classed */ #define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))